# Firmware plan

Nothing here yet. This is the plan for porting the simulator to the Pico 2 W in C with the Pico SDK.

## Rule one: the engine must match the vectors

`sim/engine.js` is the reference. The C engine is done when it reproduces every file in `test/vectors/` bit for bit:

1. **primitives.json**: `mix()`, the xorshift32 `Rng` (`next`, `below`, `chance`) and `genome()`.
2. **gen0 … gen4 \*.json**: full renders, 8 bars per case, 189 cases. Each case has a checksum (FNV-1a over the rows), so a failure shows up at once. The first differing bar tells you where to look.

Build and test the engine **on the host first**: plain C, no SDK, a test runner that reads the JSON (or a header generated from it). Only then put it on the Pico. If the music needs to change, change `engine.js`, listen in the simulator, regenerate the vectors (`npm run vectors`), and commit both together.

### JS → C traps

- **Integers**:
  - Every hash and RNG value is `uint32_t`.
  - `Math.imul(a,b)>>>0` is `(uint32_t)a*(uint32_t)b`.
  - `x>>>n` is a logical shift on `uint32_t`.
- **`fdiv` and `mod`** are floor division and a positive modulo. C's `/` and `%` truncate toward zero, so write `fdiv`/`mod` helpers that handle negatives.
- **`>>` on negative numbers**: JS shifts arithmetically, for example `(e-64)>>2`. Use `fdiv(x,4)` or make sure the compiler does an arithmetic shift (GCC on ARM does).
- **`%` in JS** truncates like C. It only matches `mod()` when the left side is non-negative.
- **`Math.floor(a*b/c)`** with non-negative ints is plain integer division.
- **Sorting**:
  - `Array.prototype.sort` is stable (ES2019), and the engine relies on it: events that tie on the sort keys keep their insertion order.
  - Use a stable sort, such as insertion sort on small arrays.
  - Sort keys: `renderBar` uses (t, track, voice), and AMEN humanising uses (t, voice).
- **No allocation in the audio path.** Fix the maximum events per bar and use static arrays. The vectors peak at 54 events in a bar (automata, energy 127); size buffers for 128.
- **`genome` has a `formName` string.** It's only for display. `describe()` is display only and doesn't need porting exactly.

## Structure (suggested)

```
firmware/
  engine/      engine.c/.h        portable, no SDK, the only thing the vectors test
  test/        host test runner   gcc, reads test/vectors
  app/         main.c             core 0: UI, screen, inputs; core 1: scheduler + MIDI out
  drivers/     midi_uart.c  pcd8544.c  matrix.c  encoder.c  pots.c
  CMakeLists.txt
```

## Runtime

- **Two cores.**
  - Core 1 owns time: it renders a bar ahead into a double buffer and sends MIDI from a hardware timer.
    - 840 ticks per quarter.
    - Clock (0xF8) every 35 ticks.
    - Start (0xFA) and stop (0xFC) on RUN.
  - Core 0 runs the UI and hands parameter changes over through a small queue or atomics.
- **MIDI out**: UART0 TX on GP0 (OUT KIT) and UART1 TX on GP4 (OUT SYNTH), both at 31 250 baud. Running status is optional.
- **MIDI in**: UART0 RX on GP1, only used by LEARN. A note-on stores {channel, note}.
- **Track gating** matches app.js:
  - Every event is rendered.
  - Muted tracks skip their note-ons, but note-offs still go out.
  - Unlearned kit tracks are skipped.
  - A held button flips the track while held.
  - Optional: changes wait for the bar line.
- **Stop** sends note-offs for everything sounding, CC 120 on each kit channel in use, and CC 120 and 123 on the synth channel.
- **Storage**: keep slots, learned pads, BPM, generator, MIDI channel and octave in the last flash sector. Write only on change, debounced.

## Drivers

- **PCD8544** (Nokia 5110):
  - SPI0 (SCK GP18, MOSI GP19, CE GP17), with DC on GP20 and RST on GP21.
  - Up to 4 MHz.
  - The 84 × 48 framebuffer is 504 bytes.
  - The screen layout and the 5 × 7 font are in app.js (`screenText`, `drawMap`, `FONT`).
  - Contrast (Vop) varies between modules, so make it a setting.
- **Matrix**:
  - Rows GP2, GP3, GP5 are inputs with pull-ups.
  - Columns GP6–GP9 are driven low one at a time and Hi-Z otherwise, with the input buffer off or a pull-up on (E9).
  - Scan at about 1 kHz with a 5–10 ms debounce.
  - Key map (row, col) → track: (1,1) KICK, (1,2) KICK 2, (1,3) SNARE, (1,4) none; (2,1) HAT, (2,2) HAT 16, (2,3) PERC, (2,4) GHOST; (3,1) BASS, (3,2) MEL A, (3,3) MEL B, (3,4) PAD. Same as `PANEL` in app.js, which also orders the screen map.
  - No FILL button: always pass `fill = false` to the engine (bar-4 fills still happen on their own).
- **Encoder**: GP10/GP11 quadrature with a state-table decoder; push on GP12. Long push (about 600 ms) is the SLOT save.
- **Pots**: ADC0/ADC1 (GP26/GP27). Average, then 7-bit with hysteresis so the values don't flicker.
- **SEED** (GP13) and **RUN** (GP14): inputs with pull-ups, debounced.

## Pico notes

- RP2350 erratum E9: use pull-ups, not pull-downs, on inputs. The whole design is active-low.
- `gpio_set_drive_strength(0, GPIO_DRIVE_STRENGTH_12MA)`, and the same for pin 4. Each MIDI loop draws about 6–8 mA.
- The W's wireless chip isn't used in v0.1.
- BOOTSEL can't be reached with the box closed. Keep the SDK's USB reset interface in the build (`pico_enable_stdio_usb`), so `picotool reboot -f -u` drops the board into the bootloader for flashing.
- Matrix columns that aren't being driven: input buffer off or pull-up on (E9).

## Order of work

1. Port the engine on the host until `test/vectors` pass.
2. Bring up the board with a blink and the UARTs: send a test note to each device.
3. Screen driver and font.
4. Inputs: matrix, encoder, pots, SEED, RUN.
5. Scheduler on core 1, running the ported engine. Compare it by ear with the simulator on the same seed.
6. Pages, LEARN, slots, flash storage.