docs: controller telemetry ring buffer — feasibility, design, bench plan (T1–T6, L1–L4) + 2-day merge/bench plan (no code)

[mbreiser]

Docs only, no code.

docs/development/controller-telemetry-ring-buffer-proposal.md

Answers can the G6 controller keep an event log without touching the SD card, and can the host drain it live? — the alternative to the SD-card event-log shape of Linear LAB-149, and the logging side of the analog-acquisition handover (F3/S4).

• Feasible; the controller is not the bottleneck. Firmware survey (2026-09-07): flat cooperative loop(), two trivial ISRs, one choke point for "frame displayed" (transmitOnRefresh → transferFrame) and one for commands; ~456 KB unused OCRAM, ~132 KB free DTCM; micros() everywhere; no telemetry today. Worst-case traffic (500 fps + 100 Hz commands + 1 kHz 2-ch analog) is 12.6 KB/s, < 1 % of USB CDC; a 5 s ring is 62 KB.
• The obstacle is the wire protocol: framed replies are capped at 197 B (one-byte length, 200 B response buffer); the only long-reply path is the raw bulk path that macOS Chrome loses bytes on (macOS Chrome Web Serial loses bytes during bulk 0x84/0x8A reads (affects SD Download + live previews) #153). Proposal drains with an ack-cursor (lossless re-send) and tests two framings: (A) chunked ≤197 B (default prior), (B) bulk.
• Yoked records: with analog on, one fixed-rate TICK [frame_idx, ain1, ain2] replaces per-frame events; otherwise sparse FRAME / CMD / STATE events (the LAB-149 payload). Opcodes 0xA8/0xA9 as reserved by firmware PR update README (test) #47.
• Michael's questions answered (§ 7–9): two files first (binary sidecar via the bridge, integrate later); controller µs on every record + per-block clock pairs → per-run linear fit (crystal drift is 50–150 ms over 40 min); and a glass-to-glass latency plan for FicTrac closed loop — segments S1–S5 across the camera, PC and controller clocks, with L1 (simulator UDP + AD3 marker vs photodiode) validating the log-reconstructed sum. Only the camera segment needs its own one-time bench measurement.
• Bench plan T1–T6 + L1–L4 on a throwaway firmware branch before any production code; decisions for the group in § 6.

docs/development/merge-bench-plan-2026-09-08.md

Two-day checklist for landing the open stack: run-log v2 (#186/#188, gate B1), Analog In S1 (#190, B2), firmware F1/F2 (#46/#47, B3/B4), S2 (#191), then #178/#175 cleanup. Records the process rules that bit on 2026-09-07 (stacked PRs get no CI until retargeted; squash-merging a parent leaves the child conflicting; never --delete-branch on another PR's base).

🤖 Generated with Claude Code