mouse-joystick-firm/examples/PyControlLinkQp

Stage 4 again, structured as a QP/C++ (v7.3.4, QV kernel) application: the same ProtocolBoard and TmcMotion as examples/PyControlLink, unchanged, inside one active object, with a QS trace leaving the board on FW_TRIG1 so a logic analyser on the InstrumentPort can see what the firmware did, per request, without USB and without touching the pyControl link.

It exists because the only thing QP buys this board is observability, and that had to be measured before deciding anything about the delivery firmware. The measurement is in qp-arduino-example/evidence/2026-10-01-rp2040-joystick-link/ (the pilot this application is derived from) and in the firmware run recorded alongside it (see "Status"). examples/PyControlLink stays the non-QP delivery sketch; nothing here changes the protocol or the pyControl side.

What runs where

The qp-arduino library comes from its released tag on GitHub (https://github.com/QuantumLeaps/qp-arduino.git#v7.3.4) through platformio.ini's [qp_env_data], since 2026-10-04; PlatformIO clones it once into .pio/libdeps and refreshes it only when the pin changes. Before the release it was the sibling checkout ../qp-arduino, linked with symlink://.

Signals and ports

FW_TRIG1 therefore no longer carries the RELEASED level of PyControlLink: that state is a LINK_STATE record. Which marker roles the v1.0 board's InstrumentPort overlay finally assigns is an OBS-IF decision still owed (mouse-joystick-pcb/docs/observability-plan.md); the two uses here are one-line changes.

Trace records

Plus QP's own state transitions, entry/exit and assertions. The per-event dispatch/post/get records are filtered out by default (LINK_QS_FULL=1 keeps them, and saturates the line at a 1 kHz tick).

The sampler under the rail (2026-10-02)

Board 4's second attempt reached breadcrumb 9, hv on complete in 272 ms, and then never idled again: with the bus up every 1 kHz tick polled the TMC5130A, and the handler ran back to back until the watchdog bit. Four things changed:

• Poll cost. TmcMotion::poll reads the encoder alone (X_ENC, two 40-bit datagrams) on every tick and the full snapshot (RAMP_STAT, DRV_STATUS, XACTUAL, VACTUAL, X_ENC: ten datagrams) every tenth tick, where completion, the limit switch and driver faults are decided, so within 10 ms. The SPI clock is kTmcSpiClockHz, 4 MHz, in Conversions.hpp (the library's 1 MHz default was chosen for a 1 MSa/s analyser; the analyser now needs 10 MSa/s to see the clock).
• Overrun guard. If the previous TICK handler ended less than 200 µs before this one starts, the AO is running back to back and the idle loop has had no turn: the tick's work is skipped and counted, so idle always gets one. If the handler exceeds the 400 µs budget three ticks running, polling drops to every other tick until the rail goes down; counted and flagged in SAMPLE_STAT.
• Tick level. In MJ_TICK_LEVEL builds (the three _usb bench builds) FW_TRIG0 is high for the whole TICK handler: the analyser shows the handler's duration directly, back-to-back levels are an overrun, a level that never falls is a stuck poll. The operation marker is then a trace record only; breadcrumb trains still pulse the pin.
• The static accounting behind this is in the evidence README of the run.
• 2026-10-02 12:45, board 4, mouse_joystick_qp_rev0_usb (qp-arduino-example/evidence/2026-10-02-1245-board4-rail-up/): hv on acked in 272 ms, the full v1 trial on real motion, 300 of 300 moves, the watchdog never fired. The tick cost with the rail up is about 640 µs flat while holding and 444 µs p50 moving, which the datagram count does not explain, so the sampler ran decimated at 500 Hz for the whole rail-up period; the next capture includes the SPI lines. Findings and the poll-cost proposal are in that README.

Watchdog and breadcrumbs

Since 2026-10-02 the BSP enables the RP2040 hardware watchdog, 2 s, after SafeState and the USB host wait, and feeds it in QV::onIdle() only: a run-to-completion step that never returns reboots the chip, and the reset drops HV_EN. Q_onError keeps its two-second FW_TRIG0 signature by feeding the watchdog inside it. The reason for a boot and the last breadcrumb are read from the watchdog block and its scratch registers before anything else runs, printed in the banner (Boot: WATCHDOG TIMEOUT, last breadcrumb N) and traced as BOOT_INFO.

BSP::crumb(n) is the breadcrumb: a train of n pulses, 25 µs high and 25 µs low, on FW_TRIG0, and n into watchdog scratch 0. An operation marker pulse is 500 µs or longer, so the two are told apart on the analyzer. A train during a running operation briefly lowers the marker; none of the checkpoints below runs during a move.

The hook into TmcMotion is setCheckpointHook(); PyControlLink does not install one and pulses nothing.

Builds

pixi run build examples/PyControlLinkQp mouse_joystick_qp
pixi run upload examples/PyControlLinkQp mouse_joystick_qp_sim_usb /dev/ttyACM0

Drive the bench build with qp-arduino-example/tools/link_pilot.py and read the trace as evidence/bench-scripts/link_run.sh does (sigrok uart decoder on the FW_TRIG1 channel, 17 through the rev 0/1 adapter the script was written for and 1 on a v1.0 board, bytes to qspy -k -f).

Status

• 2026-10-01: all three environments build; the 114 host tests still pass. The bench build ran on the rev 0 fixture (board E4654C159F2C2534, 36 V unplugged) under the pilot's full sequence: 21 of 21 steps, 1,003 lines and 1,206 replies with none dropped, QS high-water 482 of 2,048 bytes with zero buffer-full, queue and pool never below 15 of 16 and 6 of 8 free, tick exact, host-loss fault 105 ms after the last heartbeat. The delivery build was flashed and its boot sequence captured: signature, beacon, then the trace with READY and a statistics record every second, nothing on UART0. Results in qp-arduino-example/evidence/2026-10-01-rp2040-joystick-firm-qp/.
• Not yet run: TmcMotion behind this AO with the rail up (as for PyControlLink, whose first supervised run it still owes), the UART0 protocol path under QP with a pyControl host, and anything on a v1.0 board, whose GPIO changes (GP24 becomes HV_LATCH, ~HV_FAULT moves, the DAC goes to I2C) are not in BoardPins.hpp yet.
• The RP2040 hardware watchdog task of .agents/PLANS.md applies here as it does to PyControlLink; Q_onError already drops to SafeState before rebooting.
• 2026-10-01, later: protocol v1 (proto=2: BRAKE, WATCH, CFG, chunked FETCH, STREAM, TRIAL, 64-bit event times) in both halves with the corpus rewritten (46 cases, 120 native and 164 host tests), the tick raised to 1 kHz as the sampler with the tick coalesced (one TICK_SIG in flight, lost samples counted in SAMPLE_STAT rather than overflowing the queue behind the rail's soft start), and the rev 1 angle output driven from the tick: bus claimed and GAIN 0x0101 written only after hv=1, parked at the fault code while angleOutputValid() is false, released when the rail drops. Compiled only, in all four environments; nothing was flashed. The sampler cost is instrumented (SAMPLE_STAT max/last, LINK_WORK), not measured: the 400 us budget is a declaration until a run on the fixture.
• 2026-10-01, review: the capture became a ring (TrialWatch): sampled from RELEASED on, frozen post_ms after the outcome around the outcome sample (CFG pre_ms/post_ms, 500/500, sum ≤ 2047), so a pull late in a 10 s trial is captured where the old two-second linear buffer missed it. Corpus, simulator, firmware and device class changed together.
• 2026-10-01, fixture run of the bench build at firmware 0109ca5 (qp-arduino-example/evidence/2026-10-01-rp2040-joystick-ring-capture/): 31 of 31 pilot steps, the whole v1 trial shape including the 1,001-sample window fetched in 32 chunks and 100 stream lines in 2 s. Measured against the 400 µs budget: the sampler tick costs 20 to 60 µs idle, the alarm tick is exact (stdev 10 µs, none lost), but one protocol line costs 1.0 ms (ping) to 2.8 ms (status) to 15.9 ms (a 32-line FETCH chunk), so one sample is coalesced per host line (2,183 of 86,024 ticks, 2.5 %, zero dropped, filled on the grid). The cost is formatNumber's snprintf("%.3f") with software double on the M0+, about 0.5 ms per number, pre-dating this example. Also: a FETCH chunk's 34 LINK_TX records saturate the trace (QS high-water 2,048, 35 buffer-full events). Fixed the same day, below.
• 2026-10-01, no newlib on the line path (qp-arduino-example/evidence/2026-10-01-rp2040-joystick-no-newlib/): Protocol.hpp formats and parses in integer fixed point (exact on the binary value, ties to even, 124 native tests), the cache and queue copy without snprintf, and the trace takes one LINK_TX per FETCH chunk. Rerun on the fixture, 31 of 31 steps: feed cost ping 330 µs (was 1,031), status 519 (2,839), moveto 818 (1,841), a FETCH chunk 1,201 (15,921); coalesced samples 237 of 85,999 (was 2,183), QS buffer-full 4 (was 35), worst tick 694 µs (was 2,379), the window in 217 ms (was 774). Still over one tick per line: moveto (1.13 ms total, the one that coalesces a sample per command), FETCH chunks (1.6 ms), id, watch, brake, stream. The floor of about 450 µs per line, with no number in it, is not attributed yet; splitting LINK_WORK inside feed() is the next measurement, and whether long replies alternate with the tick is a decision, not a default. Accepted as is on 2026-10-02: the floor fits the rig's message rate.
• 2026-10-02, before the rail-up session: FETCH's ack carries lost=N, the window samples that were grid fills after a coalesced tick (spec, corpus, simulator, firmware, device class; a fill-path unit test on each side); the DAC_STATE record; the mouse_joystick_qp_rev1_usb build; the board 4 session script and procedure. Nothing flashed.
• 2026-10-02, board 4, first rail-up attempt (qp-arduino-example/evidence/2026-10-02-board4-rail-up/): identity ok, limits ok (travel [−10.125, 0], v_max 36), then hv on never answered: USB stayed enumerated, the tick probe kept running, the trace and the port went silent, no reset. The active object never returned from the hv LINE handler or the first TICK after it. Static reading found no unbounded wait that differs from PyControlLink's working sequence (panic() is excluded by the live tick), so the firmware gained the hardware watchdog, the breadcrumbs and the rev 0 bisect build above; the reproduction is Peter's, from the bench.

Files