FIRST_BOOT_QC: factory self-test + per-unit throttle calibration capture (v8.1)

[zjwhitehead]

Summary

Implements the FIRST_BOOT_QC design (FIRST_BOOT_QC.md, committed as the first commit of this branch): a factory QC station that runs as a blocking guided flow at the Phase 4/5 boot boundary — automatic POST framed as bus-communication tests, screen-guided per-unit throttle calibration capture, operator-confirmed output checks, a JSON QC record per unit (USB serial + persisted + readable over BLE for silent fleet sync), and a serial run_qc re-entry command.

Zero live-behavior change for the fleet: the throttle mapping stays on the fixed 0..4095 curve. Calibration is capture-only in v8.1; the mapping switch is v8.2, data-gated on the records this release collects. A potRawToPwmCalibrated() scaffold ships tested but wired to nothing.

Fleet-safety contract (the critical bit)

QC entry has exactly two paths: truly fresh NVS (new factory board) or the {"command":"run_qc"} serial command. Existing units (NVS data from ≤ v8.0) are silently back-filled qc_passed=1, never auto-calibrated, and never see the flow. Boot context is captured before refreshDeviceData() (which writes defaults on first boot and would otherwise make a fresh board indistinguishable from a fleet unit). The gate decision is a pure function covered by an exhaustive native decision-table test. No button-hold entry — button-at-boot already means perf-mode toggle.

Design decisions (Zach, 2026-07-04)

• Screen-first, button-minimal UX: the TFT directs every step; the throttle pot is the confirmation input (squeeze past 50% span = confirm, release-gated between checks). Button used only for its own test + absent-device skip-confirms.
• POST = bus tests: I2C (BMP3xx probe + sane pressure), SPI (MCP2515), CAN-ESC (active DroneCAN hardware-info request/response — never a throttle command), CAN-BMS (passive listen), CPU temp, factory-NVS round-trip, throttle ADC idle. LED is cue-only, unrecorded (invisible inside the case).
• Skip-confirm pattern: ESC/BMS absent on the bench → operator button press records "skip" (bare-controller QC passes); no press → "fail" (a dead attached device can't be silently skipped).
• Storage: new "openppg-factory" NVS namespace (15-char limit; house rule: never abbreviate) — survives user factory reset. Keys: qc_passed, qc_fw, pot_cal, pot_min, pot_max, qc_rerun, qc_record.
• Calibration gates: span ≥ 2000, idle ≤ 800, full ≥ 3200, release-recheck tolerance; 50 Hz stability window (25 samples within 30 counts, median captured); failing capture keeps safe defaults.
• BLE fleet sync: QC_RECORD_UUID on the config service using the proven ESC_PARAM_DATA paged-fetch pattern; the app reads it silently on connect → Supabase (app-side lands in the app repo).

Verification

• Native tests: 84/84 (29 new in test/test_qc: gate decision table, cal gates, stability window, v8.2 mapping scaffold, JSON golden)
• Screenshot suite (CMake/CI path): 32 pass + 4 new QC references; the 2 SplashScreen failures are pre-existing on the base branch (verified via stash) as is the pio native-screenshot env linker error on macOS
• Embedded build: OpenPPG-CESP32S3-CAN-SP140 SUCCESS
• cpplint (CI flags): changed files clean (5 pre-existing errors in the ESC relay files, untouched here)

Outstanding before merge/tag

plans/005-first-boot-qc-v81.md carries the 10-item HIL bench checklist (fresh unit, fleet-simulation must show zero QC UI, bare controller skip-confirms, dead-ESC fail, bad-pot rejection, BLE read-back, factory-reset survival, WDT idle) plus STOP conditions. Bench tooling: tools/qc_bench_logger.py.

🤖 Generated with Claude Code