Skip to content

DEV_HELPERS.md

Latest commit

 

History

History
129 lines (87 loc) · 3.48 KB

DEV_HELPERS.md

File metadata and controls

129 lines (87 loc) · 3.48 KB

Development Helper Scripts

Portable setup and deployment scripts for Raspberry Pi. For ease of development, most of this was edited on a Raspberry Pi 5 desktop environment (vscode) and tested locally, but the finishing touches had to be done on the pi zero, so these scripts were born.

Setup Scripts

install_pi.sh

Location: Project root
Runs on: Dev Raspberry Pi with display/speaker installed.
Purpose: Guided install for apt deps, venv, Python packages, and optional systemd service

./install_pi.sh
./install_pi.sh --with-service
./install_pi.sh --no-service

What it does:

  1. Installs apt packages from requirements/pi-apt.txt
  2. Creates .venv with --system-site-packages
  3. Installs requirements.txt
  4. Runs runtime verification
  5. Optionally installs and enables notemachine.service

For service installs, runtime module/arguments are configured in /etc/default/notemachine.

scripts/pi/bootstrap_pi.sh

Location: scripts/pi/
Runs on: Raspberry Pi
Purpose: Sets up Python virtual environment and installs dependencies

IMPORTANT: Install system packages first:

sudo apt install python3-aubio python3-numpy python3-pil python3-dev portaudio19-dev

Then run bootstrap:

./scripts/pi/bootstrap_pi.sh

What it does:

  1. Creates .venv with --system-site-packages (required for Pi apt packages)
  2. Upgrades pip, wheel, and setuptools
  3. Installs remaining dependencies from requirements.txt

Why --system-site-packages? On Raspberry Pi, especially Pi Zero 2 W, pip builds of aubio/numpy often fail or are very slow. Using apt packages with --system-site-packages venv is the reliable approach.

scripts/pi/install_whisplay_driver.sh

Location: scripts/pi/
Runs on: Raspberry Pi
Purpose: Installs Whisplay HAT driver (LCD, audio codec, RGB LED support)

bash scripts/pi/install_whisplay_driver.sh

Requires reboot after install. This may be expanded to support other hardware (there's a Pimoroni Pirate Radio display hat over here) but for now Whisplay only.

scripts/pi/refresh_service.sh

Location: scripts/pi/
Runs on: Raspberry Pi
Purpose: Re-renders and installs systemd service from template

bash scripts/pi/refresh_service.sh
bash scripts/pi/refresh_service.sh --no-restart

Updates service definition and optionally restarts it.

scripts/pi/verify_runtime.py

Location: scripts/pi/
Runs on: Raspberry Pi
Purpose: Validates Python dependencies and runtime environment

python scripts/pi/verify_runtime.py

Development/Testing Scripts

scripts/dev/looptest.py

Test pitch detection accuracy by playing a tone and immediately listening for it. Do not operate with partner/spouse/roommates/coworkers nearby unless they are very patient.

python scripts/dev/looptest.py --labels "C4,D4,E4,F4,G4,A4"

scripts/dev/wind_tuner.py

Sweep chromatic range to test detection reliability:

python scripts/dev/wind_tuner.py

Configuration

Unified app config

Use notemachine.toml.example as your base.

Runtime apps (notemachine.notemachine, notemachine.tonewatch) load config from:

  1. --config /path/to/notemachine.toml
  2. NOTEMACHINE_CONFIG=/path/to/notemachine.toml
  3. ./notemachine.toml
  4. ~/.config/notemachine/notemachine.toml
  5. /etc/notemachine.toml

Service installs use /etc/notemachine.toml and /etc/default/notemachine.