Seedbox v0.1 + firmware, generic kit/synth, ROOT/SCALE pages

First commit of the repo. Contents beyond the v0.1 simulator and layout:

- Full Pico 2 W firmware (firmware/app, drivers, engine port, host test).
- BANK page and 404 mode A/B removed; learned pads play exactly what was learned.
- 404/MiniFreak renamed to KIT/SYNTH throughout (jacks, code, sim, docs,
  layout labels; wiring rebuilt).
- ROLL returns to page select after a re-roll; a freshly learned track turns on.
- LCD contrast 66.
- ROOT and SCALE pages: 21 scales, AUTO = the seed picks; global and sticky.

Intended music change: the scale table grew from 8 to 21 and AUTO picks from
all of them, so every seed's scale changed. Vectors regenerated with
npm run vectors, plus new key-override cases. Flash record is now version 2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/hardware/README.md

@@ -0,0 +1,39 @@
+# Hardware
+
+| File | What |
+|---|---|
+| [bom.csv](bom.csv) | parts list with status (have / check / buy / optional); interactive version: `tools/bom.html` |
+| [pinout.md](pinout.md) | every Pico pin used, and why |
+| [wiring.md](wiring.md) | stripboard, cuts, links, off-board wires, panel wiring, build order |
+| [panel.md](panel.md) | panel layout and drill list |
+| [board-parts.csv](board-parts.csv), [wire-list.csv](wire-list.csv), [drill-list.csv](drill-list.csv), [cuts.txt](cuts.txt) | the tables, exported from the tools |
+| [svg/](svg/) | the drawings, exported from the tools |
+
+The source of truth for the stripboard is [`hardware/layout.js`](../../hardware/layout.js). Everything in this folder that describes the board is generated from it. After changing it:
+
+```sh
+node hardware/check-layout.js     # geometry, footprints, circuit rules
+node tools/build-wiring.js        # rebuilds tools/wiring.html
+```
+
+To refresh the SVGs and CSVs, open `tools/wiring.html` and `tools/panel.html` in a browser and save from there (or script it with jsdom, as the first export did).
+
+## Build constraints this design assumes
+
+- One stripboard carries the Pico (socketed in two female headers) and the MIDI circuits.
+- Everything else is panel mounted and wired with hookup wire, in 5 colours.
+- No standoffs, screws or USB extension. The board is held with foam tape or hot glue, and its USB port lines up with a slot in the box wall.
+- The Nokia 5110 module sits on top of the box. Its wires go through a hole under the header.
+- The enclosure is plastic, about 80 × 150 × 40 mm, laid out landscape.
+- The MIDI jacks are 3.5 mm TRS, Type A.
+- The Pico's USB end sits at the board edge. Its USB port powers the box and flashes the firmware through a slot in the back wall.
+
+## Verified, and not
+
+- **Checked**:
+  - `check-layout.js` covers the netlist against the pin map and the MIDI 3.3 V circuit, plus shorts, cuts and footprints.
+  - Two blind reviews by agents with no access to the design reasoning. Every finding was fixed; see [decisions](../decisions.md#process).
+- **Not checkable from here**:
+  - Lug order on your TRS jacks: find tip, ring and sleeve with the meter and a plug inserted.
+  - RP2350 pin functions: confirm against the Pico 2 W datasheet when writing the firmware.
+  - Nokia BL polarity: the wiring doc says how to test it.

docs/hardware/board-parts.csv

@@ -0,0 +1,20 @@
+part,value,holes,note
+"Pico 2W","2 × 20-pin female header","A13–T13 and A20–T20 (pins 1–20 down the left, 40–21 down the right)","USB end flush with the top edge of the board, past strip A"
+"U1","6N137","U5–X5, U8–X8","6N137 in a DIP-8 socket. Notch toward strip U, pin 1 at hole U5. Pin 7 (enable) is tied to pin 8 by the U10–V10 link."
+"R1","220 Ω","V2 – Y2","MIDI IN current limit. 3-hole span: stand it upright, or use a small ⅛ W part flat. If learning ever misses notes, use 150 Ω."
+"D1","1N4148","V4 – W4","Band (cathode) on V4, the opto LED anode side. Stands upright (1-hole span)."
+"R2","1 kΩ","W10 – AB10","Opto output pull-up to 3.3 V"
+"C1","100 nF","U11 – X11","6N137 supply bypass, right beside the chip: U11 is its 5 V (pin 8) strip, X11 its GND (pin 5) strip. Required. Fit it after the beep test."
+"R4","10 Ω","X21 – X25","MIDI OUT KIT, TX line (RC). Lies flat along strip X, across the cut at X23 (4-hole span, ¼ W fits). SEED hangs right above it."
+"R5","33 Ω ½ W","V19 – AB19","MIDI OUT KIT, 3.3 V line (RA). ½ W: a mono plug in the jack shorts it to ground."
+"R6","10 Ω","U28 – Y28","MIDI OUT SYNTH, TX line (RC)"
+"R7","33 Ω ½ W","V30 – AB30","MIDI OUT SYNTH, 3.3 V line (RA). ½ W, same reason as R5."
+"Link","wire","A34 – Z34","5 V (VBUS) to the 5 V strip"
+"Link","wire","E32 – AB32","3V3 to the 3V3 strip"
+"Link","wire","R33 – AA33","GND to the GND strip"
+"Link","wire","U13 – Z13","opto VCC to 5 V"
+"Link","wire","U10 – V10","opto enable (pin 7) to VCC (pin 8): the 6N137 output only works with pin 7 high"
+"Link","wire","X12 – AA12","opto GND to GND"
+"Link","wire","W9 – B9","opto out to GP1 (MIDI RX), strip B"
+"Link","wire","A15 – X15","GP0 (TX KIT) to strip X (R4), straight down under the Pico between its headers"
+"Link","wire","F14 – Y14","GP4 (TX SYNTH) to strip Y (R6), straight down under the Pico between its headers"

docs/hardware/bom.csv

@@ -0,0 +1,26 @@
+group,id,part,spec,qty,status,notes
+"Core","pico","Raspberry Pi Pico 2W","RP2350, micro-USB","1","have","The whole engine runs on it with lots of headroom."
+"Core","lcd","Nokia 5110 LCD module","PCD8544, 84×48, SPI","1","have","The module you used with Arduino."
+"Core","box","Enclosure","","1","have","About 80 × 150 × 40 mm. Panel layout: tools/panel.html."
+"Controls","enc","Rotary encoder with push","KY-040 module or bare EC11","1","have","Power it from 3V3."
+"Controls","pots","Potentiometer, linear","B10K (anything 5k–50k linear works)","2","have","Energy and Drift."
+"Controls","knobs","Knobs","to fit the pot and encoder shafts","3","check","Shaft types differ (D, knurled, 6 mm). Match them."
+"Controls","btn","Momentary push button, panel mount","~12 mm, non-latching","11","check","7 kit + 4 line tracks."
+"Controls","seedbtn","Momentary push button, large","16–22 mm, non-latching","1","check","SEED. Any big momentary works."
+"Controls","tog","Toggle switch, SPDT","","1","have","RUN / STOP. Your old bypass switch."
+"Controls","dio","1N4148 diode","or 1N4448 / 1N914 / any small-signal diode","12","buy","11 for the button matrix + 1 for MIDI IN. 1N4448 works too. Every button needs one: a missing diode gives phantom presses with three buttons held."
+"MIDI","trs","3.5 mm stereo (TRS) jack, panel mount","3 lugs: tip, ring, sleeve. Not mono.","3","check","IN, OUT KIT, OUT SYNTH. MIDI TRS Type A. 6 mm hole each."
+"MIDI","adapt","TRS-to-DIN MIDI adapter, Type A","female DIN, 3.5 mm plug","1","buy","For a DIN synth or sampler (e.g. MiniFreak). Must say Type A (Type B swaps tip and ring). Type A TRS gear (e.g. SP-404MKII) takes a plain stereo 3.5 mm cable."
+"MIDI","opto","6N137 optocoupler","DIP-8 (6N138 also works: then drop the pin 7 link)","1","have","MIDI IN. You have three; one is used."
+"MIDI","sock","DIP-8 IC socket","","1","buy","So the opto can be swapped."
+"MIDI","r330","Resistor 330 Ω","220–470 Ω","1","check","LCD backlight (LED pin) to 3.3 V, inline at the module."
+"MIDI","r220","Resistor 220 Ω","150–220 Ω","1","have","MIDI IN, in series with the opto LED. The 6N137 wants a bit more LED current: use 150 Ω if learning misses notes."
+"MIDI","r1k","Resistor 1 kΩ","470 Ω–2.2 kΩ is fine","2","have","Opto output pull-up, NPN base."
+"MIDI","r33","Resistor 33 Ω, ½ W","27–47 Ω is fine","2","buy","MIDI OUT ring (pin 4) line, per the MIDI 3.3 V spec. ½ W because a mono plug in an OUT jack shorts it straight to ground (0.33 W); a ¼ W one would cook."
+"MIDI","r10","Resistor 10 Ω","10–22 Ω is fine","2","check","MIDI OUT tip (pin 5) line, from TX. Don't replace with a wire: it protects the pin."
+"MIDI","cap","Ceramic capacitor 100 nF","anything 47–220 nF","3","check","C1 on the board (6N137 supply bypass, required). Optional: one per pot, soldered at the pot from wiper to the left lug, if the readings jitter."
+"Screen extras","blt","NPN or PNP transistor","2N3904 / BC547 (NPN) or 2N3906 / BC557 (PNP)","1","opt","Only for a dimmable backlight. NPN if your BL lights when grounded, PNP if it lights from 3.3 V. Otherwise hard-wire it."
+"Power and assembly","perf","Stripboard","at least 34 × 28 holes (about 86 × 71 mm)","1","check","Pico socketed at the top edge, so its USB port meets a slot in the back wall."
+"Power and assembly","hdr","Female header strip, 1 × 20","2.54 mm","2","check","Socket the Pico instead of soldering it in."
+"Power and assembly","mhdr","Male header strip, 1 × 20","2.54 mm","2","check","Soldered to the Pico so it plugs into the female headers. Skip if yours is a Pico 2 WH (headers fitted)."
+"Power and assembly","tape","Double-sided foam tape or hot glue","","—","check","Holds the stripboard and the screen without screws."

docs/hardware/cuts.txt

@@ -0,0 +1,5 @@
+Hole 6 on strips U to Y (5 cuts)
+Hole 14 on strips U to X (4 cuts)
+Hole 16 on strips A to T (20 cuts)
+Hole 23 on strip X (1 cut)
+Hole 25 on strips U to W (3 cuts)

docs/hardware/drill-list.csv

@@ -0,0 +1,22 @@
+where,part,x_mm,y_mm,hole
+"Lid","Screen wire hole (under the header)","11","28","Ø 8"
+"Lid","Encoder","15.5","61.5","Ø 7"
+"Lid","KICK","83.5","20","Ø 12"
+"Lid","KICK 2","101.2","20","Ø 12"
+"Lid","SNARE","118.8","20","Ø 12"
+"Lid","RUN toggle","136.5","20","Ø 6"
+"Lid","HAT","83.5","40","Ø 12"
+"Lid","HAT 16","101.2","40","Ø 12"
+"Lid","PERC","118.8","40","Ø 12"
+"Lid","GHOST","136.5","40","Ø 12"
+"Lid","BASS","83.5","60","Ø 12"
+"Lid","MEL A","101.2","60","Ø 12"
+"Lid","MEL B","118.8","60","Ø 12"
+"Lid","PAD","136.5","60","Ø 12"
+"Lid","ENERGY pot","63","17.3","Ø 7"
+"Lid","DRIFT pot","63","40","Ø 7"
+"Lid","SEED","63","62.7","Ø 16"
+"Back wall","Jack MIDI IN","105","20 down","Ø 6"
+"Back wall","Jack OUT · KIT","121","20 down","Ø 6"
+"Back wall","Jack OUT · SYNTH","137","20 down","Ø 6"
+"Back wall","USB slot (Pico port)","44","16 up from inside floor","12 × 8 slot"

docs/hardware/panel.md

@@ -0,0 +1,46 @@
+# Panel
+
+Landscape layout for a plastic enclosure of about 80 × 150 × 40 mm. The interactive tool (`tools/panel.html`) takes your box size and hole diameters and redraws this, with a fit check.
+
+![Panel layout, landscape](svg/panel-landscape.svg)
+
+- **Left zone**: the screen (on top of the lid), with the encoder and RUN under it.
+- **Middle zone**: ENERGY, DRIFT and SEED.
+- **Right zone**: the 4 × 3 block, in the same order as the screen map: 11 track buttons, with the RUN toggle in the top-right corner. Check at test fit that the toggle's body clears the OUT SYNTH jack behind it on the back wall.
+- **Back wall**: the USB slot for the Pico, and three 3.5 mm MIDI jacks (IN, OUT KIT, OUT SYNTH).
+
+## Inside the box
+
+- **Stripboard**: it lies on the floor with its top edge (strip A) against the back wall.
+- **USB**: the Pico's micro-USB socket ends up about 41 mm from the board's left edge and about 16 mm above the *inside* floor. That stack is foam tape ~1, board 1.6, female header 8.5, the Pico's header spacer 2.5, Pico 1, half the socket ~1.4. Measure your own before cutting the slot.
+- **Slot size**: cut it big enough for the plug's moulding (about 12 × 8 mm), not just the metal tip. The plug has to reach the socket through the wall's thickness.
+- **Fit**: the board is 71 mm front to back, which fits the box's inside depth with a little to spare. Pot and button bodies hang down from the lid above it.
+- **Under SEED**: R4 (lying flat) and pads P3/P4 sit right under SEED. Keep those two wires low and check how deep your SEED button reaches before closing the box.
+
+## Drill list
+
+Coordinates are from the lid's top-left corner, in mm, for the default sizes in the tool. Wall holes use x as drawn, which matches the lid view; heights are from the inside floor. Re-run the tool with your measured parts before drilling.
+
+| Where | Part | x mm | y mm | Hole |
+|---|---|---|---|---|
+| Lid | Screen wire hole (under the header) | 11 | 28 | Ø 8 |
+| Lid | Encoder | 15.5 | 61.5 | Ø 7 |
+| Lid | KICK | 83.5 | 20 | Ø 12 |
+| Lid | KICK 2 | 101.2 | 20 | Ø 12 |
+| Lid | SNARE | 118.8 | 20 | Ø 12 |
+| Lid | RUN toggle | 136.5 | 20 | Ø 6 |
+| Lid | HAT | 83.5 | 40 | Ø 12 |
+| Lid | HAT 16 | 101.2 | 40 | Ø 12 |
+| Lid | PERC | 118.8 | 40 | Ø 12 |
+| Lid | GHOST | 136.5 | 40 | Ø 12 |
+| Lid | BASS | 83.5 | 60 | Ø 12 |
+| Lid | MEL A | 101.2 | 60 | Ø 12 |
+| Lid | MEL B | 118.8 | 60 | Ø 12 |
+| Lid | PAD | 136.5 | 60 | Ø 12 |
+| Lid | ENERGY pot | 63 | 17.3 | Ø 7 |
+| Lid | DRIFT pot | 63 | 40 | Ø 7 |
+| Lid | SEED | 63 | 62.7 | Ø 16 |
+| Back wall | Jack MIDI IN | 105 | 20 down | Ø 6 |
+| Back wall | Jack OUT · KIT | 121 | 20 down | Ø 6 |
+| Back wall | Jack OUT · SYNTH | 137 | 20 down | Ø 6 |
+| Back wall | USB slot (Pico port) | 44 | 16 up from inside floor | 12 × 8 slot |

docs/hardware/pinout.md

@@ -0,0 +1,44 @@
+# Pinout (Pico 2 W)
+
+| Pico pin | GPIO | Function | Goes to | Notes |
+|---|---|---|---|---|
+| 1 | GP0 | UART0 TX | OUT KIT tip, via 10 Ω | drive strength 8–12 mA |
+| 2 | GP1 | UART0 RX | 6N137 output (pin 6), 1 kΩ pull-up to 3.3 V | MIDI IN |
+| 4 | GP2 | matrix row 1 | KICK, KICK 2, SNARE (col 4 empty) | input, pull-up |
+| 5 | GP3 | matrix row 2 | HAT, HAT 16, PERC, GHOST | input, pull-up |
+| 6 | GP4 | UART1 TX | OUT SYNTH tip, via 10 Ω | drive strength 8–12 mA |
+| 7 | GP5 | matrix row 3 | BASS, MEL A, MEL B, PAD | input, pull-up |
+| 9 | GP6 | matrix column 1 | KICK, HAT, BASS | driven low one at a time, else Hi-Z |
+| 10 | GP7 | matrix column 2 | KICK 2, HAT 16, MEL A | 〃 |
+| 11 | GP8 | matrix column 3 | SNARE, PERC, MEL B | 〃 |
+| 12 | GP9 | matrix column 4 | GHOST, PAD | 〃 |
+| 14 | GP10 | encoder A (SIA) | encoder | pull-up |
+| 15 | GP11 | encoder B (SIB) | encoder | pull-up |
+| 16 | GP12 | encoder push (SW) | encoder | pull-up |
+| 17 | GP13 | SEED | button to ground | pull-up |
+| 19 | GP14 | RUN | toggle to ground | pull-up |
+| 22 | GP17 | SPI0 CSn | LCD SCE (pin 3) | can be tied to GND instead |
+| 24 | GP18 | SPI0 SCK | LCD SCLK (pin 7) | |
+| 25 | GP19 | SPI0 TX | LCD DN / MOSI (pin 6) | |
+| 26 | GP20 | GPIO | LCD D/C (pin 5) | |
+| 27 | GP21 | GPIO | LCD RST (pin 4) | |
+| 31 | GP26 | ADC0 | ENERGY pot wiper | |
+| 32 | GP27 | ADC1 | DRIFT pot wiper | |
+| 33 | AGND | | pots, left lugs | |
+| 36 | 3V3 | | 3V3 strip (AB): LCD, encoder, pots, MIDI OUT rings via 33 Ω, opto pull-up | |
+| 40 | VBUS | | 5 V strip (Z): 6N137 VCC and enable only | powered from the Pico's USB |
+| 23 | GND | | GND strip (AA) | all Pico GND pins are common |
+
+Free: GP15, GP16, GP22, GP28 (ADC2), and GP17 if SCE is tied to ground. The LCD backlight runs straight from 3.3 V through 330 Ω; GP22 could dim it later through a transistor.
+
+## Firmware notes for these pins
+
+- **Pull-ups, not pull-downs.** RP2350 erratum E9 makes the internal pull-downs unreliable on inputs, so every input here is active-low with a pull-up.
+- **Drive strength.** GP0 and GP4 drive the MIDI current loops directly, about 6–8 mA. That's above the RP2350's default 4 mA drive, so set them to 8 or 12 mA with `gpio_set_drive_strength()`.
+- **Matrix.**
+  - Drive one column low at a time and leave the others Hi-Z, then read the three rows. On the idle columns, disable the input buffer (`gpio_set_input_enabled(pin, false)`) or enable the pull-up, so erratum E9 leakage can't hold them at a middle level.
+  - The diode bands point to the column.
+  - A short settle (a few µs) after switching columns helps.
+  - Debounce in software.
+- **UART.** Both UARTs run at 31 250 baud, 8N1. MIDI IN is only used to learn pads, so it can be polled.
+- **Nokia 5110.** It runs at 3.3 V on SPI up to 4 MHz.

docs/hardware/svg/encoder-pins.svg

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="enc" viewBox="0 0 300 80" role="img" aria-label="Encoder module pins" xmlns="http://www.w3.org/2000/svg" style="background:#F6F7F9"><rect x="72" y="14" width="12" height="12" fill="#111" stroke="#D4AF37" stroke-width="1.5"></rect><line x1="78" y1="26" x2="78" y2="52" stroke="#D7263D" stroke-width="4" stroke-linecap="round"></line><text x="78" y="10" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="9" fill="#18202A">VCC</text><text x="78" y="68" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="10" font-weight="700" fill="#18202A">AB4</text><rect x="108" y="14" width="12" height="12" fill="#111" stroke="#D4AF37" stroke-width="1.5"></rect><line x1="114" y1="26" x2="114" y2="52" stroke="#1E1E1E" stroke-width="4" stroke-linecap="round"></line><text x="114" y="10" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="9" fill="#18202A">GND</text><text x="114" y="68" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="10" font-weight="700" fill="#18202A">AA4</text><rect x="144" y="14" width="12" height="12" fill="#111" stroke="#D4AF37" stroke-width="1.5"></rect><line x1="150" y1="26" x2="150" y2="52" stroke="#2E9E5B" stroke-width="4" stroke-linecap="round"></line><text x="150" y="10" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="9" fill="#18202A">SW</text><text x="150" y="68" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="10" font-weight="700" fill="#18202A">P2</text><rect x="180" y="14" width="12" height="12" fill="#111" stroke="#D4AF37" stroke-width="1.5"></rect><line x1="186" y1="26" x2="186" y2="52" stroke="#2E9E5B" stroke-width="4" stroke-linecap="round"></line><text x="186" y="10" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="9" fill="#18202A">SIB</text><text x="186" y="68" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="10" font-weight="700" fill="#18202A">O2</text><rect x="216" y="14" width="12" height="12" fill="#111" stroke="#D4AF37" stroke-width="1.5"></rect><line x1="222" y1="26" x2="222" y2="52" stroke="#2E9E5B" stroke-width="4" stroke-linecap="round"></line><text x="222" y="10" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="9" fill="#18202A">SIA</text><text x="222" y="68" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="10" font-weight="700" fill="#18202A">N2</text></svg>

docs/hardware/svg/lcd-pins.svg

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="lcd" viewBox="0 0 300 92" role="img" aria-label="LCD header pins" xmlns="http://www.w3.org/2000/svg" style="background:#F6F7F9"><rect x="30.25" y="14" width="12" height="12" fill="#111" stroke="#D4AF37" stroke-width="1.5"></rect><line x1="36.25" y1="26" x2="36.25" y2="52" stroke="#D7263D" stroke-width="4" stroke-linecap="round"></line><text x="36.25" y="10" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="8" fill="#18202A">1 VCC</text><text x="36.25" y="68" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="10" font-weight="700" fill="#18202A">AB23</text><rect x="62.75" y="14" width="12" height="12" fill="#111" stroke="#D4AF37" stroke-width="1.5"></rect><line x1="68.75" y1="26" x2="68.75" y2="52" stroke="#1E1E1E" stroke-width="4" stroke-linecap="round"></line><text x="68.75" y="10" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="8" fill="#18202A">2 GND</text><text x="68.75" y="68" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="10" font-weight="700" fill="#18202A">AA23</text><rect x="95.25" y="14" width="12" height="12" fill="#111" stroke="#D4AF37" stroke-width="1.5"></rect><line x1="101.25" y1="26" x2="101.25" y2="52" stroke="#2F6FDB" stroke-width="4" stroke-linecap="round"></line><text x="101.25" y="10" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="8" fill="#18202A">3 SCE</text><text x="101.25" y="68" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="10" font-weight="700" fill="#18202A">S27</text><rect x="127.75" y="14" width="12" height="12" fill="#111" stroke="#D4AF37" stroke-width="1.5"></rect><line x1="133.75" y1="26" x2="133.75" y2="52" stroke="#2F6FDB" stroke-width="4" stroke-linecap="round"></line><text x="133.75" y="10" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="8" fill="#18202A">4 RST</text><text x="133.75" y="68" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="10" font-weight="700" fill="#18202A">N27</text><rect x="160.25" y="14" width="12" height="12" fill="#111" stroke="#D4AF37" stroke-width="1.5"></rect><line x1="166.25" y1="26" x2="166.25" y2="52" stroke="#2F6FDB" stroke-width="4" stroke-linecap="round"></line><text x="166.25" y="10" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="8" fill="#18202A">5 D/C</text><text x="166.25" y="68" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="10" font-weight="700" fill="#18202A">O27</text><rect x="192.75" y="14" width="12" height="12" fill="#111" stroke="#D4AF37" stroke-width="1.5"></rect><line x1="198.75" y1="26" x2="198.75" y2="52" stroke="#2F6FDB" stroke-width="4" stroke-linecap="round"></line><text x="198.75" y="10" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="8" fill="#18202A">6 DN</text><text x="198.75" y="68" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="10" font-weight="700" fill="#18202A">P27</text><rect x="225.25" y="14" width="12" height="12" fill="#111" stroke="#D4AF37" stroke-width="1.5"></rect><line x1="231.25" y1="26" x2="231.25" y2="52" stroke="#2F6FDB" stroke-width="4" stroke-linecap="round"></line><text x="231.25" y="10" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="8" fill="#18202A">7 SCLK</text><text x="231.25" y="68" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="10" font-weight="700" fill="#18202A">Q27</text><rect x="257.75" y="14" width="12" height="12" fill="#111" stroke="#D4AF37" stroke-width="1.5"></rect><line x1="263.75" y1="26" x2="263.75" y2="52" stroke="#D7263D" stroke-width="4" stroke-linecap="round"></line><text x="263.75" y="10" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="8" fill="#18202A">8 LED</text><text x="263.75" y="68" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="10" font-weight="700" fill="#18202A">AB22</text></svg>

docs/hardware/svg/pots-seed-run.svg

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="misc" viewBox="0 0 300 150" role="img" aria-label="Pots, SEED and RUN wiring" xmlns="http://www.w3.org/2000/svg" style="background:#F6F7F9"><circle cx="45" cy="42" r="20" fill="#2C3238"></circle><text x="45" y="14" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="10" fill="#18202A">ENERGY</text><rect x="30.5" y="62" width="5" height="12" fill="#C9CFD5"></rect><line x1="33" y1="74" x2="33" y2="96" stroke="#1E1E1E" stroke-width="4" stroke-linecap="round"></line><text x="33" y="108" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="9" font-weight="700" fill="#18202A">H27</text><rect x="42.5" y="62" width="5" height="12" fill="#C9CFD5"></rect><line x1="45" y1="74" x2="45" y2="96" stroke="#2F6FDB" stroke-width="4" stroke-linecap="round"></line><text x="45" y="108" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="9" font-weight="700" fill="#18202A">J27</text><rect x="54.5" y="62" width="5" height="12" fill="#C9CFD5"></rect><line x1="57" y1="74" x2="57" y2="96" stroke="#D7263D" stroke-width="4" stroke-linecap="round"></line><text x="57" y="108" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="9" font-weight="700" fill="#18202A">AB25</text><circle cx="115" cy="42" r="20" fill="#2C3238"></circle><text x="115" y="14" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="10" fill="#18202A">DRIFT</text><rect x="100.5" y="62" width="5" height="12" fill="#C9CFD5"></rect><line x1="103" y1="74" x2="103" y2="96" stroke="#1E1E1E" stroke-width="4" stroke-linecap="round"></line><text x="103" y="108" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="9" font-weight="700" fill="#18202A">H27</text><rect x="112.5" y="62" width="5" height="12" fill="#C9CFD5"></rect><line x1="115" y1="74" x2="115" y2="96" stroke="#2F6FDB" stroke-width="4" stroke-linecap="round"></line><text x="115" y="108" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="9" font-weight="700" fill="#18202A">I27</text><rect x="124.5" y="62" width="5" height="12" fill="#C9CFD5"></rect><line x1="127" y1="74" x2="127" y2="96" stroke="#D7263D" stroke-width="4" stroke-linecap="round"></line><text x="127" y="108" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="9" font-weight="700" fill="#18202A">AB25</text><circle cx="190" cy="42" r="16" fill="#2C3238"></circle><text x="190" y="14" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="10" fill="#18202A">SEED</text><line x1="183" y1="58" x2="183" y2="96" stroke="#D9A600" stroke-width="4" stroke-linecap="round"></line><text x="183" y="108" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="9" font-weight="700" fill="#18202A">Q2</text><line x1="197" y1="58" x2="197" y2="96" stroke="#1E1E1E" stroke-width="4" stroke-linecap="round"></line><text x="197" y="108" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="9" font-weight="700" fill="#18202A">AA6</text><rect x="240" y="30" width="34" height="24" rx="3" fill="#2C3238"></rect><text x="257" y="14" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="10" fill="#18202A">RUN</text><rect x="243.5" y="54" width="5" height="10" fill="#C9CFD5"></rect><rect x="254.5" y="54" width="5" height="10" fill="#C9CFD5"></rect><line x1="257" y1="64" x2="257" y2="96" stroke="#D9A600" stroke-width="4" stroke-linecap="round"></line><text x="257" y="108" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="9" font-weight="700" fill="#18202A">S2</text><rect x="265.5" y="54" width="5" height="10" fill="#C9CFD5"></rect><line x1="268" y1="64" x2="268" y2="96" stroke="#1E1E1E" stroke-width="4" stroke-linecap="round"></line><text x="268" y="108" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="9" font-weight="700" fill="#18202A">AA6</text><text x="150" y="138" text-anchor="middle" font-family="'Martian Mono', ui-monospace, Menlo, Consolas, monospace" font-size="9" fill="#566271">lugs facing down, seen from the front</text></svg>

docs/hardware/wire-list.csv

@@ -0,0 +1,36 @@
+pad,board_hole,colour,pico_pin_or_signal,goes_to
+"P1","Y1","blue","via R1 to opto","MIDI IN jack · ring (pin 4)"
+"P2","W1","blue","opto cathode","MIDI IN jack · tip (pin 5)"
+"P3","X26","blue","via R4 (10 Ω) from GP0","OUT KIT jack · tip (pin 5)"
+"P4","V22","red","via R5 (33 Ω) from 3V3","OUT KIT jack · ring (pin 4)"
+"P5","AA22","black","GND strip","OUT KIT jack · sleeve (pin 2)"
+"P6","U31","blue","via R6 (10 Ω) from GP4","OUT SYNTH jack · tip (pin 5)"
+"P7","V31","red","via R7 (33 Ω) from 3V3","OUT SYNTH jack · ring (pin 4)"
+"P8","AA31","black","GND strip","OUT SYNTH jack · sleeve (pin 2)"
+"P9","N27","blue","GP21","LCD · RST (pin 4)"
+"P10","S27","blue","GP17","LCD · SCE (pin 3)"
+"P11","O27","blue","GP20","LCD · D/C (pin 5)"
+"P12","P27","blue","GP19","LCD · DN/MOSI (pin 6)"
+"P13","Q27","blue","GP18","LCD · SCLK (pin 7)"
+"P14","AB23","red","3V3 strip","LCD · VCC (pin 1)"
+"P15","AA23","black","GND strip","LCD · GND (pin 2)"
+"P16","AB22","red","3V3 strip","LCD · LED (pin 8) through 330 Ω"
+"P17","N2","green","GP10","Encoder · SIA"
+"P18","O2","green","GP11","Encoder · SIB"
+"P19","P2","green","GP12","Encoder · SW"
+"P20","AB4","red","3V3 strip","Encoder · VCC"
+"P21","AA4","black","GND strip","Encoder · GND"
+"P22","J27","blue","GP26","ENERGY pot · middle lug"
+"P23","I27","blue","GP27","DRIFT pot · middle lug"
+"P24","AB25","red","3V3 strip","Pots · right lugs (chain both)"
+"P25","H27","black","AGND","Pots · left lugs (chain both)"
+"P26","Q2","yellow","GP13","SEED · one lug"
+"P27","S2","yellow","GP14","RUN toggle · middle lug"
+"P28","AA6","black","GND strip","Panel ground bus · SEED other lug, RUN one outer lug"
+"P29","D2","yellow","GP2","Matrix row 1 (KICK, KICK 2, SNARE)"
+"P30","E2","yellow","GP3","Matrix row 2 (HAT, HAT 16, PERC, GHOST)"
+"P31","G2","yellow","GP5","Matrix row 3 (BASS, MEL A, MEL B, PAD)"
+"P32","I2","green","GP6","Matrix column 1 (KICK, HAT, BASS)"
+"P33","J2","green","GP7","Matrix column 2 (KICK 2, HAT 16, MEL A)"
+"P34","K2","green","GP8","Matrix column 3 (SNARE, PERC, MEL B)"
+"P35","L2","green","GP9","Matrix column 4 (GHOST, PAD)"

docs/hardware/wiring.md

@@ -0,0 +1,239 @@
+# Wiring
+
+One stripboard carries the Pico and the MIDI circuits. Everything on the panel (screen, encoder, pots, buttons, jacks) connects to it with hookup wire.
+
+**Board positions** are strip letter + hole number. For example V4 is strip V, hole 4, counted from the left with the parts facing you. Strips run left to right: A at the top (the USB edge), then Z, AA, AB at the bottom.
+
+The interactive version, with the same drawings, is `tools/wiring.html`. Generated from [`hardware/layout.js`](../../hardware/layout.js).
+
+## Wire map: panel to board
+
+Every panel wire and the board hole it lands in: strip letter, then hole number counted from the opto end.
+
+![Wire map](svg/wire-map.svg)
+
+| Part | Lug | Wire | Board hole |
+|---|---|---|---|
+| Buttons | Row 1 · KICK, KICK 2, SNARE | yellow | **D2** |
+|  | Row 2 · HAT, HAT 16, PERC, GHOST | yellow | **E2** |
+|  | Row 3 · BASS, MEL A, MEL B, PAD | yellow | **G2** |
+|  | Col 1 · KICK, HAT, BASS (diode band side) | green | **I2** |
+|  | Col 2 · KICK 2, HAT 16, MEL A | green | **J2** |
+|  | Col 3 · SNARE, PERC, MEL B | green | **K2** |
+|  | Col 4 · GHOST, PAD | green | **L2** |
+| SEED | one lug | yellow | **Q2** |
+| RUN toggle | middle lug (it sits in the button grid, row 1 / col 4) | yellow | **S2** |
+| SEED + RUN | ground: SEED other lug, RUN one outer lug | black | **AA6** |
+| Encoder | VCC (3.3 V, never 5 V) | red | **AB4** |
+|  | GND | black | **AA4** |
+|  | SW | green | **P2** |
+|  | SIB | green | **O2** |
+|  | SIA | green | **N2** |
+| ENERGY pot | middle lug | blue | **J27** |
+| DRIFT pot | middle lug | blue | **I27** |
+| Pots | right lugs, both (3.3 V) | red | **AB25** |
+|  | left lugs, both (AGND) | black | **H27** |
+| LCD | 1 · VCC (3.3 V) | red | **AB23** |
+|  | 2 · GND | black | **AA23** |
+|  | 3 · SCE | blue | **S27** |
+|  | 4 · RST | blue | **N27** |
+|  | 5 · D/C | blue | **O27** |
+|  | 6 · DN (MOSI) | blue | **P27** |
+|  | 7 · SCLK | blue | **Q27** |
+|  | 8 · LED, through a 330 Ω resistor (if dark, move to any AA hole) | red | **AB22** |
+| MIDI IN jack | tip | blue | **W1** |
+|  | ring | blue | **Y1** |
+| OUT KIT jack | tip | blue | **X26** |
+|  | ring | red | **V22** |
+|  | sleeve | black | **AA22** |
+| OUT SYNTH jack | tip | blue | **U31** |
+|  | ring | red | **V31** |
+|  | sleeve | black | **AA31** |
+
+## Wire colours
+
+| Colour | Role |
+|---|---|
+| Red | 3.3 V and the MIDI OUT ring lugs |
+| Black | ground |
+| Yellow | button rows, SEED, RUN |
+| Green | button columns, encoder |
+| Blue | screen, pots, MIDI signals |
+| Grey | short links on the board |
+
+If your spools are other colours, keep the roles and rename them. Red and black for power and ground matter most.
+
+## Board · parts side
+
+![Stripboard, parts side](svg/stripboard-parts-side.svg)
+
+- **Size**: 34 holes × 28 strips, about 86 × 71 mm.
+- **Pico**: sits in two 20-pin female headers with pins 1 and 40 on strip A. Its USB end is flush with the top edge of the board, and the micro-USB socket reaches just past it.
+- **Mounting**: lay the board on the box floor with that edge against the back wall, behind the USB slot. The socket is about 41 mm from the board's left edge.
+- **Pads**: the numbered dots P1 … P35 are where off-board wires solder.
+
+## Board · copper side, for cutting
+
+![Stripboard, copper side](svg/stripboard-copper-side.svg)
+
+This view is flipped: hole 1 is on the right.
+
+How to cut:
+
+- Use a 3–4 mm drill bit turned by hand, or a spot-face cutter.
+- Check each cut with the meter's continuity beeper.
+
+- Hole 6 on strips U to Y (5 cuts)
+- Hole 14 on strips U to X (4 cuts)
+- Hole 16 on strips A to T (20 cuts)
+- Hole 23 on strip X (1 cut)
+- Hole 25 on strips U to W (3 cuts)
+
+### Power strips along the bottom
+
+- **Z**: 5 V from the Pico's VBUS. Only the opto uses it.
+- **AA**: ground.
+- **AB**: 3.3 V from the Pico's 3V3 pin.
+
+Every red wire to the panel starts on AB. Every black wire starts on AA, except the pots, which use the AGND strip.
+
+## Board parts and links
+
+| Part | Value | Holes | Note |
+|---|---|---|---|
+| Pico 2W | 2 × 20-pin female header | A13–T13 and A20–T20 (pins 1–20 down the left, 40–21 down the right) | USB end flush with the top edge of the board, past strip A |
+| U1 | 6N137 | U5–X5, U8–X8 | 6N137 in a DIP-8 socket. Notch toward strip U, pin 1 at hole U5. Pin 7 (enable) is tied to pin 8 by the U10–V10 link. |
+| R1 | 220 Ω | V2 – Y2 | MIDI IN current limit. 3-hole span: stand it upright, or use a small ⅛ W part flat. If learning ever misses notes, use 150 Ω. |
+| D1 | 1N4148 | V4 – W4 | Band (cathode) on V4, the opto LED anode side. Stands upright (1-hole span). |
+| R2 | 1 kΩ | W10 – AB10 | Opto output pull-up to 3.3 V |
+| C1 | 100 nF | U11 – X11 | 6N137 supply bypass, right beside the chip: U11 is its 5 V (pin 8) strip, X11 its GND (pin 5) strip. Required. Fit it after the beep test. |
+| R4 | 10 Ω | X21 – X25 | MIDI OUT KIT, TX line (RC). Lies flat along strip X, across the cut at X23 (4-hole span, ¼ W fits). SEED hangs right above it. |
+| R5 | 33 Ω ½ W | V19 – AB19 | MIDI OUT KIT, 3.3 V line (RA). ½ W: a mono plug in the jack shorts it to ground. |
+| R6 | 10 Ω | U28 – Y28 | MIDI OUT SYNTH, TX line (RC) |
+| R7 | 33 Ω ½ W | V30 – AB30 | MIDI OUT SYNTH, 3.3 V line (RA). ½ W, same reason as R5. |
+| Link | wire | A34 – Z34 | 5 V (VBUS) to the 5 V strip |
+| Link | wire | E32 – AB32 | 3V3 to the 3V3 strip |
+| Link | wire | R33 – AA33 | GND to the GND strip |
+| Link | wire | U13 – Z13 | opto VCC to 5 V |
+| Link | wire | U10 – V10 | opto enable (pin 7) to VCC (pin 8): the 6N137 output only works with pin 7 high |
+| Link | wire | X12 – AA12 | opto GND to GND |
+| Link | wire | W9 – B9 | opto out to GP1 (MIDI RX), strip B |
+| Link | wire | A15 – X15 | GP0 (TX KIT) to strip X (R4), straight down under the Pico between its headers |
+| Link | wire | F14 – Y14 | GP4 (TX SYNTH) to strip Y (R6), straight down under the Pico between its headers |
+
+## Off-board wires
+
+| Pad | Board hole | Colour | Pico pin / signal | Goes to |
+|---|---|---|---|---|
+| P1 | Y1 | blue | via R1 to opto | MIDI IN jack · ring (pin 4) |
+| P2 | W1 | blue | opto cathode | MIDI IN jack · tip (pin 5) |
+| P3 | X26 | blue | via R4 (10 Ω) from GP0 | OUT KIT jack · tip (pin 5) |
+| P4 | V22 | red | via R5 (33 Ω) from 3V3 | OUT KIT jack · ring (pin 4) |
+| P5 | AA22 | black | GND strip | OUT KIT jack · sleeve (pin 2) |
+| P6 | U31 | blue | via R6 (10 Ω) from GP4 | OUT SYNTH jack · tip (pin 5) |
+| P7 | V31 | red | via R7 (33 Ω) from 3V3 | OUT SYNTH jack · ring (pin 4) |
+| P8 | AA31 | black | GND strip | OUT SYNTH jack · sleeve (pin 2) |
+| P9 | N27 | blue | GP21 | LCD · RST (pin 4) |
+| P10 | S27 | blue | GP17 | LCD · SCE (pin 3) |
+| P11 | O27 | blue | GP20 | LCD · D/C (pin 5) |
+| P12 | P27 | blue | GP19 | LCD · DN/MOSI (pin 6) |
+| P13 | Q27 | blue | GP18 | LCD · SCLK (pin 7) |
+| P14 | AB23 | red | 3V3 strip | LCD · VCC (pin 1) |
+| P15 | AA23 | black | GND strip | LCD · GND (pin 2) |
+| P16 | AB22 | red | 3V3 strip | LCD · LED (pin 8) through 330 Ω |
+| P17 | N2 | green | GP10 | Encoder · SIA |
+| P18 | O2 | green | GP11 | Encoder · SIB |
+| P19 | P2 | green | GP12 | Encoder · SW |
+| P20 | AB4 | red | 3V3 strip | Encoder · VCC |
+| P21 | AA4 | black | GND strip | Encoder · GND |
+| P22 | J27 | blue | GP26 | ENERGY pot · middle lug |
+| P23 | I27 | blue | GP27 | DRIFT pot · middle lug |
+| P24 | AB25 | red | 3V3 strip | Pots · right lugs (chain both) |
+| P25 | H27 | black | AGND | Pots · left lugs (chain both) |
+| P26 | Q2 | yellow | GP13 | SEED · one lug |
+| P27 | S2 | yellow | GP14 | RUN toggle · middle lug |
+| P28 | AA6 | black | GND strip | Panel ground bus · SEED other lug, RUN one outer lug |
+| P29 | D2 | yellow | GP2 | Matrix row 1 (KICK, KICK 2, SNARE) |
+| P30 | E2 | yellow | GP3 | Matrix row 2 (HAT, HAT 16, PERC, GHOST) |
+| P31 | G2 | yellow | GP5 | Matrix row 3 (BASS, MEL A, MEL B, PAD) |
+| P32 | I2 | green | GP6 | Matrix column 1 (KICK, HAT, BASS) |
+| P33 | J2 | green | GP7 | Matrix column 2 (KICK 2, HAT 16, MEL A) |
+| P34 | K2 | green | GP8 | Matrix column 3 (SNARE, PERC, MEL B) |
+| P35 | L2 | green | GP9 | Matrix column 4 (GHOST, PAD) |
+
+## Panel wiring
+
+### Button matrix, seen from the back
+
+![Button matrix](svg/button-matrix.svg)
+
+Each button:
+
+- One lug goes to its row wire (yellow), daisy-chained along the row.
+- The other lug goes through a diode to its column wire (green), daisy-chained down the column.
+- The diode's band points to the column. Solder the diodes straight onto the button lugs and sleeve them. 1N4148, 1N4448 or any small-signal diode works.
+
+11 track buttons, each with its own diode, plus D1 on the board: 12 diodes. GHOST is wired at row 2 / column 4. The RUN toggle sits in the grid's row 1 / column 4 spot but isn't part of the matrix, so row 1's wire stops at SNARE and column 4 starts at GHOST.
+
+Drawn from behind the panel, the side you solder on: KICK is top-right, RUN top-left.
+
+### MIDI jacks: 3.5 mm TRS, Type A
+
+![TRS jacks](svg/midi-jacks-trs.svg)
+
+| Jack | Tip (pin 5) | Ring (pin 4) | Sleeve (pin 2) |
+|---|---|---|---|
+| MIDI IN | P2 | P1 | stays empty |
+| OUT KIT | P3 | P4 | P5 |
+| OUT SYNTH | P6 | P7 | P8 |
+
+- **Jack type**: use stereo (TRS) jacks; mono ones have no ring.
+- **Lug order**: it differs between jack models. Find the tip, ring and sleeve lugs with the meter and a plug inserted.
+- **Cables**: Type A is the MIDI standard, so a plain stereo 3.5 mm cable goes straight to another Type A device (e.g. SP-404MKII). A DIN device (e.g. MiniFreak) needs a TRS-to-DIN adapter that says **Type A**. A Type B one swaps tip and ring and gives silence; nothing breaks.
+
+### Nokia 5110 module
+
+![LCD pins](svg/lcd-pins.svg)
+
+- Pin order as printed on your module: 1 VCC, 2 GND, 3 SCE, 4 RST, 5 D/C, 6 DN (MOSI), 7 SCLK, 8 LED.
+- **LED** (backlight): wire it through a 330 Ω resistor to AB22 (3.3 V), with the resistor inline at the module end, sleeved. If it stays dark, move that wire to any free hole on strip AA (ground). GP22 (L27) stays free; it's only needed for dimming later, through a transistor.
+- **SCE** can go straight to ground instead of S27 if it's the only thing on the SPI bus. That frees GP17.
+
+### Encoder module
+
+![Encoder pins](svg/encoder-pins.svg)
+
+Pin order as printed on your module: VCC, GND, SW, SIB, SIA. Power it from 3.3 V (AB4), never 5 V: its pull-up resistors would put 5 V on the Pico's pins. If clockwise steps the wrong way, swap SIA and SIB (or flip it in firmware).
+
+### Pots, SEED, RUN
+
+![Pots, SEED and RUN](svg/pots-seed-run.svg)
+
+- **Pots**, lugs facing down, shaft toward you:
+  - left lug to AGND (P25)
+  - middle lug to its pin
+  - right lug to 3.3 V (P24)
+  - Chain the left lugs together and the right lugs together.
+  - If the readings jitter, solder a 100 nF capacitor at each pot, from wiper to left lug.
+- **SEED**: one lug to P26, the other to the ground bus (P28).
+- **RUN**: middle lug to P27, one outer lug to the ground bus. If RUN and STOP come out swapped, use the other outer lug.
+
+## Build order and checks
+
+### Board
+
+1. Cut the board to 34 × 28 holes. For the top edge, cut through the row of holes above strip A, then sand it back to about 1.3 mm from the strip A holes, stopping before the strip A copper. That puts the Pico's edge flush with the board. Unsanded, the Pico sits about 1 mm back, which still works if the wall slot lets the plug's moulding through.
+   Make the track cuts and beep each one out.
+2. Solder the two Pico headers and the DIP-8 socket (notch toward strip U). Then the resistors and the diode (band on V4).
+   - Keep everything low, because the SEED button hangs right above R4. R4 lies flat along strip X, across the cut at X23.
+   - R1's 3-hole span is tight for a ¼ W body, so stand R1 upright or use a small ⅛ W part.
+   - Leave C1 for step 4.
+3. Solder the grey links with insulated wire. The two long ones (GP0 and GP4) run straight down under the Pico, between its two headers, so fit them before the Pico goes in.
+4. Before fitting C1, with the Pico and the 6N137 out, check that AB to AA does not beep and Z to AA does not beep. Then fit C1. It can chirp briefly on the beeper once it's in.
+
+### First power
+
+1. Plug in the Pico only and power it from USB. Measure AB to AA: about 3.3 V. Z to AA: about 5 V.
+2. Unplug, then insert the 6N137 (notch toward strip U, pin 1 at hole U5).
+3. Wire the panel. Before closing the box, check that no bare lugs touch each other.
+4. Flash the firmware. Set GP0 and GP4 to 8–12 mA drive (see [pinout](pinout.md)).