pi-Stomp Core Customization Guide

Addition of hardware peripherals (switches, knobs, etc.) requires corresponding configuration objects to be defined. See the Configuration File Guide for more info.

A few common customizations…

pi-Stomp Core includes an 8-channel ADC which can be used for switches, pots, sensors, etc. Each of the 8 inputs is sampled periodically (every 10ms by default - modify-able in the pi-stomp code). The input should be a voltage between 0 and 3.3v which is translated by the pi-Stomp code to be a value from 0 to 127 then sent as a MIDI CC message that can be assigned to any MOD plugin parameter via “MIDI learn”.

Connection of resistive controls (ie. potentiometers, faders, expression pedal, etc.) is simple. Since the control acts as a simple voltage divider, the actual value of the control is not so important as long as it's greater than 1k ohms (less will draw too much current) and less than 100k. If you're choosing a new control 10k linear taper would be ideal. Log/audio taper won't work as well. The “wiper” (center terminal) of the control should connect to the numbered input of the analog header. The outer two terminals of the control should connect to the “G” (ground) and “3V” (3 volt power). Shorting ground and power is not good. R5 should prevent major current more than 90mA, but still that's a lot, R5 will get hot and could burn out. So make sure that power and ground are connected to the outer terminals of your pot/faders, not the wiper. If you don't know which is the wiper, connect an ohm meter and see which one changes with respect to the other two when you adjust the control.

Below is an example of connecting multiple pots to the Analog header…


Input 0 > Orange wire > wiper terminal (#2) of pot on right

Input 1 > Yellow wire > wiper terminal (#2) of pot on left

Ground (“G”) > Brown wire > both pots terminal #1

Power (“3v”) > Red wire > both pots terminal #3

Special consideration for attaching an Expression Pedal

There is no official standard for expression pedal wiring or the “pinout” of the cable/plug. Fortunately, most pedals (eg. Moog EP-2, Roland EV-5, M-Audio EX-P and others) follow a similar convention where the internal pot (or active circuit) is wired as a voltage divider where the Tip of the TRS plug is the “wiper”, the Ring is the voltage reference (ie. power) and the Sleeve is ground. There are a few exceptions (eg. Line6 EX1) that use a mono cable and TS plug. Those won't work well with pi-Stomp. Some others (eg. Yamaha), may also reverse the Tip and Ring.

If you can't google the answer to how your pedal is wired, as explained above, you can attach a ohm meter between Tip/Sleeve move the pedal, note how the resistance changed, then repeat for Ring/Sleeve. The combination which results in the widest resistance sweep is likely your “wiper”. That's the jack terminal that should connect to your pi-Stomp analog input (0 thru 7). The Sleeve should connect to ground (“G”) and the remaining should connect to power (“3v”).

Although not absolutely required. It's highly advised that you use a jack with “switched” connections and attach the switch terminal for the “wiper” to ground. The reason to do this is that unlike a pot wired to one of the analog inputs, your expression pedal might not always be plugged in. When that's the case, the analog input (presumably defined to be used as an input in default_config.yml) will be floating and thus likely read as constantly changing resulting in spurious MIDI CC messages getting sent. That might mess with your effects or at least eat up CPU cycles. Connecting the switch input to ground, grounds the analog input when no plug is inserted. This is an example of an expression pedal jack wired that way…


Green (wiper/analog-input) > Jack Tip

Red (voltage reference “3v”) > Jack Ring

Black (Ground “G”) > Jack Sleeve > Green Jumper > Jack Tip Switch

Switches have mechanical “bounce”. For momentary switches like footswitches and pushbuttons, this often causes a single switch action to appear as multiple to a microcontroller or pi - Not what you want. Bounce can be addressed by either “debounce” software or hardware. Both are possible with pi-Stomp Core, but using the 5 hardware debounce inputs is highly recommended for footswitches since software debounce just doesn't seem to cut it for many switches. To use, simply attach each switch between a pin pair on the “Switches” part of the expansion header “-0-” thru “-4-”. Switches have no polarity.

Below is an example showing 3 footswitches


Switch Input #0 > Orange/Yellow wires > Switch #0

Switch Input #1 > Grey/Violet wires > Switch #1

Switch Input #2 > Blue/Green wires > Switch #2

Up to 3 GPIO's are available for whatever you'd like. These could be used as outputs (LED's, etc.) or direct (not analog or debounced) inputs.

Note that the default instructions suggested inserting 3 current limit resistors R6, R7, R8 assuming that you might want to attach LED's to the GPIO's. Since they are only 33 Ohms, you probably could leave them regardless of how you plan to use them, but if you do need unadulterated GPIO, replace those with wire jumpers.

Note that the GPIO header has 6 pins. 3 for the GPIO's and 3 for Ground arranged as pairs since you'll likely need a ground reference for either an input or output. The photo above shows 3 LED halos being powered by the GPIO's. The red wires are the positive leads for each LEDs. The black leads underneath are the ground connections.

If more than 3 outputs are needed, you could feed the 3 GPIO lines to a 3-to-8 line decoder/demux for 8 outputs. Something like this perhaps: But understand that you'd have to change the software to treat those 3 lines as addresses instead of individual GPIO’s. If you can get by with just USB midi, you'd be better off using GPIO 14 and 15 (labeled MIDI Rx/Tx in the middle of HExt) for a total of 5 GPIO's.

USB MIDI is available for input and output via the USB port on the Raspberry Pi.

If you need to connect a DIN (traditional round 5-pin) or TRS MIDI cables, you can do so by adding a small breakout board.

Treefallsound offers the following breakout board that includes TRS MIDI In and Out plus a 1/4“ expression pedal input. You get all 3 functions with a simple 5-wire cable to the pi-Stomp Core board.

MIDI+Expression breakout board Build Instructions

Another option if you want DIN MIDI jacks instead of TRS and no Expression Pedal: ArtisLab Midi-in-out

Just know, that board could be tricky to mount to an enclosure as there are no panel mount-able components.

USB MIDI is always enabled, but for MOD to send/receive MIDI from traditional MIDI port(s), the ttymidi service is required.

From an SSH session:

sudo systemctl enable ttymidi
sudo systemctl start ttymidi

To stop and disable the service:

sudo systemctl stop ttymidi
sudo systemctl disable ttymidi 

If you're willing to not have any Analog inputs in favor of using the SPI connection for your own external hardware, you can simply unplug the ADC chip (U2) and plug your SPI wires into the socket pins. That won't provide a super reliable connection, so you'd be better off skipping installation of the ADC socket (S2). Then solder a header or ribbon cable to the SPI pins (labeled CLK, DOUT, DIN and CS next to the S2 socket).

Theoretically, any 40-pin Raspberry Pi can be used with pi-Stomp. Yes, I've even been successful using a pi Zero, but with only one core, I was only able to include a small handful of effects in a pedalboard. Only up to 5 or 6 as I remember, but still, pretty cool if you wanted a super small footprint.

If you're reading this, you're more likely thinking of scaling Up your processing power. For those who care about specs, here's a comparison of Raspberry Pi models

The pi3B+ or pi4B will likely perform at least somewhat better than the recommended pi3A+, but it's not always so cut and dry. Here's an analysis from a pi-Stomp perspective…

  • 4 USB ports instead of 1
  • Has an Ethernet port
  • More RAM. pi3A+: 512MB, pi3B+: 1GB, pi4B: 1, 2, 4, or 8GB. This could help performance, but as you can see from these example pedalboards (lower right corner) running on a 3A+, the RAM never seems to exceed 60%. Doesn't mean yours won't, but CPU seems definitely more important than RAM for most pi-Stomp users.
  • Clock Speed. pi3A+ 1.4GHz, pi4B 1.5GHz. ~7% Faster
  • Core Type. pi3A+ Cortex-A53, pi4 Cortex-A72. This is likely to have the greatest impact on performance, though I'm not sure how much. More processing speed/power allows pi-Stomp pedalboards to include more plugins and/or more CPU intensive plugins (Amp Sims, pitch shift, etc.). It might also allow you to reduce your latency from 5.33ms for 48kHz, down to 2.67ms by increasing the sample rate to 96kHz. 96kHz is still usable with the pi3A+ but we've generally found pedalboards start to glitch, due to buffer overruns with more than 5 or so plugins. Again, it depends on your plugins.
  • Size The “B” boards are 20.6mm (0.8”) longer than A+. The part that extends is used by the extra 3 USB ports and the Ethernet port. Unfortunately, when a pi-Stomp core system is built up, that extra will extend past the plane in which the I/O and power jacks will typically be mounted.

With 3A+

With 3B+ or pi4

Very few pi compatible audio cards have analog inputs, most just have outputs. The only makers we've found are AudioInjector, HiFiBerry and IQAudio.

To switch between audio cards, some configuration is required. Use the following utility via ssh: ~/pi-stomp/util/

Choose your card, then reboot.

This card attaches just fine and requires No additional software configuration. It's bascially the same as the AudioInjector Zero, just with RCA ins/outs and gain/volume controls. You would thus need to figure out how to connect the audio to/from the pi-Stomp board. Keep in mind those extra components extend beyond the board so it could effect your enclosure layout.

IQAudio Codec Zero is my current recommendation if you want different card with better noise performance than the AudioInjector Zero. I've not measured its performance but it does also appear to have more clarity in the high frequencies.

Physically, this card appears to have a very similar form factor to the AudioInjector Zero. However, when plugged into the Hat Hacker, it extends almost 1mm further towards the pi-Stomp board with enough overlap between the two boards that I worry about shorting something. To avoid issues, I added 1mm thick washers to the spacers between the pi-Stomp board and Hat Hacker (to stagger the boards), then wrapped a strip of electrical tape around the edge of the IQAudio. Not ideal, but it works.

The audio input and output are on opposite ends of the board compared to the AudioInjector Zero, so you'll need to make the input cable longer and the output cable shorter.

This card does yield better sound from my experience. I didn't measure the frequency response, but it sounded slightly “brighter”. I did measure the noise floor and it was about 6dB lower than for the AudioInjector Zero. So, roughly half the noise. I usually include a noise gate on most of my “gainy” pedalboards, but if High-er Fi and less noise are critical to you, you might consider this upgrade.

This card includes male headers for attaching its ins/outs. One could connect those to the HIn and HOut headers on the pi-Stomp board using female/female dupont jumpers. But note that the plastic body for such jumpers will extend almost 17mm from the board surface which for most enclosure installations is best to be closer to 10 or 11mm for proper mounting of the volume pot and encoder. So you'd need to figure out a workaround (solder direct to board, use the 1/8“ TRS jack for input and the RCA's for output, etc.)

The footprint of this card is significantly larger than an AudioInjector Zero, so installation into a 1590J sized enclosure is not possible. Larger enclosures would likely not have an issue.

The dual inputs and outputs on pi-Stomp are unbalanced. This is what most users would want. But if you need to interface with pro audio gear which uses balanced I/O, then you could add these cool Sparkfun boards to provide either balanced in or balanced out, or both.

For Balanced Input, the “OUT” pad on the InGenius could attach to the Tip and/or Ring pad(s) on the pi-Stomp Input jack.

For Balanced Output, the “IN” pad on the OutSmarts could attach to the Tip and/or Ring pad(s) on the pi-Stomp Output jack.

Power to these boards is expected to be bipolar +/-4v or more. Since we only have 5v total on pi-Stomp that won't work. I'd probably just power it with a 9v battery with a simple resistive voltage divider like so many guitar pedals use to create a 4.5v bipolar supply (eg. two 10k resistors).

A few parts on the pi-Stomp board are optional and could be eliminated to save cost and waste.

  • If you know you won't be adding analog controls, you can avoid installing the MCP3008 ADC. This could always be popped into place later.
  • If you plan to “under-mount” the LCD (see top vs. under mounting here), then you could avoid installing the HLCD header and solder the LCD directly to the board. This will be the best option for most builds.

If you wanna try to create your own, that's cool. Just know that I spent months and at least 4 board iterations before I got noise issues under control. The RPi power rail is very noisy. Grounding is tricky. You have been warned.

The pi-Stomp firmware assumes the following GPIO pinout for the Raspberry pi:

  • customization_guide.txt
  • Last modified: 2024/01/26 05:45
  • by