pi-Stomp Manual Building

Software Installation

pi-Stomp ships as a pre-built OS image. You point Raspberry Pi Imager at the pi-Stomp repository, pick the OS from the list, tell it your Wi-Fi details, and boot — there's nothing to download by hand, nothing to compile, and no packages to install.

What you need

Step 1 — Add the pi-Stomp repository

  1. Install Raspberry Pi Imager
  2. Open Raspberry Pi Imager.
  3. Click App Options → Content Repository → EDIT.

App Options menu open, Content Repository highlighted

  1. Click Use custom URL and enter (or copy/paste):
    https://treefallsound.github.io/pi-gen-pistomp/imager/pistomp.json

Content Repository dialog with the pistomp.json URL entered

  1. Click APPLY & RESTART. Imager restarts with the pi-Stomp catalog loaded.

  2. Now select the Device (typically Raspberry Pi 5 for pi-Stomp v3, Raspberry Pi 3 for pi-Stomp v2), then click NEXT

Step 2 — Flash the card

Choose OS list showing pi-Stomp OS with its icon

  1. Choose OS → select pi-Stomp OS from the list. Imager downloads the image itself and verifies the checksum — no separate download step.
  2. Choose Storage → select your microSD card.
  3. Click EDIT SETTINGS and fill in:
    • Wi-Fi network name, password, and country. The network name is case-sensitive.
    • Hostname — leave it as pistomp unless you have a reason to change it.
    • Username and password — these are the SSH login. You won't need SSH to play, but it's how you reach the device's filesystem later for things like enabling the expression pedal input.
    • Timezone.
    • SSH public key, if you'd rather log in with a key than a password.

Customization wizard with Wi-Fi and hostname fields

  1. Click Write.

The wizard writes an rpi-preseed.toml to the card's boot partition. On first boot, the rpi-preseed service applies it before any audio service starts.

When finished, eject the SD card.

Step 3 — Boot

Insert the microSD into the pi-Stomp's mainboard (inside the enclosure) and connect power. The boot splash appears on the LCD within a few seconds. First boot takes about a minute while the filesystem expands and services initialize, then the device reboots once on its own.

When the home screen appears, the pi-Stomp is on your Wi-Fi network.

Step 4 — Open the Pedalboard editor (MOD-UI)

Open a browser on any device on the same network and go to http://pistomp.local/. This is MOD-UI, where you build pedalboards.

MOD-UI comes from MOD Devices, who make their own Linux-based pedals. pi-Stomp runs their editor and their plugin host (mod-host) rather than reinventing them, with pi-Stomp's own software driving the LCD, encoders, and footswitches on top. That's why the web editor looks like a MOD product: it is one.

MOD-UI web interface

That address works through mDNS, a protocol that lets devices announce their own names on a local network with no router configuration. Not every network passes it through. If the name doesn't resolve, get the device's IP address from the LCD instead: highlight the wrench icon in the toolbar with the Navigation encoder, click it, choose System info, and read the address on the Wi-Fi: line. Browse to that address directly.

What's next

The pi-Stomp boots with a pedalboard already loaded, so it's ready to make sound as soon as you plug in. Quick Start covers connecting your instrument and setting input gain.

Pre-release images

To help test upcoming releases, use https://treefallsound.github.io/pi-gen-pistomp/imager/pistomp-testing.json as the repository URL instead. These builds can have (literal) show-stopper bugs; avoid taking them on stage.

Alternative Install method - Configuring with pistomp.conf

This is the fallback path for Raspberry Pi Imager below v2.0.11-rc1, and the way to set options the wizard doesn't expose, like the JACK audio settings.

Older Imager builds do have customization screens, but they write a format this image doesn't read — the v1.9.x line used a different engine entirely. On those versions the wizard appears to work and its settings are silently ignored, so skip it and use pistomp.conf instead.

  1. Download the latest .img.xz from pi-gen-pistomp releases (under "Assets").
  2. In Imager: Choose OS → Use custom → select the downloaded file.
  3. Choose Storage → select your microSD card → Write, skipping EDIT SETTINGS.

After flashing, the card's boot partition mounts as a small FAT volume named BOOTFS:

Platform Where to find it
macOS /Volumes/BOOTFS, and on the Finder sidebar under Locations
Windows A removable drive letter labelled BOOTFS in File Explorer
Linux Usually /media/<user>/BOOTFS; otherwise mount the card's first partition

Open pistomp.conf on that volume and edit:

Setting What to put Default
WIFI_SSID Your Wi-Fi network name ""
WIFI_PASSWORD Your Wi-Fi password ""
WIFI_COUNTRY Your country code (e.g. US, GB, DE, CA) US
HOSTNAME Leave as pistomp pistomp
USER_PASSWORD A password for SSH access pistomp
TIMEZONE Your timezone (e.g. America/Toronto, Europe/London) US/Central

Save the file, eject the card, and continue from Step 3.

The file also carries the JACK_* audio settings. Leave those alone for now; Performance explains when to change them.

If both rpi-preseed.toml and pistomp.conf are present, they don't conflict: the preseed wins for the keys it covers (Wi-Fi, hostname, password, timezone), and pistomp.conf still supplies everything else.

Troubleshooting