product-vamp/SETUP.md

Product Vamp Device Setup

Raspberry Pi Zero 2 W

Flash Raspberry Pi OS Lite 64-bit, enable SSH, and boot the device.

Install the package tarball from Gitea or build one locally:

python3 modulus.py package

Copy the tarball to the Zero, verify its .sha256, unpack it anywhere, and run:

sudo zero/install_zero.sh

The installer loads and probes zero/product_vamp_zero_linux_arm64.docker.tar, replaces Product Vamp configuration with the bundle defaults in /etc/product_vamp/vamp.json, recreates the control Wi-Fi profile, and enables the systemd units. Every installation resets Product Vamp data and settings; there is no automatic backup or migration. Use a local console or independent network connection because replacing the control Wi-Fi profile can disconnect the session.

Project-owned install paths, services, executables, and archives use underscores. The checkout and Git URL remain product-vamp. On upgrades, the installer validates and probes the incoming image before removing the old hyphenated Product Vamp paths, services, and network profile. Unrelated services, networks, and data are preserved; symlinked installation paths are rejected.

On reinstalls, the installer skips apt entirely when the required OS packages are already present. If packages are missing, the Zero needs upstream internet before the installer can finish provisioning Docker, NetworkManager, and SQLite.

Product Vamp owns tty1 while the display service is running so the DISP-7A shows the appliance UI instead of the Raspberry Pi OS Lite login console. Use SSH for normal administration. tty2 is enabled as the local fallback console.

Defaults:

• SSID: Vamp Control
• Passphrase: vamp-control
• Zero IP: 192.168.42.1
• API: http://192.168.42.1:8080

To run the service without its display, set runtime.headless to true; audio is controlled separately by audio.enabled. For a readiness check that validates configuration, catalog, page/audio assets, runtime writes, and server binding without opening hardware, run python3 modulus.py run from the configured development checkout. This invokes vamp_zero --once with the development configuration and exits after the checks. On an installed Zero, probe the running service with:

sudo docker exec product_vamp_zero /usr/bin/vamp_zero --config /etc/product_vamp/vamp.json --health-check

Score inputs are tracked under data/songs/. The build/package step generates acoustic, electric, and vocal parts, engraved pages, supplied WAV recordings, and the read-only catalog database. Installation replaces these assets together; no database migration or runtime score import is needed.

Raspberry Pi Pico 2 W

Hold BOOTSEL while plugging the Pico into USB, then copy:

pico/product_vamp_pico2w.uf2

to the mounted RPI-RP2 drive.

The default firmware connects to SSID Vamp Control with passphrase vamp-control, then talks to 192.168.42.1:8080.

The Pico screen is landscape and uses the shared dark theme. The header's connection indicator is green when connected, amber while connecting or offline, and red on a Wi-Fi initialization error; status text distinguishes connecting, offline, error, and busy states. The body shows the focused menu item, song title, or setting and its value. In score view it shows the title, selected part, performance phase, BPM, page count, and hold-to-exit hint. The palette and Petaluma Script lettering match the engraved sheet music.

Controls:

• Tap: next menu item, or next page when both audio toggles are off.
• Double tap: previous menu item, or previous page when both audio toggles are off.
• Tap and hold: select the highlighted menu row, enter/leave tempo editing, or return from score view to the part menu. While editing tempo, tap increases BPM and double tap decreases it.

Settings has independent Metronome and Backing toggles. Either starts automatic playback when a part opens; both off enables manual reading. Backing plays the recorded count-in and held ending. Metronome clicks accompany the score but stop before the three-bar held tail. Hold exits at any time.

Keep the two metronome samples under package/assets/sounds/. Put song recordings under package/assets/backing/, named <normalized_song_id>_<bpm>.wav. Supply separate files at 60, 70, 80, 90, 100, 110 and 120 BPM, each with one bar of count-in, the complete eight-bar intro plus five body passes, and its held ending. Rebuild/package after adding recordings. Backing tempo choices include only tempos supplied for every song; the current package has 120 BPM for both songs.