metronome/docs/rust-port.md

Rust port — staged plan

This is the plan for the native-Rust direction first discussed alongside the A/B-bootloader idea. What changed since then: the track format is now formally specced (docs/track-format.md) with a golden-vector conformance suite (tests/run.mjs). That suite is the thing that makes a port safe — any Rust engine has a precise, executable definition of "correct" to validate against, the same one engine.js and app.py already pass.

The core idea

Port from the inside out, lowest-risk first. The pure logic (track codec, then the scheduler) is host-testable with zero hardware and is gated by the existing golden vectors. Only once that's proven do we touch drivers, A/B, and the actual firmware. We do not rip out CircuitPython until the Rust engine passes the vectors and the drivers are proven on hardware.

Architecture: one firmware core, modular drivers per form factor

Trying many form factors (Kit, Explorer, Grid/Scroll Pack, …) is how we discover the line between core and driver. In Rust that line is enforced by the type system instead of copied by hand — today each CircuitPython form factor is its own ~1,500-line app.py clone; the Rust build is one core crate plus a thin per-board binary.

pm-core — the core (no_std, zero hardware):

• the track-format codec (rust/track-format, Stage 1) and the scheduler/clock (Stage 2, already no_std and building for RP2350),
• playback-flow (rep/end/continue, segment seams), app state, set-list model,
• the USB-MIDI / live-sync / firmware-update protocol logic (the SysEx opcode handling, which is form-factor-independent). It is host-testable and gated by the golden vectors — the same suite engine.js and app.py pass. This is "core."

Driver traits — what the core is generic over (the swappable part): define small project traits — Display (or render straight to an embedded-graphics DrawTarget), Inputs (yields button / touch events), Clicker (audio out), Indicator (RGB) — and write each concrete driver against embedded-hal bus traits (I2c, SpiBus, OutputPin, DelayNs). The core's UI code then doesn't care whether the target is a 17×7 mono matrix or a 320×480 colour TFT.

Per-board binary crates — pm-kit, pm-explorer, pm-grid: a thin main.rs BSP that instantiates the right concrete drivers and hands them to the generic core:

• Grid (Scroll Pack): IS31FL3731 over I²C (a DrawTarget for a 17×7 mono frame) + 4 GPIO buttons.
• Explorer / Kit: ST7789 via mipidsi + embedded-graphics; GT911 touch (Kit) over I²C; WS2812 via ws2812-pio; I²S to the PCM5102A via PIO.

The honest caveat (what the Grid prototype is teaching us): a 17×7 mono grid and a 320×480 touch TFT are too different for one pixel-identical UI. So the clean split is core engine + protocol + state = fully shared; the view = per-display-class. The Grid is the most extreme, minimal display in the lineup, which makes it the best forcing-function for finding exactly where that boundary falls before we commit drivers to Rust. The CircuitPython pico-scroll/ build exists to nail that UI down on real hardware first.

Stages

Stage 0 — toolchain in a container

Add a Rust toolchain image (mirroring hardware/eda/): a Containerfile with rustup, the thumbv8m.main-none-eabihf target (RP2350 is Cortex-M33), flip-link, probe-rs, elf2uf2. Driven by a run.sh like the EDA one. Never on the host.

Stage 1 — track-format crate ✅ DONE (rust/track-format/)

Implemented and passing: ./rust/run.sh builds the container and runs cargo test, which validates the crate against tests/fixtures/track-format.json (conformance + idempotency). The Rust codec agrees with engine.js and app.py on every vector — and carries vol/cd, so it's the most spec-complete of the three. Original scope below.

(original) Stage 1 — track-format crate ← the concrete first PR

A pure, no_std-compatible crate: parse(&str) -> Track and serialize(&Track) -> String, plus a normalize() that emits the neutral structure from docs/track-format.md §5. Then a cargo test that reads tests/fixtures/track-format.json and asserts each case's norm and round-trip — i.e. a third adapter alongside js_adapter.mjs / py_adapter.py. When this is green, the Rust engine provably agrees with web + device on every groove, euclid, swing, ghost, polymeter, and the playback-flow tokens. No hardware, fully testable in the container.

This is the highest-value slice: small, gated by work already done, and it proves the toolchain.

Stage 2 — scheduler/engine ✅ DONE (rust/track-format/src/schedule.rs)

Ported the look-ahead step scheduler (the durs math from app.py tick/_prepare_next). render(track, bars) produces the deterministic click timeline; tests/schedule.rs asserts the timings — quarter-note spacing, subdivisions, swing 2/3:1/3, polymeter 5:4, accents/ghosts, mute, multi-bar looping. All green on the host, no hardware. The real-time firmware loop will just play this timeline against the wall clock.

Also done: the crate is now #![no_std] + alloc and builds for the RP2350 target (cargo build --lib --target thumbv8m.main-none-eabihf) — the codec + scheduler are firmware-ready.

Stage 3 — drivers (hardware) 🔧 IN PROGRESS (rust/pm-kit/)

✅ Milestone 1 (boot) — confirmed on Pico 2: GP25 blink. Toolchain + RP2350 boot block + flash work. ✅ Milestone 2 (display) — confirmed on Pico 2: ST7796 320×480 over SPI0 via rp235x-hal + mipidsi + embedded-graphics, drawing the shared pm-ui. Key fix: hold CS low for the whole session (NoCs) — mipidsi toggles CS mid-command and the ST7796 needs it continuous (see rust-st7796-cs-gotcha). Diagnosed off-bench with host tools in rust/uisim: uisim renders pm-ui to PNG; --bin panelsim decodes mipidsi's real command/pixel stream into a PNG (proved the protocol correct → bug was physical); --bin initdump dumps the init + CASET/RASET sequence.

🟡 Milestone 3 (live metronome) — built, pending on-device check: the firmware is now an actual metronome. embedded-alloc heap → parses tracks with track-format on-device; 4 built-in grooves; Timer-driven clock; audio clicks on the master lane's hits (GP13 PWM, short edge-triggered pulses, accent louder); controls — A = play/stop, B = grid/notation view, joystick (rotated 90° CCW) up/down = tempo, left/right = groove. Renders pm-ui::draw_metronome / draw_notation, with a cheap draw_progress strip animating the bar position every frame (full redraw only on change → no flicker). All loop input reads use unwrap_or (no panics) — addresses the self-test crash. Compile + simulator verified; needs a flash to confirm audio timing, joystick directions, no crash.

pm-ui views (sim-verified, PNGs): metronome grid (accents/ghosts/polymeter), and drum notation (5-line staff, time sig, hands stem-up / feet stem-down, shared stems, beamed eighths, ledger lines).

Still to do: GT911 touch (GP8/9), WS2812 RGB (GP12), USB-MIDI, set-lists from programs.json, per-cell live playhead, the rest of the practice features. Then split pm-core out as its own crate and add pm-explorer/pm-grid binaries. HAL stays rp235x-hal (embassy later if async earns it).

On embassy / rp-hal:

• ST7789 240×320 display → mipidsi + embedded-graphics (mature; the parts are well-supported).
• I²S to the PCM5102A → RP2350 PIO.
• WS2812 → ws2812-pio. USB-MIDI → usbd-midi / embassy-usb.
• GT911 touch (Kit) over I²C.

Stage 4 — native A/B + secure boot

Replace the .mpy-level A/B hack (code.py loads app.mpy, rolls back to app.bak) with the RP2350 bootrom's native partition-table A/B + signed boot, configured via picotool (the chip already provides this — see the earlier hardware discussion). The Rust app is the image in the slot; rollback and version selection move into silicon.

What you keep / lose

• Gain: memory safety, native A/B + secure boot, performance headroom, one typed model instead of three hand-written parsers.
• Lose: the live one-click .mpy push (Rust is compile→flash→reboot). The editor's data live-sync (tempo/pattern/setlist mirroring) still works — it's a data protocol. Only live logic edits go away, and an embedded wasm3/script module could buy those back if wanted.

Acceptance gate

Every codec/engine change must pass tests/fixtures/track-format.json. The Rust crate joins js/py as a runner adapter, so "same groove on web, device, and the Rust build" is enforced, not hoped for.

Recommendation

Do Stage 1 in a container next — it's small, testable today (given a toolchain), reuses the suite, and produces a real artifact to judge the Rust path on before committing to drivers or a firmware rewrite. Defer Stages 3–4 until Stage 1–2 are green and you've decided the live-push tradeoff is acceptable.