PiPedal Guitar Effects for Raspberry Pi

PiPedal started off as a Pandemic Keep Busy Project, and as a labor of love. And then it evolved into something extraordinary. So I'm pushing it out into the world for others to use and experiment with.

What it Is

PiPedal is a multi-effect guitar pedal for Raspberry Pi 4. Connect your Raspberry Pi device to a USB Audio adapter, or directly to your guitar amp, if you have a USB-capable guitar amp such as the Boss Katana 100.

Configure and control PiPedal using a phone or tablet. The user interface was designed specifically to work with will a phone's small form factor and touch interface. Or you can connect from your desktop or laptop using a web browser for a slightly more luxurious user experience.

PiPedal provides easy setup of a Wi-Fi Direct connection that can be used to control PiPedal when you're out gigging. The PiPedal Remote Android app provides single-click discovery of and connection to PiPedal devices via Wi-Fi Direct, or via shared Wi-Fi connection through your home Wi-Fi router. (But normal people don't take their home Wi-Fi router to a gig).

PiPedal uses standard LV2 plugins, most of which work well with PiPedal. PiPedal also includes a starter set of LV2 Plugins from the ToobAmp project but the expectation is that you will install other LV2 plugins as well.

Visit the PiPedal web site to find out more about PiPedal, and how to install it.

How to Set It Up

You will need:

• A Raspberry Pi 4 with at least 2GB of RAM (4GB recommended), with Raspberry PI OS 64-bit installed.
• An external USB Audio Adapter, a Guitar Amp with a USB effect loop (e.g. the Boss Kanata 50 or Katana 100), or an external guitar effects pedal that has a USB effect loop.

Setup instructions for installing and configuring PiPedal on your Raspberry Pi device can be found here.

The PiPedal Remote Android app can be found here (or search for "PiPedal Remote" on Google Play).

How It Came to Be

The Raspberry Pi 4 is a powerful platform, but has only recently become suitable for use a guitar effects pedal. The Raspberry Pi 4 is far more powerful than the DSP chips that have traditionally been used to build guitar effects pedals. But Linux support for pro-level USB Audio adapters has historically been spotty and unreliable. Fortunately, the Linux USB Audio stack was rewritten in Linux Kernel version 5.10, and now provides stable low-latency support for pretty much any USB audio device I've been able to throw at it (3 external USB adapters, 2 effect pedals, one amp).

Initial development of PiPedal was done on Ubuntu 21.04 64-bit in order to get access to the new USB audio stack (and because 64-bit apps run significantly faster than 32-bit apps on ARM Cortex A-72 devices). But the latest version of Raspberry Pi OS now uses the Linux 5.15 kernel, so PiPedal now runs on Raspberry Pi OS as well. You will need a 64-bit version of Raspberry Pi OS though.

I happened to have a lot of time on my hands during the pandemic. My second career as a jazz musician was abruptly put on hold by COVID-19. So I decided to spend some time investigating the suitability of Raspberry Pi as a development platform for guitar effects in my copious free time.

Jazz guitarists want two things: 1) great guitar tone! 2) And a rig that's portable enough to carry on a bus or a subway. The two are not entirely compatible. I had done some previous experimental work on amp emulators on Windows platforms, with promising results. But the idea of adding a laptop to my guitar rig just wasn't palatable. (See 2, above),.

I quickly discovered that USB audio was stable and had super-low latency with no dropouts on Linux. And that the Raspberry Pi 4's ARM processors provided a startling amount of CPU power. The ToobAmp set of LV2 plugins that are included with PiPedal are essentially the results of that phase of my Pandemic Project.

Which left one outstanding problem: how does one control a Raspberry Pi guitar effect pedal when you're performing on stage? The ModeP guitar effect pedal project does provide a web interface that can be used to control a Raspberry Pi guitar effect pedal. But unfortunately, the user interface is extremely phone-unfriendly, and doesn't handle touch user interfaces well at all, even on a 10" tablet.

And so PiPedal was germinated.

To be perfectly honest, the initial plan was to write a user interface for my own private use. But as I got further and further into the project it became more and more apparent how great the result was. I was probably about halfway through when I resigned myself to the fact that this was a piece of software that was good enough that I had a duty to push it out into the world to share it.

So PiPedal came to be mostly because toy experiments worked unreasonably and unexpectedly well. In retrospect, the project has gone through four phases.

• Initial experiments with the ToobAmp plugins that produced annoyingly great guitar tone.
• Initial experiments with a remote web UI intended for private use that turned out to be irritatingly promising.
• After realizing that I had to publish, development of the Web UI and backend were escalated to professional-quality development, which requires a lot more work that toy projects.
• The fourth phase involves preparing PiPedal for use as an IoT device. This part of the project is still in progress; but major milestones on that path have been completed: a web user interface for initial setup and configuration of PiPedal, and switching to Wi-Fi Direct connections instead of using Wi-Fi Access Point connections have been completed. But more work needs to be done.

And of course, the PiPedal Remote Android app -- which wasn't actually that difficult. (See the Architecture discussion for a discussion of why that is).

PiPedal Architecture

PiPedal's user interface is written in TypeScript and HTML, using the React Framework. The React Material UI extension provides the controls used to mimic Android Material UI within the web user interface. The entire user interface is statically compiled HTML and JavaScript -- i.e. the web server passes the files to the browser without modifying them. The web application on the client then opens a websocket which is used to interact with the PiPedal server, and access anything in the web user interface that is not static.

The architecture diagram is somewhat deceptive. The user-interface portion hangs off on the bottom as a bunch of files -- which is technically completely accurate. However, almost half the source files in the entire project (and most certainly half the development effort) are React Typescript files, which are compiled to generate those static web pages.

The web server is a minimal-functionality web server, serving only static webpages, although it does provide web sockets for the client applications. Web servers are problematic to say the least in C++. Two web servers swapped out, before settling on the webpp server (which I'm still not happy with).

Audio services are provided by standard Linux Jack Audio services. However, because PiPedal runs as a daemon without an attached desktop, Jack must be run as a Daemon as well. The Jack project documents how to do this; but PiPedal configuration and setup tools take responsibility for creating the Jack systemd service, and making neccesary changes to system configuration.

LV2 audio plugins are handled with assistance from the liblilv0 library. Discovering and parsing.lv2 configuration files is non-trivial, and the liblilv0 library handles all of that.

The PiPedal model module implements the programming interface that the Web Client uses to control PiPedal. The client has a corresponding typescript module (PiPedalModel.tsx) that converts call to json packets, that are sent via a websocket to the PiPedal webserver. Return values and events are sent from the server in the same way: as json packets. Data in the json packets are unpacked on the server and converted to calls on the server-side PiPedal model. This is a common pattern in Software development: a local object (PiPedalModel.tsx in the client) pretends that is remote object on the server (PiPedalModel.cpp on the server). Things are only slightly complicated by the fact that the local proxy objects is a TypeScript/Javascript object, and the remote object is a native C++ object.

The pipedaladmind daemon is responsible for executing privileged operations on PiPedal's behalf. The web interface provides shutdown and restart menu items in the settings dialog, which is an operation that requires root privileges. Root privileges are also required to do audio and Wi-Fi Direct configuration. It's unreasonable and unsafe to run the PiPedal web service with root privileges. So the pipedaladmind daemon provides a permission-protected Linux socket interface that pipedald uses to request privileged operations. Communications over the socket are performed using json packets.

Most of the PiPedal Remote Android app's user interface is implemented using a WebControl that connects to the PiPedal web page. The main purpose of the Android app is to provide discovery and management of the Wi-Fi Direct connection between PiPedal Remote and the PiPedal server. This functionality is implemented use Java and the Android Java SDKs. The application pushes a couple of minor hooks into the WebControl so that the PiPedal user-interface code running inside the WebControl can make adjustments necessary to run well on Android. The Web application closes the web socket when running in the background in order reduce load on the server. This is has to be done slightly differently when running on Android, because we don't want to drop the web socket when a screen flip happens. Of particular interest, the Sponsor links in the web app, which link GitHub funding pages in the browser UI, are intercepted and redirected to Google Play in-app donations, in order to comply with Google Play developer policies.

Climbing the Mountain of Wi-Fi Direct

PiPedal also uses a module currently named pipedal_p2pd, which is responsible for managing the Wi-Fi Direct (also known as Wi-Fi P2P) connection. Curiously, although Raspberry Pi OS "supports" Wi-Fi P2P, there's no native service for setting up and managing permanent Wi-Fi P2P connections. The stock wpa_supplicant service provides methods that support P2P connections, but does not provide event handling, which has to be provided by an external application And it provides two sets of mutually conflicting and similarly incomplete sets of documentation on how to implement P2P session management. Considerable development has to be done to enable Wi-Fi P2p connections. And to get Android to connect, you have to make sure that there's an active DHCP server running on the Wi-Fi Direct connection, which is not easy to set up on Raspberry Pi's dhcpcd/wpa_supplicant-based network stack. (More recent versions of Linux replace this entire dhcpd/wpa_supplicant stack with a new networkd stack that makes this entire job much easier). I blew out my schedule by six unpleasant weeks on this development item!

This deficiency is a curious thing given that Raspberry Pi's have a natural affinity with the Internet-of-Things. And Wi-Fi Direct is an marvelous tool for IoT devices. (Think BlueTooth but much faster, much more reliable, and much easier to onboard). Somewhere on a long list of priorities, there's a task to convert the pipedal_p2pd to a re-usable opensource library; but it's frankly not a huge personal priority right now. If you are in dire need of help with setting up Wi-Fi Direct connections, drop me a message. I may be able to push some code your way.

State of the Project

I have built it. They will come.

It is done.

For now.

Inasmuch as any piece of software is done.

I use it in professional performance. It is a good 1.0 release, I think -- functional, stable as far as I can tell, and ready to be let loose on the world.