Plans

Current Goal

Delivered: protocol v1 on four pcb v1.0 boards across two rigs (Rig 1 2026-10-09, the desk rig 2026-10-12). v1.0.0 is tagged; the desk rig's two boards were reflashed from v1.0.0-2-g109169f (same code as the tag, docs only after it) on 2026-10-14 from Peter's laptop. Next: the same reflash on Rig 1 (procedure in the README, "Reprogramming a v1.0 board"; the Status entry for 2026-10-14 has what the laptop needs), then the researcher-facing documentation (orb-weaver-context/context/mouse-joystick-rig-documentation-plan.md, phase 2: architecture page, circuit-to-code map, diagrams).

Open Item — Two of four v1.0 units ignore the 1200 baud touch (opened 2026-10-13)

Units B and D (boards 7 and 9) take the bootloader touch at most once and then need the button under mouse_joystick_qp_rev2; units A and C take it every time with the same build. The board-side item is in mouse-joystick-pcb/.agents/PLANS.md. Firmware side:

• [ ] Confirm on a failing unit whether the host's line-coding request reaches the CDC at all (USB capture, or a QS record on the CDC callback) before anything in the application is suspected; the two units took the touch from the self-test build, which has the same core.
• [ ] If the request arrives and is ignored, look at what the delivery build does differently around USB: the 1 kHz hardware-alarm tick and the watchdog (Bsp.cpp), and whether TinyUSB's task gets starved.
• [ ] Either way, keep the B protocol verb and the button procedure in the README as the documented routes into BOOTSEL.
• [ ] 2026-10-14, Peter's laptop: board 9 (unit D) took the touch from the delivery build 316f802-dirty and flashed in 4.3 s; board 8 in 7.6 s; board 8 took a second touch (a pyserial 1200 baud open, DTR low) a minute later. So "ignores it every time" is wrong for board 9 — it is intermittent, and the host (laptop vs desk computer, hub) may matter. One board at a time: PlatformIO skips the touch when any RP2040 is already in BOOTSEL and picotool load takes no address.

Task: pcb v1.0 Bring-Up (opened 2026-10-04; boards arrive 2026-10-05)

The v1.0 boards (two ordered from the 2026-09-21 fabrication package) are the first boards with the brake sink, the torque bridge, I2C DACs, LATCH on a GPIO and the Digital-50 instrument port. The board file is unchanged from mouse-joystick-pcb commit d5ae4b0 through its fabrication package 646b8f4 and HEAD 6d5ffd3; no v1.0 tag exists yet — tagging the fabricated commit is Peter's call and the firmware comments say "no tag yet" until then. The pin map was read off footprint U601 with a script over the .kicad_pcb (the RP2040 is U601 at v1.0; U501 is now the 36 V switch), not from prose. Rig-level sequence: ../orb-weaver-context/context/mouse-joystick-rig-system-plan.md section 9, Phase A.

Done before the boards arrived (software only, 2026-10-04, uncommitted)

• [x] MJ_BOARD_REV=2 in src/BoardPins.hpp: the v1.0 map, hw=rev2, HV_LATCH on GP24 (MJ_HAS_LATCH_GPIO/MJ_LATCH_GPIO forced, overrides refused), ~{HV_FAULT} on GP23, I2C0 on GP16/GP17 with the DAC addresses 0x48/0x49, the torque ADC on SPI1 (GP10/11/12, CONVST GP15), TQ_CAL_EN GP18, ~{BRAKE_FAULT} GP13, BRAKE_ISENSE GP27, ANGLE_OUT_MON GP29, spares GP20/GP22. The SPI DAC constants do not exist for rev 2, so no SPI DAC code path compiles for it.
• [x] SafeState: drives HV_LATCH low (auto-retry, the reset default; powerUp() raises it after the rail is up), TQ_CAL_EN low and TQ_CONVST_CS high behind the open switch, leaves ~{BRAKE_FAULT}, the SPI1 and I2C pins as inputs; setInstrumentationEnabled() is a no-op on rev 2 (Digital-50 has no enable). Reset-state reads: R607, R401, R507 on GP23, R402/R403 (I2C idle high), HV_LATCH informational.
• [x] RP2040SelfTest on rev 2: 2 spare pads, the four straps above, the two monitor ADC channels at 0 V with the rail off; 20 checks by derivation from rev 1's 24 (−7 spares −1 buffer OE +2 I2C +2 ADC).
• [x] TMC5130Communication: v1.0 designators (U501, R501, R506, R508, R509; no LATCH strap). MotionAndHoming, AngleOutput and PyControlLinkQp/Bsp.cpp: the DAC transport follows the revision (rev 1 SPI1, rev 2 I2C0 on pins::kDacScl/kDacSda), MJ_DAC_I2C is derived and a contradiction is a compile error; the v1.0 ÷2 output divider is in the printed BNC volts (1.650 V full scale).
• [x] Protocol: ProtocolBoard::Config::instr_switchable (false on rev 2, so INSTR is accepted and state is always 1, per uart-protocol.md).
• [x] Envs: mouse_joystick_rev2, mouse_joystick_qp_rev2, mouse_joystick_qp_rev2_usb; the two *_rev1_i2c envs removed (they paired rev 1 pins with an I2C DAC and matched no board). mouse_joystick_rev1 is now documented as v0.3 only, not "HEAD".
• [x] Host tests: 125 pass (a Guix gcc-toolchain is needed on this machine; the conda compiler in the Pixi env fails at link against the system glibc). Target builds for every example and env: see the status line below once they have run.

Still owed, in order (software first, then the bench)

• [x] Regression of HEAD on v0.3 before the v1.0 boards (2026-10-05, board 4): every stage console on mouse_joystick_rev1 and the QP session on mouse_joystick_qp_rev1_usb, no firmware regression; see Status.
• [ ] Tag mouse-joystick-pcb v1.0 at the fabricated commit (646b8f4 is the one whose fab/ package is the order; d5ae4b0 is the last board-file change). Then replace "no tag yet" in BoardPins.hpp, platformio.ini, the README and docs/rp2040-bringup.md.
• [ ] Rig plan Phase A1 cannot see the DACs or the ADS8689 on USB alone. Both DACs run from +3.3V_FILT, the ADC from +3.3V_SW/+5V_FILT, and every one of their bus lines is behind the bus switch. "I2C sees 0x48 and 0x49, SPI1 sees the ADS8689" is an A2/A3 check with the rail up and the bus closed. Corrected in the rig plan 2026-10-04; A1 is the RP2040SelfTest run and nothing more.
• [x] A1: RP2040SelfTest on mouse_joystick_rev2, USB only (2026-10-05, unit A E4654C159F274534): 20 checks, 0 failed, HV_LATCH low, monitors at 0 V; recorded in the PCB bring-up log. Both v1.0 units arrived with a wrong part (green, banded) at every C2858031 position (C1301 on +3.3V_MCU, C1208 on TMC 5VOUT, C1501 on +5V_SW); removing C1301 brought the board up. C1208 must be refitted with a real 2.2–4.7 µF before A2.
• [x] A2 (2026-10-05, unit A): powerUp() reports the direct method; the first attempt failed because latch-off was armed 10 ms after +3.3V_SW read live while the switch was still charging the bulk (PG lines up at 6–11 ms, trip at 37 ms). Fixed in PowerSequence: LATCH stays low until HV_SNS has left the fault band for 20 ms (33–34 ms measured), powerDown() restores LATCH low, PowerUpReport::charge_ms added. Two clean passes, 5/0 register checks each; idle 36 V input current 43.6–51.3 mA. The LATCH probe's strapped half fails as designed. Numbers in the PCB bring-up log. Uncommitted.
• [x] A3 (2026-10-05, unit A): the I2C DAC at 0x48 answers, GAIN 0x0101 written and read back matched, DEVID 0x115, REF-ALARM clear, every transaction ACKed on the Digital-50 I2C taps. ANGLE_OUT_MON readback added to AngleOutput (rev 2): midscale 0.8236 V, full scale 1.6415 V, floor 12 mV at the BNC node, within the RP2040 ADC's accuracy; a meter fit is still owed. I2C set to 400 kHz in both bench consoles (the QP build already had it); the live loop's worst iteration went 1082 → 732 µs. Uncommitted.
• [x] A4 (2026-10-06, unit A): examples/BrakeAndTorque (new; the console for A4 and A5 together, line-oriented commands, tools/board_console.py drives it) configures the brake Dac80501 at 0x49 with GAIN 0x0101 read back, sweeps, steps and reads BRAKE_ISENSE/~{BRAKE_FAULT}. Brake chain linear, full scale 1.0065 V = 48.80 mA (design 1.006 V), ±0.07 % FS above half scale, the 12 V gate drive sufficient. Finding: a step above ~60 % overshoots — 62 mA (127 %) for ~5 ms at full scale — and ~{BRAKE_FAULT} never asserts, although 62 mA is above the 56.4 mA ceiling. Board question filed in the PCB plan; firmware consequence: BRAKE ramps its setpoint (≥ 6 ms to full scale) and checks BRAKE_ISENSE against it rather than trusting bit 9. Numbers in the PCB bring-up log; docs/brake-torque-bringup.md here.
• [x] A5 (2026-10-06, unit A): ADS8689 driver written (src/ADS8689*.hpp, src/ADS8689/, 22 host tests), RANGE_SEL 0x0B written and read back, SDO proven by the DATA_VAL loopback patterns before any conversion is trusted; the frames decoded on the Digital-50 taps. Torque at rest 1.5956 V (69 mV below the ideal zero: mechanism preload or offset, tare covers it), noise 95–112 µV rms at 1 kHz, 1000.1 Hz live loop at a 295 µs worst tick, no brake-to-torque coupling at 0.1 mV. The shunt-cal switch is inert (0.0 codes of a 0.744 V step), as the 2026-10-04 design review predicted; TQ cal stays a verb and not a calibration.
• [x] Brake and torque in the protocol (2026-10-06, both ends, run on unit A). src/BrakeTorqueBackend.hpp is the seam (with the simulated backend the corpus runs against); src/BrakeTorqueHw.hpp the real one (brake DAC at 0x49 with a setpoint ramped at 8 ms to full scale, BRAKE_ISENSE supervision for bit 10, the fault pin for bit 9, the ADS8689 sampled on the tick, bits 11–12). ProtocolBoard: caps brake/torque, BRAKE acks then waits for the backend to settle before releasing the drive and emitting RELEASED (motion verbs busy meanwhile, STOP/DISARM cancel), the drive re-engages BEFORE the brake comes off on every way out of RELEASED (3a; the old order was wrong and no board could show it), TQ zero|cal|get, torque in STATUS/events/TRIAL (t_touch, tq_peak, tq_out)/capture, TOUCH on the torque magnitude. Mirrored in board_sim.py; corpus grammar gained CAPS <tokens> and a live TORQUE stimulus, 5 new cases; device class torque_get()/torque_cal(). 154 Unity, 178 pytest. On unit A (mouse_joystick_qp_rev2_usb, driven by qp-arduino-example/tools/brake_torque_steps.py): RELEASED 11.6 ms after brake 1.0 and 15–17 ms after brake 3.4, torque −0.30 N·cm on the nominal zero then tared, NOMOVE at 3000.1 ms, TRIAL with torque fields, FETCH with the torque column, clean hv off. Decisions the spec left open are written up as uart-protocol.md V1.11. Numbers in the PCB bring-up log ("brake and torque in the protocol build").
• [ ] The 1 kHz sampler is decimated whenever the rail is up on v1.0, and was already on 2026-10-05 (last 110–750 µs, max 0.9–1.5 ms without the brake/torque poll; 0.26–1.2 ms and 2.1–2.5 ms with it, 1.2 ms in RELEASED with a WATCH armed). The primitives are cheap (ADS8689 sample 37 µs, BRAKE_ISENSE 4.8 µs, DAC write 110 µs, console M); delayMicroseconds() in the ADS8689 transport was the first suspect and was not it (busy wait now, no change). Attributed with POLL_STAT (QS_USER+14, per second: each backend's worst poll, its calls, and its worst primitive), run …-0942-unitA-qp-brake-torque: with the rail up EVERY primitive shows 100–500 µs maxima — the X_ENC read 350–555 µs, the five-register snapshot 400–670, the ADS8689 sample 230–480, even the BRAKE_ISENSE analogRead 110–230 µs — against 30, 150, 37 and 4.8 µs on the bench console. A 5 µs ADC read cannot take 230 µs by itself: this is interrupt time landing inside whichever bus primitive is running. The bench builds carry the protocol over USB CDC, and the Arduino core services tinyusb from a 1 kHz interrupt (tud_task() at IRQ level), so the heartbeat and the replies are the prime suspect; the QS PIO UART's ISR is the other. Next: an A/B with the heartbeat slowed and the trace off, then the delivery build over UART0 with the pyboard (which has almost no USB traffic) — the tick budget must be judged on that build, not on _usb. Until then the brake ramp's steps are coarser than designed (three writes instead of eight for 3.4 N·cm) though still below the overshoot threshold, and lost= in a trial's capture will not be 0 under load.
• [x] SafeState::driveOutput() writes the level before the direction (SDK calls, no gpio_init()): the 34 µs ~{BUS_SW_EN} boot glitch is gone, no edge on CH27 across a warm reboot (2026-10-06). measureHvCurrent() now waits for the rail to read off (and reports how long it took) instead of pausing 50 ms, so stage 2's m works after a live rail; not yet re-run on hardware.
• [x] A6 (2026-10-05, unit A): rail 3 ms / charged 34 ms, TMC 0x11, vsense 1, switch witnessed, homed, 5 of 5 at 2.0 counts, reversal dead band 89 µsteps as on board 4 (mechanism, not board), L 1000.1 Hz but worst loop 1082 µs over the I2C DAC (v0.3 SPI: 386–527 µs). Numbers in the PCB bring-up log.
• [x] After A6 (2026-10-05, unit A): PyControlLinkQp on mouse_joystick_qp_rev2_usb, phases a–e, no asserts; tick cost 305/357 µs holding with the angle output on (I2C), 15/52 idle, 116/1081 moving; host-loss 105.7 ms; 320 moves. Run with a scratch variant of the session script that remaps the Digital-50 channels to the 40-pin names the trace tools expect (CH1→CH17, CH0→CH16, CH2→CH8, CH9→CH5, CH8→CH2); the bench scripts still hard-code board 4, rev1 and the 40-pin map and are owed a serial/env/channel-map parameterisation.
• [x] Digital-50 observation through the LA5032 adapter v2.0 and the Molex 15020 FFC: straight mapping confirmed 2026-10-05, 26 of 32 channels exercised by 2026-10-06 (the UART pair last, with a pyboard).
• [x] First contact over the RJ-45 on v1.0 (2026-10-06, 09:59): the delivery build mouse_joystick_qp_rev2 (protocol on UART0) answered id from the pyboard's REPL on Breakout 1.2 port 4 (USART3) — the right joystick's port, which is the one unit A drives — with the full v1.0 identity and caps; ports 1 and 3 silent. Then the whole protocol over the real link with the rail up: hv on, torque live and tared, home, arm, brake 1.0 → RELEASED, watch → NOMOVE at 1500.0 ms, TRIAL 1 s later with torque, fetch with the torque column; a 150 ms gap in the REPL script then tripped the 100 ms host-loss watchdog exactly as specified (FAULT, hv=0, brake=0.0, nak;faulted to the next brake, clrfault recovered). Decoded on CH2/CH3. PCB bring-up log, "first contact over the RJ-45".
• [x] The tick budget, attributed and half fixed (2026-10-06). Over UART0 the primitives drop to a third of the USB build's maxima (X_ENC 161 µs, snapshot 310, ADS8689 sample 103, BRAKE_ISENSE 57–137), so the USB protocol port's interrupt-level servicing was the big inflator and the _usb builds are not where the budget is judged. What remained was structural: both hardware backends polled at every scheduler stop (the RELEASED ring adds one per millisecond), and the hv on transient latched the decimated mode until hv off. Fixed: hardware polls reuse their cache within 500 µs (TmcMotion, BrakeTorqueHw; the simulated backends are unlimited so the corpus is untouched), and decimation ends after 500 handled ticks under half the budget (LinkAo). Measured on the Gate E run — see Status.
• [x] The watchdog runs with the rail (2026-10-06, Peter's call after Gate E). hv on arms the host-loss watchdog, hv off or a fault disarms it, arm refreshes, disarm leaves it running while the rail is on (ProtocolBoard::cmdHv/cmdDisarm, board_sim._cmd_hv/_cmd_disarm, uart-protocol.md V1.12 and its tables). Three new corpus cases; two older ones rewritten (event-time-is-64-bit advances before the rail, home-timeout-above-the-maximum-is-clipped-not-refused widens the watchdog and heartbeats for its eight seconds), their unit-test mirrors in both languages likewise. Consequence: a host heartbeats from hv on; the device class's hv() docstring says so.
• [x] Tare before the watch (same day). mouse_joystick_check sends tq zero right before watch when the board has torque, so the rest offset (−0.2 to −0.35 N·cm at rest after RELEASED) stops tripping touch=0.3. Bench knobs v.wdt_ms and v.instr added for the tick attribution runs.
• [x] The tick budget, round three, attributed and fixed (2026-10-06, 11:04–11:55). Measured on the LA5032 rather than with the CPU's own clock (PCB bring-up log, "the tick budget attributed on the bus and on the pin"; scripts qp-arduino-example/tools/la/). The bus was never the problem: an X_ENC read is 27 µs on the wire and a snapshot 101 µs after the library changes, yet the firmware measured 240–430 and 400–570 µs for them, a ping cost the active object 1.2–1.9 ms (LINK_WORK), and on the pin (MJ_TICK_LEVEL) the RELEASED tick was 758 µs median for a few hundred instructions of classifier work. The trace off changed nothing; fewer host lines helped only the idle. The cause: every build ran from the W25Q128JVZPIQ through the generic single-lane 03h stage 2 (boot2_generic_03h_4, kept "until stage 1 passes" since the first article, never switched). On the quad-lane stage 2 matched to the part (tried as env:mouse_joystick_qp_rev2_fastflash, then made the default of every env at 14:05, boot2_w25q128jvxq_4; boots and runs the task first time) the RELEASED tick is 346 µs median / 450 p90 / 760 max, the ARMED tick 146 / 235 / 370 at 1000 handlers/s, a ping 0.5 ms, every POLL_STAT maximum 2–3× lower, and the sampler holds 1 kHz in ARMED. The budget constant (400 µs) then decimated the trial on its own, so it is 700 µs (measured headroom in LinkAo.cpp); run 9 (…-1147-unitA-gate-e-fastflash/): 1 kHz for the whole run, trial included, never decimated, 79 overrun skips and 47 coalesced ticks in 50 s (from ≈1900 / ≈1500), handler max 798 µs in RELEASED, 371 in ARMED. Peter made it the default at 14:05: env:mouse_joystick's boot2_source is the quad-lane one, every env inherits it, env:mouse_joystick_safeflash keeps the generic stage 2 for a first article, and the _fastflash envs are gone. Also done on the way, all measured: TMC51X0 working copy with one buffer transfer per datagram (two-buffer form on RP2040/Teensy: 17 → 12 µs per datagram, clocks back to back) and the pipelined readMany() (snapshot 10 → 6 datagrams), used by MotionSetup::snapshot(); platformio.ini pins TMC51X0.git#4.2.0 (the library is versioned and release-checked; Peter tags and pushes). Open: (1) make the quad-lane stage 2 the default for pcb v1.0 (flip env:mouse_joystick's boot2_source, or the rev2 envs'); every v1.0 board has the same flash; keep the generic one for a first article. (2) The RELEASED tick is still 2.4× the ARMED one for little work — code size and the 16 KB cache; a -Os/-O2 and section-placement pass (__not_in_flash_func on the tick path) is the next lever if ever needed. (3) Unit B and the pyboard heartbeat rate: 25/s costs 5 % of the ticks ~40 µs; fine.
• [ ] The park error: lost motion on direction reversal, measured (2026-10-06, 14:07–14:25). Every trial parked 0.99° short on the encoder with the ramp generator satisfied. Probed with the bring-up task's park knob (PCB bring-up log, "the park error measured"; evidence …-1407-unitA-park-error/): the release, the resync and the brake are not it (both frames equal and the brake off for 300 ms, the move still lands at −0.991); a chain of six moves loses 0.35–0.77° on every reversal and ≤ 0.07° on same-direction moves, independent of distance, not accumulating. Not the encoder, not the firmware. At IRUN 17 instead of 8 the after-positive state is −0.633 three times out of three (from −0.82…−0.99) and the hysteresis shrinks by a third: ~0.3° is the stepper's torque angle under friction at the bring-up current, 0.3–0.6° is drive-train lost motion. Options, in order of preference: (1) settle on the encoder after TARGET with one or two correction moves of the residual — needs a TARGET semantics decision in uart-protocol.md; (2) same-direction approach (overshoot and return); (3) IRUN toward 17 when the thermal survey allows. Until then both tasks home before every trial. Option (1) done 2026-10-07 (uart-protocol.md V1.13), measured on unit A (PCB bring-up log, "the encoder settle after a move"; evidence …-2026-10-07-0807-unitA-encoder-settle/): TmcMotion commands moves relative to the encoder, waits after position_reached for X_ENC to stand still (one count for 10 ms, bounded 100 ms), corrects a residual above one count up to twice (Conversions.hpp kMoveSettle*), reports MOVE_SETTLE in the QP trace; both simulators mirror it with the corpus SLIP stimulus and three cases (156 Unity, 188 pytest, all 15 example/env builds). The same probe chain twice: all 16 TARGETs within 0.18° (before: eight of eight short by 0.22–0.99°), the park at 0.00 and +0.08; a reversal costs 150–260 ms more, an uncorrected move 10 ms. The rig task's home_each_trial default is 0 now.
• [ ] Settle tolerance, one count or two (2026-10-07). MOVE_SETTLE shows the first correction removing most of a reversal's 0.6–1.0° and 1–2 counts remaining that a 13–25 microstep correction cannot move against static friction at IRUN 8 (the ramp frame advances, the rotor does not, and the next same-direction move overshoots by what was stuck: probe 3 arrived 0.36° past). A two-count tolerance would skip the ~100 ms second correction at the price of the last count; at IRUN 17 the torque per microstep doubles. Decide with the thermal survey; the constant is kMoveSettleToleranceMicrosteps.
• [x] The rig's trial task, dry run (2026-10-07, 08:40): joystick-rig/feat/mouse-joystick's hardware_definition_joystick.py and tasks/rig1/joystick_trial.py with home_each_trial = 0, run from their checkout (tools/pycontrol_run.py --hwd-path/--task-dir, the rig's opto_led.py symlinked into pyControl's devices/) against unit A on the right joystick: eight trials, every present and park within one count, no fault (PCB bring-up log, "the rig's trial task, dry run"; evidence …-0840-unitA-rig-trial-dryrun/). The pyboard's flash was full of device files pyControl never deletes (pycontrol/README.md, "A fourth thing"). What remains for the rig session is the solenoid cable on port 5 and the researcher.
• [x] The reward path and unit A's pull sign (2026-10-07, 08:53–08:59): with the solenoid on port 5 a hand pull was first classified PUSH (pull sign +1), the park against the held lever faulted not_following; BoardCalibration.hpp gained {"E4654C159F274534", -1.0}, and the next pull was PULL → the task's 50 ms solenoid pulse → TRIAL outcome=PULL → park at 0.0 (PCB bring-up log, "the reward path and the pull sign"; evidence …-0855-unitA-solenoid-pull/). Unit B's sign is to be measured the same way (a hand pull during WATCH; PUSH means flip it).
• [ ] A lever held through the park faults the board (2026-10-07). Correct for the stall detector, fatal for a session: TRIAL comes 1 s after the outcome, the task parks, a held lever stalls the drive at IRUN 8 → not_following → rail off. Decide with the researcher (uart-protocol.md V1.9): the board defers the move while the torque says the lever is held (a nak;busy or a wait), or the task recovers (CLRFAULT → HV ON → HOME). The rig task has no recovery path yet.
• [ ] One badverb 5 ms after a FAULT (2026-10-07, pull1_60s): the task's first faults request was refused nak;326;badverb, the retry was acknowledged; the verb dispatches by exact match. Most likely a corrupted byte on the way in around the switched-domain collapse; no capture was running. Capture CH3 (board RX) at the next fault before changing anything.
• [x] Unit B (board 7, E4654C159F404534, the LEFT joystick), stages 1 through A5 (2026-10-07, 09:07–09:31) after Peter's capacitor rework: 20/0 self-test checks, two direct-LATCH power-ups with 5/0 register checks and 29.9 mA idle, the angle DAC with GAIN read back (0.829/1.649 V mid/full on the monitor), the left joystick's switch at the positive end and active high with the encoder tracking (no config flip), homed, homing spread 9 counts (runs 3–5 within one), live loop 350 µs, brake sweep linear to 49.11 mA with the same silent 128 % full-scale overshoot as unit A, torque 103 µV rms at 1000.1 Hz. The second LA5032 (conn=1.67) is on its Digital-50, straight cable, map proven by beacon. PCB bring-up log, six new unit B sections; evidence …-0908-unitB-bringup/. Gate E passed on Breakout port 1 at 09:37 (the same sequence as unit A's to tens of ms), and the hand pull was PUSH then PULL once {"E4654C159F404534", -1.0} was in the calibration table: both joysticks pull toward decreasing angle, the left torque sensor reads it negative. Both boards pass under one hardware definition on their own ports; a task driving both at once is the researcher's.
• [x] The rig's files fit the pyboard the way the GUI uploads them (2026-10-07, 10:30). Measured: 33.8 KB free after "Load framework", the six drivers the rig definition pulls in take 22.3 KB, so the hardware definition and task must fit in ~10 KB verbatim; the originals (15.5 KB, 95 % comments; 10.2 KB, 47 %) failed on the definition at 0 bytes free. On the rig branch the definition's prose moved verbatim to notes/hardware_definition_joystick_notes.md (the .py is 2.1 KB, code AST unchanged), the task's long header to notes/261007_mouse_joystick_researcher_guide.md (6.9 KB, plus a clear_fault() at run_start); the GUI path then leaves 7.7 KB free. The researcher guide is the deliverable for the session.
• [x] 400-trial soak (2026-10-07, 10:40–11:14): the rig task on the right joystick unattended, 400 NOMOVE, 0 nak, 0 FAULT, every present and park within one count (park 0.0 × 399), period 5.08 ± 0.02 s with no drift, 53 190 link lines (PCB bring-up log, "400 trials unattended"; evidence …-1040-unitA-soak/). Not exercised: a lever in a hand, both boards at once, an hour or more; an overnight run is the next size up when the rig is idle.
• [ ] Left joystick: the torque sensor rests 1.55 N·cm above its nominal zero (unit A: 0.07 below), forty times the zero-balance spec; a mechanical preload at the sensor or lever. The tare hides it; the mounting wants a look before absolute torque is trusted. Also a small brake-to-torque coupling (−0.006 N·cm at 49 mA) unit A does not show. Peter / the rig.
• [ ] The uploader's bootloader step fails on unit B three times out of four ("The RP2040 device returned an error: ", error 157, after the 1200-baud touch has put it in BOOTSEL); unit A takes the same pixi run upload every time. Copying the UF2 to the mounted RPI-RP2 drive works every time. Two RP2040s on the bus, a different hub port, or picotool's device pick — undiagnosed; the UF2 path is the workaround (tools/pio_task.py could fall back to it).
• [x] Gate E (2026-10-06), passed on v1.0 unit A: tools/pycontrol_run.py runs a task on the pyboard headlessly through pyControl's own Pycboard API (the GUI's path, no GUI); pixi run -e pycontrol pycontrol-run. Two things pyControl 2.1.1 taught us on the way: (1) its device-file discovery is a substring match of class names over file TEXT, comments included, recursing without a cycle check, so MouseJoystick being a prefix of MouseJoystickProtocol looped it to a RecursionError — the codec is now JoystickProtocol and the constraint is written in its header; (2) the pyboard's 95 KB flash had 36 KB free against 60 KB of uploads (our files were 60 % prose, and comment-only mentions of MCP23017 and Poke pulled a 9 KB driver along), so tools/pycontrol_lean.py now generates comment- and docstring-free copies into pycontrol/dist/ (49 → 20 KB), which is what pycontrol-link points pyControl at and what the rig will ship; tests/test_lean.py imports them. The bring-up task mouse_joystick_check speaks protocol v1 with v.board selecting the side, and keeps its own v.phase because the task API has no current-state query (the third lesson; the first run on the board died on get_current_state() one step after hv on, rail up, host watchdog not yet armed). Passed twice (evidence qp-arduino-example/evidence/2026-10-06-1019-unitA-gate-e/, -1037-, -1043-): identify → hv on (180 ms from cold) → HOMED → arm → TARGET −5.041° → BRAKE 1.0 → RELEASED 23 ms later → TOUCH → NOMOVE → TRIAL → park → done; run_end stops, disarms, drops the rail. Heartbeats 25/s, none lost. Written up in pycontrol/README.md and the PCB bring-up log's "pyControl Integration". Two observations for the rig: the rest torque reading (−0.2 to −0.35 N·cm, the PCB plan's third finding) trips a 0.3 N·cm touch with nobody there — tare before watch; and the park after a trial ends ~1° short on the encoder (backlash on the direction reversal) — home first when the park position matters (fixed 2026-10-07, V1.13: the board settles on the encoder after every move).

Parallel Observability Workstream — Updated 2026-09-30

docs/observability-plan.md is the local OBS-FW plan. The shared experimental-system roadmap owns cross-repository dependencies and stages. This optional path runs alongside existing delivery, bring-up and hardware-watchdog work; it does not replace those tasks or commit the application to QP.

The QP plan now qualifies RP2040 first, using the Earle Philhower core family already used here, on a separate simple non-actuating fixture. Exact core/fixture versions and all RP2040 qualification gates remain open. Teensy hardware work is deferred and nonblocking; retained build regressions remain useful. STM32G0B1CEU6 is a later second target. Current joystick delivery remains non-QP.

Hardware intent is passive Digital-50 plus a separate optional debug/trace connector and reusable external RP2040 probe. Combined 60-pin wiring and an onboard second MCU are deferred. This does not allocate pins or change present board capabilities; OBS-IF and the selected PCB revision own those decisions.

• [ ] OBS-FW-1: define representative command/event/completion semantics; ready now, coordinate interface/fixture fields with OBS-IF/OBS-HOST.
• [ ] OBS-FW-2: prepare good/fault/gap baseline fixtures and expected outcomes.
• [ ] OBS-FW-3: implement bounded observation only after agreeing semantics and claiming affected files with the delivery/watchdog agent.
• [ ] OBS-FW-4: measure the baseline on a qualified board/capture path; hardware-gated, with measurements in the PCB bring-up log.
• [x] OBS-FW-5 (first half, 2026-10-01): the QP comparison slice exists and ran. examples/PyControlLinkQp puts ProtocolBoard and the motion backend, unchanged, inside one QP/C++ active object with a transmit-only QS trace on FW_TRIG1; the simulated-motion bench build ran the pilot's full protocol sequence on the rev 0 fixture, the delivery build (TmcMotion, UART0) builds and boots into the safe state. Evidence in ../qp-arduino-example/evidence/2026-10-01-rp2040-joystick-link/ and .../2026-10-01-rp2040-joystick-firm-qp/. Owner of the example files, platformio.ini's [qp_env_data] and the three mouse_joystick_qp* envs: this workstream. Still owed before any adopt/defer decision: TmcMotion behind the AO with the rail up (the same first supervised run PyControlLink owes), the UART0 path under QP with a pyControl host, the OBS-IF marker overlay for FW_TRIG0/FW_TRIG1, and the v1.0 pin map. Record the decision here when it is made.
• [ ] OBS-FW-6: hand off correlated evidence for a supervised observation-only experiment pilot.

Claim step, owner and exact paths before implementation; use the local plan's file-ownership and evidence checklist. Planning alone closes none of these items. Preserve selected manufactured-tag/serial context rather than assuming historical firmware wiring matches current PCB development.

Status

2026-10-14, 09:10, Peter's laptop: the desk rig's boards reflashed. Practice run for Rig 1. Laptop setup: pixi install fails on this machine until CONDA_OVERRIDE_GLIBC=2.41 is in the environment (the Guix-built pixi does not see Debian's glibc; every pixi run needs it too). First build of examples/PyControlLinkQp mouse_joystick_qp_rev2 2 min (toolchain and framework download); image v1.0.0-2-g109169f (HEAD; no code change since the tag, git diff v1.0.0 HEAD --stat -- src examples platformio.ini is empty). pixi run upload … /dev/serial/by-id/…<serial>-if00 on board 8 (E4654C159F504534): touch, load, verify, reboot, 7.6 s. The same on board 9 (E4654C159F234234): 4.3 s, touch honoured. Both re-enumerate as 2e8a:f00a with their by-id links; picotool info -a in BOOTSEL shows the flash id and no binary info, and the delivery build's USB banner cannot be caught (the CDC port appears ~1 s after reboot, after the if (Serial) check), so the only read of fw is id over the RJ-45. Done at 09:20 once Peter plugged the desk rig's pyboard into the laptop: id;1 from the pyboard's raw REPL (the desk-rig session's pyb_uart_probe.py, now tools/pyb_id_probe.py) over port 1 UART(4) and port 4 UART(3): both boards answer fw=v1.0.0-2-g109169f, boot=reboot, caps unchanged (evidence/2026-10-14-0910-deskrig-reflash/). Rig 1 plan: laptop, both boards' USB and the pyboard's USB plugged in, one upload per board, then the probe.

2026-10-06, later: Gate E passed on v1.0 unit A. pyControl 2.1.1 on the PYBV11 ran mouse_joystick_check against the board over the RJ-45 three times through the GUI's own Pycboard path (tools/pycontrol_run.py), the whole sequence from id to hv off (identify, rail, home, arm, present, BRAKE → RELEASED in 12 ms, TOUCH, NOMOVE, TRIAL, park). Getting there: the codec renamed JoystickProtocol (pyControl's substring device discovery), comment-free lean copies in pycontrol/dist/ (36 KB of pyboard flash), and the task keeping its own v.phase (no current-state query in the task API). The hardware polls are now gated to one per advance of the protocol clock, which removed the doubled bus reads and most of the overrun skips; the sampler still runs decimated (500 Hz) with the rail up because every bus primitive costs 2–4× its console cost in the link build, and attribution is the next firmware step (plan item "round three"). The board is flashed with this build (mouse_joystick_qp_rev2, 10:43), rail off. Host tests 154 Unity + 182 pytest; the two qp rev2 envs build.

2026-10-06, 14:30. TMC51X0 4.2.0 released and pinned; the quad-lane flash stage 2 is the default of every env (mouse_joystick_safeflash keeps the generic one); the park error is measured — lost motion on direction reversal, part torque angle at the bring-up current, part drive train, not the encoder or the firmware — with the encoder-settle fix as the next firmware item; the rig repository has branch feat/mouse-joystick with the device files, the hardware definition (ports 1/4, solenoid to port 5) and a first trial task. Board: unit A on the default build, rail off. Tests 156 Unity + 185 pytest; all 14 example/env builds pass.

2026-10-06, 12:00: the 1 kHz sampler is back, and the watchdog runs with the rail. The tick budget was never the bus: every build ran from flash through the generic single-lane 03h stage 2, and the quad-lane stage 2 matched to the W25Q128JV (now the default of every env; mouse_joystick_safeflash keeps the generic one) halves to thirds everything the CPU does (tick 758 → 346 µs median in RELEASED, 268 → 146 in ARMED, ping 1.35 → 0.5 ms). With the budget constant at the measured 700 µs, Gate E run 9 held 1 kHz through the whole trial. On the way: TMC51X0 working copy (buffer-transfer datagrams, pipelined readMany; unreleased, lib_deps via symlink:// until Peter tags it), one hardware poll per advance, the watchdog armed by hv on with blocked time credited (V1.12), the task taring before watch. Board: unit A on the fastflash build, rail off. Tests 156 Unity + 185 pytest + 53 library; all twelve example/env builds pass.

2026-10-06: v1.0 unit A stages A4 and A5 passed with the new examples/BrakeAndTorque (brake sink 0–48.80 mA linear; ADS8689 alive at 95–112 µV rms; both buses decoded on the Digital-50 taps), and the protocol build gained brake and torque the same day, run on unit A (ramped BRAKE → RELEASED in 11.6 / 15–17 ms, TQ, torque in every field, NOMOVE/TRIAL/FETCH with torque; uart-protocol.md V1.11 has the decisions). Two board findings — the brake step overshoot with a silent ~{BRAKE_FAULT}, and the inert TQ_CAL_EN switch — are filed in the PCB plan. Host tests 154 Unity + 178 pytest, every example/env build green. Open: the sampler's tick budget with the rail up (decimated since 2026-10-05, worse with the new poll; being attributed with POLL_STAT), and the pyboard was not on USB this session, so the UART0 path and Gate E remain owed. Bench state and next steps: .agents/handoff.local.md.

2026-10-05: HEAD (ec3b36d) regressed on board 4 (pcb v0.3) before the v1.0 boards arrive — no firmware regression. Every stage tool ran on mouse_joystick_rev1 and the QP session on mouse_joystick_qp_rev1_usb, non-interactively: stage 1 24 checks / 0 failed; stage 2 rail 133 ms, 5 / 0 registers, SPI taps decoded byte-for-byte; stage 3 switch witnessed, homed, 5 of 5 at a 2.0-count spread, live loop 1000.1 Hz; QP a–e with 320 moves, release/watch/fetch/stream, host-loss fault 124.7 ms, hv off. Host tests 125, pyControl tests 168, 15 target builds, qp-arduino resolved from the GitHub tag. Evidence ../qp-arduino-example/evidence/2026-10-05-1142-board4-regression/; numbers in the PCB bring-up log under board 4. Bench finding, settled: the reversal lost motion (reversals 6–7 counts at IRUN 8, 4–5 at IRUN 17; continuing moves 1.00; taps = X_ENC within 2 counts; same on a replacement joystick unit; board 2 had −4 counts in September) is the stepper's dead band against friction, not the TMC, not firmware, not a defect. t fails because its move away off the switch is ended by the bench console's follow check, which lacks TmcMotion's grace and second window, and is not checked. Nits, none applied: SafeState::driveOutput() drives ~{BUS_SW_EN} low for 34 µs at boot (direction set before level; seen on v1.0 unit A's Digital-50 tap); measureHvCurrent() 50 ms discharge wait (m fails after a live rail; from a cold rail it measured 12.9 mA), W sweeps with the driver disabled, the session scripts miss pre-dictionary DAC_STATE records. The UART0 path with a pyboard and Gate E remain owed; no pyboard was on the bench.

2026-10-02: protocol v1 (proto=2) implemented on both ends and run end to end on board 4 with the rail up in the QP bench build; watchdog, breadcrumbs, overrun guard, 4 MHz SPI, follow rule with grace and resync after enable are in. The rev 1 angle-output session (phases b–e) is the next bench step. Current local context, bench state and open items: .agents/handoff.local.md (top block). Cross-repository plan of record: ../orb-weaver-context/context/mouse-joystick-rig-system-plan.md.

Stage 1 passed on hardware, 2026-09-01. Board serial E4654C159F2C2534. 27 checks, 0 failed. Recorded in ../mouse-joystick-pcb/docs/bringup-log.md.

The LA5032 capture path and la5032-instrument-port-adapter v1.0 are both validated, same day, against the boot signature. TRIG0/TRIG1 on LA5032 channels 16/17; cable not mirrored. Recorded in ../la5032-instrument-port-adapter/docs/bringup-log.md.

Stage 2 passed 2026-09-02 on both boards, once the 36 V rail collapse was diagnosed as R203 strapping the switch's LATCH high and worked around with PowerSequence::staircaseStart(). See The 36 V Rail Collapse.

Stage 3 passed 2026-09-02 on board E4654C159F4D1334, the as-built unit. The motor turns, the encoder tracks it to 1.000, and homing repeats to 4 encoder counts. Written over TMC51X0 4.0.3, pinned in platformio.ini. Procedure and findings in docs/motion-bringup.md; measurements in ../mouse-joystick-pcb/docs/bringup-log.md.

Controller MicroPython upgraded 2026-09-03: 1.22.2 -> 1.26.1. This cleared a blocker that had not been recorded anywhere: devices/uart_handler.py asserts on MicroPython >= 1.26, added in pyControl 2.1.1, and MouseJoystick.__init__ constructs a UART_handler. The bench pyboard was on framework 2.1.1 over MicroPython 1.22.2, so the device class could not have been instantiated at all — every host test passes against stubs and none of them can see this. Standard PYBV11 build; the internal filesystem survived (firmware writes flash sector 0 and sectors 5+, the filesystem lives in sectors 1-4), verified rather than assumed. Backup of the board's filesystem taken first, at ~/pyboard-flash-backup-2026-09-03. UART.IRQ_RXIDLE reads 0x10, matching pycontrol/tests/stubs.py.

The rig's controller has not been checked. The board upgraded is a bench pyboard carrying a rotary-encoder test task, not the rig's hardware_definition_joystick.py. Expect to upgrade the rig's too.

Ports assigned 2026-09-03: 1 (UART4) and 4 (USART3). All three UART-capable ports were verified on the live controller — constructed at 115200 8N1 with an IRQ_RXIDLE handler accepted, achieved baud 115384 (+0.16%) on UART4 and USART3, 115226 (+0.02%) on USART1. Ports 2, 5 and 6 report UART = None. pycontrol/hardware_definitions/mouse_joystick_bringup.py now assigns ports 1 and 4.

This depends on one rig change that has been requested but not confirmed. Peter asked the researcher on 2026-09-03 to move the reward solenoid from port_4.POW_A to port_5.POW_A. Until that is reported done and joystick-rig's hardware_definition_joystick.py on source/main reads port_5.POW_A, port 4 is contested — a solenoid cable still in port 4 means the right board's connector is occupied, and the symptom is a link that never answers rather than an error. Verify before blaming the protocol.

Why port 3 was given up: it is the only Breakout 1.2 port with I2C on DIO_A/DIO_B and a free DIO_C, which is what LaserLickPort needs. That device was converted from UART to I2C (ATtiny 0x15 + MPR121 0x5A share I2C bus 1; ATtiny PB1 drives DIO_C/X5), and port 4's DIO_C is X6 = DAC_2 = the live rsync — so the lick port has exactly one home and cannot move. The solenoid needs only a driver line and all six ports have POW_A, so it is the thing that moves. Ports 1 and 4 also give both boards an identical achieved baud, both being on APB1.

On port 4, RJ-45 pin 5 must stay unconnected. It is DIO_C = X6 = the rsync driver. Rev 0 leaves it open, which is correct; driving or pulling it would fight the DAC and corrupt the alignment fingerprint the recording pipeline depends on. Full reasoning: ../mouse-joystick-pcb/docs/pycontrol-port-pinout.md.

Gate C's firmware half written 2026-09-03, and Gate C's corpus requirement is now met by two independent implementations. src/Protocol.hpp is the framing codec and src/ProtocolBoard.hpp the command layer and state machine; both are Arduino-free and allocation-free, which is what lets test/native/test_protocol/test_protocol.cpp run the shared corpus on the host. 54 native tests pass, up from 33. All three examples still build for mouse_joystick.

Mutation-testing the corpus was the part that paid. Four deliberate defects were injected to check the tests had teeth; two were not caught at first:

• Inverting the ARMED and range checks in MOVETO passed every corpus case, so the corpus documented a safety-relevant ordering it did not enforce. Added armed-is-checked-before-the-range-check, which both implementations now pass.
• A test asserting that malformed frames do not refresh the host-loss watchdog advanced a full extra timeout at the end, tripping the watchdog either way. It passed against a board that refreshed on garbage. Margins tightened.

All four mutations are caught now. Neither gap was findable from one implementation plus its own fixture.

Standing requirement for firmware integration: event time must not be a raw 32-bit microsecond counter. ProtocolBoard keeps time in uint64_t because micros() wraps at 71.6 minutes, which is shorter than a session, and every event on this link carries t_us into a recorded dataset used for alignment. A wrap would not fail loudly — it would produce timestamps that go backwards. Whatever feeds this from micros() must accumulate the wrap.

Not yet done: none of this is wired to a UART or to real motion. Motion in ProtocolBoard is the simulator's linear model at v_max, and its defaults are the simulator's placeholders (travel +/-20 deg, 180 deg/s), not the measured bench values. Replacing them changes corpus timings and belongs in its own commit with the corpus updated alongside.

Protocol layer wired to a real UART and real motion, 2026-09-03. Four new firmware pieces, and one seam that made them possible:

Why a seam rather than calling MotionSetup directly: MotionSetup::moveTo() and homeToSwitch() are blocking — they return a report once the motion is done. Right for a bench console, wrong here: the protocol must ack immediately and keep servicing the link for the whole move, and a 2.5 s blocking home would silently fail every heartbeat inside a 100 ms timeout. TmcMotion drives the same primitives in the same order without waiting.

The seam also grew two things real hardware needs and the corpus does not: consumeFault(), so a driver over-temperature or an unexpected end stop becomes a latched fault and a FAULT event with no host command in flight; and setHvEnabled(), because the 36 V domain exists to feed the driver and a rail that fails to come up is a fault rather than a nak. Both are defaulted, so the corpus behaviour is untouched, and both are tested with stub backends.

NOT YET RUN ON HARDWARE, and the first run should be supervised. Stage 3 validated the blocking implementations; this is a faithful rearrangement, which is an argument and not a measurement. Unproven: the non-blocking homing state machine, and the travel limits derived from bench geometry rather than exercised through the protocol.

Homing over the protocol is deliberately SINGLE-STAGE. The bench measured two-stage and single-stage repeatability as the same 2-5 encoder counts; the slow creep buys datum accuracy (89 microsteps of offset at 0.200 rev/s against 4.5 at the creep) and a faster primary approach, not precision. A single stage is a small amount of code whose failure modes are bounded by the chip's own reference-switch stop; a blind reimplementation of the validated two-stage sequence would not be. Follow-up: two-stage homing over the protocol, with the 89-microstep offset as the reason it matters.

First protocol contact on hardware, 2026-09-03: id passed with the 36 V supply off. Board E4654C159F591D34 through Breakout 1.2 port 1, peer driven from the pyboard REPL with machine.UART(4) directly -- no framework, no hardware definition, no device class, for the same reason stage 2 used raw SPI datagrams: first contact should not have the framework as a second unknown. The reply also closed a standing gap by announcing its own serial, so the left joystick is board E4654C159F591D34 and the right is E4654C159F4D1334. Measurements in ../mouse-joystick-pcb/docs/bringup-log.md under board 3.

Two firmware bugs found by that run, both fixed.

1. STATUS hung the core. TmcMotion::angleDeg()/xactualDeg() read position over SPI and STATUS calls both, so a status before hv on reached for SPI0 before beginSpi() had run with the bus switch open. The board then stopped answering the link and stopped honouring the 1200 baud reset touch; recovery needed SW501 through a power cycle with both USB and the RJ-45 unplugged. Fixed: position is a cache refreshed once per poll() and nothing touches SPI unless bus_up_.

2. ID reported the corpus placeholder serial. The firmware never set it from the flash unique id, so every board would have reported 0000000000000000 and a host confirming it was talking to the right board would have passed against the wrong one. Default is now unmistakable; regression test added.

THE LESSON, which is worth more than either bug. The corpus could not have caught the first one. status-is-safe-before-anything-is-configured passes on the host because SimulatedMotion just returns a number. A corpus held by two implementations pins protocol behaviour, not hardware preconditions -- one of the two has no hardware. A green corpus means "the two ends agree about the wire", not "the firmware is right". Anything the firmware does that the host model cannot express is unverified by construction, and the SPI-before-bus class is exactly that.

A latent hazard was closed at the same time: the USB mirror could block when a host connected and stopped reading, stalling the link, the motion poll and the watchdog together. It is now dropped rather than waited on -- losing a diagnostic line is free, losing the link is not.

Stage 4 ran the full motion path on hardware 2026-09-03: hv on, home, arm, moveto, disarm, clrfault, all over the RJ-45 with the motor moving. Homing repeats to about one encoder count; the commanded-move follow ratio is 0.991. ~150 byte-identical ping;9 were each answered and each refreshed the watchdog, which is open question 1's resolution demonstrated on hardware. Measurements in ../mouse-joystick-pcb/docs/bringup-log.md under board 3.

Eight firmware bugs were found by hardware in one session, none of which the shared corpus could have caught: the placeholder serial, STATUS hanging on SPI before the bus existed, a limit field nothing assigned, the missing encoder follow check, the homing driver-enable deadlock, a fault that dropped the flag but not the rail, the loop judging time before reading the link, and the datum offset below. That ratio is the point, not an accident -- see the corpus-limits note above.

A correction to the VALIDATED stage 3 code, not just the new firmware: ENC_LATCH is permanently 0 on rev 0. It latches on the encoder's N event and rev 0 leaves the index no-connect with ENCN terminated by R1201. So MoveReport::latch_encoder and HomeReport::coarse_encoder/fine_encoder -- all filled from that register -- are structurally zero on this hardware. Any stage 3 report showing one should be read as "no data".

RESOLVED: the position-frame offset. Peter's fix -- zero BOTH frames after the clearance move rather than at the switch edge -- removed it and did more besides. moveto -8.0 now reads back angle=-8.016 against xactual=-7.995, agreeing to 10 microsteps; ev;HOMED reports angle=0.0, which is what the shared corpus expects, so firmware and corpus stopped disagreeing on a pinned value; zero became a commandable position instead of one the travel limits exclude; and travel is now -10.125..0.0 deg. XACTUAL is still re-based to XLATCH first so the clearance is measured from the switch edge, which is velocity-independent where the stop position is not.

Also fixed: the approach keyed off status_latch_*, which is read-and-clear. A long approach reached the switch (limit=1) and then hung until the 8 s timeout. status_stop_* are plain status bits that survive polling, and the validated homeToSwitch() already keys off those with an explicit XLATCH fallback -- the non-blocking version had no fallback. And ev;HOMED was reporting the cache from before the datum writes.

WITHDRAWN: the "host must poll faster than the draft implies" measurement. The two observed host_timeout faults were the test harness, not the firmware: MicroPython's UART.read() blocks for its configured timeout on an empty buffer, so a timeout=50 made "20 ms pings" 72 ms and "40 ms pings" ~90 ms against a 100 ms watchdog. The loop-ordering fix stands on its own merits -- the watchdog was genuinely evaluated before the link was read -- but the margin is unmeasured. Set the UART read timeout deliberately before timing this link.

freewheel works on hardware 2026-09-03, and so do both exits. The compliant state entered from ARMED, status reported FREEWHEEL, and the encoder moved 0.133 deg while the ramp generator did not -- the divergence that makes angle and xactual two quantities, observed without touching the mechanism. moveto re-engages implicitly, stop takes the joystick back, disarm leaves it held, and after disarm both frames read identically.

Bug found: leaving FREEWHEEL never re-energised the driver, despite a comment claiming the move "re-engages implicitly". All three exits were separate omissions and now share one leaveCompliance(). Third time the encoder follow check has caught a state transition that forgot to energise what it was about to use -- the other two were homing and, indirectly, the same pattern at arm. That check has paid for itself repeatedly and should not be weakened.

OPEN: sub-degree discrepancies at the release/re-engage boundary. After freewheel -> moveto, xactual=-2.995 against angle=-3.691 (0.70 deg); after freewheel -> stop, 0.27 deg. Leading hypothesis is the rotor snapping when the driver re-energises -- a stepper's electrical angle repeats every four full steps, bounding it at ~+/-3.6 deg here, and both figures fit. The candidate fix is to re-enable BEFORE resyncing so the resync captures the post-snap truth, deliberately not done because energising against a stale XACTUAL would aim the snap at where the ramp generator thought the joystick was. Needs a measurement: park, freewheel, hand-move a known distance, read both frames before the re-engage, immediately after, and after the resync.

Stage 4's rev-0 protocol surface is fully exercised on hardware, 2026-09-03. PULL fires at the crossing (-8.016 against an armed -8.0, twice), and the raw encoder edges captured on the InstrumentPort corroborate the driver's X_ENC to 3-8 counts on a ~15 deg hand pull with zero invalid transitions. So every "anomalous" encoder reading earlier in the session was real motion, and the register can be trusted. Measurements in ../mouse-joystick-pcb/docs/bringup-log.md under board 3.

The identity beacon earned itself. The analyzers were power-cycled to clear a wedged capture and came back in opposite USB ports, silently inverting the topology-to-board mapping while the probe cables stayed put -- a capture was taken on the wrong instrument before Peter noticed the wrong analyzer blinking. The beacon re-established the mapping in one shot. examples/PyControlLink now emits it at boot, because the I command exists only in the bench consoles and the protocol firmware was the one case where identification was impossible without reflashing.

Bench consoles can wedge on USB CDC output. MotionAndHoming blocked its own loop on a Serial.print with no host draining, which enumerates fine but stops answering and stops honouring the 1200 baud reset -- recovery needed SW501. PyControlLink is guarded via usbMirror(); the three consoles are not. Worth the same guard if they are touched again.

Read .agents/handoff.local.md for bench state and the immediate next actions.

Milestones

• [x] Pixi + PlatformIO environment, mirroring the TMC51X0 layout
• [x] src/BoardPins.hpp derived from U501's pad-to-net map at PCB tag v0.1
• [x] Confirmed PCB tags v0.1 and v0.2 have byte-identical RP2040 pad maps
• [x] SafeState — safe idle without energising anything
• [x] examples/RP2040SelfTest — clocks, flash, RAM, pads, pull resistors, ADC
• [x] Boot signature and heartbeat on FW_TRIG0/FW_TRIG1, so firmware execution is observable without USB
• [x] MJ_BOARD_REV so the spare-pad test matches the revision being built
• [x] Compile clean on mouse_joystick, mouse_joystick_safeflash (was _fastflash: the quad-lane stage 2 is the default since 2026-10-06), mouse_joystick_rev1; 7/7 host tests pass
• [x] BOOTSEL enumerates (RPI-RP2 mass storage) — passed 2026-09-01
• [x] Firmware flashes, verifies, and runs — 27 checks, 0 failed, 2026-09-01
• [x] Results recorded in ../mouse-joystick-pcb/docs/bringup-log.md, 2026-09-01
• [x] LA5032 channel map confirmed against the boot signature, 2026-09-01, and recorded in the adapter's own bring-up log
• [x] Stage 2 written: examples/TMC5130Communication. Builds clean, plus 8 host tests pinning the register decoding and the expected-IOIN claim.
• [x] Stage 2 run on hardware 2026-09-01 — reached gate 2 and stopped there
• [x] 36 V power chain shown to work at least momentarily: rail up in 3 ms to 3.309 V, measured
• [x] 36 V rail collapse resolved 2026-09-02 — R203 straps the switch's LATCH high, so it cannot auto-retry through the inrush. Worked around by PowerSequence::staircaseStart(); the real fix is a board change, tracked in ../mouse-joystick-pcb/.agents/PLANS.md
• [x] Stage 2 gates 4 and 5: bus switch closed, TMC5130A IOIN read, both boards, 2026-09-02
• [x] Stage 3: motion, encoder and homing, passed 2026-09-02 on board E4654C159F4D1334, with vsense = 1 set and read back before the output stage was ever enabled
• [ ] Resolve whether the motor's 0.6 A rating is RMS or peak, and set the run current ceiling deliberately. Needs a coil-current measurement
• [ ] Run stage 3 on board E4654C159F2C2534, whose empty-connector REFL_STEP = 1 is still unexplained
• [x] Stage 4 host environment, 2026-09-02. pycontrol pixi environment (no-default-feature, so no PlatformIO), tools/pycontrol_task.py, and pycontrol/. Resolved and locked for linux-64, osx-64, osx-arm64 and win-64 — the rig PC is Windows 11, which is what ruled out a Guix-only environment. Verified: PyQt6 6.11.0 / pyqtgraph 0.14.0 / numpy 2.5.2 / pyserial 3.5 against pyControl v2.1.1; 6 environment tests pass; firmware env unchanged at 33/33
• [x] Stage 4 host half: framing codec, device class, simulator, 22-case corpus
• [x] Stage 4 firmware half: src/Protocol.hpp + src/ProtocolBoard.hpp, held to the same corpus by test/native/test_protocol/. 2026-09-03
• [x] Stage 4: protocol layer wired to a real UART and real motion — MotionBackend seam, TmcMotion, PycUart, examples/PyControlLink. 2026-09-03, not yet run on hardware
• [ ] Stage 4: two-stage homing over the protocol (single-stage today)
• [ ] Stage 4: pyControl UART protocol on hardware (Gate E)
• [x] Host half written and green, 2026-09-02. 128 tests. pycontrol/devices/mouse_joystick_protocol.py (codec, runs on the board and under pytest), pycontrol/sim/board_sim.py (simulator with an injected clock), pycontrol/devices/mouse_joystick.py (device class, asserts on port.UART and on duplicate event_name), pycontrol/tests/fixtures/protocol_cases.txt (22-case shared corpus), plus a bring-up hardware definition and task
• [x] Narrowed to rev-0 hardware, 2026-09-02. ANGOUT/ANGSCALE removed (analog outputs not populated); FREEWHEEL and a compliant state added; STATUS now reports angle (encoder) and xactual (ramp generator) separately; encoder resync on leaving compliance only. Findings appended to ../mouse-joystick-pcb/docs/uart-protocol.md as open questions, without changing its command table
• [ ] Protocol framer/parser in src/, and a host-native test that reproduces protocol_cases.txt. Until this exists Gate C is NOT passed: a simulator agreeing with a corpus only it has been checked against says nothing about the RP2040. The corpus is line-oriented so the C++ side is getline plus a prefix compare, no JSON library
• [ ] Resolve the six protocol findings below before freezing the draft
• [ ] Gate E on the Breakout 1.2, then deliver to joystick-rig

Protocol Findings, 2026-09-02

Raised by implementing ../mouse-joystick-pcb/docs/uart-protocol.md (Draft v0.1). All six are now written up in that file under "Open Questions From The First Implementation", which is where they should be resolved - this repository implements the protocol and does not define it. Summarised here because they gate Stage 4.

1. ~~The retransmission rule breaks the heartbeat.~~ RESOLVED 2026-09-03, and not by exempting PING. It was a layering error: the watchdog measures host liveness, so it is now reset on receipt of any well-formed command, before dispatch and regardless of a cache hit — badframe excepted, so a wedged serial driver cannot hold the safety timeout open. The cache is separately restricted to state-changing commands, classified on the parsed command because CAL/INSTR/HV are each a read or a write depending on their argument. Cache bounded at 2. Note MOVE is the only non-idempotent command in the set, so the cache guards one verb and could go entirely if the trial uses only absolute positioning. Implemented in pycontrol/; the corpus did not change. Owned by ../mouse-joystick-pcb/docs/uart-protocol.md, open question 1.
2. The 100 ms host timeout is shorter than a long move. At 180 deg/s an 18 degree move consumes the whole timeout, and travel is 40 degrees wide. The host must ping during motion. Possibly fine, but it should be written down rather than discovered. Confirm the real velocity and the real timeout together.
3. The command set does not match the trial. The draft models a pull as detection (ARMPULL threshold); the rig needs it as mechanical resistance - brake sets the force, motor gets out of the way. Trial shape is park, present, release, pull, present again.
4. Brake-then-release cannot be two host commands. The brake must engage before drive is released or the joystick drops. Belongs in one firmware operation, BRAKE <torque>. FREEWHEEL is a rev-0 stand-in to be replaced.
5. STATUS's "position" is two quantities once there is a compliant state - measured and commanded, disagreeing by the whole pull.
6. Resyncing XACTUAL from the encoder deletes the stall detector. Resync only on leaving compliance. Stall detection is unimplemented: it needs a fault bit the draft does not have, and bit 4 is retired for a different comparison.

Update 2026-10-01: findings 3, 4 and 5 are closed by protocol v1 (proto=2, signed off and recorded in ../mouse-joystick-pcb/docs/uart-protocol.md, "Protocol v1 Proposal"): BRAKE <torque> replaces FREEWHEEL (release-only until a board has the brake), WATCH replaces ARMPULL with thresholds relative to the release angle and one TRIAL summary per arming, STATUS carries torque, brake and t, and CFG, chunked FETCH and STREAM are new. Implemented in src/, pycontrol/ and both test runners the same day, compiled into PyControlLink and PyControlLinkQp, not yet run on a board. Finding 6 stands.

Waiting On The Researcher

Not blocking Stage 4, but they change the command set when answered. Raised 2026-09-02; the researcher has not scoped the task yet.

• What the joystick must do in a trial - whether MOVETO/MOVE/ARMPULL is the right vocabulary, or whether a hold-against-force mode is needed
• Whether move speed and motor current should be adjustable or fixed defaults. Current stays out of the protocol either way, per the draft's "deliberately absent" list; speed would be named profiles, not raw numbers
• Whether rev 0's UART-latency-only event path is acceptable for a pilot. ../mouse-joystick-pcb/docs/pycontrol-interface.md: "fine for exercising the interfaces, not fine for behavioural data"
• On heartbeat loss mid-trial, whether latching a fault and requiring CLRFAULT is the behaviour they want, given it ends the session
• ~~Which Breakout 1.2 ports the two boards get~~ — assigned 2026-09-03: ports 1 and 4. Requested of the researcher: move the reward solenoid from port_4.POW_A to port_5.POW_A. Awaiting confirmation that it is done — that is the only thing standing between this assignment and a working link. Port 3 stays with LaserLickPort, which needs the one port having both I2C and a free DIO_C. Reasoning in ../mouse-joystick-pcb/docs/pycontrol-port-pinout.md
• Whether one RSYNC output can drive both boards - still open in Gate A of pycontrol-interface.md, and now sharper: Breakout 1.2 has two BNCs and both are already in use (camera trigger, opto gate), against six lines wanted at rev 1

Controller Decided 2026-09-02

Breakout Board 1.2. UART-capable ports 1 (UART4), 3 (USART1), 4 (USART3), from devices/breakout_1_2.py. Two boards fit with a port spare.

This closes the "Which breakout the lab actually deploys" unknown in Gate A of ../mouse-joystick-pcb/docs/pycontrol-interface.md, and it means no breakout_h7.py is needed. pyControl v2.1.1 declares no port.UART for any H7 port, so the H7 breakout would have required writing and upstreaming that driver first. It does not block anything now.

Revision Facts Established 2026-09-01

Read from git show <tag>:kicad/mouse-joystick-pcb.kicad_pcb, footprint U501:

• v0.1 and v0.2 RP2040 pad-to-net maps are byte-identical. The ambiguity over which was manufactured does not affect firmware.
• HEAD differs on three pins only: GP10, GP11, GP13. HEAD routes them to the rev 1 DAC80501; v0.1 leaves them unrouted. Handled by MJ_BOARD_REV.
• Designators rotated between v0.1 and HEAD. The 36 V input block went from U201/R20x to U1901/R190x. R1901/R1902 are 100 ohm pyControl series resistors at v0.1 and 1 kohm HV_EN/HV_DIAG_EN series resistors at HEAD. All designators in this repository are v0.1 designators.
• v0.1 has three SN74LVC125A buffers (U1601, U1701, U1801), all on +3.3V_MCU. HEAD has a fourth, U2101, for the DAC bus.
• Every instrumentation buffer input is resistor-held, including the encoder taps (R805/R806 100 kohm to GND), so enabling the port floats nothing.
• USB is USB-C (J301, CC1/CC2 via 5.1 kohm), with U301 USBLC6-2P6 on the data pair. MCU power chain: VBUS -> D301 Schottky -> +5V_MCU -> U701 TPS73733 -> +3.3V_MCU. pyControl's 5 V ORs in through D1901.
• BOOTSEL is the standard circuit: SW501 shorts ~{USB_BOOT} to GND, R505 1 kohm to QSPI_SS, R504 10 kohm pull-up to +3.3V_MCU.
• Flash is U502 W25Q128JVZPIQ, 16 MiB, matching the build configuration.
• The TMC5130A's clock is an external 16 MHz oscillator X1201, powered from +3.3V_SW. It is dead until HV_EN is raised — a stage 2 consideration.

Confirmed On Hardware 2026-09-01

Board serial E4654C159F2C2534, 36 V absent, USB only.

• The generic board definition boots this board with boot2_generic_03h_4. mouse_joystick_fastflash is untried on hardware. (2026-10-06: tried, measured, and made the default; the generic one is mouse_joystick_safeflash now.)
• Flash is really 16 MiB. No aliasing at +2, +4 or +8 MiB, and picotool verified the whole image byte for byte.
• Clocks are nominal: clk_ref 12000 kHz, clk_sys 133000 kHz measured, clk_peri/clk_usb/clk_adc 48000 kHz.
• Crystal Y501 absolute error is below this method's noise floor — −18.7 ppm apparent over 9 s against host time.monotonic(), where USB CDC jitter alone is order 110 ppm. Consistent with a healthy +/-30 ppm part.
• All four resistor-defined levels are correct: R601 7.87k holds the GPIO bus isolated at reset, the buffer OE pull-ups hold the instrument port silent, R403 holds pyControl RX idle high, R205 is present with no latched fault.
• All 12 spare pads move both ways. No solder defects on any unrouted GPIO.
• +3.3V_SW reads 0.034 V with HV_EN low — the switched domain is genuinely off and R401/R402 hold it there. HV_SNS 0.016 V. Die 26.2 C.
• The 1200-baud touch works, so reflashing needs no button and no physical access to the board.

Still Unconfirmed

• ~~The LA5032 channel mapping.~~ Confirmed: the rev 0/1 map through the adapter v1.0 carried the stage 1 to 3 captures, and the v1.0 Digital-50 map through the adapter v2.0 was confirmed straight (CHn observes DIGn) on 2026-10-05 (bring-up log, unit E4654C159F274534).
• env:mouse_joystick_fastflash on hardware. (Done 2026-10-06, see the tick budget item.)
• Everything on the far side of HV_EN: the switched rails, the TMC5130A, the 16 MHz oscillator X1201, the motor, encoder, and limit switch.

Known Documentation Conflict

../mouse-joystick-pcb/docs/power.md says HV_SNS and ~{HV_FAULT} "sit behind" the GPIO isolation bus switch and cannot be read until firmware enables it. The GPIO table in docs/interface-map.md marks both byp, and the board's pad-to-net map agrees at both v0.1 and HEAD: GP28/GP29 reach the 36 V switch directly, with no underscore-suffixed twin net. power.md is stale on this point. This firmware follows the netlist. Worth fixing in the PCB repository.

Build-System Trap, Fixed 2026-09-01

lib_deps = src/MouseJoystickBoard — a bare local path — made PlatformIO copy the directory into .pio/libdeps/ and never refresh it, so edits to the library's .cpp files were silently not compiled and builds reported success while testing stale code. Several "passing" builds during initial development were affected. Fixed by declaring symlink://src/MouseJoystickBoard and adding src/MouseJoystickBoard/library.json, which symlink:// requires. Verified with a #error canary.

TMC51X0 uses the same bare-path arrangement (lib_deps_local = src/TMC51X0) and so has the same trap. Worth fixing there.

The 36 V Rail Collapse (resolved, 2026-09-02)

The blocking issue. Full detail and raw data references in .agents/handoff.local.md; the durable summary:

Symptom. HV_EN high with 36 V on J201: +3.3V_SW reaches 3.309 V at t=3 ms, holds rock steady, collapses at t=56-57 ms and stays down. Repeatable to ±1 ms. Captures in ../mouse-joystick-pcb/docs/captures/2026-09-01/.

Ruled out. A resistive short — +36V_SW to GND measures 0.87 MΩ with a DMM, board unpowered. A too-low bench supply limit — the supply was not limited and can deliver 4 A. Note the DMM result does not rule out a voltage-dependent load.

Leading hypothesis. Capacitive-charging thermal shutdown in U201, which tps1htc100-q1.pdf explicitly warns about. Charging +36V_SW's ~208 µF to 36 V costs ½CV² = 135 mJ independent of the current limit, T_REL is 60 °C, and R203 ties LATCH high which disables the auto-retry TI says is acceptable for high-impedance loads. 0.87 MΩ is a high-impedance load.

Not yet distinguishable. Whether U201 turned off or U901/U1001 shut down. Only +3.3V_SW is instrumented; +36V_SW and +5V_SW reach neither the MCU nor the InstrumentPort. This cannot be resolved from firmware — it needs a scope directly on those two rails. Do not add more ADC reads hoping to close it.

Trap. HV_SNS at VSNSFH does not identify a fault. Per Table 7-2 that level is shared by overcurrent, overvoltage, short-to-ground and thermal shutdown, and with EN low it is also OFF-state open-load. An earlier diagnosis of "continuous 1.15 A load" came from misreading it and was wrong.

If confirmed, the fix is a board change, not firmware: reduce bulk capacitance, raise R206 to lower I_CL and spread the same energy over more time, or free LATCH for auto-retry. Raising I_CL does not help.

Stage 3, Passed 2026-09-02

Full procedure, measurements and the reasoning behind each gate are in docs/motion-bringup.md. The durable summary:

It uses TMC51X0. Stage 2 deliberately did not, because first contact with a bus should not also be first contact with a library. Stage 3 needs a ramp generator, an encoder scaler and homing, TMC51X0 has all three, and the bus was already proven. Pinned to tag 4.0.3 in platformio.ini and declared again in src/MouseJoystickBoard/library.json — lib_ldf_mode = off means PlatformIO will not find it from an #include.

src/MotionSetup.hpp is glue, not a driver. It holds only what the library cannot know: the 16 MHz external clock, the 0.15 ohm shunts, the motor's rating, the encoder's resolution, the rig's travel, and CHOPCONF.vsense.

The one bit that matters. TMC51X0's Registers::Chopconf has no VSENSE field — it follows the TMC5160 layout, where bit 17 does not exist. On a TMC5130A that bit is vsense, and with 0.15 ohm shunts it is a factor of 1.8 in motor current. IHOLD_IRUN is write-only, so the current scale can never be read back; CHOPCONF is the readable half of the decision. Firmware sets bit 17 with a raw register write, reads CHOPCONF back, and refuses to enable the output stage unless the read-back says 1. It does not survive a device reset or recoverFromDeviceReset() — re-assert and re-verify after any power cycle of the switched domain.

Measured facts about the rig, all of which were unknown before:

• Travel is ~4000 microsteps, 28 deg at the motor shaft: the limit switch bounds the positive end, a mechanical stop bounds the negative end. Every bring-up distance has to fit inside it.
• The limit switch is active high (REFL rests low, goes high when hit), throw 256 microsteps, and it is at the positive end of travel. It is wired to REFL, which stops negative motion, so SW_MODE.swap_lr is required or the hardware stop guards the wrong direction.
• The encoder counts down as XACTUAL counts up. ENC_CONST resets to zero so X_ENC does not count until it is written, and the negation is −13 + 0.2, not −12 and 0.8, because the fraction is always added. Bench-confirmed: the other encoding gives a ratio of 0.875 instead of 1.000.
• The switch's reporting delay is 8.74 ms, measured by taking two closing-edge latches at two approach velocities in one position frame. No instrument needed, and it is what justifies two-stage homing.
• Homing is two-stage: a fast approach latching the closing edge, then a slow creep off the switch latching the release edge, which is the datum. It buys accuracy, not precision -- the datum stops depending on approach velocity (89 usteps of offset at 0.200 rev/s versus 4.5 at the creep) and the primary approach can run four times faster. Repeatability is 2-5 encoder counts in both schemes across four series of five runs, and the rig cannot distinguish them at n = 5. An earlier claim that the second stage halved the scatter came from one lucky series and is retracted: a repeatable 8.74 ms delay is a systematic offset, and systematic offsets do not widen spread.

Every move is bounded and encoder-watched. MotionSetup::moveTo() targets a position rather than a stop condition, and compares X_ENC against XACTUAL — the ramp generator advances whether or not the shaft follows, so that comparison is what detects an end stop, a stall, a slipping coupling or a dead encoder. It found the negative end stop on the first attempt without straining anything.

Firmware Traps Found On Hardware, Stage 3

All fixed; do not reintroduce. All four were invisible to a compile and to the host tests, and three would have moved the motor when nothing asked.

• RAMPMODE = hold does not stop the motor, it freezes the current velocity. TMC51X0's Controller::initialize() runs during setupSpi() and leaves VelocityPositiveMode with VMAX = 10, so the chip is commanded to turn from the moment the bus closes. XACTUAL crept to 125 microsteps with the driver disabled, and the motor would have started the instant ~{TMC_DRV_EN} went low. Bring the ramp to a real standstill — velocity mode, VMAX = 0, wait for VACTUAL = 0, then hold.
• A real-unit ramp value can round to zero. One chip unit of acceleration at 16 MHz is 116.4 microsteps/s^2, so asking for the library's default of 10 in real units gave D1 = 0. The datasheet forbids that in positioning mode and a TMC5130A with D1 = 0 does not fault — it crawls at about VSTOP. Symptom: VMAX 5368 written, 9.5 microsteps/s observed. conversions::nonZeroRampParameter guards it, with a host test.
• A limit switch must only block the direction that drives into it. Checking both stop status bits refused the move that gets off the switch, in 3 ms. Check only the bit guarding the direction of travel, which is what the hardware does.
• A diagnostic that can be truncated must say so. The encoder round trip ran into the switch, lost part of a leg, and reported the resulting 0.786 ratio as a possible CPR error. Run it away from the switch, and report [inconclusive] when a leg does not reach its target.

Also: reading RAMP_STAT twice loses flags. Several bits are read-and-clear and TMC51X0's leftSwitchActive() / leftLatchActive() / leftStopEvent() each perform their own read, so read it once and decode all of it. MotionSnapshot does.

Stage 2 Design Notes

• Raw SPI, not the TMC51X0 library. Stage 2 asks one question: does this board's SPI path reach the driver. Answering it with a 40-bit datagram nobody has to trust beats answering it with a library that would then be a second unknown. Bringing TMC51X0 up on this board is its own step and starts from a bus already known to work. Byte order and register addresses are copied from TMC51X0's SpiProtocol.hpp and Registers.hpp so the two cannot diverge.
• No register writes at all. A TMC5130A read requires a correct address over MOSI, a clock on SCK, framing on CS, and an answer on MISO, so reads alone prove the whole bus. Writes would buy nothing and add a way to leave the chip misconfigured.
• The load-bearing check is IOIN bit 4, DRV_ENN. It reads back the level firmware drives on GP3 through the bus switch. Nothing else in the test proves that path. Expected IOIN on this board is 0x11000010 with bit 7 (SWCOMP_IN, a comparator output) free.
• Ordering is the whole point of the bus switch. Power up: HV_EN high, wait for +3.3V_SW, settle, then close the bus. Power down: open the bus, then drop HV_EN. Get it backwards and MCU pins drive into an unpowered TMC5130A. PowerSequence enforces this and connectBus() refuses while the rail is down.
• PowerSequence is the only file that raises HV_EN, and it refuses to start unless +3.3V_SW is measurably dead first.
• vsense is reported, never written. Stage 3 owns setting it to 1 and reading it back before it lowers ~{TMC_DRV_EN}.
• FW_TRIG1 goes high for the duration of each register-read burst, so the LA5032 can trigger on ch 17 rising and capture DIG2-DIG5 for the spi decoder.
• Gotcha found: Arduino.h defines bitSet() as a macro, so the helper is named bitIsSet(). A function called bitSet will not compile.

Instrumentation Reach — A Standing Limitation

Worth stating once because it shaped this session. Firmware can see:

• +3.3V_SW, divided, on GP26
• HV_SNS and ~{HV_FAULT}, both only while HV_DIAG_EN is high
• the TMC5130A's registers, once the bus switch is closed

Firmware cannot see +36V_SW, +5V_SW, +3.3V_MCU (it is the ADC reference), or +5V_MCU. InstrumentPort-40 carries no divided motor rail to any AIN by design. Any question about those rails needs a meter or a scope on the board, and there are no test points anywhere. Budget for that rather than trying to reason around it.

Task: Enable The RP2040 Hardware Watchdog (opened 2026-09-08)

Paired with a RUN reset switch added to mouse-joystick-pcb v1.0. Both were justified by the same incident and they cover different halves of it, so neither replaces the other.

The incident: ../mouse-joystick-pcb/docs/bringup-log.md → "STATUS hung the core", 2026-09-03. The board stopped answering the link and stopped honouring the 1200 baud reset touch, so it could not be reflashed. Recovery needed SW501 held through a power cycle with both USB and the RJ-45 unplugged — pulling USB alone leaves the board alive on pyControl's 5 V through the ORing diodes.

• [ ] Enable the RP2040 hardware watchdog. A transient hang then self-recovers unattended, in the rig, with no button and no cables — the STATUS hang would have auto-recovered.
• [ ] Decide the petting point deliberately, and write down why. Petting from the main loop catches a wedged loop, which is the observed failure. Petting from a timer interrupt would have kept petting through that exact hang and bought nothing.
• [ ] Make the reset safe by construction, and verify it on hardware. The board already argues it is: HV_EN releases into R1904 10 kΩ pulling EN low at the TPS1HTC100 so +36V_SW drops, and ~{TMC_DRV_EN} pulls up to +3.3V_SW through R1103 10 kΩ so the driver disables. Confirm that a watchdog reset mid-move actually lands there rather than leaving the motor energised.
• [ ] Guard against a reset loop being worse than a stop. A watchdog reset does not enter BOOTSEL, so firmware that hangs early gives a reset loop that cannot be reflashed out of — the watchdog makes that case harder to escape, and the RUN switch plus BOOTSEL is the only exit. Consider a scratch-register reboot counter so repeated watchdog resets land in a safe halt (rail off, driver disabled, link answering) rather than looping.
• [ ] Record the watchdog reset in STATUS so a reset is visible to the host and to the capture instead of looking like a clean boot. WATCHDOG_REASON distinguishes it from a power-on reset.
• [ ] Note the division of labour in .agents/AGENTS.md: watchdog for "it wedged mid-session", RUN + BOOTSEL for "I just flashed something broken".

Not A Priority

• OTA, filesystem, or EEPROM use. board_build.filesystem_size is 0.
• Anything that energises the 36 V rail, until stage 1 passes.