rUv
00a234eda8
Closes the firmware-side ADR-110 design at v0.7.0-esp32 after a 38-iter /loop SOTA sprint. Headline (bench, COM9+COM12 ESP32-C6): - 99.56% cross-board RX, 104.1 µs smoothed offset stdev (≤100 µs §2.4 target met) - 3.95× EMA suppression, 1.4 ppm crystal skew preserved 4 firmware releases: v0.6.7 / v0.6.8 / v0.6.9 / v0.7.0-esp32. 42 ADR-110 unit tests, 1761 v2 workspace tests, full Firmware CI + QEMU green.
4.7 KiB
ADR-110 review guide
This is the one-pager for reviewers of the adr-110-esp32c6 branch / draft PR. The canonical record is docs/WITNESS-LOG-110.md; this guide is just a faster on-ramp.
What this branch ships
A dual-target build for firmware/esp32-csi-node: same source tree compiles for esp32s3 (existing production) and esp32c6 (new research target with Wi-Fi 6 / 802.15.4 / TWT / LP-core). Every C6-only module is #ifdef CONFIG_IDF_TARGET_ESP32C6 gated, so the S3 build path is byte-identical to before.
Five-minute reviewer tour
- Read the ADR:
docs/adr/ADR-110-esp32-c6-firmware-extension.md— design, phases, trade-offs. - Read the witness:
docs/WITNESS-LOG-110.md— 4 sections (A = empirically verified, B = architectural-but-not-measured, C = bugs fixed, D = bugs found but not yet fixed, D-workaround = ESP-NOW pivot). - Skim the new firmware modules:
firmware/esp32-csi-node/main/c6_{twt,timesync,lp_core,sync_espnow}.{h,c}. - Skim the new host decoders + tests:
- Rust:
v2/crates/wifi-densepose-hardware/src/{csi_frame,esp32_parser}.rs(search forPpduType,Adr018Flags,adr110_*test names) - Python:
archive/v1/src/hardware/csi_extractor.py+archive/v1/tests/unit/test_esp32_binary_parser.py(search forTestAdr110ByteEncoding)
- Rust:
- Glance at CI:
firmware-ci.ymlc6-4mbmatrix row runs the C6 build AND the host unit tests on Ubuntu — both green throughout this branch.
Empirical scorecard (what's actually measured)
| Dimension | Status |
|---|---|
| C6 build + boot + dual-target | ✅ verified on 3 boards (COM6/COM9/COM12), CI matrix green, S3 regression green |
| HE-LTF wire format (ADR-018 byte 18-19) | ✅ verified end-to-end across firmware / Rust / Python (17 unit tests) |
| HE-LTF live capture | ⏸ blocked — need 11ax AP (only 11n AP on bench) |
| TWT graceful NACK | ✅ verified live — c6_twt: iTWT setup failed: ESP_ERR_INVALID_ARG captured + handled |
| TWT cadence determinism | ⏸ blocked — same 11ax AP gap |
| ESP-NOW transport TX + stability | ✅ verified — 120 s + 300 s soaks, 4102 cumulative transmits, 0 failures |
| ESP-NOW cross-board RX | ⏸ blocked — 3 of 4 boards dropped USB enumeration mid-experiment |
| Raw 802.15.4 cross-node sync | ❌ broken — IDF v5.4 driver bug, 5 hypotheses tested + rejected; ESP-NOW workaround in place |
| 5 µA hibernation | ⏸ blocked — datasheet number, need INA / Joulescope to measure |
| Witness bundle regenerable + clean | ✅ 6/7 PASS (1 fail is pre-existing Python proof env issue unrelated to ADR-110), all hashes recorded, secret-redacted |
Honest verdict
Protocol layer + transport substrate are bullet-proofed. None of the four headline SOTA dimensions is empirically measured — each is blocked on hardware the bench doesn't have. Each blocker is documented in WITNESS-LOG-110.md §B with the exact instrument needed to unblock it. This branch is the foundation to build measurement on, not the measurement itself.
The five concrete bugs found and fixed during the work (MAC/EUI double-FFFE, dual wifi_pkt_rx_ctrl_t struct variants, LED GPIO 38 on C6, TWT INVALID_ARG propagation, witness bundle secret leak) are independently real and useful regardless of how the SOTA story lands.
Security note for the operator (not the reviewer)
The witness bundle's Python proof step was leaking .env contents into the bundled log via Pydantic validation error dumps. Bundle was nuked before push, and scripts/redact-secrets.py filter was added (commit f8a2e3695). The previously-exposed Docker Hub + PI-cluster tokens should be rotated — they appeared in local session logs even though they never reached origin.
Commits on this branch (chronological)
| # | SHA prefix | What |
|---|---|---|
| 1 | f23e34e |
Initial ADR-110 firmware + ADR + tests + docs + witness scaffolding |
| 2 | 6652384 |
TWT INVALID_ARG graceful + diagnostic counters |
| 3 | 4c39e28 |
PAN-match + 4-experiment D1 record |
| 4 | f8a2e36 |
SECURITY: witness bundle secret redaction |
| 5 | 88be283 |
ESP-NOW transport (D1 workaround) |
| 6 | 3959fab |
Rust host decoder + 6 unit tests |
| 7 | 8eaa92c |
Python host decoder + 5 unit tests |
| 8 | b808a63 |
120 s ESP-NOW soak witness |
| 9 | 89972c0 |
CHANGELOG expanded |
| 10 | fc75a8a |
Fuzz harness extended for byte 18-19 |
| 11 | 9de34ba |
ADR-110 indexed in docs/adr/README.md |
| 12 | 553b07d |
README C6 row tightened (claim → wire-format-ready) |
| 13 | e255b7d |
firmware/README acknowledges S3+C6 |
| 14 | 9a46fc8 |
300 s ESP-NOW soak witness (2.5× sample) |
| 15 | (this commit) | This review guide |