metronome/pico-cp/README.md

# PM_K‑1 "Kit" — CircuitPython edition (USB drive · push programming · MIDI audio · practice log)

The **CircuitPython** firmware for the 52Pi EP‑0172 Pico kit, set up as a self‑contained appliance.
It runs the same program‑string language as <https://metronome.varasys.io>. The simpler
**MicroPython** firmware (`../pico/main.py`) stays as a rock‑solid fallback — and the Pico can't be
bricked (BOOTSEL → drag a MicroPython `.uf2` back).

What it does: drives the 3.5″ touchscreen with a lanes/pads display + anti‑aliased text, plays the
buzzer + RGB beat light, **logs your practice to `/history.json`**, accepts new set lists **pushed
from the web editor over USB‑MIDI**, and plays through your **computer's speakers** over USB‑MIDI.

## Two power‑on modes (set by `boot.py`)

- **Appliance mode — default (just plug in / power up).** The *firmware* owns the filesystem, so it
  saves your practice log and writes set lists the editor pushes over USB‑MIDI. The drive is then
  **read‑only to the computer** — which also **protects the firmware from accidental deletion**.
- **Editor mode — hold BUTTON A while plugging in.** The drive is **writable by the computer**, so you
  can drag `programs.json` / `code.py` / fonts on from any OS or browser (the universal fallback).
  Reset afterwards to return to appliance mode.

## Install

1. **Flash CircuitPython:** hold **BOOTSEL**, plug in, drop the CircuitPython `.uf2` onto `RPI‑RP2`
   (<https://circuitpython.org/board/raspberry_pi_pico/> — Pico 2 / W builds also fine). A `CIRCUITPY`
   drive appears.
2. **Copy the whole bundle** onto `CIRCUITPY`: `boot.py`, `code.py` (loader) + `app.py` (the application),
   `programs.json`, `font_s.bin` / `font_m.bin` / `font_l.bin`, `editor.html` (offline editor), and the
   helper scripts. (`code.py` is a tiny stable loader; `app.py` is what firmware updates replace.)
3. **Power‑cycle** (so `boot.py` takes effect). It boots into appliance mode and runs.

## Program it from the web (push over USB‑MIDI)

In the editor (Chrome / Edge / **Firefox**), build a set list → set‑list **⋯** menu → **📟 Save to device**.
The editor sends it to the Pico over USB‑MIDI (SysEx); the firmware writes `/programs.json`, reloads, and
acknowledges — the editor shows **Saved ✓**. **📥 Load from device** reads it back.

*Universal fallback (any browser / OS, even Safari):* Save to device **downloads** `programs.json` when no
device answers — boot the Pico in **editor mode** (hold A) and drag the file onto the `CIRCUITPY` drive.

## Firmware updates (one‑click, A/B with auto‑rollback)

`code.py` is a small stable **loader**; the application is `app.py` (it carries `APP_VERSION`). To update:
the editor's ⋯ menu → **⬆ Update firmware…** queries the device's version, fetches the latest from the site,
shows *device vs latest*, and on confirm **pushes the new `app.py` over USB‑MIDI**. The device installs it to
a **trial slot** (keeping the old build as `app.bak`) and reboots; if the new build **doesn't boot, the loader
automatically rolls back** to `app.bak`. A build that runs cleanly for ~5 s is confirmed. No BOOTSEL, no
dragging. (Updating CircuitPython *itself* still uses BOOTSEL + a `.uf2`, but that's rare. And the Pico is
unbrickable as the ultimate backstop.)

## Play through the computer's speakers

The Pico is a USB‑MIDI device and sends a note per click (GM drum note per lane, velocity by accent).
In the editor click **🎹 Device audio**, grant MIDI access, and press play *on the device* — the editor
voices the groove through its full synth, out your speakers, locked to the device's clock. While a host is
listening the screen shows a green **MIDI** badge and the **buzzer auto‑mutes** (the computer plays instead).
The editor also syncs the device clock, so the practice log gets real wall‑clock timestamps.

## Controls & the practice log

- **Joystick:** up/down = tempo, left/right = previous/next groove.
- **Button A (GP15):** play / stop. **Button B (GP14):** tap tempo.
- **Touchscreen:** the bottom of the screen shows the **practice log** (time · BPM · duration · track) —
  newest first. Plays under 5 s aren't logged. **Tap a row to arm it (turns amber), tap again to delete.**
- **RGB LED** flashes the beat (amber accent / cyan normal / violet ghost); the **buzzer** clicks to match.
- The log is saved to `/history.json` (next to `programs.json`) in appliance mode and survives power‑cycles.

## programs.json

```json
{ "title": "PolyMeter",
  "programs": [ { "name": "Four on the floor", "prog": "t120;kick:4;snare:4=.x.x;hatClosed:4/2" } ] }
```

Each `prog` is a program string from the editor (tempo, lanes, patterns, `/2` subdivision, `/2s` swing,
`(3,8)` Euclid, `~` polymeter, `@-3` dB). The push above is the easy way to update it.

## Calibration (flags at the top of `code.py`)

- **Red/blue swapped:** flip `MADCTL` between `0x48` (default) and `0x40`.
- **Colours look negative:** toggle `INVERT_COLORS`.
- **Taps land wrong:** set `TOUCH_DEBUG = True`, read the raw coords over USB serial, then set
  `TOUCH_SWAP_XY` / `TOUCH_INVERT_X` / `TOUCH_INVERT_Y`.
- **Joystick reversed:** toggle `JOY_INVERT_X` / `JOY_INVERT_Y`.
- **Computer audio:** `MIDI_ENABLED` (default on); `MUTE_BUZZER` forces the buzzer off even standalone.
- **LED too bright/dim:** `LED_BRIGHTNESS` (0..1, default 0.15).
- **Screen tearing:** SPI panels have no tearing‑effect sync; `SPI_BAUD` (default 62.5 MHz) is pushed fast
  to minimise it — lower only if unstable.
- **Blank / garbled:** the panel lot may differ; drop `SPI_BAUD`, and if it's a 240×320 ILI9341 rather than
  the 320×480 ST7796, the init/size need changing (this targets the 320×480 you have).
- **RGB LED** uses the core `neopixel_write` (no library to install).

If `code.py` ever errors, CircuitPython prints the traceback **on the screen and over USB serial** — send
me that. The fonts are the baked anti‑aliased blobs from `../pico/gen_font.py`. `protect-firmware.sh` (hide
the firmware files) is mainly for editor mode — appliance mode already keeps the drive read‑only.