Software Installation and Updates

This guide is for installing pi-Stomp based on the latest 64-bit Raspberry pi OS Lite and MOD software.

If you're updating from a PatchboxOS build and only have one SD card, you might want to first backup your pedalboards before wiping your existing patchbox build. If your build includes analog controls (tweak knobs, expression pedal, etc.) or included custom control configuration, you might also want to make a copy of ~/data/config/default_config.yml which defines those controls. When your new build is complete, copy the file over the one automatically created. If your controls don't work in the new build, that could be why.

• A micro SD card. 8GB or larger. Class 10 recommended.
• An internet connected wifi router which supports 2.4GHz (most all do, some pi's don't support 5GHz though)
• A computer with wifi and SD card slot (or USB/SD card adapter)
• Raspberry Pi Imager installed on your computer Download
• An SSH client on your computer. Mac or Linux can use a “terminal”. For windows, you can use PuTTY

Run the Raspberry Pi Imager

Click Choose OS

select Raspberry Pi OS (other) then Raspberry Pi OS (Legacy, 64-bit) Lite Make sure it contains “Legacy”, 64-bit“ and “Lite” as other variants will not likely work.

Click Choose Storage

select your SD card

Click the Gear button (to set Advanced Options)

• hostname must be pistomp
• Enable “Enable SSH” and “Use password authentication”
• Enable “Set username and password”
• Username must be pistomp
• Remember the password you provide, you'll need it later!
• Enable “Configure wireless LAN”
• “SSID” is the name of your router wifi (case matters)
• Complete the “locale” settings as appropriate for your region

Click Save

Click Write

If the write is successful, eject your SD card, insert into the raspberry pi SD slot, power up!

Remember, you should never insert or pull the SD card from the Raspberry Pi while it is powered up. Bad things will likely happen. Bob learned the hard way. Don't be like Bob.

Upon first boot, the LCD should light but not display anything. This first time, it will likely take a few minutes before WiFi becomes available.

If your pi-Stomp connected to your home router successfully, you likely won't need to know the actual IP address and you can use pistomp.local for the following steps. If you cannot ssh using pistomp.local, these tools might help: Fing, Ping or AngryIP.

If you are not able to discover the IP, it's possible that your pi is not within range of your router, you have restrictive security settings (eg. whitelisted devices), or your wifi config info is incorrect. To try again, power cycle the pi-stomp, then repeat the previous steps.

Once you know the IP, start a new SSH session:

ssh pistomp@pistomp.local (password: YOUR_PASSWORD_SET_IN_IMAGER)

IP Address from above, Login: pistomp, Password: YOUR_PASSWORD_SET_IN_IMAGER

If you get an error, something like:

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@       WARNING: POSSIBLE DNS SPOOFING DETECTED!          @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
The ECDSA host key for pistomp.local has changed,

… that's likely because you have an old cashed key on your system, remove it with:

ssh-keygen -R pistomp.local

Once connected, run the following commands to download the pi-Stomp software

sudo apt update --fix-missing && sudo apt install -y git

git clone https://github.com/TreeFallSound/pi-stomp.git

cd pi-stomp 

Next we'll run the setup script which will build and install everything. This takes about 30 to 45 minutes depending on your internet connection etc. There are a few options based on your hardware. Choose just one of the commands below:

IQAudio is the default card now, If your Core build included an IQAudio audiocard (black PCB used after July 2022)

nohup ./setup.sh > setup.log | tail -f setup.log

Add ”-m“ if you also have a MIDI+Expression board

nohup ./setup.sh -m > setup.log | tail -f setup.log

If your Core build included an AudioInjector audiocard (blue PCB used prior to July 2022)

nohup ./setup.sh -a audioinjector-wm8731-audio > setup.log | tail -f setup.log

Add ”-m“ if you also have a MIDI+Expression board

nohup ./setup.sh -m -a audioinjector-wm8731-audio > setup.log | tail -f setup.log

If your build is v1 with the monochrome LCD

nohup ./setup.sh -v 1.0 -m -a audioinjector-wm8731-audio > setup.log | tail -f setup.log

If executing setup.sh fails for some reason. You can re-run it. If you still encounter an error, email support@treefallsound.com

If successful, the system will reboot.

Once the system comes back on line, you should see the LCD display “pi-Stomp!”. If all the services start correctly, it'll eventually display the initial pedalboard and audio should then pass. If this is not the case, check out the Troubleshooting Guide

If all seems good, and the WiFi symbol at the top of the LCD is “lit” not “greyed out”, you can also now connect to the MOD web UI, by directing a browser on your computer to pistomp.local/

Note that analog controls (tweak knobs, expression pedal, etc.) are disabled by default. To enable them, edit the default_config.yml as described in the Configuration File Guide

For optimal processing, you want the input signal to be strong enough, but not to the point of clipping. Distortion and dynamics plugins will perform less ideally if the signal is weak, and clipping just sounds like crap. When first installed, the gain is set to unity, meaning no extra gain or reduction. This might be fine for most instruments, but if your guitar has extra hot or low-output pickups, you'll want to change the gain. Here's how:

1. Make sure processing is not bypassed. The processing/bypass indicator (top right) should be green, if not navigate to it and toggle it.
2. Direct a web browser to pistomp@pistomp.local
3. Drag and drop a plugin named “TinyGain Mono” to your pedalboard. You'll find it under the UTILITY menu
4. Connect it's input by dragging a purple cable from the upper left Hardware Capture 1 input to the left side of TinyGain Mono
5. Now when you play your instrument, you should see its meter react
6. On the pi-Stomp, long-press the top encoder knob until the System Menu appears
7. Scroll down to the Input Gain item and click
8. Repeatedly play your loudest chord (open E chord on guitar), and watch the TinyGain meter. It displays dB values which are negative. More negative numbers are more quiet. The goal is to get it to display a value in the negative teens, but not single digits (when the meter turns red). Use the top encoder knob to increase or reduce gain until that's the case
9. When done, long-press the encoder knob. This value will persist between power cycles. You may need to change it when using a different instrument.

You should be able to use your pi-Stomp indefinitely without updates, but should you decide you require bug-fixes or new features, we currently recommend that you start with a fresh burnt OS image.

To improve the out-of-box experience we will be adding starter pedalboards occasionally. These aren't meant to be spot-on, but get you in the ballpark so you can start tweaking your own tone.

To update, once connected via ssh, run:

cd ~/data/.pedalboards
git pull
sudo systemctl restart jack

You can use git as revision control for your pedalboards.

A commit workflow might look something like:

cd ~/data/.pedalboards
git add MY_PEDALBOARD.pedalboard
git commit -m "adding MY_PEDALBOARD"

If you have a great pedalboard that you'd like to contribute with the community, please do. Just keep in mind that many other users will have it installed on their pi-Stomps so please follow a few guideslines:

• Unless your pedalboard is intended for a special routing use case, have Input1 be your main input and Output1 be your main output.
• Add a “Tiny Gain” plugin just before the output. Make sure when you play loudly, the meter does not peak into the single digits or turn red.
• Make sure the CPU load stays generally below 70%. If it regularly goes above 70% consider removing a plugin or two.

Additions and changes to the public repo should be done on your own branch. To create and work in that branch:

cd ~/data/.pedalboards
git branch MY_BRANCH
git checkout MY_BRANCH

Where MY_BRANCH is the name of your new personal branch

For committing, you'll need to tell git who you are:

git config user.name "MY NAME"
git config user.email MY_EMAIL

Once your pedalboard is complete (saved via the MOD web UI), commit your changes to your local repository. Please make sure you add just the specific pedalboard that you intend to share.

cd ~/data/.pedalboards
git add MY_PEDALBOARD.pedalboard
git commit -m "adding MY_PEDALBOARD" 

You'll need to generate a github personal access token if you don't already have one.

Now specify the remote github repository using that token

git remote remove origin
git remote add origin https://TOKEN@github.com/TreeFallSound/pi-stomp-pedalboards

Now you can push your commit(s) to your branch on github

git push origin MY_BRANCH 

The new pedalboard will now be on github in your branch. To have it merged to the master branch, create a Pull Request. Once tested and accepted, it'll be merged to the master branch.

You might wish to make a backup of your pedalboards or copy them to another pi-stomp or build.

Pedalboards are stored differently depending on which build you're using. 32-bit/Patchbox builds uses /var/modep/pedalboards. 64-bit/RaspberryPi OS uses ~/data/.pedalboards Pedalboards can be used on either build though some plugins may exist in one but not the other.

From 32-bit/Patchbox

ssh patch@patchbox.local "tar cfz /tmp/pedalboard_backup.tgz /var/modep/pedalboards"
scp patch@patchbox.local:/tmp/pedalboard_backup.tgz .

From 64-bit/Raspberry Pi OS

ssh pistomp@pistomp.local "tar cfz /tmp/pedalboard_backup.tgz ~/data/.pedalboards"
scp pistomp@pistomp.local:/tmp/pedalboard_backup.tgz .  

To 32-bit/Patchbox

scp pedalboard_backup.tgz patch@patchbox.local:~/pedalboard_backup.tgz .
ssh patch@patchbox.local
tar xvfz pedalboard_backup.tgz
cp pedalboards/PEDALBOARD.pedalboard /var/modep/pedalboards

To 64-bit/Raspberry Pi OS

scp pedalboard_backup.tgz pistomp@pistomp.local:~/pedalboard_backup.tgz .
ssh pistomp@pistomp.local
tar xvfz pedalboard_backup.tgz
cp pedalboards/PEDALBOARD.pedalboard ~/data/.pedalboards