pi-Stomp Developers Guide

• Main entry point that initializes the system
• Event loop with polling:
  1. Every cycle (10ms): `poll_controls()` — hardware inputs
  2. Every 2 cycles: `poll_indicators()` — LEDs/VU meters
  3. Every 20 cycles: `poll_lcd_updates()` — LCD refresh
  4. Every 100 cycles: `poll_modui_changes()` — UI sync
  5. Every 200 cycles: `poll_wifi()` — WiFi status
  6. Every 60 seconds: `poll_system_info()` — system state

• Base Handler (`pistomp/handler.py`): Abstract interface defining hardware interaction methods
• Modhandler (`modalapi/modhandler.py`): Primary implementation that:
  1. Manages pedalboards, presets, and plugins
  2. Communicates with mod-host via HTTP REST API
  3. Manages WiFi, system state, and LCD updates
  4. Uses a `Current` class to track active pedalboard state
• Mod (`modalapi/mod.py`): Legacy handler for v1 hardware

• Hardware Base Class (`pistomp/hardware.py`): Abstract base for hardware variants
• Hardware Variants:
  1. `pistomp.py` — v1 hardware (3 footswitches, 1 pot, 1 expression pedal, 2 encoders)
  2. `pistompcore.py` — v2 hardware
  3. `pistomptre.py` — v3 hardware
• Hardware Components:
  1. Footswitches: GPIO-based with LED feedback, tap tempo support
  2. Encoders: Rotary encoders with push switches
  3. Analog Controls: Potentiometers and expression pedals via SPI ADC (MCP3008)
  4. Relays: For bypass switching
  5. LED Strips: Visual feedback
  6. LCD: Various displays (320×240, 128×64, 135×240) via SPI (lcd320x240.py is the implementation used for v2 and v3 hardware)

• HandlerFactory (`pistomp/handlerfactory.py`): Creates appropriate handler based on config version
• HardwareFactory (`pistomp/hardwarefactory.py`): Creates hardware objects based on config version
• AudiocardFactory (`pistomp/audiocardfactory.py`): Manages audio card configuration

• Pedalboard (`pedalboard.py`): Manages pedalboard state using Lilv (LV2 plugin discovery)
• Plugin (`plugin.py`): Represents individual LV2 effects
• Parameter (`parameter.py`): Handles plugin parameter control
• WiFi (`wifi.py`): WiFi management for web UI access

• Widget-based UI for LCD displays
• Components: panels, dialogs, menus, footswitch displays, icons, text
• Supports different LCD resolutions and color depths
• Panel stack layout allows overlays, dialogs, etc.

• YAML-based configuration (`data/config/`)
• Hardware descriptor JSON files
• Supports default + user + pedalboard-specific overrides
• Defines MIDI mappings, footswitch functions, encoder behaviors

• MIDI Output: Sends CC messages to mod-host for parameter control
• Supports omni mode (all channels)

• Uses JACK audio server (mod-host)
• Audio card abstraction for different hardware (HiFiBerry, AudioInjector, IQAudio)
• Audio card factory manages configuration and restoration

1. Factory Pattern: For creating handlers and hardware objects
2. Singleton Pattern: Handlers and factories are singletons
3. Abstract Base Classes: Handler and Hardware provide interfaces
4. Polling Architecture: Event-driven via polling rather than interrupts

1. Hardware inputs (footswitches, encoders, pots) → Hardware layer polls
2. Hardware events → Handler callbacks
3. Handler → MIDI CC messages to mod-host OR direct HTTP API calls
4. mod-host → Processes audio through LV2 plugins
5. Handler → Monitors mod-host state via HTTP API
6. Handler → Updates LCD display via UI library

This architecture separates hardware abstraction, audio processing (MOD), and UI management, making it extensible for different hardware variants while maintaining a consistent interface.

Most developers will find it easiest to code in-place by ssh'ing to the pi-Stomp

 ssh pistomp@pistomp.local

To do live code changes, you'll need to stop the modalapistomp service so it doesn't conflict:

 ps-stop

Then you can start the main python via:

 ps-run

Or with optional logging:

 ps-run -l info
 ps-run -l debug

Stop python:

 <ctrl>C

When you're done with iterative edits, restart the service with:

 ps-restart
 

Clone the repo

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

• All code changes must go through PRs — no direct pushes
• PRs must be approved by the maintainer before merging
• Please follow project coding style and conventions

1. Fork the repo

On GitHub, click the “Fork” button (top right of the project page). This creates a copy under your own GitHub account.

2. Clone your fork locally

Replace <your-username> with your GitHub username:

 git clone -b pistomp-v3 https://github.com/<your-username>/pi-stomp.git
 cd pi-stomp

3. Add the original repo as a remote (called “upstream”)

This keeps your fork in sync with the original repo.

 git remote add upstream https://github.com/TreeFallSound/pi-stomp.git

4. Create a new branch for your work

Don't work directly on the main pistomp-v3 branch. Instead create a new one, name it bugXYZ, featureABC, etc.

 git checkout -b <branch-name>

5. Make changes and commit

Edit files, then:

 git add .
 git commit -m "Add feature: ABC"

6. Push your branch to your fork

 git push origin <branch-name>

7. Open a Pull Request (PR)

Go to your fork on GitHub, and you’ll see a prompt to open a Pull Request.

Choose pistomp-v3 as target branch

Describe your change

Submit PR

8. (Optional) Keep your fork up to date

If the main repo changes before your PR is merged:

 git fetch upstream
 git checkout pistomp-v3
 git merge upstream/pistomp-v3
 git push origin pistomp-v3
 

Then rebase or merge those updates into your feature branch:

 git checkout <branch-name>
 git rebase pistomp-v3
 git push -f origin <branch-name>