Getting Started

Prerequisites

• A pi-Stomp (v2 or v3) with the OS installed and network access
• SSH access to the device
• Git and Python 3.11+ on your development machine (pi-stomp sets requires-python = ">=3.11"; pistomp-recovery needs 3.12)
• uv for Python package management

Clone the repo

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

Development workflow

Most developers find it easiest to code in-place by SSHing to the pi-Stomp and editing files directly.

Connect to the device

ssh pistomp@pistomp.local

Stop the service

The mod-ala-pi-stomp service runs the pi-Stomp software. Stop it so your code doesn't conflict:

ps-stop

Run your code

ps-run

Stop with Ctrl-C.

ps-run takes no arguments. It execs the app with a fixed command line and no "$@", so ps-run -l debug runs at the default log level and discards the flag without complaining. To set a log level, invoke the app directly:

sudo /opt/pistomp/venvs/pi-stomp/bin/python /home/pistomp/pi-stomp/modalapistomp.py -l debug

Watch the logs

ps-journal follows the service journal, and unlike ps-run it does pass arguments through to journalctl:

ps-journal                # follow (-f)
ps-journal -n 100         # last 100 lines
ps-journal -b             # this boot only

Restart the service

When you're done with iterative edits:

ps-restart

Deploy local changes

From your development machine, use deploy.sh to copy files to the device:

./deploy.sh

Or copy individual files via SCP:

scp modalapi/*.py pistomp@pistomp.local:/home/pistomp/pi-stomp/modalapi/
ssh pistomp@pistomp.local "ps-restart"

Dev mode: git-managed source on the device

The packaged install ships a .git-meta/ folder recording the origin URL, branch, and the exact commit the .deb was built from. If you edit source directly on the device and want real git, "expand" the tree into a repo:

~/pi-stomp/util/expand-git.sh

This reads .git-meta/, runs git init, fetches full history and tags from the recorded origin, then points HEAD at the packaged commit with git reset --mixed. That never touches the working tree — your files stay exactly as dpkg unpacked them, so nothing on disk changes. It's idempotent: re-running on an already-expanded tree no-ops. When it finishes, the tree is a normal clone and git describe --dirty='*' prints something like v3.0.4-224-gab12cd3.

Two things change once the tree is expanded (both keyed off the .git/EXPANDED marker the script writes):

In recovery, a blocked update shows the pi-stomp row in red with "Cannot update pi-stomp: using git. Run util/contract-git.sh to re-enable updates." Only pi-stomp is blocked — every other package still updates.

This is the point of dev mode: you own the source, so OTA opts out. When you're done and want OTA updates back:

~/pi-stomp/util/contract-git.sh

This removes .git entirely and leaves the files untouched (still whatever dpkg last unpacked), so the tree reads as packaged again and apt upgrade pi-stomp works. There is no packaged commit to fall back to, so contracting discards any fetched history and local commits — push a branch to your own remote first if you want to keep work. Re-run expand-git.sh from scratch to get git back later.

Running tests

uv run pytest                    # all tests
uv run pytest --snapshot-update  # accept changed LCD snapshots
uv run pytest --cov=pistomp --cov=modalapi --cov=common --cov=uilib --cov-report=term-missing

Running the emulator

The emulator lets you develop and test the LCD UI on your desktop without a pi-Stomp:

./run_emulator.sh [v2|v3]

Requires MOD Desktop. Default is v3, and anything other than v2 or v3 silently becomes v3 rather than erroring — so a typo runs the wrong hardware profile without telling you.

Emulator controls: