The operating system currently supported for pi-Stomp is PatchboxOS created by Blokas Labs and based on Rpi OS Lite. On top of that, you need to install the pi-stomp specific software/firmware.

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

1. Download PatchboxOS
2. Use this guide for writing the downloaded PatchboxOS image to the SD card

PatchboxOS will either present an adhoc hotspot or it will try to connect to a router, not both. It initially will present the hotspot (named Patchbox). We'll use this so we can connect then configure wifi networking for connecting to your router which we'll need for downloading software.

1. Insert the micro SD card into the disk slot at the back of the Raspberry Pi board
2. Power it up! The red LED on the pi should immediately light. The green LED should flash indicating disk activity. If the LED's aren't lighting, turn the power off ASAP and read the troubleshooting guide guide.
3. After about a minute, the green LED should be flashing less frequently. At that point, you should be able to turn-on or redirect the wifi on your computer and connect to the Patchbox hotspot named: Patchbox (password: blokaslabs)
4. Once wifi is established, invoke your SSH client to connect to the pi:
   1. Linux/Mac Terminal: ssh patch@patchbox.local (password: blokaslabs)
   2. Windows PuTTY: IP: patchbox.local, Login: patch, Password: blokaslabs
   3. If you cannot connect, try 172.24.1.1 instead of patchbox.local
5. Once connected, the Patchbox wizard will come up automatically, Control-C to quit.

Now you should have a command prompt.

Run this:

sudo systemctl mask --now pisound-btn.service

Then execute the following and substitute your router ID (name), country code and router password. (If any of the fields includes non-alphanumic characters, you may need to surround the field with double quotes)

patchbox wifi connect --name SSID --country CC --password PASSWORD

This will restart wifi on the pi (switching from hotspot to router). Your current session will end.

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 patchbox.local for the following steps. If you cannot ssh using patchbox.local, then come back here and try some of these discovery methods. Fing, Ping or AngryIP are recommended.

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 patchbox wifi config info is incorrect. To try again, power cycle the pi-stomp, then repeat steps #2 through #6 above.

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

ssh patch@YOUR-IP-ADDRESS (password: blokaslabs)

IP Address from above, Login: patch, Password: blokaslabs

Once connected, run the following commands to download, setup and install the software and audio plugins. It could take about a half hour.

git clone -b v2.0.2-patchboxOS-based https://github.com/TreeFallSound/pi-stomp.git

cd pi-stomp 

If your system will eventually include a serial MIDI add-on, run setup with the '-m' option to enable the ttymidi service

./setup.sh -m

Otherwise, just run setup

./setup.sh

If all went well, now you can reboot

sudo 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

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. Press Footswitch #1 until it's lit.
2. Direct a web browser to patch@patchbox.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, new features or new starter pedalboards, the following should get you there.

In order to pull from the internet, updates can only be done when the pi-Stomp is in “router” wifi mode, not “hotspot” mode.

To switch modes:

• Long-press the upper encoder until the System menu appears
• Scroll to System info. Click
• Scroll to Disable Hotspot or Enable Hotspot. Click
• Wait for the network configuration to complete
• Long-press to return to the main screen

Updates can currently only be done via ssh:

ssh patch@patchbox.local

The pi-Stomp software changes frequently and you are generally encouraged to pull new updates.

Once connected via ssh, run:

cd pi-stomp
git pull
sudo systemctl restart jack

If your pi-Stomp display goes blank after this, it's possible that a recently added python library needs installing

sudo pip3 install pyalsaaudio

If that doesn't help run the following to see log output from the mod-ala-pi-stomp service

ps-journal 

Patchbox is the base operating system created by blokas.io. It doesn't change often and unless there is a specific problem, updates are generally not necessary or recommended.

When necessary, once connected via ssh, run:

patchbox update

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 /var/modep/pedalboards
sudo -u modep git pull
sudo systemctl restart jack

You can use git as revision control for your pedalboards. Because the pedalboard directory is owned by a user named “modep”, you'll need to preface all git commands with

sudo -u modep

A commit workflow might look something like:

cd /var/modep/pedalboards
sudo -u modep git add MY_PEDALBOARD
sudo -u modep 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 /var/modep/pedalboards
sudo -u modep git branch MY_BRANCH
sudo -u modep 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:

sudo -u modep git config user.name "MY NAME"
sudo -u modep 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 /var/modep/pedalboards
sudo -u modep git add MY_PEDALBOARD.pedalboard
sudo -u modep 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

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

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

sudo -u modep 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.