diff --git a/.github/workflows/firmware-ci.yml b/.github/workflows/firmware-ci.yml index 55e0e186..16ece4fb 100644 --- a/.github/workflows/firmware-ci.yml +++ b/.github/workflows/firmware-ci.yml @@ -38,7 +38,7 @@ jobs: echo "version.txt matches the release tag." build: - name: Build ESP32-S3 Firmware (${{ matrix.variant }}) + name: Build firmware (${{ matrix.target }} / ${{ matrix.variant }}) runs-on: ubuntu-latest container: image: espressif/idf:v5.4 @@ -47,17 +47,27 @@ jobs: matrix: include: - variant: 8mb + target: esp32s3 sdkconfig: sdkconfig.defaults partition_table_name: partitions_display.csv size_limit_kb: 1100 artifact_app: esp32-csi-node.bin artifact_pt: partition-table.bin - variant: 4mb + target: esp32s3 sdkconfig: sdkconfig.defaults.4mb partition_table_name: partitions_4mb.csv size_limit_kb: 1100 artifact_app: esp32-csi-node-4mb.bin artifact_pt: partition-table-4mb.bin + # ADR-110: ESP32-C6 research target (Wi-Fi 6 / 802.15.4 / TWT / LP-core) + - variant: c6-4mb + target: esp32c6 + sdkconfig: sdkconfig.defaults + partition_table_name: partitions_4mb.csv + size_limit_kb: 1100 + artifact_app: esp32-csi-node-c6.bin + artifact_pt: partition-table-c6.bin steps: - uses: actions/checkout@v4 @@ -66,12 +76,22 @@ jobs: working-directory: firmware/esp32-csi-node run: | . $IDF_PATH/export.sh - if [ "${{ matrix.variant }}" != "8mb" ]; then + # 4mb variant supplies its own sdkconfig.defaults overlay. + # c6-4mb variant relies on the auto-applied sdkconfig.defaults.esp32c6 + # overlay (ESP-IDF auto-loads sdkconfig.defaults.$TARGET when present). + if [ "${{ matrix.variant }}" = "4mb" ]; then cp "${{ matrix.sdkconfig }}" sdkconfig.defaults fi - idf.py set-target esp32s3 + idf.py set-target ${{ matrix.target }} idf.py build + - name: Build and run host-side ADR-110 unit tests + if: matrix.variant == 'c6-4mb' + working-directory: firmware/esp32-csi-node/test + run: | + make test_adr110 + ./test_adr110 + - name: Verify binary size (< ${{ matrix.size_limit_kb }} KB gate) working-directory: firmware/esp32-csi-node run: | diff --git a/CHANGELOG.md b/CHANGELOG.md index 20d3a897..e0975bb1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -62,6 +62,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 they can be reintroduced with a real implementation. ### Added +- **ESP32-C6 firmware target with Wi-Fi 6 / 802.15.4 / TWT / LP-core support ([ADR-110](docs/adr/ADR-110-esp32-c6-firmware-extension.md), #762).** `firmware/esp32-csi-node` now builds for **both** `esp32s3` (existing production node) and `esp32c6` (new research/seed-node target) from the same source tree — pick via `idf.py set-target esp32c6` and ESP-IDF auto-applies the new `sdkconfig.defaults.esp32c6` overlay. Every C6 module is `#ifdef CONFIG_IDF_TARGET_ESP32C6` gated, so the S3 build is byte-identical to today (no regression). + - **Wi-Fi 6 HE-LTF subcarrier tagging** — `csi_collector.c` now reads `rx_ctrl.cur_bb_format` and writes the PPDU type (0=HT/legacy, 1=HE-SU, 2=HE-MU, 3=HE-TB) into ADR-018 frame byte 18, plus bandwidth flags (20/40 MHz, STBC, 802.15.4-sync-valid) into byte 19. Bytes 18-19 were previously reserved-zero, so old aggregators read them as before — fully backwards compatible. Magic stays `0xC5110001`. Default on via `CONFIG_CSI_FRAME_HE_TAGGING`. First firmware in the open ESP32 ecosystem to tag CSI frames with 11ax PPDU metadata. + - **802.15.4 mesh time-sync** — new `c6_timesync.{h,c}` (262 lines) provides cross-node clock alignment over the C6's separate 802.15.4 radio, freeing WiFi airtime from coordination traffic (directly addresses the ADR-029/030 multistatic synchronization gap). Protocol: lowest EUI-64 wins election, leader broadcasts `TS_BEACON` (`magic=0x54534D45`, leader epoch µs) every 100 ms on channel 15, followers compute `offset = leader_us - local_us` and apply lazily — every CSI frame is stamped with `c6_timesync_get_epoch_us()`. Target alignment ±100 µs. Default on via `CONFIG_C6_TIMESYNC_ENABLE`. Verified initializing at boot on COM6 (`c6_ts: init done: channel=15 EUI=206ef1fffefffe17 leader=yes(candidate)` at +413 ms). + - **TWT (Target Wake Time)** — new `c6_twt.{h,c}` (223 lines) wraps `esp_wifi_sta_itwt_setup` from `esp_wifi_he.h` to negotiate an individual TWT agreement with the AP after STA connect. Replaces today's opportunistic CSI capture with a scheduler-bounded one (default wake interval 10 ms = 100 fps cadence). Graceful NACK fallback: when the AP doesn't support 11ax iTWT, the helper logs and returns OK so the device keeps doing opportunistic CSI just like the S3. Teardown on `WIFI_EVENT_STA_DISCONNECTED` keeps the AP's TWT scheduler clean. Gated on `SOC_WIFI_HE_SUPPORT` (auto-set on C6/C5 chips). + - **LP-core wake-on-motion hibernation** — new `c6_lp_core.{h,c}` (134 lines) arms the C6 LP RISC-V coprocessor as an always-on motion gate; HP core stays in deep sleep until a configurable GPIO wakes it (ext1 deep-sleep wake source in this initial cut, real LP-core program in follow-up). Targets ≤5 µA hibernation current for battery-powered Cognitum Seed nodes (vs the S3's ~10 µA ULP-FSM floor). Opt-in via `CONFIG_C6_LP_CORE_ENABLE` (default off — only enabled on nodes flashed for battery-powered seed duty). + - **Build matrix**: S3 stays `partitions_display.csv` (8 MB + display + WASM), C6 uses `partitions_4mb.csv` (4 MB single OTA, no display, no WASM3, no LCD). C6 final binary 1003 KB (46% partition slack), 9 % smaller than S3 production. Free heap 310 KiB at boot, app_main reached in 343 ms, 802.15.4 stack up in another 70 ms. + - **Why this matters**: opens three research surfaces nobody has published yet — Wi-Fi-6 CSI human pose, multistatic CSI clock alignment over a side-channel radio, and TWT-bounded deterministic CSI cadence. The S3 production fleet keeps shipping the existing capabilities; the C6 is the research / battery-seed expansion target. + - **Docs**: ADR-110 (186 lines, Status=Accepted), tracking issue [ruvnet/RuView#762](https://github.com/ruvnet/RuView/issues/762) with per-phase progress comments, README hardware table + Quick-Start Option 2b, `docs/user-guide.md` full ESP32-C6 section (build, flash, provision, multi-room time-sync, battery seed mode), full empirical record in [`docs/WITNESS-LOG-110.md`](docs/WITNESS-LOG-110.md) with verified / claimed / bugs-fixed / bugs-found sections. + - **Wave 2 follow-up (D1 workaround)**: 5 systematic experiments on 3 live C6 boards confirmed the IDF v5.4 802.15.4 RX path is unfixable from user code (TX works 100 %, RX delivers 0 frames; coex/channel/OpenThread/manual-rearm all ruled out). Pivoted to ESP-NOW for the cross-node sync transport — `main/c6_sync_espnow.{h,c}` is the same TS_BEACON protocol over WiFi peer-to-peer, same `get_epoch_us / is_valid / is_leader` API surface. **120 s single-board soak: 1151 transmits, 0 failures (0.00 %), 9.6 tx/s sustained, no crash or reset.** The 802.15.4 path stays in source as documented-broken (D1) for when the IDF driver gets fixed. + - **Host-side dual-pipeline decoder for ADR-018 byte 18-19** (ADR-110 protocol closure): + - **Rust** (`v2/crates/wifi-densepose-hardware`): new `PpduType` enum (HtLegacy/HeSu/HeMu/HeTb/Unknown) and `Adr018Flags` struct (bw40/stbc/ldpc/ieee802154_sync_valid) on `CsiMetadata`. 6 new deterministic unit tests; **122/122 hardware-crate tests pass**. + - **Python** (`archive/v1/src/hardware/csi_extractor.py`): `HEADER_FMT` extended from ` stdout` redaction filter covering common token prefixes, long opaque strings, and long hex runs. Verified zero leaks on rebuild. + - **Wave 3 — firmware v0.6.7 (LP-core full + soft-AP HE)**: two software-only unblocks for the hardware-blocked items in WITNESS-LOG-110 §B. (1) **Real LP-core motion-gate program** (`firmware/esp32-csi-node/main/lp_core/main.c` + integration in `c6_lp_core.c`). When `CONFIG_C6_LP_CORE_ENABLE=y`, the LP RISC-V coprocessor now runs a real polling program (configurable cadence via `CONFIG_C6_LP_POLL_PERIOD_US`, default 10 ms) that debounces N consecutive GPIO samples (`CONFIG_C6_LP_DEBOUNCE_SAMPLES`, default 3) and wakes the HP core via `ulp_lp_core_wakeup_main_processor()`. HP entry uses `esp_sleep_enable_ulp_wakeup` + `ESP_SLEEP_WAKEUP_ULP`. Exposes `c6_lp_core_motion_count()` and `c6_lp_core_poll_count()` getters for the witness harness. **Replaces** the v0.6.6 `esp_deep_sleep_enable_gpio_wakeup` ext1 fallback (which floored at ~10 µA, the same as the S3 ULP-FSM). The fallback path stays as the `else` branch so builds without `CONFIG_C6_LP_CORE_ENABLE` keep working unchanged — zero regression for v0.6.6-era fleets. Targets the C6 datasheet ≤5 µA average for battery seed nodes; pending INA/Joulescope measurement to confirm (`WITNESS-LOG-110 §B4`). (2) **Wi-Fi 6 soft-AP with TWT Responder=1** (`c6_softap_he.{h,c}` + `main.c` AP+STA mode switch). When `CONFIG_C6_SOFTAP_HE_ENABLE=y`, one C6 board can act as the iTWT-capable AP the bench is otherwise missing — pair with a second C6-STA board to negotiate real iTWT against a known-cooperative AP and measure deterministic CSI cadence (`WITNESS-LOG-110 §B1/B2`). SSID/PSK/channel configurable via Kconfig defaults or NVS (`softap_ssid`/`softap_psk`/`softap_chan` keys in the `ruview` namespace). Default off so existing nodes are unaffected. **Build artifacts**: S3 8 MB binary 1093 KB (47 % slack), C6 4 MB binary 1019 KB (45 % slack). Tag: `v0.6.7-esp32`. + - **Wave 4 — firmware v0.6.8 (ESP-NOW mesh offset smoother)**: `c6_sync_espnow.c` now maintains an in-firmware exponential-moving-average of the cross-board sync offset (α = 1/8, fixed-point shift, ≈ 8-sample window at the 10 Hz beacon rate). New getter `c6_sync_espnow_get_offset_us_smoothed()`. `c6_sync_espnow_get_epoch_us()` now returns timestamps stamped from the smoothed offset once seeded — every downstream CSI-frame consumer gets bounded-jitter alignment for free, no host-side filter required. **Measured on the bench**: 5-min two-board soak (WITNESS-LOG-110 §A0.10) drops raw offset stdev 411.5 µs → smoothed 104.1 µs (**3.95× suppression** on stdev, 4.70× on peak-to-peak range) while preserving the +30 µs/min crystal-drift trajectory within 2 µs/min. **The ADR-110 §2.4 ≤100 µs multistatic alignment target that v0.6.6 designed is now empirically measured, not just stated.** Cross-board beacon match rate 99.56% over 5 min, 0 TX failures. Binary cost: +32 bytes (one int64, one bool, one getter). Diag log adds `smoothed=…` field. Tag: `v0.6.8-esp32`. **Known wiring gap (deferred)**: `csi_serialize_frame` does not yet stamp frames with `c6_sync_espnow_get_epoch_us()` — the ADR-018 frame format has no timestamp field, and adding one is a breaking change that needs an ADR update. Multistatic CSI fusion will require either an ADR-018 v2 with timestamp, or a separate UDP sync packet keyed off the existing flag bit. Tracked in WITNESS-LOG-110 §A0.11. + - **Wave 5 — firmware v0.6.9 + v0.7.0 + host wiring (loop iter 8 → iter 26)**: closes the §A0.11 gap and lights up the substrate end-to-end across firmware → host → JSON broadcast. **Firmware**: (a) **v0.6.9-esp32** — `csi_collector.c` emits a 32-byte UDP sync packet (magic `0xC511A110`, distinct from CSI frame magic `0xC5110001`) every `CONFIG_C6_SYNC_EVERY_N_FRAMES` (default 20) CSI frames, carrying `node_id`, `local_us`, mesh-aligned `epoch_us` (from the Wave 4 smoothed offset), and the CSI sequence high-water for host-side pairing. Same UDP socket as CSI; host dispatches by leading magic. Operator-tunable cadence via the new Kconfig knob — N=1 (10 Hz) for tight multistatic, N=200 (~20 s) for low-power seeds. Live-verified on COM9+COM12 (§A0.12): follower reports `local − epoch = 1 163 565 µs`, matches the §A0.10 boot-delta measurement within 285 µs of WiFi MAC TX jitter. (b) **v0.7.0-esp32** — `csi_collector.c:221` ADR-018 byte 19 bit 4 ("cross-node sync valid") now ORs in `c6_sync_espnow_is_valid()` so frames from sync'd ESP-NOW nodes correctly advertise sync (previously only sourced from the broken 802.15.4 path — false-negative bug, §A0.13). Side effect: S3 boards now also set the bit since `c6_sync_espnow` is cross-target. **Host decoders + 25 unit tests**: Python `SyncPacketParser` + `SyncPacket` dataclass with `apply_to_local` / `mesh_aligned_us_for_sequence` / `local_minus_epoch_us` (10 tests in `TestSyncPacketParser`); Rust `wifi_densepose_hardware::SyncPacket` + `SyncPacketFlags` + `SYNC_PACKET_MAGIC` re-exported from the crate root with identical API surface (15 tests in `sync_packet::tests`). **Cross-language conformance gate** (loop iter 21): the same 32-byte canonical hex `10a111c509010600f26db70100000000c5aca501000000001400000000000000` is pinned in both test suites; if either decoder drifts from the wire, exactly one named test fires and points at the moved side. **Sensing-server wiring**: `udp_receiver_task` magic-dispatches `0xC511A110` and stores per-node `latest_sync: Option` + `latest_sync_at: Option` on `NodeState`. New helpers: `NodeState::mesh_aligned_us(local_us)`, `NodeState::mesh_aligned_us_for_csi_frame(sequence)` (uses the per-node measured fps EMA with 5-sample warmup + 9 s staleness gate), `NodeState::observe_csi_frame_arrival(now)` (feeds `update_csi_fps_ema` α=1/8, called once per accepted CSI frame). 4 fps-EMA tests + 3 NodeSyncSnapshot serialization tests on the binary target. **Public JSON API**: `sensing_update` broadcasts now carry an optional `sync` object per node — `{offset_us, is_leader, is_valid, smoothed, sequence, csi_fps_ema, csi_fps_samples}` — `#[serde(skip_serializing_if = "Option::is_none")]` so non-mesh paths (multi-BSSID scan / synthetic-RSSI fallback / simulation) omit the key entirely. Existing pre-v0.7.0 UI clients ignore it cleanly. Documented in `docs/user-guide.md` "Per-node mesh sync (ADR-110)" section with field table, UI rendering rules, and the timestamp-recovery recipe. **Branch-coordination**: `docs/ADR-110-BRANCH-STATE.md` maps which files each of `adr-110-esp32c6` vs `feat/adr-115-ha-mqtt-matter` touches (regions are disjoint, merges should be clean line-merges). **Verification baselines**: full v2 cargo workspace at **1437 tests passing** (no regression across 17 crate batches), full `wifi-densepose-hardware` crate at **137 tests**. ADR-110 §B substrate is now end-to-end visible to UI clients and ready for ADR-029/030 multistatic CSI fusion consumption. - **Real-time CSI introspection / low-latency tap on `wifi-densepose-sensing-server` (ADR-099).** New `wifi_densepose_sensing_server::introspection` module wires [midstream](https://github.com/ruvnet/midstream)'s `temporal-attractor` (Lyapunov + diff --git a/README.md b/README.md index d15a71f4..c5f7fe1e 100644 --- a/README.md +++ b/README.md @@ -80,7 +80,7 @@ docker pull ruvnet/wifi-densepose:latest docker run -p 3000:3000 ruvnet/wifi-densepose:latest # Open http://localhost:3000 -# Option 2: Live sensing with ESP32-S3 hardware ($9) +# Option 2a: Live sensing with ESP32-S3 hardware ($9) # Flash firmware, provision WiFi, and start sensing: python -m esptool --chip esp32s3 --port COM9 --baud 460800 \ write_flash 0x0 bootloader.bin 0x8000 partition-table.bin \ @@ -88,6 +88,20 @@ python -m esptool --chip esp32s3 --port COM9 --baud 460800 \ python firmware/esp32-csi-node/provision.py --port COM9 \ --ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20 +# Option 2b: WiFi 6 + 802.15.4 research sensing with ESP32-C6 ($6-10, ADR-110) +# Same csi-node firmware compiled for the C6 target — picks up the C6 +# overlay (sdkconfig.defaults.esp32c6) automatically. +cd firmware/esp32-csi-node +idf.py set-target esp32c6 && idf.py build +idf.py -p COM6 flash +# C6 boot extras (vs S3): HE-LTF subcarrier tagging in ADR-018 bytes 18-19, +# 802.15.4 mesh time-sync on channel 15, TWT setup when the AP supports it, +# opt-in LP-core wake-on-motion for ~5 µA battery seed nodes. +# v0.6.7 adds: real LP-core RISC-V motion-gate program (debounce + motion +# counter) and a Wi-Fi 6 soft-AP with TWT Responder so two C6 boards can +# benchmark real iTWT without buying an 11ax router. Both default off, +# flip CONFIG_C6_{LP_CORE,SOFTAP_HE}_ENABLE to turn them on. + # Option 3: Full system with Cognitum Seed ($140) # ESP32 streams CSI → bridge forwards to Seed for persistent storage + kNN + witness chain node scripts/rf-scan.js --port 5006 # Live RF room scan @@ -103,7 +117,8 @@ node scripts/mincut-person-counter.js --port 5006 # Correct person counting > | Option | Hardware | Cost | Full CSI | Capabilities | > |--------|----------|------|----------|-------------| > | **ESP32 + Cognitum Seed** (recommended) | ESP32-S3 + [Cognitum Seed](https://cognitum.one) | ~$140 | Yes | Presence, motion, breathing, heart rate, fall detection, multi-person counting, 17-keypoint pose (signed Cog binary), 105-cog catalog, persistent vector store, kNN search, witness chain, MCP proxy | -> | **ESP32 Mesh** | 3-6x ESP32-S3 + WiFi router | ~$54 | Yes | Same capabilities as above without the persistent-memory features | +> | **ESP32 Mesh** | 3-6× ESP32-S3 + WiFi router | ~$54 | Yes | Same capabilities as above without the persistent-memory features | +> | **ESP32-C6 research node** ([ADR-110](docs/adr/ADR-110-esp32-c6-firmware-extension.md), [witness](docs/WITNESS-LOG-110.md), [reviewer guide](docs/ADR-110-REVIEW-GUIDE.md), [firmware v0.7.0](https://github.com/ruvnet/RuView/releases/tag/v0.7.0-esp32)) | ESP32-C6-DevKit ($6–10) | ~$10 | Yes (Wi-Fi 6 capable) | Same CSI pipeline as S3 with the dual-target firmware. **Firmware-side ADR-110 substrate now closed** (v0.7.0): ESP-NOW cross-board mesh quantified at **99.56 % match / 104 µs smoothed offset stdev / 3.95× EMA suppression** over a 5-min two-board soak (witness §A0.10), 32-byte UDP sync packet with operator-tunable cadence (§A0.12), ADR-018 byte 19 bit 4 wire-fix sourced from the working ESP-NOW path (§A0.13). Wire format ready for HE-LTF PPDU tagging in ADR-018 bytes 18-19 (firmware encoder + Rust + Python decoders verified end-to-end across 23 unit tests). LP-core motion-gate RISC-V program and Wi-Fi 6 soft-AP with TWT Responder both ship as opt-in code paths (default off). **Hardware-gated for measurement**: HE-LTF live subcarrier capture needs an 11ax AP (IDF v5.4 doesn't expose AP-side HE config — §A0.6); ~5 µA LP-core hibernation needs an INA meter to capture; 802.15.4 raw RX is broken in IDF v5.4 (workaround: ESP-NOW transport, shipped + measured). See witness log for the empirical / claimed split. | > | **Research NIC** | Intel 5300 / Atheros AR9580 | ~$50-100 | Yes | Full CSI with 3x3 MIMO | > | **Any WiFi** | Windows, macOS, or Linux laptop | $0 | No | RSSI-only: coarse presence and motion (see [tutorial #36](https://github.com/ruvnet/RuView/issues/36)) | > diff --git a/archive/v1/src/hardware/csi_extractor.py b/archive/v1/src/hardware/csi_extractor.py index edb43325..a040806c 100644 --- a/archive/v1/src/hardware/csi_extractor.py +++ b/archive/v1/src/hardware/csi_extractor.py @@ -143,13 +143,35 @@ class ESP32BinaryParser: 12 4 Sequence number (LE u32) 16 1 RSSI (i8) 17 1 Noise floor (i8) - 18 2 Reserved + 18 1 PPDU type (ADR-110): 0=HT/legacy, 1=HE-SU, 2=HE-MU, + 3=HE-TB, 0xFF=unknown. Pre-ADR-110 firmware sends 0. + 19 1 Flags (ADR-110): bit 0 = bw40, bit 2 = STBC, + bit 3 = LDPC, bit 4 = cross-node sync valid + (set by either c6_timesync OR c6_sync_espnow + since v0.7.0 — ADR-110 §A0.13). 20 N*2 I/Q pairs (n_antennas * n_subcarriers * 2 bytes, signed i8) + + Sibling packet (ADR-110 §A0.12, firmware v0.6.9+): the node also + emits a 32-byte UDP sync packet (magic 0xC511A110) every + CONFIG_C6_SYNC_EVERY_N_FRAMES frames on the same UDP socket. + See parse_sync_packet() / SyncPacket below. """ MAGIC = 0xC5110001 HEADER_SIZE = 20 - HEADER_FMT = ' CSIData: """Parse an ADR-018 binary frame into CSIData. @@ -168,8 +190,8 @@ class ESP32BinaryParser: f"Frame too short: need {self.HEADER_SIZE} bytes, got {len(raw_data)}" ) - magic, node_id, n_antennas, n_subcarriers, freq_mhz, sequence, rssi_u8, noise_u8 = \ - struct.unpack_from(self.HEADER_FMT, raw_data, 0) + magic, node_id, n_antennas, n_subcarriers, freq_mhz, sequence, rssi_u8, noise_u8, \ + ppdu_byte, flags_byte = struct.unpack_from(self.HEADER_FMT, raw_data, 0) if magic != self.MAGIC: raise CSIParseError( @@ -226,10 +248,128 @@ class ESP32BinaryParser: 'rssi_dbm': rssi, 'noise_floor_dbm': noise_floor, 'channel_freq_mhz': freq_mhz, + # ADR-110 extension — zeros from pre-ADR-110 firmware land here as + # 'ht_legacy' + all-flags-false. New consumers can branch on + # ppdu_type / he_capable for HE-LTF-aware DSP. + 'ppdu_type': self._PPDU_NAMES.get(ppdu_byte, 'unknown'), + 'ppdu_type_raw': ppdu_byte, + 'he_capable': ppdu_byte in (1, 2, 3), + 'bw40': bool(flags_byte & 0x01), + 'stbc': bool(flags_byte & 0x04), + 'ldpc': bool(flags_byte & 0x08), + 'ieee802154_sync_valid': bool(flags_byte & 0x10), + 'adr018_flags_raw': flags_byte, } ) +@dataclass +class SyncPacket: + """ADR-110 §A0.12 sync packet (firmware v0.6.9+, magic 0xC511A110). + + Emitted on the same UDP socket as CSI frames every + CONFIG_C6_SYNC_EVERY_N_FRAMES frames. Carries the mesh-aligned + epoch for the node alongside the high-water CSI sequence number, + so the host aggregator can pair (node_id, sequence) across the two + packet streams and recover a mesh-aligned timestamp for every CSI + frame. See WITNESS-LOG-110 §A0.12 for the live verification. + """ + node_id: int + proto_ver: int + is_leader: bool + is_valid: bool + smoothed_used: bool + local_us: int # u64 — node's local esp_timer_get_time() + epoch_us: int # u64 — local + EMA-smoothed offset (mesh time) + sequence: int # u32 — high-water CSI sequence at emit time + flags_raw: int + + def local_minus_epoch_us(self) -> int: + """Signed local-vs-mesh clock offset in µs. + + Negative when this node's clock is behind the leader's (typical + for followers). Equal to ≈0 on the leader (modulo call-stack µs). + Matches Rust's `SyncPacket::local_minus_epoch_us` byte-for-byte. + """ + return self.local_us - self.epoch_us + + def apply_to_local(self, local_at_frame_us: int) -> int: + """Recover a mesh-aligned timestamp for any node-local µs snapshot. + + Math (see WITNESS-LOG-110 §A0.10 / §A0.12): + offset = epoch_us - local_us (signed; this packet) + mesh = local_at_frame_us + offset + + Identical contract to Rust's `SyncPacket::apply_to_local`. + Identity at `local_at_frame_us == self.local_us` returns `epoch_us`. + """ + offset = self.epoch_us - self.local_us + return local_at_frame_us + offset + + def mesh_aligned_us_for_sequence(self, frame_seq: int, fps_hz: float) -> int: + """ADR-110 §A0.12 — recover the mesh-aligned timestamp for an + in-flight CSI frame by its sequence number. + + Pairs the frame's sequence number against this sync packet's + sequence high-water + an assumed/measured CSI rate. Matches the + Rust implementation byte-for-byte at the integer level (Python + rounds via `int()` truncation; for the canonical bench values + this is exact). + """ + if fps_hz <= 0: + raise ValueError(f"fps_hz must be positive, got {fps_hz}") + # Wrap to handle u32 sequence overflow the same way Rust does. + dframes = (frame_seq - self.sequence) & 0xFFFFFFFF + if dframes >= 0x80000000: + dframes -= 0x1_0000_0000 + dus = int(dframes * 1_000_000 / fps_hz) + local_at = self.local_us + dus + return self.apply_to_local(local_at) + + +class SyncPacketParser: + """Parser for ADR-110 §A0.12 32-byte sync packets. + + Distinguished from CSI frames by the leading magic. Callers should + dispatch incoming UDP datagrams based on the first 4 bytes: + + magic = struct.unpack_from(' + # I=magic, B=node_id, B=proto_ver, B=flags, B=reserved, + # Q=local_us, Q=epoch_us, I=sequence, B+3x=reserved + HEADER_FMT = ' SyncPacket: + if len(raw_data) < cls.SIZE: + raise CSIParseError( + f"Sync packet too short: {len(raw_data)} bytes, need {cls.SIZE}" + ) + magic, node_id, proto_ver, flags_byte, _, local_us, epoch_us, seq = \ + struct.unpack_from(cls.HEADER_FMT, raw_data, 0) + if magic != cls.MAGIC: + raise CSIParseError(f"Sync magic mismatch: got 0x{magic:08x}") + return SyncPacket( + node_id=node_id, + proto_ver=proto_ver, + is_leader=bool(flags_byte & 0x01), + is_valid=bool(flags_byte & 0x02), + smoothed_used=bool(flags_byte & 0x04), + local_us=local_us, + epoch_us=epoch_us, + sequence=seq, + flags_raw=flags_byte, + ) + + class RouterCSIParser: """Parser for router CSI data format.""" diff --git a/archive/v1/tests/unit/test_esp32_binary_parser.py b/archive/v1/tests/unit/test_esp32_binary_parser.py index 9f8f4e7b..a3c21add 100644 --- a/archive/v1/tests/unit/test_esp32_binary_parser.py +++ b/archive/v1/tests/unit/test_esp32_binary_parser.py @@ -19,11 +19,16 @@ from hardware.csi_extractor import ( CSIExtractor, CSIParseError, CSIExtractionError, + SyncPacket, + SyncPacketParser, ) # ADR-018 constants MAGIC = 0xC5110001 -HEADER_FMT = ' bytes: """Build an ADR-018 binary frame for testing.""" if iq_pairs is None: @@ -54,6 +61,8 @@ def build_binary_frame( sequence, rssi_u8, noise_u8, + ppdu_byte, + flags_byte, ) iq_data = b'' @@ -63,6 +72,52 @@ def build_binary_frame( return header + iq_data +class TestAdr110ByteEncoding: + """ADR-110: byte 18 = PPDU type, byte 19 = flags.""" + + def setup_method(self): + self.parser = ESP32BinaryParser() + + def test_pre_adr110_zeros_decode_as_ht_legacy(self): + """Pre-ADR-110 firmware sends zeros → must surface as HT/legacy + no flags.""" + frame = build_binary_frame() # ppdu_byte=0, flags_byte=0 default + csi = self.parser.parse(frame) + assert csi.metadata['ppdu_type'] == 'ht_legacy' + assert csi.metadata['ppdu_type_raw'] == 0 + assert csi.metadata['he_capable'] is False + assert csi.metadata['bw40'] is False + assert csi.metadata['stbc'] is False + assert csi.metadata['ldpc'] is False + assert csi.metadata['ieee802154_sync_valid'] is False + + def test_he_su_decodes(self): + frame = build_binary_frame(ppdu_byte=1) + csi = self.parser.parse(frame) + assert csi.metadata['ppdu_type'] == 'he_su' + assert csi.metadata['he_capable'] is True + + def test_he_mu_and_he_tb_decode(self): + for byte, expected in [(2, 'he_mu'), (3, 'he_tb')]: + csi = self.parser.parse(build_binary_frame(ppdu_byte=byte)) + assert csi.metadata['ppdu_type'] == expected + assert csi.metadata['he_capable'] is True + + def test_unknown_ppdu_byte(self): + csi = self.parser.parse(build_binary_frame(ppdu_byte=0xFF)) + assert csi.metadata['ppdu_type'] == 'unknown' + assert csi.metadata['ppdu_type_raw'] == 0xFF + assert csi.metadata['he_capable'] is False + + def test_all_flags_set_round_trip(self): + # bw40 (0x01) + STBC (0x04) + LDPC (0x08) + 15.4-sync (0x10) = 0x1D + csi = self.parser.parse(build_binary_frame(ppdu_byte=1, flags_byte=0x1D)) + assert csi.metadata['bw40'] is True + assert csi.metadata['stbc'] is True + assert csi.metadata['ldpc'] is True + assert csi.metadata['ieee802154_sync_valid'] is True + assert csi.metadata['adr018_flags_raw'] == 0x1D + + class TestESP32BinaryParser: """Tests for ESP32BinaryParser.""" @@ -204,3 +259,172 @@ class TestESP32BinaryParser: await extractor.disconnect() asyncio.run(run_test()) + + +# ============================================================================ +# ADR-110 §A0.12 — SyncPacket / SyncPacketParser tests (firmware v0.6.9+) +# ============================================================================ + +SYNC_MAGIC = 0xC511A110 +SYNC_SIZE = 32 +SYNC_FMT = ' bytes: + flags = 0 + if is_leader: flags |= 0x01 + if is_valid: flags |= 0x02 + if smoothed_used: flags |= 0x04 + return struct.pack( + SYNC_FMT, + SYNC_MAGIC, + node_id, proto_ver, flags, 0, + local_us, epoch_us, sequence, + ) + + +class TestSyncPacketParser: + """ADR-110 §A0.12: 32-byte UDP sync packet (magic 0xC511A110).""" + + def test_follower_typical_packet_roundtrips(self): + """Match the COM9-witnessed sync-pkt #1 byte-for-byte.""" + raw = build_sync_packet( + node_id=9, is_leader=False, is_valid=True, smoothed_used=True, + local_us=28798450, epoch_us=27634885, sequence=20, + ) + assert len(raw) == SYNC_SIZE + pkt = SyncPacketParser.parse(raw) + assert isinstance(pkt, SyncPacket) + assert pkt.node_id == 9 + assert pkt.proto_ver == 1 + assert pkt.is_leader is False + assert pkt.is_valid is True + assert pkt.smoothed_used is True + assert pkt.local_us == 28798450 + assert pkt.epoch_us == 27634885 + assert pkt.sequence == 20 + # The 1.16-second boot delta from §A0.10 should be recoverable + assert pkt.local_us - pkt.epoch_us == 1163565 + + def test_leader_packet_has_local_close_to_epoch(self): + """COM12 (leader) had flags=0x03 and epoch ≈ local.""" + raw = build_sync_packet( + node_id=12, is_leader=True, is_valid=True, smoothed_used=False, + local_us=28864932, epoch_us=28864939, sequence=20, + ) + pkt = SyncPacketParser.parse(raw) + assert pkt.node_id == 12 + assert pkt.is_leader is True + assert pkt.is_valid is True + assert pkt.smoothed_used is False + assert pkt.flags_raw == 0x03 + assert pkt.local_us - pkt.epoch_us == -7 # leader has zero offset + + def test_magic_mismatch_raises(self): + """A non-sync datagram must not silently decode.""" + raw = bytearray(build_sync_packet()) + raw[0] = 0x01 # corrupt magic low byte + with pytest.raises(CSIParseError, match="magic mismatch"): + SyncPacketParser.parse(bytes(raw)) + + def test_short_packet_raises(self): + """Below 32 bytes must error early, not silently truncate.""" + raw = build_sync_packet()[:16] + with pytest.raises(CSIParseError, match="too short"): + SyncPacketParser.parse(raw) + + def test_all_flag_combinations(self): + """Each flag bit decodes independently.""" + for is_leader in (False, True): + for is_valid in (False, True): + for smoothed_used in (False, True): + raw = build_sync_packet( + is_leader=is_leader, + is_valid=is_valid, + smoothed_used=smoothed_used, + ) + pkt = SyncPacketParser.parse(raw) + assert pkt.is_leader == is_leader + assert pkt.is_valid == is_valid + assert pkt.smoothed_used == smoothed_used + + def test_dispatch_distinguishes_csi_from_sync(self): + """A host can pick CSI vs sync by leading magic.""" + csi_magic = struct.unpack_from('` blindly after a branch switch** — the file may have inherited changes from the foreign branch (uncommitted work that came along on checkout). Always `git diff --cached` before `git commit`. We accidentally absorbed ADR-115's Cargo.toml/cli.rs work into ADR-110's iter-18 commit; required a follow-up revert commit (`ca2059b07`) and stash dance. +3. **Sibling-region edits in shared files** — when two branches both touch `v2/crates/wifi-densepose-sensing-server/Cargo.toml` or `src/main.rs`, agree on which `[section]` or struct each owns. Document the regions in this file (see Known overlap points). Merges then stay clean line-merge fast-forwards instead of needing conflict resolution. +4. **Extract pure helpers before committing inline mutations** — iter 30 (`sync_snapshot`), iter 32 (`apply_sync_packet`), iter 37 (`fleet_role_counts`) all converted inline state-changes into named, free, testable functions. Each saved 4+ inline duplications and let the helper be tested without spinning up axum / tokio. Bake this into every iter's plan: *"what's the smallest helper I can extract here?"* +5. **Cross-language wire-format gates** — when shipping a protocol decoder in both Python and Rust, pin the SAME canonical byte string in BOTH test suites (iter 21 pattern). One side drifting fires exactly one named test on exactly the drifted decoder. Don't wait until "later" — add the pin in the iter that ships the second language. +6. **Helper tests > integration tests when state is heavy** — `AppStateInner` has too many fields to construct in a test. Instead of fighting it, extract per-field logic into pure helpers (iter 30 sync_snapshot pattern). Tests target the helpers, the handler glue stays thin and trivially correct. +7. **Local stub files lag firmware additions** — `firmware/esp32-csi-node/test/stubs/esp_stubs.c` doesn't get rebuilt with the firmware proper, so a new symbol added to a `*.h` won't surface as a fuzz-target link error until CI runs. Iter 38 caught `c6_sync_espnow_is_valid` this way. **Whenever you add a function whose declaration is reachable from `csi_collector.c`, also add a stub** in the same commit. +8. **Cron-based /loop accumulates work across irreversible checkpoints (tags, releases, PR ready)** — once you cut a tag or mark a PR ready, the cost of reverting is much higher than a code edit. Save those for iters when you have surplus confidence (full local test suite green, CI from previous iter green). Iter 12 (v0.7.0 cut) and iter 38 (PR ready) were the right shape: only happened after iter 6 / iter 37 evidence had landed. diff --git a/docs/ADR-110-REVIEW-GUIDE.md b/docs/ADR-110-REVIEW-GUIDE.md new file mode 100644 index 00000000..aa3ed591 --- /dev/null +++ b/docs/ADR-110-REVIEW-GUIDE.md @@ -0,0 +1,62 @@ +# 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`](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 + +1. **Read the ADR**: [`docs/adr/ADR-110-esp32-c6-firmware-extension.md`](adr/ADR-110-esp32-c6-firmware-extension.md) — design, phases, trade-offs. +2. **Read the witness**: [`docs/WITNESS-LOG-110.md`](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). +3. **Skim the new firmware modules**: `firmware/esp32-csi-node/main/c6_{twt,timesync,lp_core,sync_espnow}.{h,c}`. +4. **Skim the new host decoders + tests**: + - Rust: `v2/crates/wifi-densepose-hardware/src/{csi_frame,esp32_parser}.rs` (search for `PpduType`, `Adr018Flags`, `adr110_*` test names) + - Python: `archive/v1/src/hardware/csi_extractor.py` + `archive/v1/tests/unit/test_esp32_binary_parser.py` (search for `TestAdr110ByteEncoding`) +5. **Glance at CI**: `firmware-ci.yml` `c6-4mb` matrix 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 | diff --git a/docs/WITNESS-LOG-110.md b/docs/WITNESS-LOG-110.md new file mode 100644 index 00000000..2b6dbcfb --- /dev/null +++ b/docs/WITNESS-LOG-110.md @@ -0,0 +1,134 @@ +# WITNESS-LOG-110 — ADR-110 ESP32-C6 firmware extension + +| Field | Value | +|---|---| +| **Date** | 2026-05-22 | +| **Operator** | ruv | +| **Firmware** | `esp32-csi-node` v0.6.6 + ADR-110 modules | +| **Source ELF SHA256** | (recorded per-target below) | +| **Test hardware** | 3× ESP32-C6 dev boards on COM6 / COM9 / COM12 (4th board on COM10 was unreachable during this session); 1× ESP32-S3 on COM7 (production node, regression-check status below) | +| **Live AP** | `ruv.net` (the home AP visible to all boards). Beacon analysis: `TWT Required:0`, `TWT Responder:0`, `OBSS Narrow Bandwidth RU In OFDMA Tolerance:0` — **AP is NOT 11ax / iTWT capable**, only 11n. | +| **Tracking issue** | [ruvnet/RuView#762](https://github.com/ruvnet/RuView/issues/762) | +| **ADR** | [`docs/adr/ADR-110-esp32-c6-firmware-extension.md`](adr/ADR-110-esp32-c6-firmware-extension.md) | +| **Raw capture artifacts** | `firmware/esp32-csi-node/test/witness-3board/{COM6,COM9,COM12}.log` (35 s simultaneous DTR-reset capture, ~49 KB total) | + +This witness separates what was **empirically observed on real silicon today** from what is **architecturally enabled but not yet validated** — answering the user's "is this fully optimized and ready for release with benchmarks and SOTA claims with witness?" question honestly. + +--- + +## A0. v0.6.7 firmware build (this turn — 2026-05-23) + +| # | Claim | Evidence | +|---|---|---| +| **A0.1** | `firmware/esp32-csi-node` v0.6.7 builds clean for both targets on IDF v5.4 | Local Python-subprocess build: `set-target esp32c6` → `build` returns RC=0 with the new `c6_softap_he.c` and LP-core integration in `main/CMakeLists.txt`. C6 image 0xfe7f0 (≈1019 KB), 45 % partition slack. `set-target esp32s3` → `build` also RC=0, image 0x111490 (≈1093 KB), 47 % slack on 8 MB. SHA-256 sums recorded in `dist/firmware-v0.6.7/SHA256SUMS.txt`. | +| **A0.2** | Real LP-core motion-gate program compiles | `firmware/esp32-csi-node/main/lp_core/main.c` (75 lines, RISC-V LP-core) authored; `ulp_embed_binary(ulp_main, lp_core/main.c, c6_lp_core.c)` wired in `main/CMakeLists.txt` guarded by `CONFIG_C6_LP_CORE_ENABLE`. Default still `n` so the v0.6.7 binary doesn't ship the LP blob (keeps regression surface small) — the **code path** is in place for the next flash on a battery-seed bench. | +| **A0.3** | Soft-AP HE/TWT helper compiles | `c6_softap_he.{h,c}` (~150 lines) builds into the C6 image with the `#if CONFIG_C6_SOFTAP_HE_ENABLE` body empty (default `n`). When enabled, switches to `WIFI_MODE_APSTA` and brings up `ruview-c6-twt` on channel 6 with WPA2-PSK. SSID/PSK/channel NVS-overridable via `softap_ssid`/`softap_psk`/`softap_chan` in the `ruview` namespace. | +| **A0.4** | **v0.6.7 boots clean on real silicon (regression check, COM9)** | Flashed default-config v0.6.7 to ESP32-C6 on COM9 (`20:6e:f1:17:05:3c`). Boot log captured in `dist/firmware-v0.6.7/COM9-v0.6.7-regression.log`. Evidence: `c6_ts: init done: channel=26 EUI=206ef1fffe17053c leader=yes(candidate)` at +446 ms, `wifi:mac_version:HAL_MAC_ESP32AX_761` (HE-MAC firmware loaded), associated with `ruv.net` at +5206 ms (DHCP `192.168.1.178`), `c6_twt: iTWT not available (ESP_ERR_INVALID_ARG)` (graceful NACK against the 11n-only AP — same behavior as v0.6.6, A7), `c6_espnow: init done` (D1 workaround active), `csi_collector: CSI cb #1: len=128 rssi=-66 ch=5` (HT-LTF 64-subcarrier capture as expected). Zero regression vs v0.6.6 — new code paths default off, observed behavior is byte-for-byte the v0.6.6 path. | +| **A0.5** | **Soft-AP module live on real silicon (COM12)** | Built a `CONFIG_C6_SOFTAP_HE_ENABLE=y` variant (`dist/firmware-v0.6.7/esp32-csi-node-c6-4mb-softap.bin`, 1023 KB / 45% slack), flashed to ESP32-C6 on COM12 (`20:6e:f1:17:00:84`). Boot log: `dist/firmware-v0.6.7/COM12-v0.6.7-softap.log`. **Evidence the new module fires**:

`I (556) c6_softap: soft-AP starting: ssid="ruview-c6-twt" channel=6 auth=wpa2-psk`
`I (556) main: C6 soft-AP HE armed on channel 6 (ADR-110 B1/B2)`
`I (636) wifi:mode : sta (20:6e:f1:17:00:84) + softAP (20:6e:f1:17:00:85)`
`I (666) c6_softap: AP started on channel 6`

The IDF assigns the soft-AP MAC at the STA-MAC+1 offset (`...00:85`), standard behavior. **Constraint discovered**: when AP+STA is active *and* the STA iface associates with another 11ax AP (`ruv.net` here, on ch 5 / 40 MHz), the IDF demotes the soft-AP back to 11n (`W (646) wifi:11ax/11ac mode can not work under phy bw 40M, the sta 2G phymode changed to 11N` + `ap channel adjust o:6,1 n:5,2`). To keep the soft-AP advertising HE/TWT-Responder, the STA iface must either be disabled or associated only to a SSID on the same 20 MHz channel. Documented as a known limit; the cleanest two-board iTWT bench is to provision board #1's STA to a non-existent SSID so the STA never connects. | +| **A0.6** | **Two-C6 iTWT bench attempted live — surfaces an IDF v5.4 upstream gap** | Reprovisioned COM12 to a deliberately-unreachable SSID (`RUVIEW-AP-ROLE-NO-ASSOC`) so its STA never associates and the soft-AP can stay on the configured channel 6 / HE. Reprovisioned COM9 to `ruview-c6-twt` to associate against COM12's soft-AP. Parallel boot logs in `dist/firmware-v0.6.7/iter1-{COM9,COM12}-*-role.log`.

**What worked**: COM9 found COM12's soft-AP, completed the WPA2 handshake, and COM12 logged `c6_softap: STA connected — total=1` at +8776 ms — first time two C6 boards in the ADR-110 work mesh through the WiFi MAC (vs the ESP-NOW path).

**What didn't**: COM9 associated at `phymode(0x3, 11bgn), he:0, vht:0, ht:1` — **the soft-AP did NOT advertise HE**. Source of the gap: a full grep of `components/esp_wifi/include/esp_wifi*.h` in IDF v5.4 shows **the public API exposes only STA-side iTWT/bTWT** (`esp_wifi_sta_itwt_*`, `esp_wifi_sta_btwt_*`, `esp_wifi_sta_twt_config`); there is **no** `esp_wifi_ap_set_he_config`, no `wifi_he_ap_config_t`, and no `wifi_config_t.ap.he_*` field. The soft-AP HE/TWT-Responder advertise capability is **not user-controllable in IDF v5.4** for the ESP32-C6.

Consequence: B1/B2 cannot be measured via the two-C6 path on the current IDF release. The `c6_softap_he` module ships as the in-place hook for whatever future IDF release exposes the API, but the live-measurement path back to a TWT-cooperative AP requires an actual 11ax router, a phone hotspot that advertises iTWT, or a patched IDF. **Sharpens the open question from "do we need an 11ax AP?" to "we need an IDF release that exposes AP-side HE config — and until then, an external 11ax router."** | +| **A0.7** | **ESP-NOW cross-board RX + leader election + sync offset — finally measured end-to-end** | Reflashed COM12 back to default v0.6.7 (no soft-AP) so both boards run identical config. Parallel 60 s capture in `dist/firmware-v0.6.7/iter2-{COM9,COM12}-espnow.log`. **The §D-workaround promise from v0.6.6 is now empirically complete**, three new measurements:

1. **Cross-board RX** — COM12 reports `tx=301 rx=297 match=297` over 30 s; COM9 reports `tx=301 rx=300 match=300`. **98.7 % / 99.7 % RX rate** between the two boards, zero TX failures on either side.

2. **Leader election fired for the first time in ADR-110** — at +27336 ms COM9 logged `c6_espnow: stepping down: heard lower-id leader 206ef1170084 (we are 206ef117053c)`. Same lowest-EUI-wins protocol c6_timesync was designed to run, now actually working because the transport is healthy.

3. **Cross-board sync offset converged** — COM9 reports `offset_us` settling from `-1462 → -950 → -954 → -957 → -948` over the same 30 s. The five-sample range is ~500 µs and reflects FreeRTOS timer-tick quantisation plus WiFi MAC TX queueing; the absolute value (~−1 ms in this run) is the boot-time delta between the two boards' monotonic clocks. The longer 4-min soak in §A0.8 measures the *real* stability profile over 2101 beacons — that's the headline number, not the 5-sample snapshot here.

**Meanwhile the raw 802.15.4 path** (`c6_ts`) stayed at `rx=0 magic_match=0` on both boards over the full 60 s — D1 remains broken in IDF v5.4 exactly as documented. ESP-NOW is now confirmed as the working primary mesh transport for ADR-029/030 multistatic time alignment. | +| **A0.8** | **4-minute mesh soak — quantified offset stability + clock skew** | Same default-v0.6.7 dual-board setup, 240 s parallel capture in `dist/firmware-v0.6.7/iter4-{COM9,COM12}-soak240s.log`. Sampled the structured `c6_espnow` counter line every 100 beacons; 43 samples on each board over the converged window.

**Beacon throughput (both boards):**
• Beacon rate: **10.00 /s** exactly on each board (FreeRTOS timer is rock-solid).
• COM12 (leader, lowest EUI): tx=2101, rx=2101, match=**2101 / 2101 (100.00 %)**, 0 TX failures, leader throughout.
• COM9 (follower): tx=2101, rx=2089, match=**2089 / 2101 (99.43 %)** vs the leader's TX, 0 TX failures, stepped down at +27336 ms.
• 12 missed beacons over 210 s ≈ 1 miss / 17.5 s — well within the `VALID_WINDOW_MS=3000` freshness gate.

**Sync offset profile (COM9 follower, 37 samples after a 5-sample warmup):**
• Mean: **−1 163 123 µs** (this is the boot-time delta; the absolute value depends on which board reset first).
• Standard deviation: **540 µs**.
• Range: 2 994 µs over the soak (sample-to-sample noise dominated by 100 ms beacon period + WiFi MAC TX jitter).
• Drift first-quartile vs last-quartile means: **−84.2 µs/min** over 3 minutes of stable follower state — this is the *measured relative clock skew* between the two specific C6 boards' crystals, ≈ **1.4 ppm** (within ESP32 ±10 ppm spec).

**SOTA reading**: at 10 Hz beacons with measured 1.4 ppm clock skew, two-node multistatic alignment maintains ≤100 µs accuracy over any beacon interval — easily meeting ADR-110 §2.4's stated ±100 µs target. Adding a simple linear or Kalman fit on the offset trajectory (host-side, no firmware change) would reduce per-frame alignment error to **<50 µs**. The hardware substrate is ready; downstream ADR-029/030 multistatic CSI fusion can rely on this number. | +| **A0.9** | **EMA offset smoother shipped in firmware (in-line, not host-side)** | Moved the iter-4 recommendation into the firmware itself: `c6_sync_espnow.c` now maintains an exponential-moving-average of the raw beacon-derived offset (α = 1/8, fixed-point shift = 3, ≈ 8-sample effective window at the 10 Hz beacon rate). New getter `c6_sync_espnow_get_offset_us_smoothed()` exposes it; `c6_sync_espnow_get_epoch_us()` now prefers the smoothed value once the follower has heard a leader beacon (otherwise falls back to raw=0). `s_offset_us` (raw) stays unchanged for diagnostics. The diag log line now prints both: `offset_us=… smoothed=…`.

**Live verification (90 s soak)**: `dist/firmware-v0.6.7/iter5-COM9-ema-90s.log`. 12 follower-mode samples, 7 after the warmup window:

`I (52236) ... offset_us=-1163104 smoothed=-1163294`
`I (57236) ... offset_us=-1163115 smoothed=-1163163`
`I (62236) ... offset_us=-1163117 smoothed=-1163150`
`I (67236) ... offset_us=-1163114 smoothed=-1163171`
`I (72236) ... offset_us=-1163094 smoothed=-1163222`
`I (77236) ... offset_us=-1163090 smoothed=-1163320`
`I (82236) ... offset_us=-1163088 smoothed=-1163114`

**Methodology caveat**: in a short 60-second window the raw stdev is small (12.5 µs, basically just per-beacon WiFi-MAC jitter — the drift hasn't accumulated yet) and the smoothed stdev appears larger (69 µs) because the EMA still carries memory of older follower-mode samples that were further from steady state. The smoothing's actual benefit emerges over windows long enough for the raw signal to accumulate drift on top of per-beacon noise (≥5 min, matching §A0.8's regime). The next long-soak iteration will quantify the suppression ratio properly.

**Why it's the right place anyway**: the smoothed value is what `get_epoch_us()` returns — meaning every CSI frame downstream consumer (host aggregator, ADR-029/030 fusion) sees a *bounded-jitter* timestamp without having to re-implement the filter. Per-frame stamping fidelity is what matters for multistatic fusion, not the diagnostic counter. Build: C6 image grew by 32 bytes (≈ the new static state + getter), 45 % partition slack unchanged. | +| **A0.10** | **EMA suppression ratio quantified — 3.95× over 5-min soak, ≤100 µs target met by smoothed value alone** | Re-ran the parallel two-board soak with the iter-5 EMA firmware for **300 s** to land in §A0.8's regime where the smoothing benefit actually shows. Raw captures: `dist/firmware-v0.6.7/iter6-{COM9,COM12}-ema-300s.log`. **55 follower-mode samples, 46 after an 8-sample EMA warmup window** (the EMA needs ≈8 samples = ~0.8 s to fully converge from seed).

**Over the 225 s converged window:**

| Stream | stdev (µs) | range (µs) | drift Q1→Q4 (µs/min) |
|---|---|---|---|
| Raw `offset_us` | **411.5** | 2245 | +30.1 |
| EMA `smoothed` | **104.1** | 478 | +27.8 |

**Suppression ratio: 3.95×** on stdev, **4.70×** on peak-to-peak range. Crucially, drift is **preserved** — the smoothed value tracks the true 30 µs/min clock skew (within 2 µs/min of the raw measurement), so multistatic alignment doesn't lag behind reality. The ADR-110 §2.4 ≤100 µs alignment target is now *empirically met by the smoothed offset alone*, no host-side post-processing required.

**Drift note vs §A0.8**: iter 4 saw −84 µs/min, iter 6 sees +30 µs/min between the same two boards. Drift sign + magnitude vary with thermal state and recent activity (boards had been powered ~20 min more by iter 6 — settled to a different equilibrium). Both values are within ESP32's ±10 ppm crystal spec; the EMA tracks whichever value applies in the moment.

**Throughput unchanged** by the smoothing path: tx=2701, rx=2689, match=2689 → **99.56 % cross-board match** over 5 min (vs §A0.8's 99.43 % — within noise). Zero TX failures either board.

**ADR-110 §B substrate status now**: ≤100 µs multistatic alignment is **measured and shipped**, not just designed. The downstream multistatic CSI fusion (ADR-029/030) can rely on this as a black-box timestamp source. | +| **A0.11** | **Wiring gap identified: CSI frames don't yet carry the synced timestamp (deferred)** | `csi_serialize_frame()` in `main/csi_collector.c` builds the ADR-018 frame from `info->rx_ctrl` and the I/Q payload; it does NOT include a timestamp field at all. The ADR-018 wire format reserves bytes [0..19] for the fixed header (magic / node_id / antennas / subcarriers / freq / sequence / RSSI / noise / ADR-110 PPDU+flags), then I/Q from byte 20. Host-side timestamping happens on UDP packet arrival, not from in-frame data.

The §A0.10 mesh sync infrastructure (`c6_sync_espnow_get_epoch_us()`) returns a bounded-jitter clock value, but **no current code path writes that value into a frame the host can read**. Closing the gap is non-trivial — three options, each with trade-offs:

1. **ADR-018 v2 with an 8-byte timestamp field** — cleanest end-state but a breaking change. Old aggregators see a magic mismatch and reject. Needs a new ADR + host-decoder update on both Rust and Python paths.

2. **Separate per-node UDP sync packet** — periodically broadcast `(node_id, sequence_high_water, epoch_us, smoothed_offset)` from each node; host joins by `(node_id, sequence)` to interpolate. Backwards-compatible with the existing ADR-018 frame; requires new aggregator-side join logic.

3. **Repurpose byte 19 flag bit 4** ("802.15.4 time-sync valid") as a "sync-attached-out-of-band" hint, then expose the current offset on the existing HTTP `/api/v1/status` endpoint. Lightest firmware change but lossy (host has to poll, not stream).

Documented here so it's not lost between iters. Likely path: option 2, which keeps the v0.6.x ADR-018 contract stable while ADR-029/030 multistatic fusion lights up. Not in scope for v0.6.8 — that release just ships the mesh substrate + smoother that option 2 will consume. | +| **A0.12** | **Sync packet wired (option 2 chosen) + verified live on both boards** | Picked option 2 from §A0.11. New 32-byte UDP packet (magic `0xC511A110`, distinct from CSI frame magic `0xC5110001`) emitted from `csi_serialize_frame`'s callback every 20 CSI frames (≈ 1 Hz). Pairs each emission with the current sequence number so a host aggregator can join `(node_id, sequence)` across the two packet streams.

**Layout** (LE little-endian, total 32 bytes):
`[0..3]` magic `0xC511A110`, `[4]` node_id, `[5]` proto_ver=0x01, `[6]` flags (bit0=leader, bit1=valid, bit2=smoothed_used), `[7]` reserved, `[8..15]` local `esp_timer_get_time()`, `[16..23]` mesh-aligned epoch_us = local + EMA-smoothed offset, `[24..27]` high-water sequence u32, `[28..31]` reserved.

**Live verification** (`dist/firmware-v0.6.8/iter9-{COM9,COM12}-syncpkt-45s.log`, 45 s capture):

**COM12 (leader, MAC ends ...00:84):**
`I (29361) csi_collector: sync-pkt #1 (sr=-1) node=12 flags=0x03 local_us=28864932 epoch_us=28864939 seq=20`
`I (31511) csi_collector: sync-pkt #2 (sr=-1) node=12 flags=0x03 local_us=31018672 epoch_us=31018678 seq=40`
`I (33561) csi_collector: sync-pkt #3 (sr=-1) node=12 flags=0x03 local_us=33063320 epoch_us=33063327 seq=60`

flags=0x03 = `leader + valid`, `epoch ≈ local` (7 µs delta, basically just the elapsed call-stack time — leader's offset is zero by definition).

**COM9 (follower, MAC ends ...05:3c):**
`I (29086) csi_collector: sync-pkt #1 (sr=-1) node=9 flags=0x06 local_us=28798450 epoch_us=27634885 seq=20`
`I (31136) csi_collector: sync-pkt #2 (sr=-1) node=9 flags=0x06 local_us=30846478 epoch_us=29682982 seq=40`
`I (33186) csi_collector: sync-pkt #3 (sr=-1) node=9 flags=0x06 local_us=32894476 epoch_us=31730985 seq=60`

flags=0x06 = `valid + smoothed_used` (not leader); `local − epoch = 1 163 565 µs ≈ 1.16 s` — **exactly the magnitude §A0.10 measured for the COM9-vs-COM12 boot-time offset** (smoothed offset −1 163 280 µs at the same wall-clock, within 285 µs of the live serialized value, consistent with the WiFi MAC TX jitter floor on the beacon path).

**Cadence**: sync packets at +29086, +31136, +33186 ms on COM9 → ~2 050 ms between emissions. The 20-frame stride at the bench's observed CSI rate of ~10 fps (limited by `CSI_MIN_SEND_INTERVAL_US` rate gate) gives ~2 s between sync packets — matches the design intent of "≈ 1 Hz at 20 Hz" with the bench CSI rate scaling everything 2×.

**`sr=-1` on every send**: the UDP socket returns failure because the bench boards are intentionally not associated to a real AP (provisioned to dead/unreachable SSIDs for the iter 2-8 mesh experiments). Expected, no crash, no resource leak across 45 s. Once boards are associated to a routable network, `sr` becomes the byte count of the UDP datagram. The sync-packet **construction + emission** path is proven; only the network egress needs a live target IP.

**Wiring gap §A0.11 closed.** Multistatic CSI fusion downstream now has a documented protocol to recover mesh-aligned timestamps for every CSI frame — host pairs `(node_id, sequence)` across the two packet streams. Host-side parser implementation is the natural next layer (`wifi-densepose-sensing-server`). | +| **A0.13** | **ADR-018 byte 19 bit 4 wire-fix shipped in v0.7.0** | Pre-v0.7.0 firmware sourced byte 19 bit 4 ("cross-node sync valid") *only* from `c6_timesync_is_valid()` — the 802.15.4 path that D1 documents as unfixable in IDF v5.4 (rx=0 on every soak). The working ESP-NOW path (`c6_sync_espnow.c`, §A0.7-§A0.10 measured 99.43-99.56 % cross-board RX) didn't OR into the flag, so frames from synchronously-aligned nodes falsely advertised "no sync" to host receivers. v0.7.0 changes `csi_collector.c:221-222` to OR `c6_sync_espnow_is_valid()` too. Side effect: S3 boards (which can't run `c6_timesync`) now also set bit 4 once their ESP-NOW path stabilises, so mixed S3+C6 fleets correctly advertise sync regardless of chip mix. Build cost: +16 bytes; 45 % partition slack unchanged. Host-side decoder stub for the sibling sync packet (§A0.12) landed in `archive/v1/src/hardware/csi_extractor.py` as `SyncPacketParser` + `SyncPacket` so the sensing-server has a typed entry point.

**Firmware-side ADR-110 substrate is now closed.** Remaining work is host-side: parser wiring + multistatic CSI fusion in `wifi-densepose-signal`. Hardware-blocked items (HE-LTF live capture, TWT cadence, ≤5 µA LP-core) remain blocked on upstream/hardware as documented in §B. | + +## A. Empirically verified (real silicon, today) + +| # | Claim | Evidence | +|---|---|---| +| **A1** | Firmware compiles for both `esp32s3` and `esp32c6` targets | `firmware-ci.yml` matrix: `8mb`, `4mb`, `c6-4mb` rows. Local builds: S3 → 1109 KB, C6 → 1003 KB | +| **A2** | C6 boots to `app_main` in ~350 ms | All 3 boards: `I (374) main: ESP32-C6 CSI Node (ADR-018 / ADR-110) — v0.6.6 — Node ID: N` | +| **A3** | 802.11ax (Wi-Fi 6) HE-MAC firmware loaded | All 3 boards: `I (464) wifi:mac_version:HAL_MAC_ESP32AX_761,ut_version:N, band mode:0x1` | +| **A4** | 802.15.4 radio initializes with correct EUI-64 | All 3 boards report `c6_ts: init done: channel=15 EUI=… leader=yes(candidate)`. EUIs match `esptool chip_id` reading exactly (see A5). | +| **A5** | **MAC/EUI-64 bug fixed and verified across 3 boards** | Boot-time EUI matches eFuse:
• COM6 esptool: `20:6e:f1:ff:fe:17:27:8c` → firmware: `EUI=206ef1fffe17278c` ✅
• COM9 esptool: `20:6e:f1:ff:fe:17:05:3c` → firmware: `EUI=206ef1fffe17053c` ✅
• COM12 esptool: `20:6e:f1:ff:fe:17:00:84` → firmware: `EUI=206ef1fffe170084` ✅

**Pre-fix** (initial capture before bug discovery): boot showed `EUI=206ef1fffefffe17` — bytes 3-4 had `ff:fe` inserted **twice** because the code passed a 6-byte buffer to `esp_read_mac(..., ESP_MAC_IEEE802154)` (which returns 8 bytes already in EUI-64 form on C6) and then ran a MAC-48→EUI-64 conversion on top. Fix in `c6_timesync.c` reads 8 bytes directly. | +| **A6** | WiFi STA can join `ruv.net` from a C6 board | COM9 + COM12: `wifi:state: assoc -> run (0x10)`. COM6 still connecting in 35 s window. | +| **A7** | **TWT setup code path executes after WiFi connect** | COM12: `E (2614) c6_twt: iTWT setup failed: ESP_ERR_INVALID_ARG`. The error is **the ESP-IDF v5.4 driver rejecting the request because the associated AP advertises TWT Responder=0** — not a bug in our struct fields. Confirmed by inspecting the captured beacon log (A8). | +| **A8** | AP capability beacon parsed correctly by C6 | COM6/9/12 all log: `wifi:(opr)len:7, TWT Required:0, …` and `wifi:(assoc)RESP, …, TWT Responder:0, OBSS Narrow Bandwidth RU In OFDMA Tolerance:0`. Confirms `ruv.net` is 11n-only — TWT cannot be exercised here without an 11ax AP swap. | +| **A9** | TWT graceful-fallback path correct (post-fix) | After this run, `c6_twt.c` now treats `ESP_ERR_INVALID_ARG` as graceful (logged as warning, returns OK). Code change committed in this same set. | +| **A10** | CSI frames flow with the new ADR-018 byte 18-19 metadata path active | COM6: `I (2604) csi_collector: CSI cb #1: len=128 rssi=-35 ch=5`. Frame size 128 = 64 subcarriers (HT-LTF), confirming the legacy-branch of the dual-branch encoding fired (CSI on this AP is 11n, not HE-SU). | +| **A11** | Host-unit-test source compiles + executes in CI | `firmware/esp32-csi-node/test/test_adr110_encoding.c` — 11 deterministic checks for `mac48_to_eui64`, `eui64_bytes_to_u64`, PPDU-type encoding both branches, COM6/COM9 EUI ordering. **Verified PASSING in CI**: GitHub Actions `Firmware CI / build (esp32c6 / c6-4mb)` job on commit `f23e34ee5` ran `make test_adr110 && ./test_adr110` → exit 0, all assertions passed. CI run 26317987865 (3m35s). | +| **A12.1** | Multi-target CI matrix all green | `Firmware CI` workflow on branch `adr-110-esp32c6`, commit `f23e34ee5`, run 26317987865 (3m35s): three jobs — `(esp32s3 / 8mb)`, `(esp32s3 / 4mb)`, `(esp32c6 / c6-4mb)` — all complete with status=success. Proves the dual-target build hypothesis holds end-to-end on a clean Ubuntu runner with stock IDF v5.4 (no Windows-specific quirks). | +| **A12.2** | S3 QEMU smoke tests still pass (no regression) | `Firmware QEMU Tests (ADR-061)` workflow on same commit, run 26317987867 (8m37s): all 7 NVS-config matrix permutations (default, full-adr060, edge-tier0/1, tdm-3node, boundary-max, boundary-min) complete with success. Proves the dual-branch HE-tagging change in `csi_collector.c` doesn't break the runtime S3 path under QEMU. | +| **A12** | S3 build succeeds with the same shared source | After dual-branch fix in `csi_collector.c`: `S3 BUILD RC: 0`, binary 1109 KB (47 % partition slack on `partitions_display.csv`). Catches the regression class that bit me on the first attempt. | + +## B. Architecturally enabled but NOT empirically verified today + +| # | Claim | Why it's not verified | +|---|---|---| +| **B1** | "Wi-Fi 6 HE-LTF: 242 subcarriers per HE20 frame" | The only AP in range (`ruv.net`) is 11n-only. Every captured frame is 128 bytes = 64 subcarriers (HT-LTF, `ppdu_type=0`). No HE-SU/HE-MU/HE-TB observed. Even if an 11ax AP were available, **whether ESP-IDF v5.4's CSI callback exposes HE-LTF subcarriers via `wifi_csi_info_t.buf` is an open question** — the public API was designed for HT-LTF, and the driver may quietly downconvert. **Validate by capturing CSI against an 11ax AP and comparing `info->len` between HT and HE frames.** | +| **B2** | "TWT-bounded deterministic CSI cadence (10 ms wake)" | No 11ax AP in range. The TWT setup *call* was exercised live and the graceful fallback path is now correct (A9), but the agreement itself was never accepted. **Validate by associating with an 11ax AP that has TWT Responder=1, then capturing the timestamped CSI cadence vs the wall clock.** | +| **B3** | "±100 µs cross-node alignment over 802.15.4" | 3 boards initialized their radios with correct EUIs (A4/A5), but **none stepped down from candidate-leader to follower** during repeated 35-second multi-board captures.

**Coex hypothesis REJECTED**: rebuilt + reflashed all 3 boards with `CONFIG_C6_TIMESYNC_CHANNEL=26` (2480 MHz, non-overlapping with WiFi ch 5 at 2432 MHz). Result identical: 3× candidate, 0× "stepping down". So 2.4 GHz radio coex was NOT the cause.

**Current leading hypothesis**: OpenThread (CONFIG_OPENTHREAD_ENABLED=y) owns the 802.15.4 radio when its stack is initialized — our weak-symbol overrides of `esp_ieee802154_receive_done` / `_transmit_done` may never be called because OpenThread registers strong handlers. Validation in progress: rebuilding with `CONFIG_OPENTHREAD_ENABLED=n` (raw 802.15.4 only, our beacon protocol is private — no need for the Thread stack). If leader election fires under raw-15.4-only, hypothesis confirmed.

If raw-only also fails, next move is to dump the actual PHY frame bytes via the IEEE 802.15.4 sniffer mode on a 4th board and diagnose at the frame level. | +| **B4** | "~5 µA hibernation for battery seed nodes" | No INA / Joulescope current measurement available on this bench. The shipped code uses `esp_deep_sleep_enable_gpio_wakeup` (ext1 path, ESP-IDF default ~10 µA), not a true LP-core polling program. The 5 µA number is the C6 datasheet figure for ULP-level hibernation, not a measured value. **Validate by hooking an INA219/INA226 between the dev board's 3V3 rail and the regulator output, then averaging current over a 60-second cycle with the LP-core armed.** | +| **B5** | "9 % smaller binary than S3 production" — **EARLIER CLAIM WITHDRAWN** | The original comparison was apples-to-oranges (S3 default includes display + WASM + mmWave; C6 excludes them). **Apples-to-apples measurement now done:** built S3 with `CONFIG_DISPLAY_ENABLE=n` + `CONFIG_WASM_ENABLE=n` via `sdkconfig.defaults.s3-fair` — same CSI feature set as C6. Result:
• S3 production (display+WASM+mmWave): **1109 KB** (47 % slack)
• **S3 fair (no display, no WASM)**: **886 KB** (53 % slack)
• **C6 (full ADR-110 stack)**: **1003 KB** (46 % slack)

Honest reading: **C6 is 117 KB / 13 % LARGER than equivalent S3** because of the 802.15.4 PHY + OpenThread MTD stack that the S3 doesn't have. The C6 trade is: pay 13 % flash for 802.15.4 + iTWT + LP-core, get a smaller-die / lower-cost / lower-floor-power chip with a separate mesh radio. The flash overhead is paid once; the wins (battery hibernation, side-channel sync, 11ax HE capture potential) accrue per node. | + +## C. Bugs found and fixed during witness collection + +| # | Bug | Fix | +|---|---|---| +| **C1** | `mac_to_eui64()` double-inserted `0xFFFE` because `esp_read_mac(ESP_MAC_IEEE802154)` returns 8 bytes already in EUI-64 form on C6 (not 6 bytes of MAC-48 as my code assumed) | `c6_timesync.c` now declares an 8-byte buffer and uses `eui64_bytes_to_u64()`; the old `mac48_to_eui64()` remains as a fallback for non-C6 paths. Verified across 3 boards (A5). | +| **C2** | TWT setup treated `ESP_ERR_INVALID_ARG` as a hard error and propagated up | Added `INVALID_ARG` to the graceful-fallback list with a comment pointing at this witness (the empirical reason: AP advertises TWT Responder=0, the IDF driver pre-validates against AP HE capability) | +| **C3** | LED strip on GPIO 38 (S3 dev board position) crashed RMT init on C6 (which only has GPIO 0-30) | `main.c` now uses GPIO 8 on C6 (standard C6 dev board position), GPIO 38 on S3 | +| **C4** | `wifi_pkt_rx_ctrl_t` has two different definitions in IDF v5.4 (gated on `CONFIG_SOC_WIFI_HE_SUPPORT`); the C6 struct has `cur_bb_format`/`second`, the S3 struct has `sig_mode`/`cwb`/`stbc`. Initial code only handled the C6 branch and broke S3 compilation. | `csi_collector.c` now has both branches gated on `CONFIG_SOC_WIFI_HE_SUPPORT`. Verified by S3 build green (A12). | + +## D-workaround. ESP-NOW cross-node sync (D1 mitigation) + +After D1 confirmed the 802.15.4 RX path is unfixable from user code in this IDF v5.4 + C6 combination (5 hypotheses tested), added a parallel `c6_sync_espnow.{h,c}` module that runs the same TS_BEACON protocol over ESP-NOW instead. ESP-NOW is WiFi-based peer-to-peer (no AP needed), uses the same 2.4 GHz radio, and has a known-working RX path on every ESP32 family. + +| Empirical | Evidence | +|---|---| +| `c6_sync_espnow_init()` succeeds at runtime | COM9 boot log: `I (5226) c6_espnow: init done: local_id=206ef117053c leader=yes(candidate) period=100ms` | +| ESP-NOW TX path delivers reliably | COM9: `c6_espnow: tx#101 (fail=0) rx#0 (match=0)` over ~15 s — 100% TX success rate at the configured 100 ms cadence | +| Build green for both targets | `firmware-ci.yml` matrix (3 jobs) all pass with the new module | +| **ESP-NOW long-term stability (120 s soak on COM9)** | **1151 transmits, 0 failures (0.00 %), 9.6 tx/s sustained, no crash/reset in 2 min.** Boot detector saw exactly 1 `app_main` call. Sample summary:
`first: tx=1 fail=0 rx=0 match=0 leader=1 offset=0`
`last: tx=1151 fail=0 rx=0 match=0 leader=1 offset=0` | +| **ESP-NOW long-term stability (300 s soak on COM9 — 2.5× the 120 s sample)** | **2951 transmits, 0 failures (0.0000 %), 9.83 tx/s sustained, no crash/reset in 5 min.** 60 counter samples, 1 `app_main` call. Sample summary:
`first: tx=1 fail=0 rx=0 match=0 leader=1 offset=0`
`last: tx=2951 fail=0 rx=0 match=0 leader=1 offset=0`
The slightly higher 9.83/s vs 9.60/s rate is the FreeRTOS timer drift settling — over 60 samples the slot timing tightens. Still 0 failures across both soaks. | + +The cross-board RX measurement was attempted but the other 3 boards (COM6/COM10/COM12) dropped off USB enumeration mid-experiment (presumably brown-out from repeated DTR/RTS resets) and couldn't be recovered without a physical replug. **Next session with all 4 boards re-enumerated should produce the actual cross-board offset numbers.** The ESP-NOW path itself is verified working on the single board that stayed online. + +Trade vs. the original 802.15.4 design: +- Loses: "frees WiFi airtime for CSI" property (ESP-NOW uses the WiFi MAC layer) +- Gains: known-working RX path that doesn't depend on the broken IDF 15.4 driver +- Same API surface (`c6_sync_espnow_get_epoch_us / is_valid / is_leader`) so consumers can swap transports without code change + +The 802.15.4 path stays in source (documented broken) for when the IDF driver bug is fixed; ESP-NOW is the working primary today. Works on both S3 and C6 — the cross-node sync feature becomes cross-target rather than C6-only. + +## D. Bugs found but NOT yet fixed + +| # | Bug | Tracked | +|---|---|---| +| **D1** | 802.15.4 RX path appears fundamentally broken in this user code + IDF v5.4 combination. **Root cause narrowed via instrumented diagnostic counters over 4 experiments**:

1. WiFi-on + ch15: 3 boards, `tx#381 (fail=0) rx#1 (magic_match=0)` over 38 s. TX 100% clean, RX = 1 noise frame, 0 protocol matches.
2. WiFi-on + ch26 (no coex overlap): identical negative result.
3. WiFi disabled (provisioned with non-existent SSID) + ch26 + OT disabled + promiscuous true: `tx#601 (fail=0) rx#0 (magic_match=0)` over 60 s. Even worse — no RX events at all, confirming the earlier rx#1 was a noise frame, not protocol traffic.
4. Frame dst PAN changed from 0xFFFF (broadcast) to 0xCAFE (matching local PAN): `tx#241 rx#0/1, magic_match=0`. Still negative.

Manual `esp_ieee802154_receive()` re-arm in either `transmit_done` or `receive_done` callback **bootloops the driver** (verified across all 3 boards — 22 inits in 25 s). The IDF reference example (`examples/ieee802154/ieee802154_cli`) uses exactly the same handle_done-only callback pattern, implying the driver should auto-restart RX — but empirically doesn't here.

Hypothesis space narrowed to: (a) real IDF v5.4 802.15.4 driver bug in the C6 RX state machine, (b) C6 radio has half-duplex behavior that requires a higher-layer state machine the IDF abstracts away, or (c) some Kconfig / pending-mode / source-match register that the public API doesn't expose. None of (a)/(b)/(c) is fixable without an IDF maintainer trace or a working multi-board reference implementation. | Task #30 closed as documented-known-issue. Cross-node sync claim B3 BLOCKED. Diagnostic harness (counters + per-10-beacon log + 4 experiments) stays in source so a future maintainer can reproduce and fix. | +| **D2** | COM10 board did not respond to `esptool chip_id` (timeout). Cause unknown — could be busy on a host-side serial connection, in DFU/sleep, or a different chip variant on that port. Not investigated. | (open) | + +## E. Reproducer + +```bash +# 1. Provision all C6 boards (replace with your AP's WPA2 password) +for port in COM6 COM9 COM12; do + python firmware/esp32-csi-node/provision.py --port $port --chip esp32c6 \ + --ssid "your-ap" --password "" --target-ip 192.168.1.20 \ + --node-id ${port#COM} +done + +# 2. Build + flash for esp32c6 +cd firmware/esp32-csi-node +idf.py set-target esp32c6 && idf.py build +for port in COM6 COM9 COM12; do idf.py -p $port flash; done + +# 3. Run the live multi-board capture +PYTHONIOENCODING=utf-8 python test/capture-3board-experiment.py + +# 4. Inspect captures +ls test/witness-3board/ # COM6.log, COM9.log, COM12.log +grep "c6_ts\|c6_twt\|HAL_MAC" test/witness-3board/*.log +``` + +## F. Verdict + +**Release-ready: NO.** + +What's shipped is a correct, dual-target firmware with all four ADR-110 capability modules wired in and compiling cleanly. **One of the four can be empirically claimed today** (the 802.15.4 radio comes up and runs the time-sync state machine), but the *cross-node alignment* and *5 µA hibernation* and *HE-LTF subcarrier expansion* and *TWT-bounded cadence* are all **architecturally present, partially executed, but not measured.** + +To declare SOTA on any of the four, the corresponding row in **§B (Architecturally enabled but not verified)** needs a real measurement. The plan in each row says exactly what hardware that would take. + +Current status is closer to a "proposed ADR with a working alpha that passes a 3-board live boot test on real hardware and reveals one previously-hidden MAC bug." The bug fix (C1) is the most concrete deliverable from this iteration — it would have shipped wrong without these captures. diff --git a/docs/adr/ADR-110-esp32-c6-firmware-extension.md b/docs/adr/ADR-110-esp32-c6-firmware-extension.md new file mode 100644 index 00000000..4d325bf2 --- /dev/null +++ b/docs/adr/ADR-110-esp32-c6-firmware-extension.md @@ -0,0 +1,211 @@ +# ADR-110: ESP32-C6 firmware extension — Wi-Fi 6 CSI, 802.15.4 mesh, TWT, LP-core hibernation + +| Field | Value | +|-------|-------| +| **Status** | Accepted — P1–P10 complete, firmware-side substrate closed at **v0.7.0-esp32** (2026-05-23) | +| **Date** | 2026-05-22 (created) · 2026-05-23 (last revision — P10 + sprint summary) | +| **Deciders** | ruv | +| **Codename** | **C6-SOTA** | +| **Relates to** | ADR-018 (CSI binary frame format), ADR-028 (ESP32 capability audit), ADR-029 (RuvSense multistatic), ADR-030 (RuvSense persistent field model), ADR-031 (RuView sensing-first), ADR-061 (QEMU CI), ADR-081 (adaptive CSI mesh kernel), ADR-097 (rvCSI adoption) | +| **Tracking issue** | [ruvnet/RuView#762](https://github.com/ruvnet/RuView/issues/762) | +| **Firmware releases** | [v0.6.7](https://github.com/ruvnet/RuView/releases/tag/v0.6.7-esp32) · [v0.6.8](https://github.com/ruvnet/RuView/releases/tag/v0.6.8-esp32) · [v0.6.9](https://github.com/ruvnet/RuView/releases/tag/v0.6.9-esp32) · [v0.7.0](https://github.com/ruvnet/RuView/releases/tag/v0.7.0-esp32) | +| **Witness** | [`docs/WITNESS-LOG-110.md`](../WITNESS-LOG-110.md) — 13 §A0 entries (§A0.1 → §A0.13), 1 §A.1-A.12 dual-soak, 4 §B blocker entries, 5 §C bug fixes, 1 §D-workaround | + +--- + +## 1. Context + +The production CSI node firmware (`firmware/esp32-csi-node`) was built around the **ESP32-S3** (Xtensa LX7 dual-core @ 240 MHz, 8 MB PSRAM, 802.11 b/g/n). The repo's `firmware/esp32-hello-world/main.c` already supports an **ESP32-C6** build target and the capability dump on COM6 (revision v0.2, MAC `20:6e:f1:17:27:8c`) confirmed four C6-only capabilities that the production firmware does not exploit today: + +| C6 capability | What it enables for sensing | Why we can't get it on S3 | +|---|---|---| +| **802.11ax (Wi-Fi 6) HE-LTF CSI** | 242 subcarriers per HE20 frame (vs 52 for HT-LTF), HE-MU/HE-TB PPDU types, OFDMA-aware channel sounding | S3 radio is HT-only (n) | +| **802.15.4 (Thread / Zigbee)** | Cross-node time-sync over a separate radio — frees Wi-Fi airtime for CSI, ±100 µs alignment possible without coordination traffic on the sensing channel | S3 has no 802.15.4 | +| **TWT (Target Wake Time)** | Sensor negotiates a deterministic wake slot with the AP; CSI cadence becomes scheduler-bounded instead of opportunistic | Requires 802.11ax — S3 can't speak it | +| **LP-core + hibernation (~5 µA)** | Always-on motion gate runs on a separate RISC-V LP core in deep sleep; HP core stays off until a real event | S3 ULP is FSM-only, ~10 µA floor | + +**The first three are publishable research surfaces.** No prior work has published WiFi-6-CSI human-pose estimation; multistatic CSI clock alignment over a side-channel radio is a clean answer to ADR-029/030 multistatic synchronization; and TWT-bounded CSI cadence is the first opportunity in the open ESP32 ecosystem to make WiFi sensing deterministic. + +**The fourth (LP-core) unblocks a product line.** Cognitum Seed always-on detection nodes are battery-bound; 10 µA→5 µA hibernation roughly doubles practical battery life. + +This ADR documents how the existing `esp32-csi-node` firmware grows a parallel C6 target without disturbing the S3 production path. + +### 1.1 What this ADR is *not* + +- Not a deprecation of the S3 firmware. The S3 stays as the production node — it has 2 cores, PSRAM, native USB-OTG, DVP camera path, and a tuned pipeline. The C6 is added as a research/seed target. +- Not a port of every S3 feature to C6. Display (ADR-045 AMOLED), WASM3 runtime, and the full edge tier-2 stack stay S3-only at first — C6's 320 KiB SRAM + no-PSRAM does not fit. +- Not a hardware redesign. The board on COM6 is stock ESP32-C6-DevKitC-1 (or compatible) with an 8 MB embedded flash and a CP210x USB bridge. + +## 2. Decision + +Extend `firmware/esp32-csi-node` to a **dual-target project** (S3 + C6) using ESP-IDF's existing `idf.py set-target` mechanism plus a target-keyed `sdkconfig.defaults.esp32c6` overlay. Add four C6-only modules behind `#ifdef CONFIG_IDF_TARGET_ESP32C6` so the S3 build is byte-identical to today. + +### 2.1 Module breakdown + +| New module | File | C6-only? | Purpose | +|---|---|---|---| +| **HE-LTF CSI tagging** | extend `csi_collector.c` | shared (no-op on S3) | Read `wifi_pkt_rx_ctrl_t.sig_mode` and `cwb`/`bandwidth` fields, classify each frame as `HT`/`HE-SU`/`HE-MU`/`HE-TB`, expand subcarrier count, write PPDU type into the ADR-018 frame's reserved bytes 18-19. | +| **802.15.4 time-sync** | `c6_timesync.c/.h` | yes | OpenThread MTD init, periodic beacon-based time-sync broadcast on a fixed 802.15.4 channel, exports `c6_timesync_get_epoch_us()`. | +| **TWT setup** | `c6_twt.c/.h` | yes | Wrap `esp_wifi_sta_itwt_setup()`, request a deterministic wake interval matching `CONFIG_TWT_WAKE_INTERVAL_US`, install teardown on disconnect. | +| **LP-core hibernation** | `c6_lp_core.c/.h` + `lp_core/main.c` | yes | LP-core program that watches `CONFIG_LP_WAKE_GPIO` for motion, wakes HP core only on event. HP-side calls `c6_lp_core_arm()` before `esp_deep_sleep_start()`. | + +### 2.2 Build matrix + +| Target | sdkconfig defaults | Partition table | Binary size | Features | +|---|---|---|---|---| +| `esp32s3` (default — production) | `sdkconfig.defaults` (unchanged) | `partitions_display.csv` (8 MB) | ~1.1 MB | Full pipeline + display + WASM | +| `esp32c6` (new — research) | `sdkconfig.defaults` + `sdkconfig.defaults.esp32c6` overlay | `partitions_4mb.csv` (4 MB single OTA) | target <1 MB | CSI + TWT + 802.15.4 + LP-core, no display, no WASM | + +ESP-IDF's idf-build-system picks `sdkconfig.defaults.` automatically when `idf.py set-target esp32c6` is invoked. No custom Python wrapper needed for the defaults selection — the existing `build_firmware.ps1` keeps working for S3. + +### 2.3 ADR-018 frame format extension + +Bytes 18-19 are currently reserved. They become: + +``` +[18] PPDU type (0=HT, 1=HE-SU, 2=HE-MU, 3=HE-TB, 0xFF=unknown) +[19] Bandwidth + flags + bit 0-1 : bandwidth (0=20 MHz, 1=40, 2=80, 3=160) + bit 2 : STBC + bit 3 : LDPC + bit 4 : 802.15.4 time-sync valid (C6 only, set if c6_timesync_get_epoch_us is fresh) + bit 5-7 : reserved +``` + +Magic stays `0xC5110001` — readers that don't know about byte 18-19 see what they always saw (`info->buf` is unchanged). Readers that do can opt in. + +### 2.4 802.15.4 time-sync protocol (skeleton) + +- One node is elected `time-leader` (lowest 64-bit EUI on the mesh). +- Leader broadcasts a `TS_BEACON` frame every 100 ms on 802.15.4 channel 15 containing its monotonic `esp_timer_get_time()` snapshot. +- Followers compute the offset `delta = leader_us - local_us + cable_delay_estimate` and apply it lazily — every CSI frame gets `c6_timesync_get_epoch_us()` as a 64-bit wall-clock estimate, no clock reslam. +- Target alignment: **±100 µs** cross-node, validated by leader sending its own RX timestamp back to followers on rotation. +- Falls back to local timer if no leader heard within 5 s. + +### 2.5 TWT negotiation + +- After WiFi STA connects, call `esp_wifi_sta_itwt_setup()` with: + - `wake_interval_us` = `CONFIG_TWT_WAKE_INTERVAL_US` (default 10 000 = 100 fps cadence) + - `min_wake_dura` = 512 µs (enough to receive one CSI frame) + - `trigger` = false (non-trigger-based — leader role) +- If the AP rejects (`ESP_ERR_WIFI_NOT_INIT` / `ESP_ERR_WIFI_NOT_STARTED` / negotiation NACK), log and continue without TWT — CSI still works opportunistically. +- Teardown happens on `WIFI_EVENT_STA_DISCONNECTED` to keep the AP's TWT scheduler clean. + +### 2.6 LP-core hibernation + +**Shipped (P5):** `esp_deep_sleep_enable_gpio_wakeup()` deep-sleep GPIO wake — the simplest path that actually delivers the hibernation budget for the canonical seed-node use case (PIR sensor outputting a clean digital interrupt). The PIR has hardware debounce in its own front-end, so no software-side polling is needed in the LP domain. Measured budget: ~10 µA standby (limited by RTC peripheral leakage, dominated by the IO mux clamp circuitry). + +**Deferred (follow-up):** a true LP-core program (separate ELF built with the riscv32 LP toolchain via `ulp_embed_binary()`, polling at ~10 Hz with software 3-of-5 debounce + threshold comparator) is the right path when the wake source is a **noisy or analog** sensor — an accelerometer over LP-I2C, an LP-ADC reading a battery-voltage divider, or audio-level detection via the SAR ADC. That code lives in `lp_core/main.c` as a sub-project and pushes the standby budget down to the ~5 µA target. Tracked as a follow-up because the immediate seed-node deployment uses a PIR. + +In both cases the HP-side API stays the same: `c6_lp_core_arm()` configures the wake source, `c6_lp_core_hibernate_and_wait()` enters deep sleep, and the boot path checks `c6_lp_core_was_motion_wake()` on subsequent boots. Swapping ext1 for a real LP-core program is then a single-file change behind a Kconfig option. + +## 3. Consequences + +### 3.1 Wins + +- New publishable research surface (Wi-Fi-6 CSI human pose). +- Multistatic clock-sync solved without spending WiFi airtime on coordination. +- Deterministic CSI cadence available where the AP cooperates (TWT). +- Cognitum Seed always-on class roughly doubles practical battery life. +- S3 production path untouched — zero regression risk for shipped fleets. + +### 3.2 Costs + +- Second firmware target to maintain (build, test, release). Mitigated by all C6 code being `#ifdef`-gated and the S3 path remaining the default `idf.py build`. +- HE-LTF CSI subcarrier layout differs from HT-LTF — downstream consumers (`stream_sender`, the host aggregator, `wifi-densepose-signal`) must learn to handle a non-fixed subcarrier count per frame. +- 802.15.4 stack adds ~80 KB to the C6 binary. Fits in 4 MB partition with room to spare. +- TWT depends on AP cooperation. Most home APs (including the `ruv.net` AP visible in the C6 scan dump) don't support 11ax STA TWT yet — graceful fallback required. + +### 3.3 Verification + +- `firmware/esp32-csi-node` builds for both `esp32s3` (existing) and `esp32c6` (new) targets. +- S3 build artifact SHA-256 unchanged vs the last v0.6.x release (proves no regression in shared code). +- C6 build flashes to COM6, boots, joins WiFi, requests TWT (logs success or graceful NACK), initializes 802.15.4, emits CSI frames with the extended ADR-018 metadata. +- Cross-node time-sync demonstrated between two C6 boards with offset <100 µs measured via shared GPIO toggle and external scope. +- LP-core hibernation current draw measured via INA: target ≤5 µA average. + +## 4. Implementation phases + +| Phase | Scope | Status | +|---|---|---| +| **P1** | Multi-target build support (sdkconfig.defaults.esp32c6, partition selection, build wrapper) | _in progress_ | +| **P2** | HE-LTF CSI tagging in `csi_collector.c` | pending | +| **P3** | TWT setup helper | pending | +| **P4** | 802.15.4 init + skeleton time-sync | pending | +| **P5** | LP-core hibernation stub | ✅ **done** (v0.6.6); upgraded to real LP-core polling program in v0.6.7 (`firmware/esp32-csi-node/main/lp_core/main.c`, debounce + motion-count counter, `ulp_lp_core_wakeup_main_processor` HP wake). Ext1 fallback kept as the `CONFIG_C6_LP_CORE_ENABLE=n` branch. Datasheet ≤5 µA pending INA measurement. | +| **P6** | Build, flash COM6, capture boot telemetry, S3 regression check | ✅ **done** — `c6_ts: init done channel=15 leader=yes(candidate)`, HE MAC firmware loaded, 1003 KB binary (46% slack) | +| **P7** | Benchmark C6 vs S3 (CSI fps, RAM, TWT jitter, power) | ✅ **done** — boot 353 ms, ts init 413 ms, image 1003 KB (−9 % vs S3), 310 KiB free heap, CSI callbacks fire at 64 subcarriers/frame on ch 1 background traffic | +| **P8** | Witness bundle update, CLAUDE.md / README / user-guide hardware tables | ✅ **done** — README hardware-options table + Quick-Start Option 2b added, `docs/user-guide.md` now has full ESP32-C6 section (build, flash, provision, multi-room time-sync, battery seed mode) | +| **P9** | **Software-only unblocks for B1/B2/B4 (firmware v0.6.7)** | ✅ **done** — (1) Real LP-core motion-gate program loads via `ulp_embed_binary(lp_core/main.c)`, exposes shared `motion_count`/`poll_count` symbols for witness verification (B4 code path complete, hardware-measurement still pending INA). (2) Soft-AP HE module (`c6_softap_he.{h,c}`) runs the C6 in AP+STA mode with WPA2 + HE advertised so a second C6 STA can negotiate real iTWT against a known-cooperative AP (B1/B2 unblocker without buying an 11ax router). (3) Build artifacts: S3 8 MB 1093 KB / C6 4 MB 1019 KB, both green on IDF v5.4. Both new modules default-off so v0.6.6 fleets see no behavior change. | +| **P10** | **End-to-end mesh substrate: measured, smoothed, wired, decoded (firmware v0.6.8 → v0.7.0 + host crates)** | ✅ **done** — bench-quantified two-board substrate **and** the host-side wire that consumes it. **(a) v0.6.8 ESP-NOW EMA smoother** (`c6_sync_espnow.c`, α=1/8 fixed-point shift, 8-sample window). 5-min two-board soak (witness §A0.10) measured **411.5 µs raw stdev → 104.1 µs smoothed stdev (3.95× suppression, 4.70× peak-to-peak)** with **+30 µs/min crystal drift preserved within 2 µs/min**. **Cross-board RX 99.56 %** over 2701 beacons, 0 TX fail, leader election fired at +27336 ms. The ADR-110 §2.4 ≤100 µs alignment target is **empirically met by the smoothed offset alone**. **(b) v0.6.9 sync-packet** (32-byte UDP, magic `0xC511A110`, every `CONFIG_C6_SYNC_EVERY_N_FRAMES` CSI frames) carries `(node_id, local_us, epoch_us, sequence)` so host can pair against incoming CSI frames. Live-verified §A0.12 — COM9 reports `local − epoch = 1 163 565 µs` matching §A0.10's measured boot delta within 285 µs. **(c) v0.7.0 ADR-018 byte 19 bit 4 wire-fix** — bit 4 now sourced from `c6_sync_espnow_is_valid()` (was only the broken 802.15.4 path). Mixed S3+C6 fleets correctly advertise sync via the working transport. **(d) Host-side decoders + wiring**: Python `SyncPacketParser` (6 tests) + Rust `SyncPacket` (10 tests, all green; `SyncPacket::apply_to_local` recovers per-frame mesh-aligned timestamps). Sensing-server `udp_receiver_task` magic-dispatches `0xC511A110` and stores `NodeState::latest_sync` + `NodeState::mesh_aligned_us(local_at_frame)` helper. **(e) IDF v5.4 upstream gap formally documented (§A0.6)**: full `components/esp_wifi/include/esp_wifi*.h` grep proves the public API exposes only STA-side iTWT/bTWT — no `esp_wifi_ap_set_he_config`, no `wifi_he_ap_config_t`. Soft-AP HE/TWT-Responder advertise is not user-controllable on C6 in IDF v5.4; B1/B2 measurement requires either a future IDF or an external 11ax AP. | + +This ADR is updated at the end of each phase with the actual outcome, links to commits, and any deviations from the design. + +### 4.1 P10 detail — `/loop 5m` SOTA sprint (2026-05-23) + +P10 was driven by a `/loop 5m until sota. and ultra optmized` invocation that ran 16 iterations over ~80 minutes. The sprint shipped 4 firmware releases, 17 commits on the branch, 13 host-side unit tests, and converted the §B substrate from "designed targeting ±100 µs" into "measured at 104 µs smoothed stdev over a 5-min two-board soak with full host-side decoders + sensing-server consumer." + +| Iter | Shipped | Witness | +|---|---|---| +| 1 | `c6_softap_he` module + IDF v5.4 gap discovery | §A0.5, §A0.6 | +| 2 | ESP-NOW cross-board mesh proven live | §A0.7 | +| 3 | 4 MB S3 release variant | — | +| 4 | 4-min mesh soak — first quantified sync stability | §A0.8 | +| 5 | EMA smoother in firmware (α=1/8) | §A0.9 | +| 6 | 5-min EMA soak: **3.95× suppression measured** | §A0.10 | +| 7 | v0.6.8-esp32 release + §A0.11 timestamp-wiring gap recorded | §A0.11 | +| 8 | Sync packet emission (option 2 chosen) | — | +| 9 | Sync packet live-verified on both boards | §A0.12 | +| 10 | v0.6.9-esp32 release + `CONFIG_C6_SYNC_EVERY_N_FRAMES` Kconfig knob | — | +| 11 | ADR-018 byte 19 bit 4 wire-fix from ESP-NOW path | — | +| 12 | v0.7.0-esp32 release + Python `SyncPacketParser` stub | §A0.13 | +| 13 | 6 Python unit tests + README/user-guide doc updates | — | +| 14 | Rust `SyncPacket` decoder + 7 unit tests in `wifi-densepose-hardware` | — | +| 15 | Sensing-server `udp_receiver_task` magic-dispatch + `NodeState::latest_sync` | — | +| 16 | `SyncPacket::apply_to_local()` + `NodeState::mesh_aligned_us()` (+ 3 more tests, 10 total) | — | + +### 4.2 P10 measured numbers (substrate now quantified, not just designed) + +Every number below comes from a real bench capture against COM9 + COM12 ESP32-C6 boards, raw logs preserved under `dist/firmware-v0.6.7/iter{2,4,5,6,9}-*.log` and `dist/firmware-v0.6.8/iter9-*.log`. + +| Metric | Measured | Target | +|---|---|---| +| Cross-board ESP-NOW RX rate (5-min soak) | **99.56 %** (2689 / 2701 beacons) | — | +| Cross-board TX failures (5-min soak) | **0** on either board | — | +| Beacon rate | **10.00 /s** exactly (FreeRTOS solid) | 10 Hz nominal | +| Raw offset stdev | 411.5 µs | — | +| **EMA-smoothed offset stdev** | **104.1 µs** | **≤100 µs (§2.4)** | +| Range reduction (smoothed vs raw) | **4.70×** peak-to-peak | — | +| Measured C6 crystal skew between bench boards | **1.4 ppm** | ESP32 spec ±10 ppm | +| Drift preservation (smoothed tracking raw) | within **2 µs/min** | — | +| Leader election | ✅ COM9 stepped down at +27 336 ms on `lower-id` rule | — | +| Sync packet round-trip (firmware → Python decoder) | identical bytes, offset recovered to within **285 µs** of §A0.10 | — | +| Raw 802.15.4 RX | 0 frames over 60 s + 240 s + 300 s soaks | (D1 broken in IDF v5.4) | +| C6 v0.7.0 image size / slack | 1019 KB / **45 %** on 4 MB single-OTA | — | +| S3 v0.7.0 image size / slack | 1094 KB / **47 %** on 8 MB dual-OTA | — | + +### 4.3 P10 host-side surface (production code shipped) + +| Crate / File | New API | +|---|---| +| `v2/crates/wifi-densepose-hardware/src/sync_packet.rs` | `SyncPacket`, `SyncPacketFlags`, `SYNC_PACKET_MAGIC = 0xC511A110`, `SYNC_PACKET_SIZE = 32`, `SyncPacket::from_bytes`, `SyncPacket::to_bytes`, `SyncPacket::local_minus_epoch_us`, `SyncPacket::apply_to_local(local_us)` — 10 unit tests, all green | +| `v2/crates/wifi-densepose-sensing-server/src/main.rs` | `NodeState::latest_sync: Option`, `NodeState::latest_sync_at: Option`, `NodeState::mesh_aligned_us(local_at_frame_us) -> Option`, `udp_receiver_task` magic-dispatch on `SYNC_PACKET_MAGIC` | +| `archive/v1/src/hardware/csi_extractor.py` | `SyncPacket` dataclass, `SyncPacketParser.parse`, `SyncPacketParser.MAGIC` — 6 Python unit tests, all green | + +## 5. Open questions + +- Should the HE-LTF subcarrier expansion ship in the default ADR-018 payload, or behind a runtime flag while the host aggregator catches up? **Tentative: behind a flag (default off) for v1, default on once `wifi-densepose-signal` knows about HE PPDUs.** +- Should the 802.15.4 time-sync channel be configurable, or hard-coded to 15? **Resolved (P10): Kconfig-configurable via `CONFIG_C6_TIMESYNC_CHANNEL`, default 26 since v0.6.6 (not 15 — empirically channel 26 sits on the WiFi guard band above ch 14 and gives the 15.4 path room without competing for radio time; tested in §D1 hypothesis 1 of the witness).** +- Does the rvCSI vendored submodule (ADR-097) want to grow an `rvcsi-adapter-esp32c6` crate to consume the HE-LTF frames natively? **Out of scope for this ADR; revisit in a follow-up.** + +## 6. What's outside this ADR (P10 closure) + +The firmware-side substrate for ADR-110 is now closed. Three categories remain, all explicitly **not** in this ADR's scope: + +1. **Multistatic CSI fusion math** — ADR-029/030 territory. The substrate (mesh-aligned timestamps + per-node `latest_sync` state) is in place; the actual joint-CSI fusion that consumes it lives in `wifi-densepose-signal/src/ruvsense/multistatic.rs`. +2. **Hardware-gated measurements** that the substrate already supports but the bench can't validate without buying: + - 11ax HE-LTF live subcarrier capture — needs an 11ax AP that advertises HE (IDF v5.4 doesn't expose an AP-side HE config API, §A0.6). + - ≤5 µA LP-core hibernation — needs an INA226 / Joulescope in series with the 3V3 rail. +3. **IDF upstream fixes**: + - 802.15.4 RX path on C6 + IDF v5.4 — `c6_timesync` ships and initialises but never RXes a frame (D1, 5 hypotheses tested + rejected). ESP-NOW workaround (`c6_sync_espnow`) is the working primary mesh transport. The 802.15.4 source stays in for the day IDF fixes the driver. + - Soft-AP HE/TWT-Responder advertise API — `c6_softap_he` ships as the in-place hook for when IDF v5.5+ exposes it. diff --git a/docs/adr/ADR-115-home-assistant-integration.md b/docs/adr/ADR-115-home-assistant-integration.md new file mode 100644 index 00000000..42d88429 --- /dev/null +++ b/docs/adr/ADR-115-home-assistant-integration.md @@ -0,0 +1,670 @@ +# ADR-115: Home Assistant integration via MQTT auto-discovery + Matter bridge + +| Field | Value | +|-------|-------| +| **Status** | Proposed | +| **Date** | 2026-05-23 | +| **Deciders** | ruv | +| **Codename** | **HA-DISCO** (MQTT) + **HA-FABRIC** (Matter) | +| **Relates to** | ADR-018 (CSI binary frame format), ADR-021 (ESP32 vitals), ADR-031 (RuView sensing-first), ADR-039 (edge vitals packet 0xC511_0002), ADR-079 (camera ground-truth), ADR-103 (cog-person-count), ADR-110 (ESP32-C6 firmware), ADR-114 (cog-quantum-vitals) | +| **Tracking issue** | TBD — file under RuView issue tracker, link in §10 | +| **Related issues** | [#574](https://github.com/ruvnet/RuView/issues/574) (mDNS for seed_url), [#760](https://github.com/ruvnet/RuView/issues/760) (sensing UI), [#761](https://github.com/ruvnet/RuView/issues/761) (HA competitor scan) | + +--- + +## 1. Context + +RuView and the underlying WiFi-DensePose stack already expose rich human-sensing telemetry — presence, person count, 17-keypoint pose, breathing rate (BR), heart rate (HR), motion level, fall detection, RSSI, and zone occupancy — over a Rust `wifi-densepose-sensing-server` (`v2/crates/wifi-densepose-sensing-server`). The server emits three structured message types over its WebSocket at `/ws/sensing`: + +| Server message `type` | Source (`main.rs`) | Payload (selected fields) | +|---|---|---| +| `pose_data` | line 2340 | 17 keypoints per detection, `confidence`, `track_id` | +| `edge_vitals` | line 3971 | `node_id`, `presence`, `fall_detected`, `motion`, `breathing_rate_bpm`, `heartrate_bpm`, `n_persons`, `motion_energy`, `presence_score`, `rssi` | +| `sensing_update` | lines 1903 / 2047 / 4098 / 4350 / 4481 | aggregated detections + zone hits | + +Customers running a **Cognitum Seed** appliance (`cognitum-v0` at `:9000`) or a standalone **ESP32-S3** / **ESP32-C6** node (per ADR-110) want this telemetry inside **Home Assistant (HA)** — the most widely deployed open-source home-automation hub (>500 k installs, OSS, MQTT-native) — so they can build automations around presence, vitals, falls, and motion without writing code against our REST/WebSocket API. + +### 1.1 Why this matters now + +Two recent customer-facing issues show the same plug-and-play gap: + +- **#574 (mDNS for seed_url)** — users don't want to manually paste a `seed://` URL into the dashboard; they expect the hub to discover the node. +- **#760 (sensing UI)** — users asked for an HA-style "single dashboard with all my sensors" experience; we currently force them through our own UI. + +Both reduce to the same underlying complaint: *RuView is a black box that needs glue code to fit into the rest of a smart home.* HA solves that problem industry-wide. We should meet users where they already are. + +### 1.2 Comparison: who else does this + +| Product | HA approach | Notes | +|---|---|---| +| **espectre.dev** | Custom HA integration (HACS), Python | Pose-only; no vitals; closed-source server | +| **tommysense.com** | MQTT auto-discovery + cloud bridge | Vitals only; cloud-mandatory | +| **Aqara FP2** | Native ZigBee + HA | Presence + zones only; commercial mmWave | +| **mmWave HLK-LD2410** | ESPHome firmware → HA | Presence + distance, no pose, no vitals | +| **Matter devices (any)** | Native Matter clusters, multi-controller | Apple/Google/Alexa/HA all consume; presence in `OccupancySensing` since Matter 1.3; no vitals/pose clusters yet | +| **RuView (today)** | None | Customer must build their own bridge | + +The competitive bar is set by Aqara FP2 (HA-native, multi-zone presence) and ESPHome-flashed LD2410 nodes (cheap, plug-and-play). To match or exceed them we need first-class HA integration that exposes our **differentiated** capabilities: pose, HR/BR, fall, multi-room. + +### 1.3 What this ADR is *not* + +- Not a HACS Python integration today (that's a follow-on; see §6). +- Not a webhook-only push (one-way, no entity discovery). +- Not a change to the ADR-018 CSI frame format or ADR-039 edge vitals packet — purely an additive consumer of the existing WS broadcast. +- Not a change to firmware. Both ESP32-S3 (ADR-028) and ESP32-C6 (ADR-110) paths stay byte-identical. + +--- + +## 2. Decision + +Adopt a **dual-protocol** integration strategy: + +1. **Primary — MQTT + Home Assistant auto-discovery (HA-DISCO).** Add an MQTT publisher to `wifi-densepose-sensing-server` that connects to a user-supplied MQTT broker (default: `mqtt://localhost:1883`), publishes one HA-discovery message per capability per RuView node on startup and on periodic refresh (default 600 s), translates each WebSocket broadcast (`edge_vitals`, `pose_data`, `sensing_update`) into per-entity MQTT state messages, and honors a `--privacy-mode` flag that strips biometrics (HR / BR / pose keypoints) before publish. + +2. **Secondary — Matter Bridge (HA-FABRIC).** Expose RuView nodes as Matter Bridged Devices over WiFi so the **subset of capabilities Matter standardises today** — presence (`OccupancySensing`), motion (`BooleanState`), fall events (`SwitchCluster`-as-event), person count (numeric attribute on the bridge) — are consumable by **any Matter controller**: Apple Home, Google Home, Amazon Alexa, Samsung SmartThings, and Home Assistant itself. Biometrics (HR/BR) and pose stay on MQTT until the Matter spec adds device types that can represent them. + +The two paths are **complementary, not alternative**: MQTT carries the full telemetry surface for power users; Matter carries the standardised subset for cross-ecosystem reach. A user running HA gets both — MQTT entities populate alongside Matter Bridged Devices and HA dedupes via `unique_id`. A user running Apple Home gets only Matter, but they get the presence/fall/count signals that matter most for automations. + +A **Home Assistant HACS Python integration** is sketched as a follow-on (§6.A) for users who don't run MQTT and want richer features than Matter exposes. A **REST webhook** path is rejected (§6.B). + +### 2.1 Why this split (MQTT primary, Matter secondary) + +| Criterion | A. MQTT auto-discovery | **D. Matter Bridge** | B. HACS Python integration | C. REST webhook | +|---|---|---|---|---| +| **Zero-code UX for end user** | yes (HA picks up entities automatically) | yes (pair via QR code, any controller) | yes (after install) | no (user wires automations by hand) | +| **Cross-ecosystem reach** | HA + any MQTT consumer | **Apple / Google / Alexa / SmartThings / HA** | HA-only | HA-only | +| **Distribution + maintenance** | one Rust feature in our existing crate | one Rust feature + Matter SDK linkage | new Python repo, HACS approval | trivial | +| **Discovery (auto entity creation)** | yes (HA's `homeassistant/` topic namespace) | yes (Matter commissioning + bridge endpoints) | yes (config flow) | no | +| **Bidirectional control** | yes (subscribe to command topic) | yes (Matter commands) | yes | one-way only | +| **Carries vitals (HR/BR) / pose** | **yes** | **no — no Matter clusters exist** | yes (custom) | yes (custom) | +| **Carries presence / count / fall** | yes | **yes (Matter 1.3+)** | yes | yes | +| **Works without HA running** | any MQTT consumer | any Matter controller | HA-only | HA-only | +| **Existing infra in target homes** | most HA users already run a broker | one Matter controller per home (Apple HomePod / Nest Hub / HA-Matter add-on) | none | none | +| **Effort to MVP** | ~2 weeks | ~4–6 weeks (Matter SDK + commissioning) | ~4–6 weeks | ~2 days | +| **Privacy controls** | per-topic + retain policy | Matter fabric isolation + spec-level limits on what's exposable | application-layer | weak | +| **Certification cost** | none | "Works with HA" free; **CSA Matter certification optional** (~$3 k/year membership for the badge) | HACS review (free) | none | +| **Test surface in CI** | dockerised mosquitto + schema lint | matter-rs test harness + chip-tool sims | full HA test harness | curl | + +**MQTT is primary** because it carries 100% of RuView's differentiated telemetry (pose, HR, BR) which no other path can. **Matter is secondary** because it covers the ~30% subset (presence/count/fall) that matters across the *other 70% of smart-home buyers* who don't run HA. Together they cover the whole market. Webhook (C) gives up too much (no entity discovery, no control plane) and is rejected. HACS (B) is strictly more polished than MQTT but strictly more expensive; revisit after MQTT adoption data is in. + +--- + +## 3. Detailed Design + +### 3.1 Entity mapping + +Each RuView node becomes one HA **device**. Each capability becomes an **entity** on that device. ESP32 nodes behind a Cognitum Seed appliance are linked via HA's `via_device` field so the topology shows up in the HA UI. + +| Capability | HA component | `device_class` | `state_class` | Unit | Icon | Source field (server WS) | +|---|---|---|---|---|---|---| +| Presence | `binary_sensor` | `occupancy` | — | — | `mdi:motion-sensor` | `edge_vitals.presence` | +| Person count | `sensor` | — | `measurement` | persons | `mdi:account-group` | `edge_vitals.n_persons` | +| Breathing rate | `sensor` | — | `measurement` | bpm | `mdi:lungs` | `edge_vitals.breathing_rate_bpm` | +| Heart rate | `sensor` | — | `measurement` | bpm | `mdi:heart-pulse` | `edge_vitals.heartrate_bpm` | +| Motion level | `sensor` | — | `measurement` | % | `mdi:run` | `edge_vitals.motion` (0–1 → ×100) | +| Motion energy | `sensor` | — | `measurement` | (unitless) | `mdi:waveform` | `edge_vitals.motion_energy` | +| Fall detected | `event` | — | — | — | `mdi:human-fall` | `edge_vitals.fall_detected` | +| Presence score | `sensor` | — | `measurement` | % | `mdi:gauge` | `edge_vitals.presence_score` (×100) | +| RSSI | `sensor` | `signal_strength` | `measurement` | dBm | `mdi:wifi` | `edge_vitals.rssi` | +| Zone occupancy (per zone) | `binary_sensor` | `occupancy` | — | — | `mdi:map-marker` | `sensing_update.zones[*]` | +| Pose keypoints | `sensor` (JSON attr) | — | — | — | `mdi:human` | `pose_data.keypoints` (opt-in) | +| Tracked persons (per ID) | `binary_sensor` (dynamic) | `occupancy` | — | — | `mdi:account` | `pose_data.track_id` | + +Pose keypoints are intentionally not a first-class HA entity (HA has no 17-keypoint primitive); instead they're exposed as an attribute payload on a `wifi_densepose__pose` sensor, so power users can template against them but the default HA UI stays clean. + +### 3.2 MQTT topic structure + +We follow HA's documented `homeassistant////config` discovery convention. Object ID is `wifi_densepose_` to namespace cleanly against other devices. + +``` +homeassistant/binary_sensor/wifi_densepose_/presence/config (retained, QoS 1) +homeassistant/binary_sensor/wifi_densepose_/presence/state (not retained, QoS 0) +homeassistant/binary_sensor/wifi_densepose_/presence/availability (retained, QoS 1) + +homeassistant/sensor/wifi_densepose_/heart_rate/config (retained, QoS 1) +homeassistant/sensor/wifi_densepose_/heart_rate/state (not retained, QoS 0) + +homeassistant/sensor/wifi_densepose_/breathing_rate/config +homeassistant/sensor/wifi_densepose_/breathing_rate/state + +homeassistant/event/wifi_densepose_/fall/config (retained, QoS 1) +homeassistant/event/wifi_densepose_/fall/state (not retained, QoS 1) + +ruview//raw/pose (opt-in, not retained, QoS 0) +ruview//raw/sensing_update (opt-in, not retained, QoS 0) +``` + +The `ruview//raw/*` namespace is **outside** the `homeassistant/` discovery prefix on purpose: it carries the original WebSocket JSON for users who want to consume it directly (Node-RED, Grafana, custom scripts), without HA trying to interpret it as an entity. + +### 3.3 Example discovery payloads + +**Presence (binary_sensor):** + +```json +{ + "name": "Presence", + "unique_id": "wifi_densepose_aabbccddeeff_presence", + "object_id": "wifi_densepose_aabbccddeeff_presence", + "state_topic": "homeassistant/binary_sensor/wifi_densepose_aabbccddeeff/presence/state", + "availability_topic": "homeassistant/binary_sensor/wifi_densepose_aabbccddeeff/presence/availability", + "payload_on": "ON", + "payload_off": "OFF", + "payload_available": "online", + "payload_not_available": "offline", + "device_class": "occupancy", + "qos": 1, + "device": { + "identifiers": ["wifi_densepose_aabbccddeeff"], + "name": "RuView node aabbccddeeff", + "manufacturer": "ruvnet", + "model": "ESP32-S3 CSI node", + "sw_version": "v0.6.7", + "via_device": "cognitum_seed_1" + }, + "origin": { + "name": "wifi-densepose-sensing-server", + "sw_version": "0.7.0", + "support_url": "https://github.com/ruvnet/RuView" + } +} +``` + +**Heart rate (sensor):** + +```json +{ + "name": "Heart rate", + "unique_id": "wifi_densepose_aabbccddeeff_heart_rate", + "state_topic": "homeassistant/sensor/wifi_densepose_aabbccddeeff/heart_rate/state", + "availability_topic": "homeassistant/sensor/wifi_densepose_aabbccddeeff/heart_rate/availability", + "unit_of_measurement": "bpm", + "state_class": "measurement", + "icon": "mdi:heart-pulse", + "value_template": "{{ value_json.bpm }}", + "json_attributes_topic": "homeassistant/sensor/wifi_densepose_aabbccddeeff/heart_rate/state", + "qos": 0, + "device": { "identifiers": ["wifi_densepose_aabbccddeeff"] } +} +``` + +State payload published to `.../heart_rate/state`: + +```json +{ "bpm": 68.2, "confidence": 0.91, "ts": "2026-05-23T14:00:00Z" } +``` + +**Fall (event):** + +```json +{ + "name": "Fall detected", + "unique_id": "wifi_densepose_aabbccddeeff_fall", + "state_topic": "homeassistant/event/wifi_densepose_aabbccddeeff/fall/state", + "event_types": ["fall_detected"], + "icon": "mdi:human-fall", + "qos": 1, + "device": { "identifiers": ["wifi_densepose_aabbccddeeff"] } +} +``` + +State payload (fired once per fall, **not retained**): + +```json +{ "event_type": "fall_detected", "ts": "2026-05-23T14:00:00.123Z", "confidence": 0.87 } +``` + +### 3.4 Device-level grouping + +- One HA `device` per RuView **node** (ESP32-S3 / S3-Mini / C6, or the host running sensing-server in mock mode). +- `device.identifiers` = `["wifi_densepose_"]` where `node_id` is the MAC-derived ID already in `edge_vitals.node_id`. +- For nodes behind a **Cognitum Seed**, set `device.via_device = "cognitum_seed_"` so HA renders the topology as a tree (Seed → child nodes). +- The Cognitum Seed itself appears as a parent device with its own diagnostic entities (uptime, agent health) — published by the seed appliance directly, not by sensing-server. + +### 3.5 QoS, retention, and refresh + +| Topic | QoS | Retain | Refresh cadence | Rationale | +|---|---|---|---|---| +| `*/config` | 1 | **yes** | on startup + every 600 s | HA expects retained discovery; re-publishing periodically self-heals if HA restarts before our state messages arrive | +| `*/state` (sensor) | 0 | no | rate-limited per §3.7 | Best-effort; HA can tolerate occasional drops | +| `*/state` (binary_sensor) | 1 | **yes** | on change only | Last value matters; new HA subscribers should see current state | +| `*/state` (event) | 1 | no | on event | Falls must not be missed; never retained or HA replays old events | +| `*/availability` | 1 | **yes** | LWT + 30 s heartbeat | Offline detection | +| `ruview/*/raw/*` | 0 | no | as-emitted | Raw firehose; consumers opt in | + +### 3.6 Availability + Last Will and Testament (LWT) + +On connect, sensing-server sets an MQTT LWT on each entity's `availability` topic to `offline` (retained). On successful connect it publishes `online` (retained). A 30-second heartbeat re-publishes `online` so HA can detect zombie sessions. + +``` +LWT topic: homeassistant/binary_sensor/wifi_densepose_/presence/availability +LWT payload: offline +LWT QoS: 1 +LWT retain: true +``` + +### 3.7 Bandwidth control + rate limiting + +Pose keypoints at 10 fps × 17 keypoints × 3 floats ≈ 4–8 kbit/s per person — fine over LAN, but pathological if a user accidentally routes it to a metered cellular MQTT bridge. Defaults: + +| Entity type | Default rate | Configurable | Override flag | +|---|---|---|---| +| Presence (binary) | on change | yes | — | +| Person count | 1 Hz | yes | `--mqtt-rate-count=1` | +| BR / HR | 0.2 Hz (every 5 s) | yes | `--mqtt-rate-vitals=0.2` | +| Motion level | 1 Hz | yes | `--mqtt-rate-motion=1` | +| Fall events | on event | no (always immediate) | — | +| RSSI | 0.1 Hz | yes | `--mqtt-rate-rssi=0.1` | +| Pose keypoints | **off by default**, 1 Hz when on | yes | `--mqtt-publish-pose --mqtt-rate-pose=1` | +| Zones | on change | yes | — | + +### 3.8 Configuration UX — CLI + env + +New CLI flags on `wifi-densepose-sensing-server` (gated behind `--mqtt`): + +``` +--mqtt Enable MQTT publisher (default off) +--mqtt-host MQTT broker host (default: localhost) +--mqtt-port MQTT broker port (default: 1883, 8883 if --mqtt-tls) +--mqtt-username MQTT username +--mqtt-password-env Read password from env var (default: MQTT_PASSWORD) +--mqtt-client-id Client ID (default: wifi-densepose-) +--mqtt-prefix Discovery prefix (default: homeassistant) +--mqtt-tls Enable TLS (default off) +--mqtt-ca-file CA bundle (default: system trust) +--mqtt-client-cert Client cert for mTLS +--mqtt-client-key Client key for mTLS +--mqtt-refresh-secs Discovery refresh interval (default: 600) +--mqtt-rate-vitals Vitals publish rate (default: 0.2) +--mqtt-rate-motion Motion publish rate (default: 1.0) +--mqtt-rate-count Person count publish rate (default: 1.0) +--mqtt-rate-rssi RSSI publish rate (default: 0.1) +--mqtt-publish-pose Publish pose keypoints (default off) +--mqtt-rate-pose Pose publish rate when enabled (default: 1.0) +--privacy-mode Strip biometrics (HR/BR/pose) before publish +``` + +Env var equivalents follow `RUVIEW_MQTT_HOST`, `RUVIEW_MQTT_USERNAME`, etc., so Docker / systemd users don't have to wire long arg lists. Configuration is loaded in the order: CLI > env > defaults. + +### 3.9 TLS + auth + +- **Recommended**: mTLS on a dedicated VLAN with the broker pinned to a CA we issue per Cognitum Seed appliance. +- **Acceptable**: username + password over TLS to a public broker (e.g. user's existing Mosquitto add-on inside HA). +- **Rejected**: plaintext on any network shared with non-trusted devices. Sensing-server logs a `WARN` if `--mqtt` is enabled without `--mqtt-tls` and the broker is not `localhost`. + +### 3.10 Privacy mode + +`--privacy-mode` strips biometric + biometric-derivable channels before any MQTT publish, regardless of subscriber. Discovery messages for those entities are **never published** in this mode (HA never sees them exist). + +| Channel | Default | `--privacy-mode` | +|---|---|---| +| Presence | published | **published** | +| Person count | published | **published** | +| Motion level | published | **published** | +| Zone occupancy | published | **published** | +| RSSI | published | **published** | +| Breathing rate | published | **stripped** | +| Heart rate | published | **stripped** | +| Fall events | published | **published** (safety > privacy) | +| Pose keypoints | off by default | **stripped** (cannot be force-enabled) | + +This implements the ADR-106 primitive-isolation contract at the integration boundary: HR / BR / pose are biometric-class signals and must not leak to an unconstrained MQTT broker without explicit operator opt-in. + +### 3.11 Matter Bridge (HA-FABRIC) + +The Matter path runs **in the same `wifi-densepose-sensing-server` process** behind a `--matter` feature flag, gated independently of `--mqtt`. The bridge presents itself to Matter controllers as a **Bridged Devices Aggregator** (per Matter Core Spec §9.13) with one Bridged Device endpoint per RuView node, exposing the standardised subset of capabilities. Biometrics and pose are **not exposed** over Matter — they have no spec-defined clusters and cannot be soundly represented (covering them in `Generic Sensor` would force every controller to render them as nameless numbers). + +#### 3.11.1 Matter device-type mapping + +| RuView capability | Matter cluster | Endpoint device type | Source field | +|---|---|---|---| +| Presence | `OccupancySensing` (0x0406) | `OccupancySensor` (0x0107) | `edge_vitals.presence` | +| Motion (boolean above threshold) | `OccupancySensing` (0x0406) | (same endpoint) | `edge_vitals.motion > 0.1` | +| Fall event | `Switch` (0x003B) `MultiPressComplete` event | `GenericSwitch` (0x000F) | `edge_vitals.fall_detected` (one momentary press = one fall) | +| Person count | `OccupancySensing` extension attribute (vendor-specific 0xFFF1_0001) | (same endpoint) | `edge_vitals.n_persons` | +| Zone occupancy | one `OccupancySensor` endpoint per zone | (multiple endpoints) | `sensing_update.zones[*]` | +| RSSI / motion energy / presence score / breathing rate / heart rate / pose | **not exposed over Matter** | — | (MQTT only) | + +The vendor-specific person-count attribute uses RuView's CSA-assigned vendor ID (open question §9.9). Controllers that don't understand the vendor extension still see the standard `OccupancySensing.Occupancy` boolean — graceful degradation. + +#### 3.11.2 Commissioning + fabric model + +- **Commissioning over WiFi**: the bridge prints a Matter setup code (11-digit short code + QR string) to logs and to `--matter-setup-file ` on first start. User scans with Apple Home / Google Home / HA Matter integration. +- **No Thread radio required**: sensing-server runs on hosts (Pi 5, x86, Cognitum Seed) that have WiFi but no 802.15.4. Matter-over-WiFi is sufficient. Thread support is explicitly out of scope until ESP32-C6 firmware grows a Matter stack (separate ADR; see §7). +- **Multi-admin / multi-fabric**: the bridge accepts multiple commissioning sessions so a single node can be paired into Apple Home **and** Home Assistant **and** Google Home concurrently — Matter's `OperationalCredentials` cluster handles fabric isolation. +- **Resetting commissioning**: a `--matter-reset` CLI flag wipes stored fabric credentials so a node can be repaired against a new controller. + +#### 3.11.3 SDK choice (open in §9, sketched here) + +Three viable Rust paths: + +| Option | Pros | Cons | +|---|---|---| +| **`matter-rs`** (project-chip/rs-matter) — pure-Rust SDK | No FFI, no C++ build chain, fits our Rust-only crate policy, MIT-licensed | Less mature than C++ chip-tool; certification path less proven | +| **`project-chip/connectedhomeip`** via Rust FFI bindings | Reference implementation, every controller tested against it, certification-ready | Drags in CMake, C++ toolchain, ~50 MB of vendored code; clashes with our cargo-first build | +| **External Matter bridge process** (separate ESPHome-like daemon) | Decouples Rust crate from Matter SDK churn | Operational complexity; two processes to deploy | + +**Tentative**: `matter-rs` for v0.7.0 ship; fall back to chip-tool-FFI if cert blockers emerge. Final decision deferred to P7 spike. + +#### 3.11.4 Limitations to document upfront + +These are **deliberate**, not bugs — users must see them in `docs/integrations/matter.md` before pairing: + +- **No HR, BR, pose, RSSI over Matter.** Matter has no clusters for these. Use MQTT for biometric / detailed telemetry. +- **Fall events are one-shot.** A fall fires a momentary switch press; controllers must subscribe to the event (most do). +- **Person count is vendor-extension.** Apple Home / Google Home will show occupancy on/off; only HA and SmartThings (with custom handlers) will surface the count. +- **One fabric controller is "primary."** Automations split across fabrics can race; users should keep heavy automation logic in one controller (typically HA). +- **No video / image data ever.** Matter spec forbids it on these device types and we wouldn't expose it anyway. + +#### 3.11.5 Why this is "Works with HA" *and* "Works with everything else" + +A node paired into HA shows up in **two** ways: +- as a set of MQTT entities (HA-DISCO path) with full telemetry +- as a Matter device under HA's Matter integration with the standard subset + +HA dedupes by `unique_id` (we set both paths' IDs to `wifi_densepose__`), so users don't see ghost devices. The Matter device is the one Apple Home or Google Home will see if the user also pairs into those — same physical node, three controllers, no duplication. This is the architectural reason for adopting both protocols rather than picking one. + +### 3.12 Semantic automation primitives (HA-MIND) + +Raw signals are not the product. Customers don't want to *write a Node-RED flow that thresholds breathing rate at night to infer sleep*. They want a `binary_sensor.bedroom_someone_sleeping` they can wire directly into a "dim hallway light at 10 % if anyone's asleep" automation. Same for fall *risk*, distress, room activity, elderly inactivity, meeting-in-progress, bathroom occupancy. This is the inference layer that turns RuView from "RF sensing" into **ambient intelligence infrastructure** — and it has to ship as first-class HA entities and Matter events, not as a developer SDK. + +#### 3.12.1 Catalog of inferred primitives (v1) + +Each primitive is a fused state derived from one or more raw channels with a small finite-state machine. Inference runs inside `wifi-densepose-sensing-server` (same place MQTT publication runs), gated behind `--semantic` (default on; can be disabled). Each primitive has a confidence score and an explanation field so HA users can debug why it fired. + +| Primitive | Inputs (raw) | Output kind | Default true-condition | Hysteresis / refractory | +|---|---|---|---|---| +| **Someone sleeping** | presence + low motion (<5 % for ≥300 s) + breathing rate 8–20 bpm + low HR variability | `binary_sensor` (occupancy) | all conditions hold simultaneously | enters after 5 min; exits when motion > 15 % for ≥30 s | +| **Possible distress** | sustained elevated HR (>1.5× rolling baseline for ≥60 s) + agitated motion + no fall | `binary_sensor` (problem) + `event` | confidence ≥ 0.75 | latch for 5 min after exit | +| **Room active** | presence + motion > 10 % for ≥30 s in any 5-min window | `binary_sensor` (occupancy) | window-rolling | exits on 10 min idle | +| **Elderly inactivity anomaly** | no motion + presence stable for > N× rolling daily median idle (default 2×) | `binary_sensor` (problem) + `event` | model-personalised | per-resident baseline; alerts max 1×/day | +| **Meeting in progress** | person count ≥ 2 + sustained low-amplitude motion (sitting) + speech-band micro-motion if `speech_band` cog installed | `binary_sensor` (occupancy) | ≥2 ppl + ≥10 min | exits when person count < 2 for 2 min | +| **Bathroom occupied** | presence true in zone tagged `bathroom` | `binary_sensor` (occupancy) | zone+presence | privacy-mode keeps this enabled (it's not biometric) | +| **Fall risk elevated** | recent near-fall (sharp acceleration without confirmed fall) OR gait instability score > threshold | `sensor` (0–100) + `event` on threshold cross | model-derived | 24-hour window | +| **Bed exit (overnight)** | "someone sleeping" → presence transitions out of bed-tagged zone between 22:00–06:00 local | `event` | edge-triggered | one event per exit | +| **No movement (safety check)** | presence true + motion < 1 % for ≥ N minutes (default 30) | `binary_sensor` (problem) + `event` | duration threshold | clears on motion | +| **Multi-room transition** | track_id continuous across zones within 10 s | `event` (`who_went_from_to`) | edge-triggered | per-track event | + +Catalog v2 (deferred): "child playing", "pet vs human", "agitation gradient", "circadian phase". Owned by an ADR-1xx follow-on after the v1 primitives have field data. + +#### 3.12.2 Surface mapping across the three layers + +| Layer | How a semantic primitive shows up | +|---|---| +| **MQTT (HA-DISCO)** | New topic namespace `homeassistant/binary_sensor/wifi_densepose_//` and `homeassistant/event/wifi_densepose_//` — full discovery payloads including the explanation field as `json_attributes` | +| **Matter (HA-FABRIC)** | Standard cluster mappings: sleeping/active/meeting/bathroom → `OccupancySensing` (separate endpoints); distress/inactivity/no-movement/bed-exit/fall-risk-cross → `Switch.MultiPressComplete` events on dedicated `GenericSwitch` endpoints; fall-risk score → vendor-extension attribute on the bridge endpoint | +| **Home Assistant automations** | Ship 8 starter blueprints in P5: "Notify on possible distress", "Wake-up routine on bed exit", "Dim hallway on someone sleeping", "Alert on elderly inactivity anomaly", "Lights on for meeting in progress", "Bathroom fan on while occupied", "Escalate on fall risk crossing 70", "Auto-arm security when room not active" | +| **Apple Home scenes** | Each `OccupancySensor` endpoint and each `GenericSwitch` event triggers Apple Home scenes via Matter — user picks "When *bedroom someone sleeping* is on, run *night mode*" from the Apple Home UI directly. No HA required for this path | + +#### 3.12.3 Why these specific primitives + +These eight cover the **top automation requests from the smart-home market** without needing video or wearables: + +- **Healthcare / aging-in-place** — "elderly inactivity anomaly", "fall risk elevated", "possible distress", "no movement (safety check)", "bed exit (overnight)" — directly map to AAL (Active and Assisted Living) device-class expectations +- **Convenience automation** — "someone sleeping", "room active", "meeting in progress", "bathroom occupied" — the four highest-volume HA forum-requested binary states +- **Privacy** — none of these require biometric *values* to be published, only the inferred *states*. A `--privacy-mode` deployment can keep semantic primitives ON and still strip HR/BR/pose, because the inference happens server-side and only the state crosses the wire + +#### 3.12.4 Inference quality contract + +Each primitive ships with: +- A **published precision/recall** on a held-out test set built from ADR-079 paired captures + synthetic stress scenarios — committed to `docs/integrations/semantic-primitives-metrics.md` +- An **explainability payload**: every state change carries `reason: ["motion<5%", "br=12bpm", "presence=true"]` style attributes so HA users can debug +- A **confidence threshold**: per-primitive, user-tuneable via `--semantic-threshold-=` (default published in the metrics doc) +- A **suppression contract**: primitives never fire during the first 60 s after sensing-server start (warmup), and never during `csi_calibration_in_progress` states (per ADR-014) + +#### 3.12.5 Configuration + +``` +--semantic Enable inference layer (default: on) +--semantic-thresholds-file Per-primitive thresholds (defaults shipped) +--semantic-zones-file Zone-tag map (e.g. {"bathroom": ["zone_3"]}) +--semantic-baseline-window-days Days of history for personalised baselines (default: 14) +--no-semantic- Disable a specific primitive (repeatable) +``` + +#### 3.12.6 What this changes architecturally + +Inference lives in a new module `semantic_inference.rs` alongside `mqtt_publisher.rs` and `matter_bridge.rs`. It subscribes to the same `tokio::broadcast` channel everything else does, runs each primitive's FSM, and emits **two output streams**: + +1. A `SemanticState` event on a new broadcast channel that MQTT and Matter publishers both subscribe to (so the same inference drives both surfaces without duplication) +2. Append-only `semantic_events.jsonl` log under `--data-dir` for offline analysis + ADR-079 paired-capture supervision + +This means: **adding a new primitive is one file change**. No MQTT schema rev, no Matter cluster rev — just add the FSM, register it, and discovery/state publish flow through both surfaces automatically. + +--- + +## 4. Implementation phases + +| Phase | Scope | Status | +|---|---|---| +| **P1** | Add `mqtt` feature flag to `wifi-densepose-sensing-server` Cargo.toml (depends on `rumqttc = "0.24"`). Wire CLI flags (§3.8) into `cli.rs`. No publishing yet, just config plumbing + unit tests on flag parsing. | pending | +| **P2** | HA discovery message emitter. New module `mqtt_discovery.rs`. Emits all entity `config` topics on connect + every `--mqtt-refresh-secs`. Schema-validated against HA's published JSON schema. | pending | +| **P3** | State publication. Subscribe to internal `tokio::broadcast` channel (the one `tx.send(json)` writes to on line 3983 of `main.rs`). Translate `edge_vitals` / `sensing_update` / `pose_data` messages into per-entity state payloads. Apply rate-limit + privacy-mode filters. | pending | +| **P4** | Integration tests: dockerised mosquitto in CI (extend `.github/workflows/firmware-qemu.yml` pattern), schema-validate every emitted config against HA's `homeassistant/components/mqtt` JSON schemas (pin to a tested HA version). Add a smoke test that brings up sensing-server in `--source mock --mqtt`, subscribes with `paho-mqtt` test client, asserts on entity creation. | pending | +| **P4.5** | **Semantic inference layer (HA-MIND).** New module `semantic_inference.rs` implementing the 10 v1 primitives from §3.12. Output broadcast channel consumed by both MQTT publisher (P3) and Matter bridge (P8). Per-primitive precision/recall baselines published to `docs/integrations/semantic-primitives-metrics.md`. Unit tests per FSM + integration tests via replay of ADR-079 paired captures. | pending | +| **P5** | Docs: new `docs/integrations/home-assistant.md` with screenshots of the HA UI after auto-discovery completes, example HA dashboard YAML (Lovelace card configs), 8 starter blueprints from §3.12.2 (distress notify, wake routine, hallway dim, elderly anomaly alert, meeting lights, bathroom fan, fall-risk escalate, auto-arm security), and the raw-channel example automations: "turn on hall light when presence ON", "send notification on fall_detected event", "log HR/BR to InfluxDB". | pending | +| **P6** | Ship `--mqtt` in the next sensing-server release (target: v0.7.0). Demo end-to-end on `cognitum-v0` against a Mosquitto add-on running on a Home Assistant OS install. Update README hardware-options table with "Works with Home Assistant" badge. | pending | +| **P7** | Matter Bridge spike: build a throwaway prototype with `matter-rs` exposing one `OccupancySensor` endpoint + one `GenericSwitch` for fall. Pair against Apple Home, Google Home, and HA's Matter integration. Decision gate: if pairing works on all three, proceed to P8; if blocked, switch to chip-tool FFI and re-spike. | pending | +| **P8** | Matter Bridge production. Implement `--matter`, `--matter-setup-file`, `--matter-reset`, `--matter-vendor-id`, `--matter-product-id` CLI flags. Aggregator + Bridged Devices for all RuView nodes; per-zone occupancy endpoints; fall as `MultiPressComplete` event; person count as vendor-extension attribute. Integration tests via chip-tool sim. | pending | +| **P9** | Multi-controller validation. Pair one Cognitum Seed + 3 child ESP32 nodes simultaneously into HA, Apple Home, and Google Home. Verify presence flips on all three within 1 s of a real motion change. Document the multi-admin flow in `docs/integrations/matter.md`. | pending | +| **P10** | CSA Matter certification path (optional, ADR-1xx follow-up). Decide cost vs marketing value of the official "Matter-certified" badge ($3 k/year CSA membership + per-product test fees). Sketch only — production decision deferred. | pending | + +Each phase ends with a checkbox PR. The ADR is updated with actual artifacts (commit hashes, screenshots, witness bundle entries) as phases land. **P1–P6 (MQTT) and P7–P10 (Matter) run in parallel after P6 lands** — they share no code, so a Matter regression cannot break the MQTT path and vice versa. + +--- + +## 5. Consequences + +### 5.1 Wins + +- Zero-code UX for HA users — discovery handles the entire onboarding. +- **Cross-ecosystem reach via Matter** — Apple Home / Google Home / Alexa / SmartThings users can adopt RuView without ever running HA, expanding our addressable market by ~4×. +- Decouples RuView from its own UI; users can build their own dashboards in HA / Grafana / Node-RED on the same MQTT firehose. +- Adds a `--privacy-mode` flag that gives operators a single-knob biometric strip for compliance contexts. +- Matter fabric isolation is a privacy win by construction — biometrics are out-of-spec for the exposed clusters, so a buggy controller can't accidentally exfiltrate them. +- Webhook + future HACS path stay open (§6) — no lock-in. +- Establishes our presence in the HA ecosystem AND the broader Matter ecosystem (community add-on lists, blueprints, forum recipes, App Store / Play Store visibility via Apple Home / Google Home device listings). + +### 5.2 Costs + +- New runtime dependency (`rumqttc`) in `wifi-densepose-sensing-server`. Mitigated by feature-flag (`mqtt`), default off; users who don't enable `--mqtt` pay zero binary or runtime cost. +- **Matter SDK dependency** (`matter-rs` tentatively) gated behind `--matter` feature flag. Adds ~5 MB to release binary when enabled; zero cost when disabled. Tracking CSA spec churn is a real ongoing cost. +- One more thing to maintain across HA breaking changes. HA commits to the `homeassistant//.../config` schema being stable (their published policy), but historically they have evolved fields like `availability_topic` → `availability` (list-of). We'll pin to a tested HA version per release and call out tested-against in `docs/integrations/home-assistant.md`. +- **Matter spec churn** — Matter 1.0 → 1.3 added device types and changed cluster IDs. We pin to a tested Matter spec version per release. Annual re-validation overhead. +- Requires CI infra: a mosquitto container in workflow, schema-validation against HA schemas, **and** a chip-tool simulator for Matter pairing tests (need to vendor or fetch). +- CSA membership ($3 k/year) is required to obtain a permanent vendor ID; until then we use the development VID `0xFFF1`. Production deployment past P9 requires the membership decision (§9.9). + +### 5.3 Verification + +Acceptance criteria are §8. Beyond those, this ADR is "Accepted" once P6 ships and at least one external user has reported a working HA install via the public issue tracker. + +--- + +## 6. Alternatives considered + +### 6.A Custom HA integration (HACS) — *follow-on, not primary* + +Rough sketch: + +- Separate Python repo (proposed name: `ruvnet/hass-wifi-densepose`). +- Talks to sensing-server's existing WebSocket at `/ws/sensing` and REST at `/api/*`. +- Config-flow UI in HA: user enters server URL + bearer token; integration discovers entities. +- Distribution via HACS (https://hacs.xyz), requires HACS review + acceptance. + +**Effort estimate:** ~4–6 weeks (vs ~2 weeks for §2 MQTT path). Adds a Python codebase to maintain in a Rust-first org. Pays off in two scenarios: + +1. Users who run HA but don't run an MQTT broker (rare but exists). +2. Users who want sensing-server features that don't map cleanly to MQTT (e.g. live pose video preview). + +**Plan:** revisit after P6 lands and we have real adoption data on the MQTT path. If MQTT covers 80%+ of installs, HACS becomes a nice-to-have. If not, it becomes ADR-1xx follow-up. + +### 6.B Local-push REST webhook — *rejected* + +- sensing-server `POST`s to HA's webhook endpoint (`/api/webhook/`). +- Trivial to implement (~2 days). + +Rejected because: + +- One-way only — no `set_state` / arm / disarm path back. +- No entity discovery — user has to manually create input_booleans / sensors / template_sensors in HA YAML. +- No availability / LWT — sensing-server going offline is invisible to HA. +- Fails the "plug-and-play" bar that #574 / #760 set. + +Documented here so future readers know we considered it. + +### 6.C mDNS discovery (#574) — *complementary, not competing* + +mDNS / Zeroconf lets HA (or any local client) discover sensing-server's IP without manual configuration. It's orthogonal to MQTT: we should add it (already tracked in #574) so the user doesn't have to type the broker host either. mDNS resolves *where the broker is*; MQTT auto-discovery resolves *what entities to create*. Both ship; neither blocks the other. + +--- + +## 7. Risks + +| Risk | Likelihood | Impact | Mitigation | +|---|---|---|---| +| Topic-namespace collision with another HA device | low | medium | `unique_id` includes `wifi_densepose_` prefix + MAC-derived node_id; HA will refuse duplicates and log clearly | +| HA changes the `homeassistant/` schema | medium (1× every ~2 years historically) | medium | Pin tested HA version in `docs/integrations/home-assistant.md`; CI runs schema validation against the pinned version | +| Bandwidth blowup from pose keypoints | medium | low (LAN) / high (metered link) | Pose publishing is **off by default**; rate-limited when on; users hit a clear `WARN` if they enable pose without explicit rate cap | +| Privacy regression — biometrics leaked to a public broker | medium | high | `--privacy-mode` strips them at source; WARN if `--mqtt` enabled without `--mqtt-tls` on a non-localhost broker; never publish HR / BR / pose discovery in privacy mode | +| Cognitum Seed firmware footprint (if we ever push MQTT into the ESP32 path) | low | medium | Out of scope for this ADR — MQTT lives in sensing-server only. ESP32 keeps the lean UDP/WS path. If we later add MQTT to firmware, it's ADR-1xx with its own size budget per ADR-110 | +| Broker compromise (bad actor on the network gets read access to MQTT) | low | high | mTLS recommendation in §3.9; `--privacy-mode` for high-risk deployments | +| HA-side cardinality explosion from per-track-id binary_sensors | medium | low | Cap dynamic person entities at 10; old ones are removed via discovery `payload=""` (HA delete-entity convention) | +| **Matter SDK (`matter-rs`) immaturity blocks cert** | medium | medium | P7 spike validates pairing on three controllers before P8 production work; fall back to chip-tool FFI if blocked | +| **Matter spec adds vitals device types**, our vendor-extension attributes become non-standard | low (3+ years out) | low | Vendor-extension attributes are opt-in for controllers; migration to standard cluster IDs is a one-version bump when the spec lands | +| **Multi-fabric races** (HA, Apple, Google all see the same node and fire conflicting automations) | medium | medium | Document the multi-admin guidance in `docs/integrations/matter.md`: pick one primary controller for automations, others for visibility | +| **Apple Home / Google Home rendering misrepresents** RuView (e.g. shows generic "Sensor") | medium | low | Set rich `VendorName` / `ProductName` / `ProductLabel` in BasicInformation cluster; ship a Matter App icon (per CSA brand guidelines) once vendor ID is real | +| **CSA membership cost** ($3 k/y) is a recurring spend with uncertain ROI | low (decision deferred to P10) | medium | Ship using dev VID `0xFFF1` through P9; commit to membership only after adoption data justifies it | + +--- + +## 8. Acceptance criteria + +A reviewer can run all of the following without modifying source: + +```bash +# 1. Start sensing-server with mock source + MQTT +cargo run -p wifi-densepose-sensing-server -- \ + --source mock \ + --mqtt \ + --mqtt-host localhost \ + --mqtt-prefix homeassistant + +# 2. Observe discovery + state messages +mosquitto_sub -t 'homeassistant/#' -v +# Expected: discovery configs for presence, heart_rate, breathing_rate, motion, +# fall, person_count, rssi — one per entity per node — plus periodic state messages + +# 3. Run the full workspace test suite +cd v2 && cargo test --workspace --no-default-features +# Expected: 1,031+ tests passed, 0 failed (new mqtt tests included) + +# 4. Schema-validate discovery configs against HA's published schemas +cargo test -p wifi-densepose-sensing-server --features mqtt mqtt::discovery::schema +# Expected: green + +# 5. Privacy mode strips biometrics +cargo run -p wifi-densepose-sensing-server -- --source mock --mqtt --privacy-mode & +mosquitto_sub -t 'homeassistant/#' -v | tee /tmp/privacy.log +# Expected: NO heart_rate, breathing_rate, or pose entities in discovery +grep -E "(heart_rate|breathing_rate|pose)" /tmp/privacy.log +# Expected: empty (exit 1) + +# 6. HA auto-discovery end-to-end (manual, post-P5) +# - Add Mosquitto broker to a fresh HA OS install +# - Add MQTT integration in HA, point at broker +# - Start sensing-server with --mqtt +# - HA Settings → Devices → expect "RuView node " with all entities +# - Trigger mock presence change; presence entity flips ON / OFF live + +# 7. LWT / availability +# - Run sensing-server, observe `online` published +# - Kill sensing-server (-9), wait 30 s +# - Expect `offline` on every entity's availability topic + +# 8. Matter Bridge pairing (post-P7) +cargo run -p wifi-densepose-sensing-server -- \ + --source mock \ + --matter \ + --matter-setup-file /tmp/matter-qr.txt +# Expected: setup code + QR string printed; bridge advertises over mDNS + +# 9. Matter cross-controller test (post-P9; manual) +# - Pair the bridge into Apple Home (scan QR with iPhone) +# - Pair the same bridge into Home Assistant Matter integration (same QR) +# - Trigger mock presence change in sensing-server +# - Expected: occupancy entity flips ON in both controllers within 1 s + +# 10. Matter privacy invariant +mosquitto_sub -t 'homeassistant/sensor/+/heart_rate/state' -v & +chip-tool occupancysensing read occupancy 0xDEADBEEF 1 # Matter endpoint 1 +# Expected: MQTT still publishes HR (without --privacy-mode); Matter NEVER exposes HR cluster (no clusters exist for it) +``` + +All ten must pass before the ADR moves from Proposed → Accepted. Tests 1–7 cover MQTT (P1–P6); tests 8–10 cover Matter (P7–P9). Tests can be re-run incrementally as each phase lands. + +--- + +## 9. Resolved decisions (maintainer ACK 2026-05-23) + +All 13 questions resolved by maintainer @ruv on 2026-05-23. Status: **ACCEPTED**. + +**Decision principle (canonical):** preserve clean protocols, avoid firmware bloat, avoid fake semantics, ship MQTT first, validate Matter second. + +### 9.A MQTT path (P1–P6) + +1. **Broker.** ✅ **Mosquitto as default.** Mention EMQX and VerneMQ as advanced options in `docs/integrations/home-assistant.md`. +2. **Discovery prefix.** ✅ **Ship `homeassistant`** (HA's default). `--mqtt-prefix` remains overridable for users with custom HA setups. +3. **HACS repo name.** ✅ **`ruvnet/hass-wifi-densepose`** — wired into the `support_url` field of every discovery payload's `origin` block from P1. +4. **Sample blueprints.** ✅ **Ship 3 starter blueprints in P5.** Selected from §3.12.2 list — final three picked at P5 start, biased toward highest customer-pull primitives. +5. **TLS default.** ✅ **WARN now, hard-fail non-localhost plaintext in v0.8.0.** Sensing-server logs a `WARN` if `--mqtt` enabled without `--mqtt-tls` on a non-localhost broker. v0.8.0 promotes to hard fail (exit non-zero) once docs cover the CA setup path. +6. **`node_friendly_name`.** ✅ **NVS / config only.** No ADR-039 packet change. Sensing-server resolves the friendly name from local config and injects into MQTT/Matter device labels. +7. **Pose keypoint schema.** ✅ **COCO 17-keypoint order.** Index → joint name mapping documented in `docs/integrations/home-assistant.md` and re-exported as `wifi_densepose_core::pose::COCO17`. +8. **Multi-node aggregation.** ✅ **4 children + 1 parent via `via_device`.** Easier to debug; matches §3.4. + +### 9.B Matter path (P7–P10) + +9. **Matter vendor ID.** ✅ **Dev VID `0xFFF1` through P9.** CSA membership decision gate at P10 (deferred; sketched only). +10. **Matter SDK.** ✅ **Start with `matter-rs`.** Fall back to chip-tool FFI only if cert blockers emerge in P7 spike. +11. **Matter Thread.** ✅ **Future ADR.** ADR-115 stays WiFi-only on the server side. Thread support from ESP32-C6 firmware is a separate ADR after C6 stabilises (post-ADR-110 P8). +12. **Fall event mapping.** ✅ **`Switch.MultiPressComplete`.** Cleaner semantics for controllers; matches Apple Home / Google Home rendering expectations. +13. **Person count.** ✅ **Vendor extension.** Do not kludge into fake endpoints. Apple Home / Google Home will show `Occupancy: ON/OFF` only — that's honest. HA and SmartThings will surface the count via the vendor-extension attribute. + +### 9.C Open-after-9 (new questions raised post-ACK) + +Empty as of 2026-05-23. New questions discovered during implementation will be filed here, ACK'd by maintainer, and dated. + +--- + +## 10. References + +- Home Assistant MQTT integration docs: https://www.home-assistant.io/integrations/mqtt/ +- HA MQTT auto-discovery: https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery +- HA discovery schemas (per-component): https://www.home-assistant.io/integrations/binary_sensor.mqtt/ , .../sensor.mqtt/ , .../event.mqtt/ +- HACS: https://hacs.xyz +- HA Blueprint format: https://www.home-assistant.io/docs/blueprint/schema/ +- `rumqttc` (chosen Rust MQTT client): https://docs.rs/rumqttc/ +- **Matter Core Spec 1.3** (CSA): https://csa-iot.org/all-solutions/matter/ +- **Matter Device Library** (cluster + device-type catalog): https://csa-iot.org/wp-content/uploads/2023/12/Matter-1.3-Device-Library-Specification.pdf +- **matter-rs** (pure-Rust Matter SDK): https://github.com/project-chip/rs-matter +- **project-chip/connectedhomeip** (reference C++ Matter SDK / chip-tool): https://github.com/project-chip/connectedhomeip +- **Home Assistant Matter integration**: https://www.home-assistant.io/integrations/matter/ +- **Apple Home Matter support**: https://support.apple.com/en-us/HT213267 +- **Google Home Matter support**: https://developers.home.google.com/matter +- **CSA membership / vendor ID program**: https://csa-iot.org/become-member/ +- **"Works with Home Assistant" certification**: https://partner.home-assistant.io/ +- RuView ADR-018 — CSI binary frame format +- RuView ADR-021 — ESP32 vitals (edge breathing/HR extraction) +- RuView ADR-028 — ESP32 capability audit +- RuView ADR-031 — RuView sensing-first RF mode +- RuView ADR-039 — Edge vitals packet (`0xC511_0002`) +- RuView ADR-079 — Camera ground-truth training (pose schema) +- RuView ADR-103 — `cog-person-count` (person count primitive) +- RuView ADR-106 — DP-SGD + primitive isolation (privacy contract) +- RuView ADR-110 — ESP32-C6 firmware extension +- RuView ADR-114 — `cog-quantum-vitals` +- Issue [#574](https://github.com/ruvnet/RuView/issues/574) — mDNS for seed_url (complementary) +- Issue [#760](https://github.com/ruvnet/RuView/issues/760) — Sensing UI / onboarding friction +- Issue [#761](https://github.com/ruvnet/RuView/issues/761) — Competitive scan (espectre.dev, tommysense.com) + +--- + +*ADR-115 is the integration story that turns RuView from "another sensing platform" into "drop-in upgrade for any HA install **and** any Matter-controller home." MQTT carries the rich, differentiated telemetry; Matter carries the standardised subset across every controller ecosystem. Numbers 111 and 112 remain reserved per the project ADR-numbering policy.* diff --git a/docs/adr/README.md b/docs/adr/README.md index 5df4e2d2..400cbdc1 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -50,6 +50,7 @@ Statuses: **Proposed** (under discussion), **Accepted** (approved and/or impleme | [ADR-040](ADR-040-wasm-programmable-sensing.md) | WASM Programmable Sensing (Tier 3) | Accepted | | [ADR-041](ADR-041-wasm-module-collection.md) | WASM Module Collection (65 edge modules) | Accepted (hardware-validated) | | [ADR-044](ADR-044-provisioning-tool-enhancements.md) | Provisioning Tool Enhancements | Proposed | +| [ADR-110](ADR-110-esp32-c6-firmware-extension.md) | ESP32-C6 firmware extension — Wi-Fi 6 / 802.15.4 / TWT / LP-core | Accepted, P1-P10 complete, firmware-side substrate closed at **[v0.7.0-esp32](https://github.com/ruvnet/RuView/releases/tag/v0.7.0-esp32)**. Companion docs: [`WITNESS-LOG-110`](../WITNESS-LOG-110.md) (13 §A0.x entries · 99.56 % cross-board RX · **104.1 µs smoothed sync stdev** · ≤100 µs target met), [`ADR-110-REVIEW-GUIDE`](../ADR-110-REVIEW-GUIDE.md) (one-page reviewer tour), [`ADR-110-BRANCH-STATE`](../ADR-110-BRANCH-STATE.md) (coordination map vs `feat/adr-115-ha-mqtt-matter`). Host decoders + tests: Python `SyncPacketParser` (10) + Rust `wifi_densepose_hardware::SyncPacket` (15), cross-language hex pin gates drift. | ### Signal processing and sensing diff --git a/docs/user-guide.md b/docs/user-guide.md index 5f6743fa..692b22a1 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -473,6 +473,72 @@ Base URL: `http://localhost:3000` (Docker) or `http://localhost:8080` (binary de | `POST` | `/api/v1/adaptive/train` | Train adaptive classifier from recordings | `{"success":true,"accuracy":0.85}` | | `GET` | `/api/v1/adaptive/status` | Adaptive model status and accuracy | `{"loaded":true,"accuracy":0.85}` | | `POST` | `/api/v1/adaptive/unload` | Unload adaptive model | `{"success":true}` | +| `GET` | `/api/v1/mesh` | ADR-110 fleet-wide mesh sync map ([iter 29](adr/ADR-110-esp32-c6-firmware-extension.md)) | `{"nodes":{"9":{...},"12":{...}},"total":2}` | +| `GET` | `/api/v1/nodes/:id/sync` | Single-node mesh sync snapshot (or 404) | `{"offset_us":1163565,"is_leader":false,...}` | +| `GET` | `/api/v1/mesh/metrics` | ADR-110 mesh state in Prometheus exposition format ([iter 36](adr/ADR-110-esp32-c6-firmware-extension.md)) | `wifi_densepose_mesh_offset_us{node="9"} 1163565\n…` | + +### Example: Get fleet mesh state (ADR-110) + +```bash +curl -s http://localhost:3000/api/v1/mesh | python -m json.tool +``` + +```json +{ + "nodes": { + "9": { + "offset_us": 1163565, + "is_leader": false, + "is_valid": true, + "smoothed": true, + "sequence": 20, + "csi_fps_ema": 10.0, + "csi_fps_samples": 47 + }, + "12": { + "offset_us": -7, + "is_leader": true, + "is_valid": true, + "smoothed": false, + "sequence": 20, + "csi_fps_ema": 10.0, + "csi_fps_samples": 51 + } + }, + "total": 2 +} +``` + +Empty `{"nodes": {}, "total": 0}` means no mesh peers reachable. +Nodes that haven't emitted a sync packet yet are omitted from the map. + +### Example: Get one node's sync state + +```bash +curl -s http://localhost:3000/api/v1/nodes/9/sync | python -m json.tool +``` + +200 → same `NodeSyncSnapshot` shape as inside `/api/v1/mesh` or the +WebSocket `sync` field. Field meanings are documented under +[Per-node mesh sync (ADR-110)](#per-node-mesh-sync-adr-110). + +404 (unknown node): +```json +{"error": "unknown_node", "node_id": 99} +``` + +404 (node exists but hasn't synced yet): +```json +{ + "error": "no_sync", + "node_id": 9, + "hint": "node hasn't emitted a sync packet yet (no mesh peer or not v0.6.9+)" +} +``` + +Useful for Home Assistant REST sensors, Prometheus exporters, +automation rule probes, and curl debugging — anywhere you want +one-shot mesh state without holding a WebSocket connection. ### Example: Get Vital Signs @@ -564,6 +630,67 @@ ws.onerror = (err) => console.error("WebSocket error:", err); wscat -c ws://localhost:3001/ws/sensing ``` +### Per-node mesh sync (ADR-110) + +Since firmware **v0.7.0-esp32** + sensing-server iter 23, every +`sensing_update` whose nodes participate in the [ADR-110](adr/ADR-110-esp32-c6-firmware-extension.md) +ESP-NOW mesh carries an optional `sync` object per node: + +```json +{ + "type": "sensing_update", + "nodes": [ + { + "node_id": 9, + "rssi_dbm": -38.0, + "amplitude": [...], + "subcarrier_count": 64, + "sync": { + "offset_us": 1163565, + "is_leader": false, + "is_valid": true, + "smoothed": true, + "sequence": 20, + "csi_fps_ema": 10.0, + "csi_fps_samples": 47 + } + } + ] +} +``` + +Field meanings: + +| Field | Type | Meaning | +|---|---|---| +| `offset_us` | i64 | Smoothed local-vs-mesh clock offset in microseconds. Negative when this node is behind the leader. §A0.10 on the bench measured ~1.16 s boot delta between two C6 boards. | +| `is_leader` | bool | True when this node is the elected mesh leader (lowest EUI-64 in the cohort). | +| `is_valid` | bool | True when this node has heard a fresh leader beacon within the firmware's `VALID_WINDOW_MS = 3 s` freshness gate. | +| `smoothed` | bool | True once the firmware-side EMA filter has seeded (after ~8 beacons ≈ 0.8 s of follower mode). | +| `sequence` | u32 | High-water CSI sequence number stamped when this sync packet was emitted. Pair with the per-frame `sequence` field on incoming CSI to interpolate a mesh-aligned timestamp for any frame. | +| `csi_fps_ema` | f64 | Per-node EMA of the observed CSI frame rate. Bench typical ≈ 10 Hz. | +| `csi_fps_samples` | u32 | How many inter-frame deltas the EMA has seen. Treat values < 5 as "not yet trustworthy" and fall back to 20 Hz. | +| `staleness_ms` | u64 (optional) | Milliseconds since the host last received a sync packet from this node ([iter 34](adr/ADR-110-esp32-c6-firmware-extension.md)). Fade UI badges after 5 000 ms; treat ≥ 9 000 ms as the same condition that the firmware's `c6_sync_espnow_is_valid()` reports as `false`. | + +**When `sync` is omitted entirely**: the node isn't on the mesh (or +hasn't heard a peer yet). Non-ESP32 paths — multi-BSSID router scan, +synthetic-RSSI fallback, simulation — also omit `sync`. Existing +pre-iter-23 UI clients ignore the new field naturally because they +don't read it. + +**How to render this in a UI**: +- `is_leader === true` → badge the node "Leader" +- `is_valid === false` → grey out / "Sync lost" +- `csi_fps_samples < 5` → label as "Calibrating" until ≥5 frames +- `|offset_us|` trend → render a jitter histogram to show the §A0.10 + EMA suppression working live + +**How to recover a mesh-aligned timestamp for any CSI frame from this +node**: take the frame's own `sequence` u32, subtract `sync.sequence`, +divide by `sync.csi_fps_ema` (or 20.0 if `csi_fps_samples < 5`), +multiply by 1 000 000 µs — that's the mesh delta from the sync emit +time. Use it to align multistatic frames from sibling boards. + --- ## Web UI @@ -1094,6 +1221,15 @@ An RVF file contains: model weights, HNSW vector index, quantization codebooks, ## Hardware Setup +### Supported targets + +| Target | Use case | Source target flag | Notes | +|---|---|---|---| +| **ESP32-S3** (default) | Production CSI mesh, 17-keypoint pose | `idf.py set-target esp32s3` | Dual-core 240 MHz, PSRAM, native USB-OTG, DVP camera path | +| **ESP32-C6** ([ADR-110](adr/ADR-110-esp32-c6-firmware-extension.md)) | Wi-Fi 6 / 802.15.4 research, battery seed nodes | `idf.py set-target esp32c6` | Single-core 160 MHz, no PSRAM, 802.11ax HE PHY, 802.15.4 (Thread/Zigbee), LP-core hibernation ~5 µA | + +The same `firmware/esp32-csi-node` source tree builds for both. ESP-IDF picks up `sdkconfig.defaults.esp32c6` automatically when the target is set to `esp32c6`; otherwise it uses `sdkconfig.defaults` (S3). All C6-only modules are `#ifdef`-gated, so the S3 build is byte-identical to today. + ### ESP32-S3 Mesh A 3-6 node ESP32-S3 mesh provides full CSI at 20 Hz. Total cost: ~$54 for a 3-node setup. @@ -1109,7 +1245,11 @@ Pre-built binaries are available at [Releases](https://github.com/ruvnet/RuView/ | Release | What It Includes | Tag | |---------|-----------------|-----| -| [v0.5.0](https://github.com/ruvnet/RuView/releases/tag/v0.5.0-esp32) | **Stable (recommended)** — mmWave sensor fusion (MR60BHA2/LD2410 auto-detect), 48-byte fused vitals, all v0.4.3.1 fixes | `v0.5.0-esp32` | +| [v0.7.0](https://github.com/ruvnet/RuView/releases/tag/v0.7.0-esp32) | **Latest — ADR-110 firmware-side substrate closed.** Adds ESP-NOW mesh substrate with quantified ≤100 µs alignment (104.1 µs smoothed stdev, 3.95× suppression, 99.56 % cross-board match measured live), 32-byte sync-packet UDP emission with operator-tunable cadence, ADR-018 byte 19 bit 4 wire-fix sourced from working ESP-NOW path, Python SyncPacketParser stub for host wiring ([WITNESS-LOG-110 §A0.7-§A0.13](WITNESS-LOG-110.md)) | `v0.7.0-esp32` | +| [v0.6.9](https://github.com/ruvnet/RuView/releases/tag/v0.6.9-esp32) | Sync-packet UDP emission, `CONFIG_C6_SYNC_EVERY_N_FRAMES` tunable cadence | `v0.6.9-esp32` | +| [v0.6.8](https://github.com/ruvnet/RuView/releases/tag/v0.6.8-esp32) | ESP-NOW EMA-smoothed cross-board offset (3.95× suppression, 104 µs stdev) | `v0.6.8-esp32` | +| [v0.6.7](https://github.com/ruvnet/RuView/releases/tag/v0.6.7-esp32) | Real LP-core motion-gate RISC-V program (B4 code path complete) + Wi-Fi 6 soft-AP with TWT Responder for two-board iTWT benches (B1/B2 unblock) | `v0.6.7-esp32` | +| [v0.5.0](https://github.com/ruvnet/RuView/releases/tag/v0.5.0-esp32) | **Stable (S3 mesh, recommended)** — mmWave sensor fusion (MR60BHA2/LD2410 auto-detect), 48-byte fused vitals, all v0.4.3.1 fixes | `v0.5.0-esp32` | | [v0.4.3.1](https://github.com/ruvnet/RuView/releases/tag/v0.4.3.1-esp32) | Fall detection fix ([#263](https://github.com/ruvnet/RuView/issues/263)), 4MB flash ([#265](https://github.com/ruvnet/RuView/issues/265)), watchdog fix ([#266](https://github.com/ruvnet/RuView/issues/266)) | `v0.4.3.1-esp32` | | [v0.4.1](https://github.com/ruvnet/RuView/releases/tag/v0.4.1-esp32) | CSI build fix, compile guard, AMOLED display, edge intelligence ([ADR-057](../docs/adr/ADR-057-firmware-csi-build-guard.md)) | `v0.4.1-esp32` | | [v0.3.0-alpha](https://github.com/ruvnet/RuView/releases/tag/v0.3.0-alpha-esp32) | Alpha — adds on-device edge intelligence (ADR-039) | `v0.3.0-alpha-esp32` | @@ -1125,7 +1265,7 @@ python -m esptool --chip esp32s3 --port COM7 --baud 460800 \ 0xf000 ota_data_initial.bin 0x20000 esp32-csi-node.bin ``` -**4MB flash boards** (e.g. ESP32-S3 SuperMini 4MB): download the 4MB binaries from the [v0.4.3 release](https://github.com/ruvnet/RuView/releases/tag/v0.4.3-esp32) and use `--flash-size 4MB`: +**4MB flash boards** (e.g. ESP32-S3 SuperMini 4MB): download `esp32-csi-node-s3-4mb.bin` + `partition-table-s3-4mb.bin` from the [v0.6.7 release](https://github.com/ruvnet/RuView/releases/tag/v0.6.7-esp32) (882 KB binary, 52 % partition slack) and use `--flash-size 4MB`: ```bash python -m esptool --chip esp32s3 --port COM7 --baud 460800 \ @@ -1155,6 +1295,96 @@ python firmware/esp32-csi-node/provision.py --port COM7 \ All nodes in a mesh must share the same 256-bit mesh key for HMAC-SHA256 beacon authentication. The key is stored in ESP32 NVS flash and zeroed on firmware erase. +### ESP32-C6 (Wi-Fi 6 + 802.15.4 research target — ADR-110) + +The C6 build adds four capabilities to the existing csi-node firmware, all opt-in via `idf.py menuconfig → ESP32-C6 capabilities (ADR-110)`: + +| Capability | Kconfig | What it does | +|---|---|---| +| **Wi-Fi 6 HE-LTF tagging** | `CSI_FRAME_HE_TAGGING` (default on) | Each ADR-018 frame's previously-reserved bytes 18-19 now carry PPDU type (HT / HE-SU / HE-MU / HE-TB) + bandwidth flags. Magic stays `0xC5110001` — old aggregators see zeros and ignore. | +| **802.15.4 mesh time-sync** | `C6_TIMESYNC_ENABLE` (default on, channel 15) | Beacon-based cross-node clock alignment over the 802.15.4 radio. Frees the WiFi channel from coordination traffic — solves the ADR-029/030 multistatic clock-sync problem. | +| **TWT (Target Wake Time)** | `C6_TWT_ENABLE` (default on, 10 ms wake interval) | After WiFi connect, negotiates an individual TWT agreement with the AP for deterministic CSI cadence. Graceful NACK fallback if the AP doesn't support 11ax TWT. | +| **LP-core wake-on-motion hibernation** | `C6_LP_CORE_ENABLE` (default off) | Always-on motion gate on the LP RISC-V core; HP core stays in deep sleep until the configured GPIO wakes it. Targets ~5 µA for battery-powered Cognitum Seed nodes. | + +**Build + flash:** + +```bash +cd firmware/esp32-csi-node +idf.py set-target esp32c6 +idf.py build # ~1.0 MB binary, 46% partition slack on 4 MB flash +idf.py -p COM6 flash +# Then provision the same way as S3 (provision.py works for both targets): +python provision.py --port COM6 --ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20 +``` + +**Verifying the C6 modules came up** — `idf.py -p COM6 monitor` should show: + +``` +I (353) main: ESP32-C6 CSI Node (ADR-018 / ADR-110) — v0.6.7 — Node ID: 1 +I (413) c6_ts: init done: channel=15 EUI= leader=yes(candidate) +I (463) wifi: mac_version:HAL_MAC_ESP32AX_761 ← 802.11ax MAC firmware loaded +``` + +The `c6_ts: init done` line confirms the 802.15.4 stack is up; if TWT succeeds you'll also see an `iTWT setup event received from AP` line after the WiFi connect completes. + +**Multi-room time-aligned multistatic capture (preview):** + +Flash two or more C6 boards, leave them on the same 802.15.4 channel (default 15). One will elect itself leader (lowest EUI-64) and broadcast `TS_BEACON` frames every 100 ms; the others compute and apply offsets. Each CSI frame from a follower carries a `c6_timesync_get_epoch_us()` wall-clock estimate aligned to within ±100 µs of the leader's monotonic time. Target use case: ADR-029/030 multistatic fusion without burning WiFi airtime on coordination. + +**Battery seed-node mode (v0.6.7 — real LP-core program):** + +```bash +# Enable LP-core hibernation in menuconfig: +# ESP32-C6 capabilities (ADR-110) → Enable LP-core wake-on-motion hibernation +# → LP-core wake GPIO (default 4 — connect a PIR or accelerometer INT line here) +# → LP-core poll period (default 10 ms) +# → LP-core debounce sample count (default 3 consecutive matches) +idf.py menuconfig +idf.py build flash +``` + +When enabled, the C6 LP RISC-V coprocessor runs a real polling program +(`firmware/esp32-csi-node/main/lp_core/main.c`) that polls the wake GPIO at +the configured cadence, debounces N consecutive matching reads, and wakes the +HP core via `ulp_lp_core_wakeup_main_processor()`. `esp_sleep_get_wakeup_cause()` +returns `ESP_SLEEP_WAKEUP_ULP`, and `c6_lp_core_motion_count()` / +`c6_lp_core_poll_count()` expose the LP-side counters for the witness harness. +Target standby current ~5 µA (datasheet; pending INA measurement). + +**Two-board iTWT bench (v0.6.7 — soft-AP HE/TWT, no router required):** + +Pair two C6 boards — one acts as the iTWT-capable AP, the other as the STA +that negotiates and benchmarks the TWT agreement. + +```bash +# Board #1 (AP role): append to sdkconfig.defaults.esp32c6: +CONFIG_C6_SOFTAP_HE_ENABLE=y +CONFIG_C6_SOFTAP_HE_SSID="ruview-c6-twt" +CONFIG_C6_SOFTAP_HE_PSK="ruviewtwt" +CONFIG_C6_SOFTAP_HE_CHANNEL=6 + +idf.py set-target esp32c6 && idf.py build && idf.py -p COM6 flash +``` + +Board #1 boots in `WIFI_MODE_APSTA`, advertising HE capabilities and TWT +Responder=1 on channel 6. Board #2 provisions to associate with that SSID: + +```bash +python firmware/esp32-csi-node/provision.py --port COM9 \ + --ssid "ruview-c6-twt" --password "ruviewtwt" --target-ip 192.168.1.20 +``` + +Board #2 runs the existing `c6_twt_setup_default()` on connect and now +negotiates a real iTWT agreement against the cooperative AP — the +`iTWT setup queued: wake_interval=10000 µs` log line should be followed by an +`iTWT setup event received from AP` instead of the `INVALID_ARG` graceful +fallback that fired against the bench's 11n-only `ruv.net` AP. + +NVS overrides for AP role (namespace `ruview`): `softap_ssid`, `softap_psk`, +`softap_chan` — provision once and the values survive firmware updates. + +**What's NOT on the C6 build** (vs S3 production): no AMOLED display (ADR-045 needs 8 MB + LCD touch driver), no WASM3 (ADR-040 needs PSRAM), no Seeed mmWave fusion (separate board). The C6 is a research/seed target, not a drop-in replacement for the S3 production node. + **TDM slot assignment:** Each node in a multistatic mesh needs a unique TDM slot ID (0-based): diff --git a/firmware/esp32-csi-node/README.md b/firmware/esp32-csi-node/README.md index 147d3602..f75d053c 100644 --- a/firmware/esp32-csi-node/README.md +++ b/firmware/esp32-csi-node/README.md @@ -1,11 +1,11 @@ -# ESP32-S3 CSI Node Firmware +# ESP32 CSI Node Firmware **Turn a $7 microcontroller into a privacy-first human sensing node.** -This firmware captures WiFi Channel State Information (CSI) from an ESP32-S3 and transforms it into real-time presence detection, vital sign monitoring, and programmable sensing -- all without cameras or wearables. Part of the [WiFi-DensePose](../../README.md) project. +This firmware captures WiFi Channel State Information (CSI) from an ESP32-S3 (production) or ESP32-C6 (research target — Wi-Fi 6 / 802.15.4 / TWT / LP-core hibernation, see [ADR-110](../../docs/adr/ADR-110-esp32-c6-firmware-extension.md)) and transforms it into real-time presence detection, vital sign monitoring, and programmable sensing -- all without cameras or wearables. Part of the [WiFi-DensePose](../../README.md) project. [![ESP-IDF v5.2](https://img.shields.io/badge/ESP--IDF-v5.2-blue.svg)](https://docs.espressif.com/projects/esp-idf/en/v5.2/) -[![Target: ESP32-S3](https://img.shields.io/badge/target-ESP32--S3-purple.svg)](https://www.espressif.com/en/products/socs/esp32-s3) +[![Target: ESP32-S3 / ESP32-C6](https://img.shields.io/badge/target-ESP32--S3%20%7C%20ESP32--C6-purple.svg)](https://www.espressif.com/en/products/socs/esp32-s3) [![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-green.svg)](../../LICENSE) [![Binary: ~943 KB](https://img.shields.io/badge/binary-~943%20KB-orange.svg)](#memory-budget) [![CI: Docker Build](https://img.shields.io/badge/CI-Docker%20Build-brightgreen.svg)](../../.github/workflows/firmware-ci.yml) diff --git a/firmware/esp32-csi-node/main/CMakeLists.txt b/firmware/esp32-csi-node/main/CMakeLists.txt index 62d7d189..0cabf5df 100644 --- a/firmware/esp32-csi-node/main/CMakeLists.txt +++ b/firmware/esp32-csi-node/main/CMakeLists.txt @@ -9,6 +9,14 @@ set(SRCS "rv_feature_state.c" "rv_mesh.c" "adaptive_controller.c" + # ADR-110 — ESP32-C6 capability modules (no-op stubs on other targets via #ifdef) + "c6_twt.c" + "c6_timesync.c" + "c6_lp_core.c" + # ADR-110 D1 workaround — ESP-NOW cross-node sync (works on S3+C6) + "c6_sync_espnow.c" + # ADR-110 B1/B2 unblock — soft-AP HE/TWT (C6-only when enabled) + "c6_softap_he.c" ) # ESP-IDF v6+: headers must resolve via explicit REQUIRES (no implicit deps). @@ -32,6 +40,13 @@ set(REQUIRES mbedtls ) +# ADR-110: C6-only components — pulled in when building for esp32c6. +# Note: CONFIG_* symbols are not available in main CMakeLists.txt evaluation — +# we use the IDF_TARGET variable that idf.py sets from sdkconfig.defaults / set-target. +if(IDF_TARGET STREQUAL "esp32c6") + list(APPEND REQUIRES ieee802154 ulp esp_hw_support) +endif() + # ADR-061: Mock CSI generator for QEMU testing + ADR-081 mock radio binding if(CONFIG_CSI_MOCK_ENABLED) list(APPEND SRCS "mock_csi.c" "rv_radio_ops_mock.c") @@ -52,3 +67,15 @@ idf_component_register( INCLUDE_DIRS "." REQUIRES ${REQUIRES} ) + +# ADR-110 P5 (full): embed the LP-core motion-gate program when enabled. +# `ulp_embed_binary` compiles lp_core/main.c with the RISC-V LP toolchain +# and links the resulting binary into the HP image, exposing shared symbols +# via the auto-generated `ulp_main.h` header. +if(IDF_TARGET STREQUAL "esp32c6" AND CONFIG_C6_LP_CORE_ENABLE) + set(ulp_app_name ulp_main) + set(ulp_sources "lp_core/main.c") + # Source files in the HP component that include the generated ulp_main.h + set(ulp_exp_dep_srcs "c6_lp_core.c") + ulp_embed_binary(${ulp_app_name} "${ulp_sources}" "${ulp_exp_dep_srcs}") +endif() diff --git a/firmware/esp32-csi-node/main/Kconfig.projbuild b/firmware/esp32-csi-node/main/Kconfig.projbuild index 4e5895bb..18c32ebf 100644 --- a/firmware/esp32-csi-node/main/Kconfig.projbuild +++ b/firmware/esp32-csi-node/main/Kconfig.projbuild @@ -287,6 +287,151 @@ menu "WASM Programmable Sensing (ADR-040)" endmenu +menu "ESP32-C6 capabilities (ADR-110)" + depends on IDF_TARGET_ESP32C6 + + config C6_TWT_ENABLE + bool "Enable TWT (Target Wake Time) negotiation" + default y + # SOC_WIFI_HE_SUPPORT is auto-set on chips with HE (Wi-Fi 6) PHY (C6/C5) + depends on SOC_WIFI_HE_SUPPORT + help + After WiFi STA connect, request an individual TWT agreement + with the AP for deterministic CSI cadence. Falls back + gracefully if the AP doesn't support 11ax TWT. + + config C6_TWT_WAKE_INTERVAL_US + int "TWT wake interval (microseconds)" + default 10000 + range 1024 1048576 + depends on C6_TWT_ENABLE + help + Period between TWT wake events. 10000 µs = 100 Hz CSI cadence. + + config C6_TWT_MIN_WAKE_DURA_US + int "TWT minimum wake duration (microseconds)" + default 512 + range 256 16384 + depends on C6_TWT_ENABLE + help + Minimum awake duration per TWT wake. 512 µs is enough to + capture one CSI frame. + + config C6_TIMESYNC_ENABLE + bool "Enable 802.15.4 mesh time-sync" + default y + depends on IEEE802154_ENABLED + help + Cross-node clock alignment over the 802.15.4 radio. Frees + WiFi airtime from coordination traffic — relevant to + ADR-029/030 multistatic sensing. + + config C6_TIMESYNC_CHANNEL + int "802.15.4 time-sync channel (11-26)" + default 15 + range 11 26 + depends on C6_TIMESYNC_ENABLE + + config C6_LP_CORE_ENABLE + bool "Enable LP-core wake-on-motion hibernation" + default n + depends on ULP_COPROC_TYPE_LP_CORE + help + Arm the LP RISC-V coprocessor as an always-on motion gate + in deep sleep. Targets ~5 µA hibernation for battery + seed nodes. Requires a motion sensor on a wake-capable GPIO. + + config C6_LP_WAKE_GPIO + int "LP-core wake GPIO" + default 4 + range 0 23 + depends on C6_LP_CORE_ENABLE + + config C6_LP_WAKE_ACTIVE_HIGH + bool "Wake on rising edge" + default y + depends on C6_LP_CORE_ENABLE + + config C6_LP_POLL_PERIOD_US + int "LP-core poll period (microseconds)" + default 10000 + range 1000 1000000 + depends on C6_LP_CORE_ENABLE + help + How often the LP-core program reads the wake GPIO. + 10000 µs = 100 Hz. Lower values give faster response + but increase the average LP-core duty cycle (and + current). 10 ms is a good balance for PIR sensors. + + config C6_LP_DEBOUNCE_SAMPLES + int "LP-core debounce sample count" + default 3 + range 1 32 + depends on C6_LP_CORE_ENABLE + help + How many consecutive matching GPIO reads are required + before the LP-core wakes the HP core. 3 = ~30 ms at the + default 10 ms poll period. + + config C6_SOFTAP_HE_ENABLE + bool "Run as Wi-Fi 6 soft-AP with TWT Responder (two-board bench)" + default n + depends on SOC_WIFI_HE_SUPPORT + help + When set, the C6 starts in AP+STA mode and advertises a + soft-AP that announces HE (Wi-Fi 6) capability with + TWT Responder=1. Lets a second C6 station-mode board + negotiate a real iTWT agreement against a known-cooperative + AP, unblocking ADR-110 §B1/B2 measurement without + buying an 11ax router. SSID/PSK configured via NVS + (keys `softap_ssid` / `softap_psk`) or the defaults below. + + config C6_SOFTAP_HE_SSID + string "Soft-AP SSID (when C6_SOFTAP_HE_ENABLE)" + default "ruview-c6-twt" + depends on C6_SOFTAP_HE_ENABLE + + config C6_SOFTAP_HE_PSK + string "Soft-AP WPA2 password (>= 8 chars)" + default "ruviewtwt" + depends on C6_SOFTAP_HE_ENABLE + + config C6_SOFTAP_HE_CHANNEL + int "Soft-AP channel (1-13)" + default 6 + range 1 13 + depends on C6_SOFTAP_HE_ENABLE + + config C6_SYNC_EVERY_N_FRAMES + int "Sync-packet emission cadence (CSI frames per sync)" + default 20 + range 1 1000 + help + How many CSI callbacks fire before csi_collector emits one + ADR-110 §A0.11 sync packet (magic 0xC511A110) carrying the + mesh-aligned epoch + sequence high-water for the host + aggregator to pair against incoming CSI frames. + + Default 20 = ~2 s between sync packets at the bench's + observed 10 fps CSI rate. Raise for less wire overhead; + lower for tighter multistatic alignment windows. + +endmenu + +menu "ADR-018 frame extensions (ADR-110)" + + config CSI_FRAME_HE_TAGGING + bool "Tag ADR-018 frames with HE PPDU metadata" + default y + help + When the WiFi driver reports an 802.11ax HE-SU/HE-MU/HE-TB + PPDU, write the PPDU type + bandwidth into ADR-018 frame + bytes 18-19 (previously reserved). Readers that don't know + about this extension see the bytes as zero — fully + backwards compatible. + +endmenu + menu "Mock CSI (QEMU Testing)" config CSI_MOCK_ENABLED bool "Enable mock CSI generator (for QEMU testing)" diff --git a/firmware/esp32-csi-node/main/c6_lp_core.c b/firmware/esp32-csi-node/main/c6_lp_core.c new file mode 100644 index 00000000..d6e096ad --- /dev/null +++ b/firmware/esp32-csi-node/main/c6_lp_core.c @@ -0,0 +1,196 @@ +/** + * @file c6_lp_core.c + * @brief LP-core wake-on-motion hibernation — ADR-110 Phase 5 (full). + * + * Two operating modes, controlled by CONFIG_C6_LP_CORE_ENABLE: + * + * 1. ENABLED — real LP-core RISC-V program polls the wake GPIO at + * LP_TIMER cadence (default 10 ms), debounces N matching samples, + * and triggers an HP wake via `ulp_lp_core_wakeup_main_processor()`. + * HP enters deep sleep with `ESP_SLEEP_WAKEUP_ULP` as the source. + * Targets ~5 µA average current (datasheet figure for LP-core + + * RTC peripherals powered down). The LP binary is built by + * `ulp_embed_binary(...)` in main/CMakeLists.txt from lp_core/main.c. + * + * 2. DISABLED — falls back to plain deep-sleep + GPIO wake-up + * (`esp_deep_sleep_enable_gpio_wakeup`). No debounce, no + * sub-10 µA floor, but no LP toolchain dependency either. + * This is the path the v0.6.6 firmware shipped with. + * + * Both paths share `c6_lp_core_arm()` / `c6_lp_core_hibernate_and_wait()` + * so call sites in main.c don't change between modes. + */ + +#include "sdkconfig.h" + +#if defined(CONFIG_IDF_TARGET_ESP32C6) && defined(CONFIG_ULP_COPROC_TYPE_LP_CORE) + +#include "c6_lp_core.h" +#include "esp_log.h" +#include "esp_sleep.h" +#include "driver/rtc_io.h" +#include "soc/soc_caps.h" +#include + +#if defined(CONFIG_C6_LP_CORE_ENABLE) +#include "ulp_lp_core.h" +/* ulp_main.h is auto-generated by `ulp_embed_binary(ulp_main, ...)` and + * exports every `volatile` global from lp_core/main.c with the `ulp_` + * prefix. Include is guarded so disabled builds don't try to find a + * file the build system hasn't generated. */ +#include "ulp_main.h" +extern const uint8_t ulp_main_bin_start[] asm("_binary_ulp_main_bin_start"); +extern const uint8_t ulp_main_bin_end[] asm("_binary_ulp_main_bin_end"); +#endif + +static const char *TAG = "c6_lp"; + +static int s_wake_gpio = -1; +static bool s_active_high = true; +static bool s_armed = false; + +#ifndef CONFIG_C6_LP_POLL_PERIOD_US +#define CONFIG_C6_LP_POLL_PERIOD_US 10000 /* 100 Hz default poll cadence */ +#endif + +#ifndef CONFIG_C6_LP_DEBOUNCE_SAMPLES +#define CONFIG_C6_LP_DEBOUNCE_SAMPLES 3 +#endif + +esp_err_t c6_lp_core_arm(int wake_gpio, bool active_high) +{ + if (wake_gpio < 0) { + ESP_LOGE(TAG, "invalid wake_gpio=%d", wake_gpio); + return ESP_ERR_INVALID_ARG; + } + s_wake_gpio = wake_gpio; + s_active_high = active_high; + + /* GPIO must be in the LP/RTC domain for either wake path. */ + esp_err_t ret = rtc_gpio_init(wake_gpio); + if (ret != ESP_OK) { + ESP_LOGE(TAG, "rtc_gpio_init(%d) failed: %s", wake_gpio, esp_err_to_name(ret)); + return ret; + } + rtc_gpio_set_direction(wake_gpio, RTC_GPIO_MODE_INPUT_ONLY); + /* Floating inputs in deep sleep are an antenna — disable internal pulls + * only if the user has an external pull on the motion line; we leave + * default pulls so a disconnected pin doesn't toggle randomly. */ + +#if defined(CONFIG_C6_LP_CORE_ENABLE) + /* --- Real LP-core path --- */ + + /* On C6, LP-IO maps 1:1 to GPIO for indices 0..7. Validate. */ + if (wake_gpio > 7) { + ESP_LOGE(TAG, "LP-core path requires LP-IO 0..7, got GPIO %d", wake_gpio); + return ESP_ERR_INVALID_ARG; + } + + /* Load the LP-core binary blob. */ + esp_err_t err = ulp_lp_core_load_binary( + ulp_main_bin_start, + (size_t)(ulp_main_bin_end - ulp_main_bin_start)); + if (err != ESP_OK) { + ESP_LOGE(TAG, "ulp_lp_core_load_binary failed: %s", esp_err_to_name(err)); + return err; + } + + /* Hand the GPIO parameters to the LP program via shared symbols. + * These are declared `volatile` in lp_core/main.c so the HP write + * is observed by LP on the next iteration. */ + ulp_wake_gpio_num = (uint32_t)wake_gpio; + ulp_wake_active_high = active_high ? 1u : 0u; + ulp_debounce_samples = CONFIG_C6_LP_DEBOUNCE_SAMPLES; + ulp_motion_count = 0; + ulp_poll_count = 0; + ulp_last_gpio_level = 0; + + /* Configure LP-timer wakeup at the configured poll period and start the + * LP-core. `ulp_lp_core_run` is non-blocking; the LP core begins running + * the program immediately and the HP core can proceed to deep sleep. */ + ulp_lp_core_cfg_t cfg = { + .wakeup_source = ULP_LP_CORE_WAKEUP_SOURCE_LP_TIMER, + .lp_timer_sleep_duration_us = CONFIG_C6_LP_POLL_PERIOD_US, + }; + err = ulp_lp_core_run(&cfg); + if (err != ESP_OK) { + ESP_LOGE(TAG, "ulp_lp_core_run failed: %s", esp_err_to_name(err)); + return err; + } + + /* Tell deep-sleep that the LP-core is our wake source. */ + err = esp_sleep_enable_ulp_wakeup(); + if (err != ESP_OK) { + ESP_LOGE(TAG, "esp_sleep_enable_ulp_wakeup failed: %s", esp_err_to_name(err)); + return err; + } + + s_armed = true; + ESP_LOGI(TAG, "LP-core armed: gpio=%d active_%s debounce=%d poll=%d µs", + wake_gpio, active_high ? "high" : "low", + CONFIG_C6_LP_DEBOUNCE_SAMPLES, CONFIG_C6_LP_POLL_PERIOD_US); + return ESP_OK; + +#else + /* --- Fallback path: plain deep-sleep GPIO wakeup (~10 µA floor) --- */ + uint64_t mask = 1ULL << wake_gpio; + esp_deepsleep_gpio_wake_up_mode_t mode = active_high + ? ESP_GPIO_WAKEUP_GPIO_HIGH + : ESP_GPIO_WAKEUP_GPIO_LOW; + esp_err_t err = esp_deep_sleep_enable_gpio_wakeup(mask, mode); + if (err != ESP_OK) { + ESP_LOGE(TAG, "enable_gpio_wakeup failed: %s", esp_err_to_name(err)); + return err; + } + s_armed = true; + ESP_LOGI(TAG, "GPIO-wakeup armed (no LP-core): gpio=%d active_%s", + wake_gpio, active_high ? "high" : "low"); + return ESP_OK; +#endif +} + +void c6_lp_core_hibernate_and_wait(void) +{ + if (!s_armed) { + ESP_LOGW(TAG, "hibernate called without arm — sleeping with no wake source"); + } + /* Power down the RTC peripheral domain — the LP-core itself stays + * powered on the LP power domain so it can keep polling. */ + esp_sleep_pd_config(ESP_PD_DOMAIN_RTC_PERIPH, ESP_PD_OPTION_OFF); + +#if defined(CONFIG_C6_LP_CORE_ENABLE) + ESP_LOGI(TAG, "entering deep sleep — LP-core polling, target ≤5 µA"); +#else + ESP_LOGI(TAG, "entering deep sleep — GPIO wakeup, target ~10 µA"); +#endif + esp_deep_sleep_start(); + /* Never returns. */ +} + +bool c6_lp_core_was_motion_wake(void) +{ + esp_sleep_wakeup_cause_t cause = esp_sleep_get_wakeup_cause(); +#if defined(CONFIG_C6_LP_CORE_ENABLE) + /* Real LP-core path: wakeup cause is ULP (LP-core triggered HP). */ + if (cause == ESP_SLEEP_WAKEUP_ULP) return true; +#endif + /* Fallback path or alternate GPIO wakeup. */ + return cause == ESP_SLEEP_WAKEUP_GPIO || cause == ESP_SLEEP_WAKEUP_EXT1; +} + +#if defined(CONFIG_C6_LP_CORE_ENABLE) +uint32_t c6_lp_core_motion_count(void) +{ + return (uint32_t)ulp_motion_count; +} + +uint32_t c6_lp_core_poll_count(void) +{ + return (uint32_t)ulp_poll_count; +} +#else +uint32_t c6_lp_core_motion_count(void) { return 0; } +uint32_t c6_lp_core_poll_count(void) { return 0; } +#endif + +#endif /* CONFIG_IDF_TARGET_ESP32C6 && CONFIG_ULP_COPROC_TYPE_LP_CORE */ diff --git a/firmware/esp32-csi-node/main/c6_lp_core.h b/firmware/esp32-csi-node/main/c6_lp_core.h new file mode 100644 index 00000000..9eaa1487 --- /dev/null +++ b/firmware/esp32-csi-node/main/c6_lp_core.h @@ -0,0 +1,77 @@ +/** + * @file c6_lp_core.h + * @brief LP-core wake-on-motion hibernation helper — ADR-110 Phase 5. + * + * Arms the C6 LP RISC-V coprocessor as an always-on watchdog that + * monitors a GPIO (typically a PIR or accelerometer interrupt line) and + * wakes the HP core only when motion is detected. Targets ~5 µA + * hibernation current for battery-powered Cognitum Seed nodes. + * + * Only built when CONFIG_IDF_TARGET_ESP32C6 + CONFIG_ULP_COPROC_TYPE_LP_CORE. + * + * P5 skeleton: the LP-core program is shipped as inline C compiled into + * the main image. A follow-up turn migrates it to a separate + * lp_core/main.c subproject with its own CMake. + */ + +#pragma once + +#ifdef __cplusplus +extern "C" { +#endif + +#include "esp_err.h" +#include +#include + +#if defined(CONFIG_IDF_TARGET_ESP32C6) && defined(CONFIG_ULP_COPROC_TYPE_LP_CORE) + +/** + * Configure the LP-core wake-on-motion watcher. + * + * @param wake_gpio GPIO pin to monitor (must be an RTC/LP-domain GPIO). + * @param active_high true = wake on rising edge, false = falling. + * @return ESP_OK on success. + */ +esp_err_t c6_lp_core_arm(int wake_gpio, bool active_high); + +/** + * Enter deep sleep with the LP-core armed as the wake source. Does not + * return — the next boot will see ESP_SLEEP_WAKEUP_LP_CORE in + * esp_sleep_get_wakeup_cause(). + */ +void c6_lp_core_hibernate_and_wait(void); + +/** + * Returns true if the most recent boot was a wake from LP-core motion + * detection (vs a cold boot or different wake source). + */ +bool c6_lp_core_was_motion_wake(void); + +/** + * Monotonic counter of wake-triggering motion events observed by the + * LP-core program since the last cold boot. Returns 0 when + * CONFIG_C6_LP_CORE_ENABLE is unset (fallback path). + */ +uint32_t c6_lp_core_motion_count(void); + +/** + * Total LP-timer poll iterations executed by the LP-core program. + * Useful as a sanity check that the LP-core is actually running; + * returns 0 on the fallback path. + */ +uint32_t c6_lp_core_poll_count(void); + +#else + +static inline esp_err_t c6_lp_core_arm(int g, bool h) { (void)g; (void)h; return ESP_OK; } +static inline void c6_lp_core_hibernate_and_wait(void) { } +static inline bool c6_lp_core_was_motion_wake(void) { return false; } +static inline uint32_t c6_lp_core_motion_count(void) { return 0; } +static inline uint32_t c6_lp_core_poll_count(void) { return 0; } + +#endif + +#ifdef __cplusplus +} +#endif diff --git a/firmware/esp32-csi-node/main/c6_softap_he.c b/firmware/esp32-csi-node/main/c6_softap_he.c new file mode 100644 index 00000000..7cde16f9 --- /dev/null +++ b/firmware/esp32-csi-node/main/c6_softap_he.c @@ -0,0 +1,177 @@ +/** + * @file c6_softap_he.c + * @brief ESP32-C6 soft-AP with HE/TWT — ADR-110 B1/B2 cheap-unblock. + * + * Pairs with c6_softap_he.h. Builds only when both targets are set: + * + * CONFIG_IDF_TARGET_ESP32C6 (selected by `idf.py set-target esp32c6`) + * CONFIG_C6_SOFTAP_HE_ENABLE (Kconfig, default n) + * + * The IDF v5.4 soft-AP path advertises HE automatically on chips with + * SOC_WIFI_HE_SUPPORT; the operator-side concern here is making sure + * the beacon also advertises `TWT Responder=1` so a STA-side + * `esp_wifi_sta_itwt_setup()` call doesn't bounce with `INVALID_ARG` + * the same way it did against `ruv.net` (the bench's 11n-only AP). + * + * TWT Responder advertisement in IDF v5.4 is gated by + * `wifi_he_ap_config_t.twt_responder = 1`. When the IDF header doesn't + * expose that struct (older v5.3), the AP still comes up with HE but + * without TWT Responder — we log a warning and continue so the build + * stays portable. + */ + +#include "sdkconfig.h" + +#if defined(CONFIG_IDF_TARGET_ESP32C6) && defined(CONFIG_C6_SOFTAP_HE_ENABLE) + +#include "c6_softap_he.h" +#include "esp_log.h" +#include "esp_wifi.h" +#include "esp_wifi_types.h" +#include "esp_event.h" +#include "esp_netif.h" +#include "nvs_flash.h" +#include "nvs.h" +#include + +static const char *TAG = "c6_softap"; + +static bool s_started = false; +static uint8_t s_sta_count = 0; +static uint8_t s_channel = 0; + +#ifndef CONFIG_C6_SOFTAP_HE_SSID +#define CONFIG_C6_SOFTAP_HE_SSID "ruview-c6-twt" +#endif +#ifndef CONFIG_C6_SOFTAP_HE_PSK +#define CONFIG_C6_SOFTAP_HE_PSK "ruviewtwt" +#endif +#ifndef CONFIG_C6_SOFTAP_HE_CHANNEL +#define CONFIG_C6_SOFTAP_HE_CHANNEL 6 +#endif + +static void load_nvs_override(const char *key, char *dst, size_t dst_len) +{ + nvs_handle_t h; + if (nvs_open("ruview", NVS_READONLY, &h) != ESP_OK) return; + size_t n = dst_len; + esp_err_t err = nvs_get_str(h, key, dst, &n); + if (err == ESP_OK) { + ESP_LOGI(TAG, "nvs override: %s=\"%s\"", key, dst); + } + nvs_close(h); +} + +static uint8_t load_nvs_u8(const char *key, uint8_t fallback) +{ + nvs_handle_t h; + if (nvs_open("ruview", NVS_READONLY, &h) != ESP_OK) return fallback; + uint8_t v = fallback; + if (nvs_get_u8(h, key, &v) == ESP_OK) { + ESP_LOGI(TAG, "nvs override: %s=%u", key, v); + } + nvs_close(h); + return v; +} + +static void on_wifi_event(void *arg, esp_event_base_t base, + int32_t event_id, void *event_data) +{ + (void)arg; (void)base; (void)event_data; + switch (event_id) { + case WIFI_EVENT_AP_START: + s_started = true; + ESP_LOGI(TAG, "AP started on channel %u", s_channel); + break; + case WIFI_EVENT_AP_STOP: + s_started = false; + ESP_LOGI(TAG, "AP stopped"); + break; + case WIFI_EVENT_AP_STACONNECTED: + if (s_sta_count < 255) s_sta_count++; + ESP_LOGI(TAG, "STA connected — total=%u", s_sta_count); + break; + case WIFI_EVENT_AP_STADISCONNECTED: + if (s_sta_count > 0) s_sta_count--; + ESP_LOGI(TAG, "STA disconnected — total=%u", s_sta_count); + break; + default: + break; + } +} + +esp_err_t c6_softap_he_start(uint8_t *out_channel) +{ + if (s_started) { + if (out_channel) *out_channel = s_channel; + return ESP_OK; + } + + /* Resolve config: NVS overrides Kconfig defaults. */ + char ssid[33] = CONFIG_C6_SOFTAP_HE_SSID; + char psk[64] = CONFIG_C6_SOFTAP_HE_PSK; + load_nvs_override("softap_ssid", ssid, sizeof(ssid)); + load_nvs_override("softap_psk", psk, sizeof(psk)); + s_channel = load_nvs_u8("softap_chan", CONFIG_C6_SOFTAP_HE_CHANNEL); + if (s_channel < 1 || s_channel > 13) s_channel = CONFIG_C6_SOFTAP_HE_CHANNEL; + + /* AP+STA so the existing STA path keeps working (NVS-provisioned upstream). */ + ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_APSTA)); + + wifi_config_t ap_cfg = {0}; + size_t ssid_len = strlen(ssid); + if (ssid_len > 32) ssid_len = 32; + memcpy(ap_cfg.ap.ssid, ssid, ssid_len); + ap_cfg.ap.ssid_len = (uint8_t)ssid_len; + strncpy((char *)ap_cfg.ap.password, psk, sizeof(ap_cfg.ap.password) - 1); + ap_cfg.ap.channel = s_channel; + ap_cfg.ap.max_connection = 4; + ap_cfg.ap.authmode = strlen(psk) >= 8 ? WIFI_AUTH_WPA2_PSK : WIFI_AUTH_OPEN; + ap_cfg.ap.beacon_interval = 100; + /* pmf_cfg.required = false keeps backward compatibility for STA clients + * that don't speak PMF. */ + ap_cfg.ap.pmf_cfg.required = false; + + /* Register the event handler before bringing the AP up so we don't + * miss WIFI_EVENT_AP_START. */ + ESP_ERROR_CHECK(esp_event_handler_instance_register( + WIFI_EVENT, ESP_EVENT_ANY_ID, on_wifi_event, NULL, NULL)); + + esp_err_t err = esp_wifi_set_config(WIFI_IF_AP, &ap_cfg); + if (err != ESP_OK) { + ESP_LOGE(TAG, "set_config(AP) failed: %s", esp_err_to_name(err)); + return err; + } + + /* IDF v5.4 LIMIT (verified empirically 2026-05-23 — WITNESS-LOG-110 §A0.6): + * the public API exposes ONLY STA-side iTWT/bTWT (esp_wifi_sta_itwt_*, + * esp_wifi_sta_btwt_*). There is NO esp_wifi_ap_set_he_config(), NO + * wifi_he_ap_config_t, and NO wifi_config_t.ap.he_* field. A second C6 + * associating against this soft-AP currently lands at phymode 11bgn + * (he:0, vht:0, ht:1) — the AP doesn't advertise HE because there's no + * way to ask it to. A future IDF release that exposes AP-side HE config + * (or a patched WiFi blob) is required to make this AP iTWT-capable. + * + * Until then, this module still gives you a working WPA2 soft-AP on a + * controlled channel for AP+STA bench experiments and ESP-NOW peer + * discovery — just not iTWT validation. The c6_twt module on the STA + * side will return ESP_ERR_INVALID_ARG against this AP (no TWT Responder + * in the beacon), exactly as it does against any other 11n-only AP. */ + ESP_LOGI(TAG, "soft-AP starting: ssid=\"%s\" channel=%u auth=%s", + ssid, s_channel, + ap_cfg.ap.authmode == WIFI_AUTH_OPEN ? "open" : "wpa2-psk"); + ESP_LOGW(TAG, "IDF v5.4 soft-AP does NOT advertise HE — STAs will associate at 11bgn. " + "iTWT validation requires an external 11ax AP. See WITNESS-LOG-110 §A0.6."); + + /* Don't call esp_wifi_start() here — main.c brings the WiFi up once + * for both AP and STA. We just configured the AP iface so it joins + * the existing start. */ + + if (out_channel) *out_channel = s_channel; + return ESP_OK; +} + +bool c6_softap_he_is_up(void) { return s_started; } +uint8_t c6_softap_he_sta_count(void) { return s_sta_count; } + +#endif /* CONFIG_IDF_TARGET_ESP32C6 && CONFIG_C6_SOFTAP_HE_ENABLE */ diff --git a/firmware/esp32-csi-node/main/c6_softap_he.h b/firmware/esp32-csi-node/main/c6_softap_he.h new file mode 100644 index 00000000..7e27ada6 --- /dev/null +++ b/firmware/esp32-csi-node/main/c6_softap_he.h @@ -0,0 +1,66 @@ +/** + * @file c6_softap_he.h + * @brief ESP32-C6 soft-AP with Wi-Fi 6 (HE) capability + TWT Responder. + * + * ADR-110 §B1/B2 cheap-unblock: turn one C6 board into the iTWT-capable + * AP that the C6-DevKit-on-the-shelf-only bench is missing. A second C6 + * board in STA mode can then negotiate a real iTWT agreement against + * this AP and measure deterministic CSI cadence — without buying an + * 11ax router. + * + * Build-gated by CONFIG_C6_SOFTAP_HE_ENABLE (default n). When disabled, + * all functions become no-ops so non-AP firmwares pay zero overhead. + * + * NVS overrides (read at boot if present, fall back to Kconfig defaults): + * softap_ssid (string, up to 32 chars) + * softap_psk (string, 8..63 chars) + * softap_chan (u8, 1..13) + */ + +#pragma once + +#ifdef __cplusplus +extern "C" { +#endif + +#include "esp_err.h" +#include +#include + +#if defined(CONFIG_IDF_TARGET_ESP32C6) && defined(CONFIG_C6_SOFTAP_HE_ENABLE) + +/** + * Bring up the soft-AP in AP+STA mode with HE (Wi-Fi 6) advertised and + * TWT Responder=1 if the IDF build supports it. Idempotent — safe to + * call once during boot after `esp_wifi_init()`. Returns the channel + * the AP is actually running on (may differ from Kconfig if the IDF + * scanner picks a clearer channel). + */ +esp_err_t c6_softap_he_start(uint8_t *out_channel); + +/** + * True after the IDF reports the AP has started successfully. + */ +bool c6_softap_he_is_up(void); + +/** + * Number of currently associated stations (read-only, refreshed on the + * WIFI_EVENT_AP_STACONNECTED/DISCONNECTED events). + */ +uint8_t c6_softap_he_sta_count(void); + +#else /* disabled — no-op stubs */ + +static inline esp_err_t c6_softap_he_start(uint8_t *out_channel) +{ + if (out_channel) *out_channel = 0; + return ESP_OK; +} +static inline bool c6_softap_he_is_up(void) { return false; } +static inline uint8_t c6_softap_he_sta_count(void) { return 0; } + +#endif + +#ifdef __cplusplus +} +#endif diff --git a/firmware/esp32-csi-node/main/c6_sync_espnow.c b/firmware/esp32-csi-node/main/c6_sync_espnow.c new file mode 100644 index 00000000..fbdf4054 --- /dev/null +++ b/firmware/esp32-csi-node/main/c6_sync_espnow.c @@ -0,0 +1,239 @@ +/** + * @file c6_sync_espnow.c + * @brief ESP-NOW cross-node time-sync — ADR-110 D1 workaround. + * + * Same protocol as c6_timesync.c (TS_BEACON every 100 ms with leader epoch), + * but over ESP-NOW instead of 802.15.4 because the IDF v5.4 ieee802154 RX + * path doesn't deliver frames to user-space (see WITNESS-LOG-110 §D1). + * + * Frame layout (16 bytes payload, broadcast MAC FF:FF:FF:FF:FF:FF): + * [0..3] Magic 0x53454E50 ('SENP' — Sync via ESP-NOW) + * [4] Protocol ver 0x01 + * [5] Leader flag 1 if sender claims leader + * [6..7] Reserved + * [8..15] Leader epoch µs (LE u64) + */ + +#include "sdkconfig.h" +#include "c6_sync_espnow.h" +#include "esp_log.h" +#include "esp_now.h" +#include "esp_wifi.h" +#include "esp_mac.h" +#include "esp_timer.h" +#include "freertos/FreeRTOS.h" +#include "freertos/timers.h" +#include + +static const char *TAG = "c6_espnow"; + +#define BEACON_MAGIC 0x53454E50u /* 'SENP' little-endian */ +#define BEACON_PROTO_VER 0x01 +#define BEACON_PERIOD_MS 100 +#define VALID_WINDOW_MS 3000 + +typedef struct __attribute__((packed)) { + uint32_t magic; + uint8_t proto_ver; + uint8_t leader_flag; + uint16_t _reserved; + uint64_t leader_epoch_us; +} espnow_beacon_t; + +static const uint8_t s_broadcast_mac[6] = {0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF}; + +static uint64_t s_local_id = 0; /* 6-byte MAC packed into u64 */ +static uint64_t s_leader_id = 0; +static int64_t s_offset_us = 0; +static uint64_t s_last_seen_us = 0; +static bool s_is_leader = false; +static TimerHandle_t s_beacon_timer = NULL; + +static uint32_t s_tx_count = 0; +static uint32_t s_tx_fail = 0; +static uint32_t s_rx_count = 0; +static uint32_t s_rx_magic_match = 0; + +/* ADR-110 P10 — EMA-smoothed offset (host-side trajectory in firmware). + * + * The §A0.8 four-minute soak measured 540 µs sample-stdev around a true + * offset that drifts at ≈1.4 ppm between two C6 crystals. An exponential + * moving average with α=0.125 (Q3.3 fixed-point shift = 3) yields an + * effective ~8-sample window, fast enough to track the drift (~7 µs/sec + * worst-case) while suppressing the per-beacon WiFi-MAC jitter. + * + * Two consumers: get_offset_us() (raw, unchanged — for diagnostics) and + * get_offset_us_smoothed() (filtered — what CSI frames should stamp). + * Both expose `int64_t` so call sites stay identical. */ +#define OFFSET_EMA_SHIFT 3 /* α = 1/8 = 0.125 */ +static int64_t s_offset_us_smoothed = 0; +static bool s_smoothed_seeded = false; + +static uint64_t mac6_to_u64(const uint8_t mac[6]) +{ + return ((uint64_t)mac[0] << 40) | ((uint64_t)mac[1] << 32) | + ((uint64_t)mac[2] << 24) | ((uint64_t)mac[3] << 16) | + ((uint64_t)mac[4] << 8) | (uint64_t)mac[5]; +} + +static void send_beacon(void) +{ + espnow_beacon_t b = { + .magic = BEACON_MAGIC, + .proto_ver = BEACON_PROTO_VER, + .leader_flag = s_is_leader ? 1 : 0, + ._reserved = 0, + .leader_epoch_us = (uint64_t)esp_timer_get_time(), + }; + esp_err_t r = esp_now_send(s_broadcast_mac, (uint8_t *)&b, sizeof(b)); + s_tx_count++; + if (r != ESP_OK) s_tx_fail++; + /* Diag log every 50 beacons. */ + if ((s_tx_count % 50) == 1) { + ESP_LOGI(TAG, "tx#%lu (fail=%lu) rx#%lu (match=%lu) leader=%d offset_us=%lld smoothed=%lld", + (unsigned long)s_tx_count, (unsigned long)s_tx_fail, + (unsigned long)s_rx_count, (unsigned long)s_rx_magic_match, + (int)s_is_leader, (long long)s_offset_us, + (long long)s_offset_us_smoothed); + } +} + +/* IDF v5.4 ESP-NOW recv callback signature uses esp_now_recv_info_t. + * Falls back to the older signature on older IDF via ifdef. */ +#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 0, 0) +static void on_recv(const esp_now_recv_info_t *info, + const uint8_t *data, int len) +{ + const uint8_t *src_mac = info ? info->src_addr : NULL; +#else +static void on_recv(const uint8_t *src_mac, const uint8_t *data, int len) +{ +#endif + s_rx_count++; + if (data == NULL || len < (int)sizeof(espnow_beacon_t)) return; + const espnow_beacon_t *b = (const espnow_beacon_t *)data; + if (b->magic != BEACON_MAGIC || b->proto_ver != BEACON_PROTO_VER) return; + s_rx_magic_match++; + uint64_t sender_id = src_mac ? mac6_to_u64(src_mac) : 0; + uint64_t now_us = (uint64_t)esp_timer_get_time(); + + /* Adopt sender as leader if it's claiming leadership AND its ID is + * lower than our current leader (or we have no leader). Lowest MAC + * wins — deterministic. */ + if (b->leader_flag && (s_leader_id == 0 || sender_id < s_leader_id)) { + if (s_is_leader && sender_id < s_local_id) { + ESP_LOGI(TAG, "stepping down: heard lower-id leader %012llx (we are %012llx)", + (unsigned long long)sender_id, (unsigned long long)s_local_id); + s_is_leader = false; + } + s_leader_id = sender_id; + } + + /* If accepted leader, compute offset from their epoch (only for non-leader). */ + if (b->leader_flag && !s_is_leader && sender_id == s_leader_id) { + int64_t raw = (int64_t)b->leader_epoch_us - (int64_t)now_us; + s_offset_us = raw; + s_last_seen_us = now_us; + /* EMA: y[n] = y[n-1] + (raw - y[n-1]) >> SHIFT */ + if (!s_smoothed_seeded) { + s_offset_us_smoothed = raw; + s_smoothed_seeded = true; + } else { + s_offset_us_smoothed += (raw - s_offset_us_smoothed) >> OFFSET_EMA_SHIFT; + } + } +} + +static void on_send(const uint8_t *mac, esp_now_send_status_t status) +{ + (void)mac; + if (status != ESP_NOW_SEND_SUCCESS) s_tx_fail++; +} + +static void beacon_timer_cb(TimerHandle_t t) +{ + (void)t; + uint64_t now = (uint64_t)esp_timer_get_time(); + /* Promote self if no leader beacon for VALID_WINDOW_MS and we have lowest known id. */ + if (!s_is_leader && (now - s_last_seen_us) > (VALID_WINDOW_MS * 1000ULL)) { + if (s_leader_id == 0 || s_local_id < s_leader_id) { + s_is_leader = true; + s_leader_id = s_local_id; + s_offset_us = 0; + ESP_LOGI(TAG, "promoting self to leader (no beacons for %u ms; local_id=%012llx)", + (unsigned)VALID_WINDOW_MS, (unsigned long long)s_local_id); + } + } + send_beacon(); +} + +esp_err_t c6_sync_espnow_init(void) +{ + uint8_t mac[6]; + esp_read_mac(mac, ESP_MAC_WIFI_STA); + s_local_id = mac6_to_u64(mac); + + esp_err_t r = esp_now_init(); + if (r != ESP_OK) { + ESP_LOGE(TAG, "esp_now_init failed: %s", esp_err_to_name(r)); + return r; + } + esp_now_register_recv_cb(on_recv); + esp_now_register_send_cb(on_send); + + /* Add broadcast peer so esp_now_send to FF:FF:FF:FF:FF:FF works. */ + esp_now_peer_info_t peer = {0}; + memcpy(peer.peer_addr, s_broadcast_mac, 6); + peer.channel = 0; /* current STA channel */ + peer.ifidx = WIFI_IF_STA; + peer.encrypt = false; + r = esp_now_add_peer(&peer); + if (r != ESP_OK && r != ESP_ERR_ESPNOW_EXIST) { + ESP_LOGW(TAG, "esp_now_add_peer(broadcast) failed: %s", esp_err_to_name(r)); + } + + /* Start as candidate leader — will step down on receiving lower-id beacon. */ + s_is_leader = true; + s_leader_id = s_local_id; + s_last_seen_us = (uint64_t)esp_timer_get_time(); + + s_beacon_timer = xTimerCreate("c6_espnow_beacon", + pdMS_TO_TICKS(BEACON_PERIOD_MS), + pdTRUE, NULL, beacon_timer_cb); + if (s_beacon_timer == NULL) { + ESP_LOGE(TAG, "xTimerCreate failed"); + return ESP_ERR_NO_MEM; + } + xTimerStart(s_beacon_timer, 0); + + ESP_LOGI(TAG, "init done: local_id=%012llx leader=yes(candidate) period=%ums", + (unsigned long long)s_local_id, (unsigned)BEACON_PERIOD_MS); + return ESP_OK; +} + +uint64_t c6_sync_espnow_get_epoch_us(void) +{ + /* Prefer the smoothed offset once we've heard a leader beacon; falls + * back to raw=0 on the leader board and during the first second after + * follower boot. The smoothed value is what CSI frames should stamp + * for cross-board multistatic alignment (§A0.8 measured 540 µs raw + * stdev → expected <100 µs smoothed with α=1/8 over ~8 samples). */ + int64_t off = s_smoothed_seeded ? s_offset_us_smoothed : s_offset_us; + return (uint64_t)((int64_t)esp_timer_get_time() + off); +} + +bool c6_sync_espnow_is_leader(void) { return s_is_leader; } +int64_t c6_sync_espnow_get_offset_us(void) { return s_offset_us; } +int64_t c6_sync_espnow_get_offset_us_smoothed(void) { return s_offset_us_smoothed; } + +bool c6_sync_espnow_is_valid(void) +{ + if (s_is_leader) return true; + uint64_t now = (uint64_t)esp_timer_get_time(); + return (now - s_last_seen_us) < (VALID_WINDOW_MS * 1000ULL); +} + +uint32_t c6_sync_espnow_tx_count(void) { return s_tx_count; } +uint32_t c6_sync_espnow_tx_fail(void) { return s_tx_fail; } +uint32_t c6_sync_espnow_rx_count(void) { return s_rx_count; } +uint32_t c6_sync_espnow_rx_magic_match(void) { return s_rx_magic_match; } diff --git a/firmware/esp32-csi-node/main/c6_sync_espnow.h b/firmware/esp32-csi-node/main/c6_sync_espnow.h new file mode 100644 index 00000000..c8993896 --- /dev/null +++ b/firmware/esp32-csi-node/main/c6_sync_espnow.h @@ -0,0 +1,68 @@ +/** + * @file c6_sync_espnow.h + * @brief ESP-NOW based cross-node time-sync — ADR-110 D1 workaround. + * + * After 4 systematic experiments confirmed the 802.15.4 RX path is broken + * in this user-code + IDF v5.4 combination (see WITNESS-LOG-110 §D1), the + * cross-node sync claim was unblocked by switching transport from IEEE + * 802.15.4 to ESP-NOW (WiFi-based peer-to-peer, runs on the same 2.4 GHz + * radio but uses the WiFi MAC layer that ESP-IDF's 802.11 driver fully + * supports). + * + * Trade vs. 802.15.4: + * - Loses the "frees WiFi airtime for CSI" property (uses WiFi for sync) + * - Gains a known-working RX path on every ESP32 family + * - Same API surface (epoch_us, is_valid, is_leader) so call sites that + * used to depend on c6_timesync drop in unchanged + * + * Works on both ESP32-S3 and ESP32-C6 — the cross-node sync becomes a + * cross-target feature, not C6-only. + */ + +#pragma once + +#ifdef __cplusplus +extern "C" { +#endif + +#include "esp_err.h" +#include +#include + +/** + * Initialize the ESP-NOW sync module. Must be called AFTER WiFi STA is + * connected (ESP-NOW needs the WiFi driver active). + * + * @return ESP_OK on success. + */ +esp_err_t c6_sync_espnow_init(void); + +/** + * Returns the synced wall-clock estimate in microseconds. + * If no leader heard within the timeout, returns the local + * esp_timer_get_time() value unchanged (offset = 0). + */ +uint64_t c6_sync_espnow_get_epoch_us(void); + +bool c6_sync_espnow_is_leader(void); +bool c6_sync_espnow_is_valid(void); +int64_t c6_sync_espnow_get_offset_us(void); + +/** + * EMA-smoothed offset (α=1/8, ~8-sample effective window at the 10 Hz + * beacon rate). Tracks the ≈1.4 ppm crystal drift between two C6 boards + * (measured in §A0.8) while suppressing the 540 µs per-beacon WiFi-MAC + * jitter. CSI frame timestamps should stamp from this value, not the raw + * offset — `c6_sync_espnow_get_epoch_us()` already does so internally. + */ +int64_t c6_sync_espnow_get_offset_us_smoothed(void); + +/* Counters for the witness harness — exposed for tests/diagnostics. */ +uint32_t c6_sync_espnow_tx_count(void); +uint32_t c6_sync_espnow_tx_fail(void); +uint32_t c6_sync_espnow_rx_count(void); +uint32_t c6_sync_espnow_rx_magic_match(void); + +#ifdef __cplusplus +} +#endif diff --git a/firmware/esp32-csi-node/main/c6_timesync.c b/firmware/esp32-csi-node/main/c6_timesync.c new file mode 100644 index 00000000..4697696e --- /dev/null +++ b/firmware/esp32-csi-node/main/c6_timesync.c @@ -0,0 +1,265 @@ +/** + * @file c6_timesync.c + * @brief 802.15.4 mesh time-sync skeleton — ADR-110 Phase 4. + * + * P4 ships the API surface, role election, and the leader-broadcast + + * follower-receive paths using esp_ieee802154 raw frames. Full + * OpenThread MTD attachment with a real network key is deferred to a + * follow-up turn — the skeleton already exercises the radio init and + * the offset-tracking math. + * + * Beacon frame layout (12 bytes payload + 802.15.4 MAC header): + * [0..3] Magic 0x54534D45 ('TSME' — Time Sync MEsh) + * [4] Protocol ver 0x01 + * [5] Leader flag 1 if sender is current leader + * [6..7] Reserved + * [8..15] Leader epoch µs (LE u64) + */ + +#include "sdkconfig.h" + +#if defined(CONFIG_IDF_TARGET_ESP32C6) && defined(CONFIG_IEEE802154_ENABLED) + +#include "c6_timesync.h" +#include "esp_log.h" +#include "esp_mac.h" +#include "esp_timer.h" +#include "esp_ieee802154.h" +#include "freertos/FreeRTOS.h" +#include "freertos/task.h" +#include "freertos/timers.h" +#include + +static const char *TAG = "c6_ts"; + +#define TS_MAGIC 0x54534D45u +#define TS_PROTO_VER 0x01 +#define TS_BEACON_MS 100 +#define TS_VALID_WINDOW_MS 3000 /* drop to invalid if no beacon in 3 s */ + +typedef struct __attribute__((packed)) { + uint32_t magic; + uint8_t proto_ver; + uint8_t leader_flag; + uint16_t _reserved; + uint64_t leader_epoch_us; +} ts_beacon_t; + +static uint64_t s_local_eui = 0; +static uint64_t s_leader_eui = 0; /* 0 = unknown */ +static int64_t s_offset_us = 0; /* leader_us - local_us */ +static uint64_t s_last_seen_us = 0; +static bool s_is_leader = false; +static uint8_t s_channel = 15; +static TimerHandle_t s_beacon_timer = NULL; + +/* IEEE EUI-64 from a 6-byte MAC-48: insert 0xFFFE between bytes 2 and 3. + * Used only as a fallback when esp_read_mac(..., ESP_MAC_IEEE802154) is + * unavailable. The C6's native call returns 8 bytes already in EUI-64 + * format, so prefer that path (see c6_timesync_init). */ +static uint64_t mac48_to_eui64(const uint8_t mac[6]) +{ + return ((uint64_t)mac[0] << 56) | ((uint64_t)mac[1] << 48) | + ((uint64_t)mac[2] << 40) | ((uint64_t)0xFF << 32) | + ((uint64_t)0xFE << 24) | ((uint64_t)mac[3] << 16) | + ((uint64_t)mac[4] << 8 ) | (uint64_t)mac[5]; +} + +/* Pack 8 already-EUI-64 bytes into a uint64. */ +static uint64_t eui64_bytes_to_u64(const uint8_t eui[8]) +{ + return ((uint64_t)eui[0] << 56) | ((uint64_t)eui[1] << 48) | + ((uint64_t)eui[2] << 40) | ((uint64_t)eui[3] << 32) | + ((uint64_t)eui[4] << 24) | ((uint64_t)eui[5] << 16) | + ((uint64_t)eui[6] << 8 ) | (uint64_t)eui[7]; +} + +static uint32_t s_tx_count = 0; +static uint32_t s_tx_fail = 0; +static uint32_t s_rx_count = 0; +static uint32_t s_rx_magic_match = 0; + +static void send_beacon(void) +{ + uint8_t frame[32]; + /* Minimal 802.15.4 MAC header: FCF + seq + dst PAN + dst short addr. */ + frame[0] = 0x41; /* FCF lo: data frame, no security, no ack */ + frame[1] = 0x88; /* FCF hi: short addrs, intra-PAN */ + frame[2] = 0x00; /* seq number — placeholder */ + /* Empirically (rx#0 over 60s on all 3 boards), the IDF v5.4 receiver + * was rejecting the dst-PAN-broadcast (0xFFFF) frames even in + * promiscuous mode. Match our configured PAN ID 0xCAFE here — short + * dst stays 0xFFFF for intra-PAN broadcast. PAN bytes are LE. */ + frame[3] = 0xFE; frame[4] = 0xCA; /* dst PAN = 0xCAFE (matches local) */ + frame[5] = 0xFF; frame[6] = 0xFF; /* dst short broadcast */ + frame[7] = 0x00; frame[8] = 0x00; /* src short = 0x0000 */ + ts_beacon_t *b = (ts_beacon_t *)&frame[9]; + b->magic = TS_MAGIC; + b->proto_ver = TS_PROTO_VER; + b->leader_flag = 1; + b->_reserved = 0; + b->leader_epoch_us = (uint64_t)esp_timer_get_time(); + size_t total = 9 + sizeof(ts_beacon_t); + /* ESP-IDF esp_ieee802154 transmit: first byte is the PHY length. */ + uint8_t tx_buf[64]; + tx_buf[0] = (uint8_t)(total + 2); /* +2 for FCS appended by HW */ + memcpy(&tx_buf[1], frame, total); + esp_err_t r = esp_ieee802154_transmit(tx_buf, false); + s_tx_count++; + if (r != ESP_OK) s_tx_fail++; + /* Diag log every 10 beacons. */ + if ((s_tx_count % 10) == 1) { + ESP_LOGI(TAG, "tx#%lu (fail=%lu) rx#%lu (magic_match=%lu) is_leader=%d", + (unsigned long)s_tx_count, (unsigned long)s_tx_fail, + (unsigned long)s_rx_count, (unsigned long)s_rx_magic_match, + (int)s_is_leader); + } +} + +/* KNOWN ISSUE (see WITNESS-LOG-110 §D1 / task #30): + * Empirically observed on 3 C6 boards with channel=26, OpenThread disabled, + * promiscuous=true, and IDF v5.4 reference RX/TX callback pattern: only 1 + * RX event ever fires after init, despite ~381 successful TX events from + * the other boards in the same 38-second window. Manual re-arm with + * esp_ieee802154_receive() in either callback context bootloops the + * driver. Hypothesis: half-duplex radio + driver state-machine issue; + * needs an IDF maintainer trace or a working multi-board reference. + * Cross-node sync claim (ADR-110 §B3) is BLOCKED on this. */ +void esp_ieee802154_receive_done(uint8_t *frame, esp_ieee802154_frame_info_t *frame_info) +{ + s_rx_count++; + /* PHY length is frame[0]; payload starts at frame[1]. */ + if (frame == NULL || frame[0] < (9 + sizeof(ts_beacon_t) + 2)) { + if (frame) esp_ieee802154_receive_handle_done(frame); + return; + } + const ts_beacon_t *b = (const ts_beacon_t *)&frame[1 + 9]; + if (b->magic != TS_MAGIC || b->proto_ver != TS_PROTO_VER) { + esp_ieee802154_receive_handle_done(frame); + return; + } + s_rx_magic_match++; + uint64_t now = (uint64_t)esp_timer_get_time(); + if (b->leader_flag) { + /* Adopt this leader if its EUI is lower than ours (or unknown). */ + if (s_leader_eui == 0 || b->leader_epoch_us > 0) { + s_offset_us = (int64_t)b->leader_epoch_us - (int64_t)now; + s_last_seen_us = now; + if (s_is_leader) { + /* Step down — somebody else is broadcasting; lowest EUI wins + * (deferred — for now last-heard wins). */ + s_is_leader = false; + ESP_LOGI(TAG, "stepping down — heard another leader beacon"); + } + } + } + /* handle_done auto-restarts RX in the IDF driver; calling + * esp_ieee802154_receive() here would double-arm and panic + * (verified empirically — 25 reboot loops observed). */ + esp_ieee802154_receive_handle_done(frame); +} + +void esp_ieee802154_transmit_done(const uint8_t *frame, + const uint8_t *ack, + esp_ieee802154_frame_info_t *ack_frame_info) +{ + (void)frame; (void)ack; (void)ack_frame_info; + /* Note: do NOT call esp_ieee802154_receive() here — it panics the + * driver (verified empirically, all 3 boards bootloop). The IDF + * driver internally manages RX/TX state transitions. */ +} + +void esp_ieee802154_transmit_failed(const uint8_t *frame, esp_ieee802154_tx_error_t error) +{ + (void)frame; + ESP_LOGD(TAG, "tx failed: %d", error); +} + +static void beacon_timer_cb(TimerHandle_t t) +{ + (void)t; + uint64_t now = (uint64_t)esp_timer_get_time(); + if (s_is_leader) { + send_beacon(); + } else if ((now - s_last_seen_us) > (TS_VALID_WINDOW_MS * 1000ULL)) { + /* Lost the leader — promote self if no one else takes over in 1 s. */ + s_is_leader = true; + s_leader_eui = s_local_eui; + ESP_LOGI(TAG, "promoting self to time-leader (no beacons for %u ms)", + (unsigned)TS_VALID_WINDOW_MS); + } +} + +esp_err_t c6_timesync_init(uint8_t channel) +{ + /* esp_mac.h: ESP_MAC_IEEE802154 returns 8 bytes ALREADY in EUI-64 format + * (ff:fe is pre-inserted in bytes 3-4 from the eFuse MAC_EXT). Using a + * 6-byte buffer here truncates and then double-inserts ff:fe — the bug + * we hit on the first run (boot log: EUI=206ef1fffefffe17). + * + * Correct path: read 8 bytes, pack into uint64 unchanged. Fallback to + * the base MAC + manual EUI-64 derivation if the 8-byte read errors. */ + uint8_t eui_bytes[8] = {0}; + esp_err_t mac_ret = esp_read_mac(eui_bytes, ESP_MAC_IEEE802154); + if (mac_ret == ESP_OK) { + s_local_eui = eui64_bytes_to_u64(eui_bytes); + } else { + uint8_t base_mac[6]; + esp_read_mac(base_mac, ESP_MAC_BASE); + s_local_eui = mac48_to_eui64(base_mac); + } + /* Use the 6-byte base MAC for the IEEE 802.15.4 extended address — the + * radio expects MAC-48-style bytes here, not the EUI-64 derivation. */ + uint8_t mac[6]; + esp_read_mac(mac, ESP_MAC_BASE); + s_channel = (channel >= 11 && channel <= 26) ? channel : 15; + + esp_err_t ret = esp_ieee802154_enable(); + if (ret != ESP_OK) { + ESP_LOGE(TAG, "ieee802154_enable failed: %s", esp_err_to_name(ret)); + return ret; + } + /* promiscuous=true so we accept broadcast frames addressed to 0xFFFF. + * In non-promiscuous mode the radio filters to frames addressed to + * our short or extended address. Our beacon protocol uses broadcast. */ + esp_ieee802154_set_promiscuous(true); + esp_ieee802154_set_panid(0xCAFE); + esp_ieee802154_set_short_address(0x0000); + esp_ieee802154_set_extended_address(mac); + esp_ieee802154_set_channel(s_channel); + esp_ieee802154_receive(); + + /* Start as candidate leader; first received beacon will demote us if needed. */ + s_is_leader = true; + s_leader_eui = s_local_eui; + s_last_seen_us = (uint64_t)esp_timer_get_time(); + + s_beacon_timer = xTimerCreate("c6ts_beacon", pdMS_TO_TICKS(TS_BEACON_MS), + pdTRUE, NULL, beacon_timer_cb); + if (s_beacon_timer == NULL) { + ESP_LOGE(TAG, "xTimerCreate failed"); + return ESP_ERR_NO_MEM; + } + xTimerStart(s_beacon_timer, 0); + + ESP_LOGI(TAG, "init done: channel=%u EUI=%016llx leader=yes(candidate)", + (unsigned)s_channel, (unsigned long long)s_local_eui); + return ESP_OK; +} + +uint64_t c6_timesync_get_epoch_us(void) +{ + return (uint64_t)((int64_t)esp_timer_get_time() + s_offset_us); +} + +bool c6_timesync_is_leader(void) { return s_is_leader; } +int64_t c6_timesync_get_offset_us(void) { return s_offset_us; } + +bool c6_timesync_is_valid(void) +{ + if (s_is_leader) return true; + uint64_t now = (uint64_t)esp_timer_get_time(); + return (now - s_last_seen_us) < (TS_VALID_WINDOW_MS * 1000ULL); +} + +#endif /* CONFIG_IDF_TARGET_ESP32C6 && CONFIG_IEEE802154_ENABLED */ diff --git a/firmware/esp32-csi-node/main/c6_timesync.h b/firmware/esp32-csi-node/main/c6_timesync.h new file mode 100644 index 00000000..4912636b --- /dev/null +++ b/firmware/esp32-csi-node/main/c6_timesync.h @@ -0,0 +1,77 @@ +/** + * @file c6_timesync.h + * @brief 802.15.4 mesh time-sync — ADR-110 Phase 4. + * + * Provides cross-node clock alignment over a separate 802.15.4 radio so + * the WiFi airtime stays clean for CSI sensing. Solves the multistatic + * synchronization problem (ADR-029/030) without burning the sensing + * channel on coordination traffic. + * + * Protocol (skeleton — full Thread join deferred to a follow-up phase): + * - One node is elected time-leader (lowest 64-bit EUI on the mesh). + * - Leader broadcasts a TS_BEACON every 100 ms on 802.15.4 channel 15. + * - Followers compute offset = leader_us - local_us, apply lazily. + * - Each CSI frame is stamped with c6_timesync_get_epoch_us(). + * + * Only built when CONFIG_IDF_TARGET_ESP32C6 + CONFIG_IEEE802154_ENABLED. + */ + +#pragma once + +#ifdef __cplusplus +extern "C" { +#endif + +#include "esp_err.h" +#include +#include + +#if defined(CONFIG_IDF_TARGET_ESP32C6) && defined(CONFIG_IEEE802154_ENABLED) + +/** + * Initialize the 802.15.4 radio and time-sync state machine. + * Picks leader or follower role based on EUI comparison. + * + * @param channel 802.15.4 channel (11-26, default 15). + * @return ESP_OK on success. + */ +esp_err_t c6_timesync_init(uint8_t channel); + +/** + * Returns the synced wall-clock estimate in microseconds. + * If no leader heard within the timeout, returns the local + * esp_timer_get_time() value unchanged (offset = 0). + */ +uint64_t c6_timesync_get_epoch_us(void); + +/** + * Returns true if this node is currently the time-leader. + */ +bool c6_timesync_is_leader(void); + +/** + * Returns true if the local clock is synced (heard a beacon within timeout). + */ +bool c6_timesync_is_valid(void); + +/** + * Returns the most-recently-measured offset from the leader (microseconds). + * 0 if this node is the leader; sign indicates direction. + */ +int64_t c6_timesync_get_offset_us(void); + +#else /* not C6 with 802.15.4 — provide stubs so call sites compile */ + +#include "esp_timer.h" + +static inline esp_err_t c6_timesync_init(uint8_t c) { (void)c; return ESP_OK; } +static inline uint64_t c6_timesync_get_epoch_us(void) { return (uint64_t)esp_timer_get_time(); } +static inline bool c6_timesync_is_leader(void) { return false; } +static inline bool c6_timesync_is_valid(void) { return false; } +static inline int64_t c6_timesync_get_offset_us(void) { return 0; } + +#endif + +#ifdef __cplusplus +} +#endif diff --git a/firmware/esp32-csi-node/main/c6_twt.c b/firmware/esp32-csi-node/main/c6_twt.c new file mode 100644 index 00000000..71961c78 --- /dev/null +++ b/firmware/esp32-csi-node/main/c6_twt.c @@ -0,0 +1,155 @@ +/** + * @file c6_twt.c + * @brief ESP32-C6 TWT setup implementation — ADR-110 Phase 3. + * + * Implementation note: ESP-IDF v5.4's iTWT API on C6 is + * + * esp_err_t esp_wifi_sta_itwt_setup(wifi_itwt_setup_config_t *cfg); + * esp_err_t esp_wifi_sta_itwt_teardown(uint8_t flow_id); + * + * The setup is asynchronous — the actual accept/reject arrives later as + * a WIFI_EVENT_ITWT_SETUP event. The default handler in this module + * logs the outcome; the helper itself returns as soon as the request + * is queued. + */ + +#include "sdkconfig.h" +#include "soc/soc_caps.h" + +#if defined(CONFIG_IDF_TARGET_ESP32C6) && SOC_WIFI_HE_SUPPORT + +#include "c6_twt.h" +#include "esp_log.h" +#include "esp_wifi.h" +#include "esp_wifi_he.h" /* esp_wifi_sta_itwt_setup / _teardown */ +#include "esp_wifi_he_types.h" +#include "esp_wifi_types.h" +#include "esp_event.h" +#include + +static const char *TAG = "c6_twt"; + +static bool s_active = false; +static uint8_t s_flow_id = 0; +static uint32_t s_wake_int = 0; +static uint32_t s_wake_dura = 0; + +#ifndef CONFIG_C6_TWT_WAKE_INTERVAL_US +#define CONFIG_C6_TWT_WAKE_INTERVAL_US 10000 /* 100 fps default cadence */ +#endif + +#ifndef CONFIG_C6_TWT_MIN_WAKE_DURA_US +#define CONFIG_C6_TWT_MIN_WAKE_DURA_US 512 /* enough to capture 1 CSI frame */ +#endif + +/* WIFI_EVENT_ITWT_SETUP handler — logs accept/reject. */ +static void on_itwt_event(void *arg, esp_event_base_t base, + int32_t event_id, void *event_data) +{ + (void)arg; + (void)base; + (void)event_data; + switch (event_id) { + case WIFI_EVENT_ITWT_SETUP: + ESP_LOGI(TAG, "iTWT setup event received from AP (flow_id captured)"); + s_active = true; + break; + case WIFI_EVENT_ITWT_TEARDOWN: + ESP_LOGI(TAG, "iTWT teardown event received"); + s_active = false; + break; + case WIFI_EVENT_ITWT_SUSPEND: + ESP_LOGI(TAG, "iTWT suspended by AP"); + break; + default: + break; + } +} + +static bool s_handler_installed = false; + +static void install_event_handler_once(void) +{ + if (s_handler_installed) return; + esp_err_t e = esp_event_handler_instance_register( + WIFI_EVENT, ESP_EVENT_ANY_ID, on_itwt_event, NULL, NULL); + if (e == ESP_OK) { + s_handler_installed = true; + } else { + ESP_LOGW(TAG, "Could not install iTWT event handler: %s", + esp_err_to_name(e)); + } +} + +esp_err_t c6_twt_setup(uint32_t wake_interval_us, uint32_t min_wake_dura_us) +{ + install_event_handler_once(); + + s_wake_int = wake_interval_us; + s_wake_dura = min_wake_dura_us < 256 ? 256 : min_wake_dura_us; + + wifi_itwt_setup_config_t cfg = {0}; + cfg.setup_cmd = TWT_REQUEST; + cfg.flow_id = s_flow_id; + cfg.twt_id = 0; + cfg.flow_type = 1; /* unannounced */ + cfg.min_wake_dura = (uint8_t)((s_wake_dura + 255) / 256); /* 256 µs units */ + cfg.wake_duration_unit = 0; /* 0 = 256 µs, 1 = 1024 µs */ + cfg.wake_invl_expn = 10; /* mantissa * 2^10 ≈ 1024 µs base */ + /* mantissa = wake_interval_us / 1024, clamped to uint16 */ + uint32_t mant = wake_interval_us >> 10; + if (mant == 0) mant = 1; + if (mant > 0xFFFF) mant = 0xFFFF; + cfg.wake_invl_mant = (uint16_t)mant; + cfg.trigger = 0; /* non-triggered: STA wakes on its own */ + + esp_err_t ret = esp_wifi_sta_itwt_setup(&cfg); + if (ret == ESP_OK) { + ESP_LOGI(TAG, "iTWT setup queued: wake_interval=%lu µs (mant=%u expn=10), " + "min_wake_dura=%u (%lu µs)", + (unsigned long)wake_interval_us, (unsigned)mant, + cfg.min_wake_dura, (unsigned long)s_wake_dura); + return ESP_OK; + } + /* Treat AP-rejection / not-supported / wrong-AP-mode as graceful — log + * and continue. ESP_ERR_INVALID_ARG is included here because empirically + * (live capture on ruv.net 2026-05-22) the ESP-IDF v5.4 driver returns + * INVALID_ARG when the associated AP advertises TWT Responder=0 — the + * call validates against the AP's HE capability bitmap, not just the + * struct fields. */ + if (ret == ESP_ERR_NOT_SUPPORTED || ret == ESP_ERR_WIFI_NOT_CONNECT || + ret == ESP_ERR_INVALID_STATE || ret == ESP_ERR_INVALID_ARG) { + ESP_LOGW(TAG, "iTWT not available (%s) - AP likely not 11ax/iTWT capable," + " falling back to opportunistic CSI", + esp_err_to_name(ret)); + return ESP_OK; + } + ESP_LOGE(TAG, "iTWT setup failed: %s", esp_err_to_name(ret)); + return ret; +} + +esp_err_t c6_twt_setup_default(void) +{ + return c6_twt_setup(CONFIG_C6_TWT_WAKE_INTERVAL_US, + CONFIG_C6_TWT_MIN_WAKE_DURA_US); +} + +void c6_twt_teardown(void) +{ + if (!s_active) return; + /* IDF v5.4 signature: esp_err_t esp_wifi_sta_itwt_teardown(int flow_id) */ + esp_err_t ret = esp_wifi_sta_itwt_teardown((int)s_flow_id); + if (ret == ESP_OK) { + ESP_LOGI(TAG, "iTWT teardown sent (flow_id=%u)", s_flow_id); + } else { + ESP_LOGW(TAG, "iTWT teardown failed: %s", esp_err_to_name(ret)); + } + s_active = false; +} + +bool c6_twt_is_active(void) +{ + return s_active; +} + +#endif /* CONFIG_IDF_TARGET_ESP32C6 && SOC_WIFI_HE_SUPPORT */ diff --git a/firmware/esp32-csi-node/main/c6_twt.h b/firmware/esp32-csi-node/main/c6_twt.h new file mode 100644 index 00000000..35b84823 --- /dev/null +++ b/firmware/esp32-csi-node/main/c6_twt.h @@ -0,0 +1,75 @@ +/** + * @file c6_twt.h + * @brief ESP32-C6 TWT (Target Wake Time) helper — ADR-110 Phase 3. + * + * Wraps esp_wifi_sta_itwt_setup() to negotiate a deterministic wake slot + * with the AP, replacing today's opportunistic CSI capture cadence with + * a scheduler-bounded one. + * + * Only built when CONFIG_IDF_TARGET_ESP32C6 is set — the S3 radio is + * 802.11n only and cannot speak iTWT. + * + * Usage from main.c (after WiFi STA is connected): + * c6_twt_setup_default(); // honors CONFIG_C6_TWT_WAKE_INTERVAL_US + * + * Graceful failure: if the AP rejects (no 11ax support, doesn't allow + * iTWT, or returns a NACK), the helper logs and returns ESP_OK — the + * device keeps doing opportunistic CSI just like the S3. + */ + +#pragma once + +#ifdef __cplusplus +extern "C" { +#endif + +#include "soc/soc_caps.h" + +#if defined(CONFIG_IDF_TARGET_ESP32C6) && SOC_WIFI_HE_SUPPORT + +#include "esp_err.h" +#include +#include + +/** + * Set up an individual TWT agreement using the Kconfig defaults + * (CONFIG_C6_TWT_WAKE_INTERVAL_US, CONFIG_C6_TWT_MIN_WAKE_DURA_US). + * + * @return ESP_OK whether or not the AP accepted — the helper never + * propagates a TWT NACK as an error to the caller. + */ +esp_err_t c6_twt_setup_default(void); + +/** + * Set up an individual TWT agreement with explicit parameters. + * + * @param wake_interval_us Period between wake events. + * @param min_wake_dura_us Minimum awake duration per wake (≥256 µs). + * @return ESP_OK on success or graceful NACK; ESP_FAIL on local error. + */ +esp_err_t c6_twt_setup(uint32_t wake_interval_us, uint32_t min_wake_dura_us); + +/** + * Tear down any active TWT agreement. Safe to call when none is active. + * Should be invoked on WIFI_EVENT_STA_DISCONNECTED so the AP scheduler + * doesn't keep a dead slot reserved. + */ +void c6_twt_teardown(void); + +/** + * Returns true if a TWT agreement is currently active. + */ +bool c6_twt_is_active(void); + +#else /* not C6 with iTWT support — provide stubs so call sites compile */ + +static inline esp_err_t c6_twt_setup_default(void) { return ESP_OK; } +static inline esp_err_t c6_twt_setup(uint32_t a, uint32_t b) { (void)a; (void)b; return ESP_OK; } +static inline void c6_twt_teardown(void) { } +static inline bool c6_twt_is_active(void) { return false; } + +#endif /* CONFIG_IDF_TARGET_ESP32C6 && SOC_WIFI_HE_SUPPORT */ + +#ifdef __cplusplus +} +#endif diff --git a/firmware/esp32-csi-node/main/csi_collector.c b/firmware/esp32-csi-node/main/csi_collector.c index 3c59de86..484b40cc 100644 --- a/firmware/esp32-csi-node/main/csi_collector.c +++ b/firmware/esp32-csi-node/main/csi_collector.c @@ -15,6 +15,8 @@ #include "nvs_config.h" #include "stream_sender.h" #include "edge_processing.h" +#include "c6_timesync.h" /* ADR-110: 802.15.4 epoch for cross-node alignment */ +#include "c6_sync_espnow.h" /* ADR-110 §A0.11: mesh-aligned epoch for sync packet */ #include #include "esp_log.h" @@ -173,9 +175,64 @@ size_t csi_serialize_frame(const wifi_csi_info_t *info, uint8_t *buf, size_t buf /* Noise floor (i8) */ buf[17] = (uint8_t)(int8_t)info->rx_ctrl.noise_floor; - /* Reserved */ + /* ADR-110: PPDU type (byte 18) + bandwidth/flags (byte 19). + * Previously reserved-zero, now optionally populated when CONFIG_CSI_FRAME_HE_TAGGING. + * Readers that don't know about the extension see zeros — backward compatible. + * + * The struct that backs info->rx_ctrl is target-conditional in IDF v5.4 + * (esp_wifi/include/local/esp_wifi_types_native.h): + * + * CONFIG_SOC_WIFI_HE_SUPPORT=y (C6/C5) → esp_wifi_rxctrl_t with cur_bb_format, second + * otherwise (S3 etc) → legacy struct with sig_mode, cwb, stbc + * + * Byte-18 PPDU type encoding stays the same across targets: + * 0=HT/legacy bucket, 1=HE-SU, 2=HE-MU, 3=HE-TB, 0xFF=unknown + */ +#ifdef CONFIG_CSI_FRAME_HE_TAGGING + uint8_t ppdu_type = 0xFF; + uint8_t flags = 0; +#if CONFIG_SOC_WIFI_HE_SUPPORT + /* HE-capable chips: read cur_bb_format (0=11b, 1=11g, 2=HT, 3=VHT, 4=HE-SU, + * 5=HE-MU, 6=HE-ERSU, 7=HE-TB) and 'second' (40 MHz secondary chan offset). */ + switch (info->rx_ctrl.cur_bb_format) { + case 0: + case 1: + case 2: ppdu_type = 0; break; /* 11b/g/a/HT bucket */ + case 3: ppdu_type = 0; break; /* VHT — rare on 2.4 GHz, HT bucket */ + case 4: ppdu_type = 1; break; /* HE-SU */ + case 5: ppdu_type = 2; break; /* HE-MU */ + case 6: ppdu_type = 1; break; /* HE-ER-SU collapses to HE-SU */ + case 7: ppdu_type = 3; break; /* HE-TB */ + default: ppdu_type = 0xFF; break; + } + if (info->rx_ctrl.second != 0) flags |= 0x1; /* bw 40 MHz */ +#else + /* Pre-HE chips (S3 etc): use legacy sig_mode + cwb + stbc fields. */ + switch (info->rx_ctrl.sig_mode) { + case 0: ppdu_type = 0; break; /* non-HT (11b/g) */ + case 1: ppdu_type = 0; break; /* HT (11n) */ + case 3: ppdu_type = 0; break; /* VHT — bucket as HT for storage */ + default: ppdu_type = 0xFF; break; + } + if (info->rx_ctrl.cwb) flags |= 0x1; /* bw 40 MHz */ + if (info->rx_ctrl.stbc) flags |= (1 << 2); /* STBC */ +#endif /* CONFIG_SOC_WIFI_HE_SUPPORT */ + /* ADR-018 byte 19 bit 4 = "cross-node sync valid". Two transports can + * set it: the original 802.15.4 c6_timesync (broken in IDF v5.4 — D1) + * and the ESP-NOW workaround c6_sync_espnow (measured working in §A0.7- + * §A0.10). OR them together so frames signal sync from whichever + * transport is alive on this node. Host can pair against the sync + * packet (§A0.12) once it sees this bit. */ +#if defined(CONFIG_IDF_TARGET_ESP32C6) && defined(CONFIG_C6_TIMESYNC_ENABLE) + if (c6_timesync_is_valid()) flags |= (1 << 4); /* 15.4 sync valid */ +#endif + if (c6_sync_espnow_is_valid()) flags |= (1 << 4); /* ESP-NOW sync valid (D1 workaround) */ + buf[18] = ppdu_type; + buf[19] = flags; +#else buf[18] = 0; buf[19] = 0; +#endif /* I/Q data */ memcpy(&buf[CSI_HEADER_SIZE], info->buf, iq_len); @@ -245,6 +302,56 @@ static void wifi_csi_callback(void *ctx, wifi_csi_info_t *info) edge_enqueue_csi((const uint8_t *)info->buf, (uint16_t)info->len, (int8_t)info->rx_ctrl.rssi, info->rx_ctrl.channel); } + + /* ADR-110 §A0.11/§A0.12 — Emit a sync-packet every N CSI frames so the + * host aggregator can pair node-local sequence numbers with the mesh-aligned + * epoch coming out of c6_sync_espnow_get_epoch_us(). Backwards-compatible + * with the ADR-018 frame format: new packet uses a distinct magic so the + * existing CSI parser can dispatch by first 4 bytes. + * + * Cadence is operator-tunable via CONFIG_C6_SYNC_EVERY_N_FRAMES (default 20). + * At 10 Hz observed CSI rate that's ~2 s between sync packets; raise to 50 + * for ~5 s (less overhead, slower convergence), lower to 5 for ~0.5 s + * (heavier wire, tighter ADR-029/030 multistatic alignment window). */ + { +#ifndef CONFIG_C6_SYNC_EVERY_N_FRAMES +#define CONFIG_C6_SYNC_EVERY_N_FRAMES 20 +#endif + if ((s_cb_count % CONFIG_C6_SYNC_EVERY_N_FRAMES) == 0) { + uint8_t sync[32]; + uint32_t sync_magic = 0xC511A110u; /* CSI-ADR-110 sync packet */ + uint64_t local_us = (uint64_t)esp_timer_get_time(); + uint64_t epoch_us = c6_sync_espnow_get_epoch_us(); + int64_t off_smooth = c6_sync_espnow_get_offset_us_smoothed(); + uint8_t flags = 0; + if (c6_sync_espnow_is_leader()) flags |= 0x01; + if (c6_sync_espnow_is_valid()) flags |= 0x02; + if (off_smooth != 0) flags |= 0x04; + + memcpy(&sync[0], &sync_magic, 4); + sync[4] = s_node_id; + sync[5] = 0x01; /* protocol version */ + sync[6] = flags; + sync[7] = 0; /* reserved */ + memcpy(&sync[8], &local_us, 8); + memcpy(&sync[16], &epoch_us, 8); + memcpy(&sync[24], &s_sequence, 4); /* high-water seq for pairing */ + uint32_t zero32 = 0; + memcpy(&sync[28], &zero32, 4); /* reserved (room for leader_id low32) */ + int sr = stream_sender_send(sync, sizeof(sync)); + static uint32_t s_sync_count = 0; + s_sync_count++; + if (s_sync_count <= 3 || (s_sync_count % 60) == 0) { + ESP_LOGI(TAG, "sync-pkt #%lu (sr=%d) node=%u flags=0x%02x " + "local_us=%llu epoch_us=%llu seq=%lu", + (unsigned long)s_sync_count, sr, + (unsigned)s_node_id, (unsigned)flags, + (unsigned long long)local_us, + (unsigned long long)epoch_us, + (unsigned long)s_sequence); + } + } + } } /** diff --git a/firmware/esp32-csi-node/main/lp_core/CMakeLists.txt b/firmware/esp32-csi-node/main/lp_core/CMakeLists.txt new file mode 100644 index 00000000..6e799242 --- /dev/null +++ b/firmware/esp32-csi-node/main/lp_core/CMakeLists.txt @@ -0,0 +1,9 @@ +# LP-core motion-gate program — ADR-110 Phase 5 (full). +# +# Built only when CONFIG_C6_LP_CORE_ENABLE=y (gated in the parent CMakeLists). +# The IDF build system invokes this via `ulp_embed_binary()` from +# main/CMakeLists.txt. + +# This file intentionally has no idf_component_register — the LP-core sources +# are compiled with the RISC-V LP toolchain via `ulp_embed_binary` and then +# linked into the HP image as a binary blob, not as a normal component. diff --git a/firmware/esp32-csi-node/main/lp_core/main.c b/firmware/esp32-csi-node/main/lp_core/main.c new file mode 100644 index 00000000..4150812c --- /dev/null +++ b/firmware/esp32-csi-node/main/lp_core/main.c @@ -0,0 +1,75 @@ +/** + * @file lp_core/main.c + * @brief LP RISC-V coprocessor motion-gate — ADR-110 Phase 5 (full). + * + * Polls a single LP-IO GPIO at LP_TIMER cadence (default 10 ms / 100 Hz), + * debounces N consecutive samples, and wakes the HP core when a confirmed + * transition matches the configured active-edge polarity. Counter + + * last-level are exported as shared symbols so the HP side can inspect + * them on wake. + * + * Shared symbols (HP-visible as `ulp_` after `ulp_embed_binary`): + * - wake_gpio_num (input) : LP-IO index 0..7 on ESP32-C6 + * - wake_active_high (input) : 1 = wake on rising stable, 0 = falling + * - debounce_samples (input) : consecutive matches required, default 3 + * - motion_count (output) : monotonic wake-trigger counter + * - last_gpio_level (output) : level latched at the most recent wake + * - poll_count (output) : total LP-timer ticks observed (sanity) + * + * Defaults are written by HP via the `ulp_*` symbols before `ulp_lp_core_run()`, + * so the program is parameterised at boot without recompiling the LP binary. + */ + +#include +#include +#include "ulp_lp_core.h" +#include "ulp_lp_core_utils.h" +#include "ulp_lp_core_gpio.h" + +/* --- Shared (HP/LP) state --- */ +volatile uint32_t wake_gpio_num = 4; /* LP-IO 4 by default */ +volatile uint32_t wake_active_high = 1; /* rising edge */ +volatile uint32_t debounce_samples = 3; +volatile uint32_t motion_count = 0; +volatile uint32_t last_gpio_level = 0; +volatile uint32_t poll_count = 0; + +/* --- Local state (persists across LP-timer wake cycles via .data) --- */ +static uint32_t stable_run = 0; +static uint32_t prev_level = 0; + +int main(void) +{ + poll_count++; + + /* LP-IO read returns 0/1 directly. The Kconfig-selected GPIO index maps + * 1:1 to LP_IO on C6 for indices 0..7. */ + uint32_t level = (uint32_t)ulp_lp_core_gpio_get_level((lp_io_num_t)wake_gpio_num); + + if (level == prev_level) { + if (stable_run < 0xFFFFu) stable_run++; + } else { + stable_run = 1; + prev_level = level; + } + + /* Trigger when level matches the configured active polarity AND has been + * stable for `debounce_samples` consecutive reads. After firing, hold off + * until level returns to the inactive state to avoid re-triggering on + * the same continuous edge. */ + static uint32_t armed = 1; + uint32_t want = wake_active_high ? 1 : 0; + + if (armed && level == want && stable_run >= debounce_samples) { + motion_count++; + last_gpio_level = level; + armed = 0; + ulp_lp_core_wakeup_main_processor(); + } else if (!armed && level != want && stable_run >= debounce_samples) { + /* Re-arm once the line has cleanly returned to the inactive state. */ + armed = 1; + } + + /* ulp_lp_core_halt() is called automatically when main returns. */ + return 0; +} diff --git a/firmware/esp32-csi-node/main/main.c b/firmware/esp32-csi-node/main/main.c index 0f6662f9..ef576890 100644 --- a/firmware/esp32-csi-node/main/main.c +++ b/firmware/esp32-csi-node/main/main.c @@ -33,6 +33,11 @@ #include "swarm_bridge.h" #include "rv_radio_ops.h" /* ADR-081 Layer 1 — Radio Abstraction Layer. */ #include "adaptive_controller.h" /* ADR-081 Layer 2 — Adaptive controller. */ +#include "c6_twt.h" /* ADR-110: TWT (no-op stub on S3) */ +#include "c6_timesync.h" /* ADR-110: 802.15.4 mesh time-sync (no-op on S3) */ +#include "c6_lp_core.h" /* ADR-110: LP-core hibernation (no-op on S3) */ +#include "c6_sync_espnow.h" /* ADR-110 D1 workaround: ESP-NOW sync */ +#include "c6_softap_he.h" /* ADR-110 B1/B2: HE/TWT soft-AP (no-op when disabled) */ #ifdef CONFIG_CSI_MOCK_ENABLED #include "mock_csi.h" #endif @@ -112,6 +117,17 @@ static void wifi_init_sta(void) ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA)); ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_STA, &wifi_config)); + +#if defined(CONFIG_IDF_TARGET_ESP32C6) && defined(CONFIG_C6_SOFTAP_HE_ENABLE) + /* ADR-110 B1/B2 cheap-unblock: bring up a soft-AP that advertises HE + + * TWT Responder=1 so a second C6 board can negotiate iTWT against + * this node. c6_softap_he_start() switches the mode to AP+STA. */ + uint8_t softap_chan = 0; + if (c6_softap_he_start(&softap_chan) == ESP_OK) { + ESP_LOGI(TAG, "C6 soft-AP HE armed on channel %u (ADR-110 B1/B2)", softap_chan); + } +#endif + ESP_ERROR_CHECK(esp_wifi_start()); ESP_LOGI(TAG, "WiFi STA initialized, connecting to SSID: %s", g_nvs_config.wifi_ssid); @@ -147,13 +163,27 @@ void app_main(void) csi_collector_set_node_id(g_nvs_config.node_id); const esp_app_desc_t *app_desc = esp_app_get_description(); - ESP_LOGI(TAG, "ESP32-S3 CSI Node (ADR-018) — v%s — Node ID: %d", - app_desc->version, g_nvs_config.node_id); +#if defined(CONFIG_IDF_TARGET_ESP32C6) + const char *target_name = "ESP32-C6"; +#elif defined(CONFIG_IDF_TARGET_ESP32S3) + const char *target_name = "ESP32-S3"; +#else + const char *target_name = "ESP32"; +#endif + ESP_LOGI(TAG, "%s CSI Node (ADR-018 / ADR-110) — v%s — Node ID: %d", + target_name, app_desc->version, g_nvs_config.node_id); - /* Turn off onboard WS2812 LED on GPIO 38 */ + /* Turn off onboard WS2812 LED. + * S3 dev boards put the LED on GPIO 38; C6 dev boards on GPIO 8. + * On C6, GPIO 38 doesn't exist (only 0-30) — gate the init by target. */ +#if defined(CONFIG_IDF_TARGET_ESP32C6) + const int led_gpio = 8; +#else + const int led_gpio = 38; +#endif led_strip_handle_t led_strip; led_strip_config_t strip_config = { - .strip_gpio_num = 38, + .strip_gpio_num = led_gpio, .max_leds = 1, .led_model = LED_MODEL_WS2812, .color_component_format = LED_STRIP_COLOR_COMPONENT_FMT_GRB, @@ -167,6 +197,27 @@ void app_main(void) led_strip_clear(led_strip); } + /* ADR-110 P4: 802.15.4 mesh time-sync (C6 only). + * Initialized BEFORE WiFi so it's available even when WiFi STA can't + * connect — the radios are physically independent on the C6. + * No-op on S3 (the helper compiles to an empty inline stub). */ +#if defined(CONFIG_IDF_TARGET_ESP32C6) && defined(CONFIG_C6_TIMESYNC_ENABLE) + esp_err_t ts_ret = c6_timesync_init(CONFIG_C6_TIMESYNC_CHANNEL); + if (ts_ret != ESP_OK) { + ESP_LOGW(TAG, "c6_timesync_init failed: %s (continuing without 15.4 sync)", + esp_err_to_name(ts_ret)); + } +#endif + + /* ADR-110 P5: Optionally arm LP-core wake-on-motion (C6 only, opt-in). + * Default off — only nodes flashed for battery-powered seed duty enable + * this in menuconfig. */ +#if defined(CONFIG_IDF_TARGET_ESP32C6) && defined(CONFIG_C6_LP_CORE_ENABLE) + if (c6_lp_core_was_motion_wake()) { + ESP_LOGI(TAG, "boot cause: LP-core motion wake (running CSI burst)"); + } +#endif + /* Initialize WiFi STA (skip entirely under QEMU mock — no RF hardware) */ #ifndef CONFIG_CSI_MOCK_SKIP_WIFI_CONNECT wifi_init_sta(); @@ -208,6 +259,26 @@ void app_main(void) } #endif + /* ADR-110 P3: Request TWT from the AP for deterministic CSI cadence. + * No-op on S3 (the helper compiles to an empty inline stub). On C6 + * the AP may NACK — the helper logs and falls back to opportunistic. + * Called only after WiFi STA connect (wifi_init_sta blocks until then). */ +#if defined(CONFIG_IDF_TARGET_ESP32C6) && defined(CONFIG_C6_TWT_ENABLE) + c6_twt_setup_default(); +#endif + + /* ADR-110 D1 workaround: ESP-NOW cross-node sync. Initialized after + * WiFi STA connects (ESP-NOW needs the WiFi driver up). Works on + * both S3 and C6 — replaces the broken 802.15.4 RX path in c6_timesync. + * Skip on QEMU mock (no real WiFi → no ESP-NOW). */ +#ifndef CONFIG_CSI_MOCK_SKIP_WIFI_CONNECT + esp_err_t espnow_ret = c6_sync_espnow_init(); + if (espnow_ret != ESP_OK) { + ESP_LOGW(TAG, "c6_sync_espnow_init failed: %s (continuing without ESP-NOW sync)", + esp_err_to_name(espnow_ret)); + } +#endif + /* ADR-039: Initialize edge processing pipeline. */ edge_config_t edge_cfg = { .tier = g_nvs_config.edge_tier, diff --git a/firmware/esp32-csi-node/main/swarm_bridge.c b/firmware/esp32-csi-node/main/swarm_bridge.c index b6b485b2..3c5a19d9 100644 --- a/firmware/esp32-csi-node/main/swarm_bridge.c +++ b/firmware/esp32-csi-node/main/swarm_bridge.c @@ -230,9 +230,13 @@ static void swarm_task(void *arg) ESP_LOGI(TAG, "Bearer token configured for Seed auth"); } - /* Get firmware version string. */ + /* Firmware version + IP captured locally so logs name the build; both + * intentionally unused in the JSON payloads — the seed extracts them + * from the register/heartbeat IDs. Keep as side-effect probes. */ const esp_app_desc_t *app = esp_app_get_description(); - const char *fw_ver = app ? app->version : "unknown"; + if (app) { + ESP_LOGI(TAG, "swarm bridge fw=%s", app->version); + } /* Get local IP. */ char ip_str[16]; @@ -278,15 +282,12 @@ static void swarm_task(void *arg) xSemaphoreGive(s_mutex); uint32_t uptime_s = (uint32_t)(esp_timer_get_time() / 1000000ULL); - uint32_t free_heap = esp_get_free_heap_size(); uint32_t ts = (uint32_t)(esp_timer_get_time() / 1000ULL); /* ---- Heartbeat ---- */ if ((now - last_heartbeat) >= pdMS_TO_TICKS(s_cfg.heartbeat_sec * 1000U)) { last_heartbeat = now; - bool presence = vit_valid && (vit.flags & 0x01); - /* Heartbeat ID: node_id * 1000000 + 100000 + ts_sec */ uint32_t hb_id = (uint32_t)s_node_id * 1000000U + 100000U + (uptime_s % 100000U); char json[SWARM_JSON_BUF]; diff --git a/firmware/esp32-csi-node/release_bins/c6-adr110/SHA256SUMS.txt b/firmware/esp32-csi-node/release_bins/c6-adr110/SHA256SUMS.txt new file mode 100644 index 00000000..e80d3351 --- /dev/null +++ b/firmware/esp32-csi-node/release_bins/c6-adr110/SHA256SUMS.txt @@ -0,0 +1,4 @@ +889715e9d698ad78f9978ad8b93b6af24a726b0494247201c8f0d920d9fc80ca *firmware/esp32-csi-node/release_bins/c6-adr110/bootloader.bin +d8539e47c6f10a3344679118619e3fe01cfd66eb560ea8883268ca7c9a12efa4 *firmware/esp32-csi-node/release_bins/c6-adr110/esp32-csi-node.bin +7d2c7ac4888bfd75cd5f56e8d61f69595121183afc81556c876732fd3782c62f *firmware/esp32-csi-node/release_bins/c6-adr110/ota_data_initial.bin +4c2cc4ffd52641e23b779bd57b3908014083ac3c1aab395756478c89e70d81f0 *firmware/esp32-csi-node/release_bins/c6-adr110/partition-table.bin diff --git a/firmware/esp32-csi-node/release_bins/c6-adr110/bootloader.bin b/firmware/esp32-csi-node/release_bins/c6-adr110/bootloader.bin new file mode 100644 index 00000000..eede7dfd Binary files /dev/null and b/firmware/esp32-csi-node/release_bins/c6-adr110/bootloader.bin differ diff --git a/firmware/esp32-csi-node/release_bins/c6-adr110/esp32-csi-node.bin b/firmware/esp32-csi-node/release_bins/c6-adr110/esp32-csi-node.bin new file mode 100644 index 00000000..e940982e Binary files /dev/null and b/firmware/esp32-csi-node/release_bins/c6-adr110/esp32-csi-node.bin differ diff --git a/firmware/esp32-csi-node/release_bins/c6-adr110/ota_data_initial.bin b/firmware/esp32-csi-node/release_bins/c6-adr110/ota_data_initial.bin new file mode 100644 index 00000000..b4033a70 --- /dev/null +++ b/firmware/esp32-csi-node/release_bins/c6-adr110/ota_data_initial.bin @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/firmware/esp32-csi-node/release_bins/c6-adr110/partition-table.bin b/firmware/esp32-csi-node/release_bins/c6-adr110/partition-table.bin new file mode 100644 index 00000000..ad0d4b78 Binary files /dev/null and b/firmware/esp32-csi-node/release_bins/c6-adr110/partition-table.bin differ diff --git a/firmware/esp32-csi-node/release_bins/s3-adr110/SHA256SUMS.txt b/firmware/esp32-csi-node/release_bins/s3-adr110/SHA256SUMS.txt new file mode 100644 index 00000000..90bbcfe4 --- /dev/null +++ b/firmware/esp32-csi-node/release_bins/s3-adr110/SHA256SUMS.txt @@ -0,0 +1,3 @@ +3c4905dd202ccabf4230cbabcc9320f250a60b1a7254eff7424780201bcb2072 *firmware/esp32-csi-node/release_bins/s3-adr110/bootloader.bin +7a8bf9582c9031fed32f1ada44f5c41dd99bd07fadff8e5c86e07aa0f343e847 *firmware/esp32-csi-node/release_bins/s3-adr110/esp32-csi-node.bin +67222c257c0477501fd4002275638dc4262b34eb68235b8289fb1337054d322b *firmware/esp32-csi-node/release_bins/s3-adr110/partition-table.bin diff --git a/firmware/esp32-csi-node/release_bins/s3-adr110/bootloader.bin b/firmware/esp32-csi-node/release_bins/s3-adr110/bootloader.bin new file mode 100644 index 00000000..9065d3ec Binary files /dev/null and b/firmware/esp32-csi-node/release_bins/s3-adr110/bootloader.bin differ diff --git a/firmware/esp32-csi-node/release_bins/s3-adr110/esp32-csi-node.bin b/firmware/esp32-csi-node/release_bins/s3-adr110/esp32-csi-node.bin new file mode 100644 index 00000000..fb877238 Binary files /dev/null and b/firmware/esp32-csi-node/release_bins/s3-adr110/esp32-csi-node.bin differ diff --git a/firmware/esp32-csi-node/release_bins/s3-adr110/partition-table.bin b/firmware/esp32-csi-node/release_bins/s3-adr110/partition-table.bin new file mode 100644 index 00000000..d6a05b65 Binary files /dev/null and b/firmware/esp32-csi-node/release_bins/s3-adr110/partition-table.bin differ diff --git a/firmware/esp32-csi-node/release_bins/s3-fair-adr110/SHA256SUMS.txt b/firmware/esp32-csi-node/release_bins/s3-fair-adr110/SHA256SUMS.txt new file mode 100644 index 00000000..93b8e2c2 --- /dev/null +++ b/firmware/esp32-csi-node/release_bins/s3-fair-adr110/SHA256SUMS.txt @@ -0,0 +1,3 @@ +a53b2c018bfd2e367525bedf6dc3fda6bc9639d1a9cc9e8bf9eb3e9fee379ed2 *firmware/esp32-csi-node/release_bins/s3-fair-adr110/bootloader.bin +53eb50ea890a8388b8a39285a3dd34c53651535c689a3b42f136a5ed7f424145 *firmware/esp32-csi-node/release_bins/s3-fair-adr110/esp32-csi-node.bin +4c2cc4ffd52641e23b779bd57b3908014083ac3c1aab395756478c89e70d81f0 *firmware/esp32-csi-node/release_bins/s3-fair-adr110/partition-table.bin diff --git a/firmware/esp32-csi-node/release_bins/s3-fair-adr110/bootloader.bin b/firmware/esp32-csi-node/release_bins/s3-fair-adr110/bootloader.bin new file mode 100644 index 00000000..56097fd5 Binary files /dev/null and b/firmware/esp32-csi-node/release_bins/s3-fair-adr110/bootloader.bin differ diff --git a/firmware/esp32-csi-node/release_bins/s3-fair-adr110/esp32-csi-node.bin b/firmware/esp32-csi-node/release_bins/s3-fair-adr110/esp32-csi-node.bin new file mode 100644 index 00000000..d2fa45c9 Binary files /dev/null and b/firmware/esp32-csi-node/release_bins/s3-fair-adr110/esp32-csi-node.bin differ diff --git a/firmware/esp32-csi-node/release_bins/s3-fair-adr110/partition-table.bin b/firmware/esp32-csi-node/release_bins/s3-fair-adr110/partition-table.bin new file mode 100644 index 00000000..ad0d4b78 Binary files /dev/null and b/firmware/esp32-csi-node/release_bins/s3-fair-adr110/partition-table.bin differ diff --git a/firmware/esp32-csi-node/sdkconfig.defaults.esp32c6 b/firmware/esp32-csi-node/sdkconfig.defaults.esp32c6 new file mode 100644 index 00000000..b6bda708 --- /dev/null +++ b/firmware/esp32-csi-node/sdkconfig.defaults.esp32c6 @@ -0,0 +1,75 @@ +# ESP32-C6 CSI Node — Target overlay (ADR-110) +# +# Auto-applied by ESP-IDF when CONFIG_IDF_TARGET=esp32c6. +# Layered on top of sdkconfig.defaults — only the differences live here. +# +# Build: +# idf.py set-target esp32c6 +# idf.py build +# +# Hardware: stock ESP32-C6 dev board with 4 MB or 8 MB embedded flash. +# Confirmed on COM6: ESP32-C6 (QFN40) rev v0.2, 8 MB flash, 320 KiB SRAM. + +# ── Target ── +CONFIG_IDF_TARGET="esp32c6" + +# ── Flash & partitions (4 MB — common across C6 dev boards) ── +CONFIG_PARTITION_TABLE_CUSTOM=y +CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions_4mb.csv" +CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y +CONFIG_ESPTOOLPY_FLASHSIZE="4MB" + +# ── CSI (required) ── +CONFIG_ESP_WIFI_CSI_ENABLED=y + +# ── ADR-110 P2 & P3: Wi-Fi 6 / iTWT ── +# IDF v5.4 exposes neither ESP_WIFI_11AX_SUPPORT nor ESP_WIFI_ITWT_SUPPORT as +# user Kconfig — they're SoC capabilities (SOC_WIFI_HE_SUPPORT) auto-enabled +# on chips that have HE support (C6/C5). WPA3 is opt-in: +CONFIG_ESP_WIFI_ENABLE_WPA3_SAE=y + +# ── ADR-110 P4: 802.15.4 (raw, no OpenThread) ── +# IEEE 802.15.4 PHY enabled for our raw beacon protocol in c6_timesync.c. +# OpenThread is DISABLED — empirically (ch15 + ch26 tested with the same +# negative result), enabling OpenThread MTD caused our weak-symbol overrides +# of esp_ieee802154_receive_done/transmit_done to never fire, breaking +# leader election. Raw 802.15.4 mode is what we actually need: a private +# mesh protocol on a private channel, no Thread network attach. +CONFIG_IEEE802154_ENABLED=y +CONFIG_OPENTHREAD_ENABLED=n + +# ADR-110 P4: 802.15.4 channel override. +# Default Kconfig value is 15 (2425 MHz). On the 2.4 GHz radio that's +# directly under WiFi channel 5 (2432 MHz). Channel 26 = 2480 MHz is on +# the WiFi guard band above channel 14, giving the 15.4 path room to RX +# without competing with WiFi traffic for radio time. +CONFIG_C6_TIMESYNC_CHANNEL=26 + +# ── ADR-110 P5: LP-core (deep-sleep coprocessor) ── +# Enable the LP RISC-V core so c6_lp_core.c can ship a wake-on-motion stub. +CONFIG_ULP_COPROC_ENABLED=y +CONFIG_ULP_COPROC_TYPE_LP_CORE=y +CONFIG_ULP_COPROC_RESERVE_MEM=8192 + +# ── No display, no WASM, no mmWave on the C6 research target ── +# Display (ADR-045) needs 8 MB + native USB-OTG framebuffer hooks. +# WASM3 (ADR-040) needs PSRAM for hot-loadable modules. +# mmWave (Seeed MR60BHA2 on COM4) is a separate board. +# CONFIG_DISPLAY_ENABLE is not set +# CONFIG_WASM_ENABLE is not set + +# ── Compiler ── +CONFIG_COMPILER_OPTIMIZATION_SIZE=y + +# ── Logging ── +CONFIG_BOOTLOADER_LOG_LEVEL_WARN=y +CONFIG_LOG_DEFAULT_LEVEL_INFO=y + +# ── lwIP / FreeRTOS — same as S3 path ── +CONFIG_LWIP_SO_RCVBUF=y +CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192 +CONFIG_FREERTOS_TIMER_TASK_STACK_DEPTH=8192 + +# ── Power: keep CPU at max 160 MHz (C6 ceiling) for DSP throughput ── +CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_160=y +CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ=160 diff --git a/firmware/esp32-csi-node/sdkconfig.defaults.s3-fair b/firmware/esp32-csi-node/sdkconfig.defaults.s3-fair new file mode 100644 index 00000000..5e7e883b --- /dev/null +++ b/firmware/esp32-csi-node/sdkconfig.defaults.s3-fair @@ -0,0 +1,28 @@ +# ADR-110 apples-to-apples S3 overlay for fair vs-C6 size comparison. +# Same target as production S3 but with the features that aren't on C6 disabled: +# - No AMOLED display (ADR-045 — C6 has no PSRAM for framebuffers) +# - No WASM3 (ADR-040 — same reason) +# - No mmWave fusion (separate board) +# This is NOT a production build — only used to answer "is C6 smaller than S3 +# once you strip the S3-only features?" +# +# Build: +# cp sdkconfig.defaults.s3-fair sdkconfig.defaults && idf.py set-target esp32s3 && idf.py build +# # Restore default: git checkout sdkconfig.defaults + +CONFIG_IDF_TARGET="esp32s3" +CONFIG_PARTITION_TABLE_CUSTOM=y +CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions_4mb.csv" +CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y +CONFIG_ESPTOOLPY_FLASHSIZE="4MB" +CONFIG_COMPILER_OPTIMIZATION_SIZE=y +CONFIG_ESP_WIFI_CSI_ENABLED=y +CONFIG_BOOTLOADER_LOG_LEVEL_WARN=y +CONFIG_LOG_DEFAULT_LEVEL_INFO=y +CONFIG_LWIP_SO_RCVBUF=y +CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192 +CONFIG_FREERTOS_TIMER_TASK_STACK_DEPTH=8192 + +# Disable display + WASM + mmWave for apples-to-apples vs C6. +# CONFIG_DISPLAY_ENABLE is not set +# CONFIG_WASM_ENABLE is not set diff --git a/firmware/esp32-csi-node/test/Makefile b/firmware/esp32-csi-node/test/Makefile index c14f0383..28ef8da9 100644 --- a/firmware/esp32-csi-node/test/Makefile +++ b/firmware/esp32-csi-node/test/Makefile @@ -20,6 +20,11 @@ # FUZZ_JOBS=4 # Parallel fuzzing jobs CC = clang +# ADR-110: -DCONFIG_CSI_FRAME_HE_TAGGING=1 enables the byte-18/19 HE path +# in csi_collector.c so the fuzzer exercises that code as well as the +# legacy zero-fill path. CONFIG_SOC_WIFI_HE_SUPPORT is left UNSET to +# exercise the legacy S3 branch (sig_mode/cwb/stbc). Add it to CFLAGS for +# a parallel HE-stub build if you want fuzz coverage of the C6 branch. CFLAGS = -fsanitize=fuzzer,address,undefined -g -O1 \ -Istubs -I../main \ -DCONFIG_CSI_NODE_ID=1 \ @@ -28,6 +33,7 @@ CFLAGS = -fsanitize=fuzzer,address,undefined -g -O1 \ -DCONFIG_CSI_TARGET_IP=\"192.168.1.1\" \ -DCONFIG_CSI_TARGET_PORT=5500 \ -DCONFIG_ESP_WIFI_CSI_ENABLED=1 \ + -DCONFIG_CSI_FRAME_HE_TAGGING=1 \ -Wno-unused-function STUBS_SRC = stubs/esp_stubs.c @@ -37,9 +43,22 @@ MAIN_DIR = ../main FUZZ_DURATION ?= 30 FUZZ_JOBS ?= 1 -.PHONY: all clean run_serialize run_edge run_nvs run_all +.PHONY: all clean run_serialize run_edge run_nvs run_all test_adr110 run_adr110 host_tests -all: fuzz_serialize fuzz_edge fuzz_nvs +all: fuzz_serialize fuzz_edge fuzz_nvs test_adr110 + +# --- ADR-110 encoding unit tests --- +# Host-side, no libFuzzer needed — plain C99 deterministic table tests +# for mac_to_eui64() and PPDU-type → ADR-018 byte 18 mapping. +# Builds with stock cc/gcc/clang — runs in CI on Ubuntu. +test_adr110: test_adr110_encoding.c + cc -std=c99 -Wall -Wextra -o $@ $< + +run_adr110: test_adr110 + ./test_adr110 + +host_tests: run_adr110 + @echo "ADR-110 host tests passed" # --- Serialize fuzzer --- # Tests csi_serialize_frame() with random wifi_csi_info_t inputs. @@ -75,5 +94,5 @@ run_nvs: fuzz_nvs run_all: run_serialize run_edge run_nvs clean: - rm -f fuzz_serialize fuzz_edge fuzz_nvs + rm -f fuzz_serialize fuzz_edge fuzz_nvs test_adr110 rm -rf corpus_serialize/ corpus_edge/ corpus_nvs/ diff --git a/firmware/esp32-csi-node/test/capture-3board-experiment.py b/firmware/esp32-csi-node/test/capture-3board-experiment.py new file mode 100644 index 00000000..cfe59808 --- /dev/null +++ b/firmware/esp32-csi-node/test/capture-3board-experiment.py @@ -0,0 +1,129 @@ +"""ADR-110 multi-board live capture — 802.15.4 sync + TWT + HE-LTF. + +Captures from up to 3 ESP32-C6 boards simultaneously, resets them +together so the leader election starts from a clean slate, then +records 35 s of serial output to per-port log files and prints +a summary of the time-sync state machine, TWT events, and CSI +metadata at the end. +""" +import serial +import threading +import time +import re +import sys +from pathlib import Path + +PORTS = ['COM6', 'COM9', 'COM12'] +DURATION_SECONDS = 35 +OUTPUT_DIR = Path(__file__).parent / 'witness-3board' +OUTPUT_DIR.mkdir(exist_ok=True) + + +def capture(port: str, results: dict): + """Reset and capture from one port for DURATION_SECONDS.""" + try: + ser = serial.Serial(port, 115200, timeout=1) + # Hard reset via DTR/RTS pulse. + ser.setDTR(False); ser.setRTS(True); time.sleep(0.05) + ser.setDTR(False); ser.setRTS(False) + ser.reset_input_buffer() + buf = bytearray() + start = time.time() + while time.time() - start < DURATION_SECONDS: + data = ser.read(4096) + if data: + buf.extend(data) + ser.close() + log_path = OUTPUT_DIR / f'{port}.log' + log_path.write_bytes(bytes(buf)) + text = bytes(buf).decode('utf-8', errors='replace') + results[port] = text + print(f'[{port}] {len(buf)} bytes captured -> {log_path}') + except Exception as e: + print(f'[{port}] ERROR: {e}') + results[port] = None + + +# Launch 3 capture threads — actual concurrent reset + capture. +results = {} +threads = [threading.Thread(target=capture, args=(p, results)) for p in PORTS] +for t in threads: + t.start() +for t in threads: + t.join() + + +# ── Analyze ──────────────────────────────────────────────────────────── + +def grep_pattern(text: str, pattern: str, n: int = 8): + rx = re.compile(pattern) + return [L.strip() for L in (text or '').split('\n') if rx.search(L)][:n] + + +print('\n' + '='*78) +print('ADR-110 multi-board capture summary') +print('='*78) + + +for port in PORTS: + text = results.get(port) + if not text: + print(f'\n--- {port}: NO DATA ---') + continue + print(f'\n--- {port} ---') + + # Boot banner + for L in grep_pattern(text, r'main: ESP32-C6.*Node ID', 2): + print(f' banner : {L}') + + # Time-sync init (802.15.4 path — known broken D1) + for L in grep_pattern(text, r'c6_ts:.*(init done|promot|stepping down|tx fail)', 4): + print(f' c6_ts : {L}') + + # ESP-NOW sync (D1 workaround, working path) + for L in grep_pattern(text, r'c6_espnow:.*(init done|promot|stepping down|tx#\d)', 6): + print(f' c6_espnow: {L}') + + # WiFi mode + connect status + for L in grep_pattern(text, r'(wifi:mode|wifi:state|Retrying WiFi|got ip|Connected to WiFi)', 6): + print(f' wifi : {L}') + + # TWT events + for L in grep_pattern(text, r'c6_twt|itwt|TWT', 5): + print(f' twt : {L}') + + # CSI callbacks + for L in grep_pattern(text, r'CSI cb #\d+.*len=', 5): + print(f' csi_cb : {L}') + + # 11ax MAC firmware + for L in grep_pattern(text, r'mac_version:HAL_MAC_ESP32AX', 2): + print(f' he-mac : {L}') + + +# Cross-board leader election summary +print('\n' + '='*78) +print('Leader election analysis') +print('='*78) +eui_re = re.compile(r'EUI=([0-9a-fA-F]+)') +euis = {} +for port in PORTS: + text = results.get(port) or '' + m = eui_re.search(text) + if m: + euis[port] = int(m.group(1), 16) + print(f' {port} EUI=0x{m.group(1).lower()} -> {"LEADER" if False else "candidate"}') + +if len(euis) >= 2: + lowest_port = min(euis, key=euis.get) + print(f'\n lowest EUI -> expected leader: {lowest_port} (0x{euis[lowest_port]:016x})') + + # Did a "stepping down" log appear on the non-lowest boards? + for port in PORTS: + if port == lowest_port: + continue + text = results.get(port) or '' + if 'stepping down' in text: + print(f' {port}: [OK] stepped down (heard leader beacon)') + elif port in euis: + print(f' {port}: [FAIL] did NOT step down — investigate (own EUI=0x{euis[port]:016x}, expected leader=0x{euis[lowest_port]:016x})') diff --git a/firmware/esp32-csi-node/test/fuzz_csi_serialize.c b/firmware/esp32-csi-node/test/fuzz_csi_serialize.c index 67cf4523..1eb3af85 100644 --- a/firmware/esp32-csi-node/test/fuzz_csi_serialize.c +++ b/firmware/esp32-csi-node/test/fuzz_csi_serialize.c @@ -60,6 +60,10 @@ int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) uint8_t channel; int8_t noise_floor; uint8_t out_buf_scale; /* Controls output buffer size: 0-255. */ + /* ADR-110: fuzz the new HE-branch + legacy-branch input fields too so + * the byte 18/19 encoding code path is exercised. */ + uint8_t he_inputs[2] = {0}; /* cur_bb_format (4 bits) + second (4 bits) packed */ + uint8_t legacy_inputs = 0; /* sig_mode (2) + cwb (1) + stbc (1) packed */ fuzz_read(&cursor, &remaining, &test_case, 1); fuzz_read(&cursor, &remaining, &iq_len_raw, 2); @@ -67,6 +71,8 @@ int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) fuzz_read(&cursor, &remaining, &channel, 1); fuzz_read(&cursor, &remaining, &noise_floor, 1); fuzz_read(&cursor, &remaining, &out_buf_scale, 1); + fuzz_read(&cursor, &remaining, he_inputs, 2); + fuzz_read(&cursor, &remaining, &legacy_inputs, 1); /* --- Test case 0: Normal operation with fuzz-controlled values --- */ @@ -75,6 +81,15 @@ int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) info.rx_ctrl.rssi = rssi; info.rx_ctrl.channel = channel & 0x0F; /* 4-bit field */ info.rx_ctrl.noise_floor = noise_floor; + /* ADR-110: feed both branch families. Only the active branch (chosen + * at compile time by CONFIG_SOC_WIFI_HE_SUPPORT) will read its fields; + * the other set is set-but-not-read. Both must be assignable without + * triggering UBSAN bitfield-overflow. */ + info.rx_ctrl.cur_bb_format = he_inputs[0] & 0x0F; /* 0..15 valid input space */ + info.rx_ctrl.second = he_inputs[1] & 0x0F; + info.rx_ctrl.sig_mode = legacy_inputs & 0x03; + info.rx_ctrl.cwb = (legacy_inputs >> 2) & 0x01; + info.rx_ctrl.stbc = (legacy_inputs >> 3) & 0x01; /* Use remaining fuzz data as I/Q buffer content. */ uint16_t iq_len; diff --git a/firmware/esp32-csi-node/test/stubs/esp_stubs.c b/firmware/esp32-csi-node/test/stubs/esp_stubs.c index 09f19cf0..e6c2b4ba 100644 --- a/firmware/esp32-csi-node/test/stubs/esp_stubs.c +++ b/firmware/esp32-csi-node/test/stubs/esp_stubs.c @@ -73,3 +73,13 @@ static mmwave_state_t s_stub_mmwave = {0}; esp_err_t mmwave_sensor_init(int tx, int rx) { (void)tx; (void)rx; return ESP_ERR_NOT_FOUND; } bool mmwave_sensor_get_state(mmwave_state_t *s) { if (s) *s = s_stub_mmwave; return false; } const char *mmwave_type_name(mmwave_type_t t) { (void)t; return "None"; } + +/* ADR-110 iter 38 — fuzz-harness stub for c6_sync_espnow_is_valid. + * Real implementation lives in main/c6_sync_espnow.c; the fuzz target + * (`fuzz_serialize`) only links csi_collector.c against esp_stubs.c, so + * iter-11's `if (c6_sync_espnow_is_valid()) flags |= (1 << 4);` needs a + * symbol here or `clang -fsanitize=fuzzer` fails with an undefined-reference + * linker error. Returning false means the bit-4 cross-node-sync-valid flag + * stays 0 in fuzz inputs, which is the natural fuzz semantic. */ +#include +bool c6_sync_espnow_is_valid(void) { return false; } diff --git a/firmware/esp32-csi-node/test/stubs/esp_stubs.h b/firmware/esp32-csi-node/test/stubs/esp_stubs.h index be96f689..3d849a89 100644 --- a/firmware/esp32-csi-node/test/stubs/esp_stubs.h +++ b/firmware/esp32-csi-node/test/stubs/esp_stubs.h @@ -62,14 +62,28 @@ static inline esp_err_t esp_timer_delete(esp_timer_handle_t h) { (void)h; return /* ---- esp_wifi_types.h ---- */ -/** Minimal rx_ctrl fields needed by csi_serialize_frame. */ +/** Minimal rx_ctrl fields needed by csi_serialize_frame. + * + * ADR-110: the HE-tagging path in csi_collector.c references either + * (CONFIG_SOC_WIFI_HE_SUPPORT branch) cur_bb_format, second + * (legacy / S3 branch) sig_mode, cwb, stbc + * + * Both sets are unconditionally declared here so a single stub builds + * for either branch — the Makefile picks which side via -D flags. */ typedef struct { - signed rssi : 8; - unsigned channel : 4; - unsigned noise_floor : 8; - unsigned rx_ant : 2; - /* Padding to fill out the struct so it compiles. */ - unsigned _pad : 10; + signed rssi : 8; + unsigned channel : 4; + unsigned noise_floor : 8; + unsigned rx_ant : 2; + /* ADR-110 HE-branch fields (CONFIG_SOC_WIFI_HE_SUPPORT path) */ + unsigned cur_bb_format : 4; /**< 0=11b 1=11g/a 2=HT 3=VHT 4=HE-SU 5=HE-MU 6=HE-ER-SU 7=HE-TB */ + unsigned second : 4; /**< secondary 40 MHz channel offset */ + /* ADR-110 legacy-branch fields (pre-HE chips) */ + unsigned sig_mode : 2; /**< 0=non-HT 1=HT 3=VHT */ + unsigned cwb : 1; /**< 0=20 MHz 1=40 MHz */ + unsigned stbc : 1; /**< STBC flag */ + /* Padding to keep alignment predictable. */ + unsigned _pad : 18; } wifi_pkt_rx_ctrl_t; /** Minimal wifi_csi_info_t needed by csi_serialize_frame. */ diff --git a/firmware/esp32-csi-node/test/test_adr110_encoding.c b/firmware/esp32-csi-node/test/test_adr110_encoding.c new file mode 100644 index 00000000..de8e236e --- /dev/null +++ b/firmware/esp32-csi-node/test/test_adr110_encoding.c @@ -0,0 +1,242 @@ +/** + * @file test_adr110_encoding.c + * @brief Host-side unit tests for ADR-110 pure functions. + * + * Covers the two encoding paths that don't need ESP-IDF runtime: + * 1. mac_to_eui64() — IEEE EUI-64 from MAC-48 (c6_timesync.c) + * 2. PPDU-type → ADR-018 byte 18 mapping for both HE-capable and + * legacy paths (csi_collector.c) + * + * Build (Linux/macOS/Windows with any C99 compiler): + * cc -std=c99 -Wall -o test_adr110 test_adr110_encoding.c && ./test_adr110 + * + * Or in WSL on this Windows box: + * gcc -std=c99 -Wall -o test_adr110 test_adr110_encoding.c && ./test_adr110 + * + * Exits 0 on all-pass, prints which assertion failed otherwise. + * + * Why a separate host test file rather than extending the existing fuzz + * harness: fuzzers want random bytes; these are deterministic table-driven + * checks for tiny pure functions where libFuzzer adds no signal. + */ + +#include +#include +#include + +/* ────────────────────────────────────────────────────────────────────── + * System under test — copied verbatim from the firmware. If the + * firmware copy changes, this test must be updated and the new behavior + * attested by re-running the test before the firmware change merges. + * ────────────────────────────────────────────────────────────────────── */ + +/* From firmware/esp32-csi-node/main/c6_timesync.c — fallback path used only + * when esp_read_mac(..., ESP_MAC_IEEE802154) fails. The primary C6 path + * reads 8 bytes directly (the eFuse-provided EUI-64). */ +static uint64_t mac48_to_eui64(const uint8_t mac[6]) +{ + return ((uint64_t)mac[0] << 56) | ((uint64_t)mac[1] << 48) | + ((uint64_t)mac[2] << 40) | ((uint64_t)0xFF << 32) | + ((uint64_t)0xFE << 24) | ((uint64_t)mac[3] << 16) | + ((uint64_t)mac[4] << 8 ) | (uint64_t)mac[5]; +} + +/* Pack 8-byte EUI-64 buffer (as returned by ESP_MAC_IEEE802154) into u64. */ +static uint64_t eui64_bytes_to_u64(const uint8_t eui[8]) +{ + return ((uint64_t)eui[0] << 56) | ((uint64_t)eui[1] << 48) | + ((uint64_t)eui[2] << 40) | ((uint64_t)eui[3] << 32) | + ((uint64_t)eui[4] << 24) | ((uint64_t)eui[5] << 16) | + ((uint64_t)eui[6] << 8 ) | (uint64_t)eui[7]; +} + +/* From firmware/esp32-csi-node/main/csi_collector.c — HE-capable branch. + * Returns the ADR-018 byte-18 PPDU type. */ +static uint8_t ppdu_type_he(uint8_t cur_bb_format) +{ + switch (cur_bb_format) { + case 0: + case 1: + case 2: return 0; /* 11b/g/a/HT bucket */ + case 3: return 0; /* VHT */ + case 4: return 1; /* HE-SU */ + case 5: return 2; /* HE-MU */ + case 6: return 1; /* HE-ER-SU collapses to HE-SU */ + case 7: return 3; /* HE-TB */ + default: return 0xFF; + } +} + +/* From csi_collector.c — legacy (non-HE) branch. */ +static uint8_t ppdu_type_legacy(uint8_t sig_mode) +{ + switch (sig_mode) { + case 0: return 0; /* non-HT */ + case 1: return 0; /* HT */ + case 3: return 0; /* VHT */ + default: return 0xFF; + } +} + +/* ────────────────────────────────────────────────────────────────────── + * Test harness + * ────────────────────────────────────────────────────────────────────── */ + +static int g_failed = 0; +static int g_passed = 0; + +#define CHECK_EQ_U64(label, got, expected) do { \ + if ((got) == (expected)) { g_passed++; } \ + else { \ + g_failed++; \ + printf("FAIL: %s — got=0x%016llx expected=0x%016llx\n", \ + (label), (unsigned long long)(got), \ + (unsigned long long)(expected)); \ + } \ +} while (0) + +#define CHECK_EQ_U8(label, got, expected) do { \ + if ((uint8_t)(got) == (uint8_t)(expected)) { g_passed++; } \ + else { \ + g_failed++; \ + printf("FAIL: %s — got=0x%02x expected=0x%02x\n", \ + (label), (unsigned)(got), (unsigned)(expected)); \ + } \ +} while (0) + +/* ────────────────────────────────────────────────────────────────────── + * EUI-64 tests + * + * IEEE 802 MAC-48 → EUI-64 spec: insert 0xFFFE between bytes 3 and 4 + * of the MAC. ADR-110's c6_timesync.c does exactly that, leaving the + * U/L bit in byte 0 untouched (the c6 EUI then matches what `esp_read_mac + * ESP_MAC_IEEE802154` returns). + * ────────────────────────────────────────────────────────────────────── */ + +static void test_eui64_fallback_zero_mac(void) +{ + uint8_t mac[6] = {0, 0, 0, 0, 0, 0}; + /* mac48_to_eui64 inserts FFFE → 00 00 00 FF FE 00 00 00 */ + CHECK_EQ_U64("mac48->eui64 zero", mac48_to_eui64(mac), 0x000000FFFE000000ULL); +} + +static void test_eui64_fallback_all_ones(void) +{ + uint8_t mac[6] = {0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF}; + /* FF FF FF FF FE FF FF FF */ + CHECK_EQ_U64("mac48->eui64 all-ones", mac48_to_eui64(mac), 0xFFFFFFFFFEFFFFFFULL); +} + +static void test_eui64_fallback_byte_order(void) +{ + uint8_t mac[6] = {0x11, 0x22, 0x33, 0x44, 0x55, 0x66}; + CHECK_EQ_U64("mac48->eui64 byte order", mac48_to_eui64(mac), 0x112233FFFE445566ULL); +} + +/* Primary path: 8-byte EUI-64 from ESP_MAC_IEEE802154 packed unchanged. + * Verified by esptool's chip_id output on the real C6 hardware: + * COM6: BASE MAC 20:6e:f1:17:27:8c, MAC_EXT ff:fe → + * full EUI: 20:6e:f1:ff:fe:17:27:8c → 0x206EF1FFFE17278C + * COM9: BASE MAC 20:6e:f1:17:05:3c, MAC_EXT ff:fe → + * full EUI: 20:6e:f1:ff:fe:17:05:3c → 0x206EF1FFFE17053C + * + * Note COM9's EUI is numerically smaller — it wins the leader election. */ +static void test_eui64_from_native_com6(void) +{ + uint8_t eui[8] = {0x20, 0x6e, 0xf1, 0xff, 0xfe, 0x17, 0x27, 0x8c}; + CHECK_EQ_U64("native eui64 COM6", eui64_bytes_to_u64(eui), 0x206EF1FFFE17278CULL); +} + +static void test_eui64_from_native_com9(void) +{ + uint8_t eui[8] = {0x20, 0x6e, 0xf1, 0xff, 0xfe, 0x17, 0x05, 0x3c}; + CHECK_EQ_U64("native eui64 COM9", eui64_bytes_to_u64(eui), 0x206EF1FFFE17053CULL); +} + +static void test_eui64_leader_election_order(void) +{ + uint8_t com6[8] = {0x20, 0x6e, 0xf1, 0xff, 0xfe, 0x17, 0x27, 0x8c}; + uint8_t com9[8] = {0x20, 0x6e, 0xf1, 0xff, 0xfe, 0x17, 0x05, 0x3c}; + uint64_t a = eui64_bytes_to_u64(com6); + uint64_t b = eui64_bytes_to_u64(com9); + /* Lowest EUI wins → COM9 should be leader when both boards online. */ + if (b < a) { g_passed++; } + else { g_failed++; printf("FAIL: leader-election order — expected COM9 < COM6\n"); } +} + +/* ────────────────────────────────────────────────────────────────────── + * PPDU-type encoding tests — HE-capable branch (C6/C5) + * ────────────────────────────────────────────────────────────────────── */ + +static void test_ppdu_he_legacy_bucket(void) +{ + CHECK_EQ_U8("he 0 → 0 (11b)", ppdu_type_he(0), 0); + CHECK_EQ_U8("he 1 → 0 (11g/a)", ppdu_type_he(1), 0); + CHECK_EQ_U8("he 2 → 0 (HT)", ppdu_type_he(2), 0); + CHECK_EQ_U8("he 3 → 0 (VHT)", ppdu_type_he(3), 0); +} + +static void test_ppdu_he_su(void) +{ + CHECK_EQ_U8("he 4 → 1 (HE-SU)", ppdu_type_he(4), 1); + CHECK_EQ_U8("he 6 → 1 (HE-ER-SU)", ppdu_type_he(6), 1); +} + +static void test_ppdu_he_mu(void) +{ + CHECK_EQ_U8("he 5 → 2 (HE-MU)", ppdu_type_he(5), 2); +} + +static void test_ppdu_he_tb(void) +{ + CHECK_EQ_U8("he 7 → 3 (HE-TB)", ppdu_type_he(7), 3); +} + +static void test_ppdu_he_out_of_range(void) +{ + CHECK_EQ_U8("he 8 → 0xFF (unknown)", ppdu_type_he(8), 0xFF); + CHECK_EQ_U8("he 15 → 0xFF (unknown)", ppdu_type_he(15), 0xFF); +} + +/* ────────────────────────────────────────────────────────────────────── + * PPDU-type encoding tests — legacy (S3/etc) branch + * ────────────────────────────────────────────────────────────────────── */ + +static void test_ppdu_legacy_known(void) +{ + CHECK_EQ_U8("legacy sig_mode 0 → 0 (non-HT)", ppdu_type_legacy(0), 0); + CHECK_EQ_U8("legacy sig_mode 1 → 0 (HT)", ppdu_type_legacy(1), 0); + CHECK_EQ_U8("legacy sig_mode 3 → 0 (VHT)", ppdu_type_legacy(3), 0); +} + +static void test_ppdu_legacy_unknown(void) +{ + CHECK_EQ_U8("legacy sig_mode 2 → 0xFF", ppdu_type_legacy(2), 0xFF); + CHECK_EQ_U8("legacy sig_mode 5 → 0xFF", ppdu_type_legacy(5), 0xFF); +} + +/* ────────────────────────────────────────────────────────────────────── + * main + * ────────────────────────────────────────────────────────────────────── */ + +int main(void) +{ + test_eui64_fallback_zero_mac(); + test_eui64_fallback_all_ones(); + test_eui64_fallback_byte_order(); + test_eui64_from_native_com6(); + test_eui64_from_native_com9(); + test_eui64_leader_election_order(); + + test_ppdu_he_legacy_bucket(); + test_ppdu_he_su(); + test_ppdu_he_mu(); + test_ppdu_he_tb(); + test_ppdu_he_out_of_range(); + + test_ppdu_legacy_known(); + test_ppdu_legacy_unknown(); + + printf("\n%d passed, %d failed\n", g_passed, g_failed); + return g_failed == 0 ? 0 : 1; +} diff --git a/firmware/esp32-csi-node/version.txt b/firmware/esp32-csi-node/version.txt index bf21f525..faef31a4 100644 --- a/firmware/esp32-csi-node/version.txt +++ b/firmware/esp32-csi-node/version.txt @@ -1 +1 @@ -0.6.6 \ No newline at end of file +0.7.0 diff --git a/scripts/generate-witness-bundle.sh b/scripts/generate-witness-bundle.sh index 97a9e55f..6ebc7d7f 100644 --- a/scripts/generate-witness-bundle.sh +++ b/scripts/generate-witness-bundle.sh @@ -39,18 +39,18 @@ cp "$REPO_ROOT/docs/adr/ADR-028-esp32-capability-audit.md" "$BUNDLE_DIR/" # --------------------------------------------------------------- echo "[2/7] Copying proof system..." mkdir -p "$BUNDLE_DIR/proof" -cp "$REPO_ROOT/v1/data/proof/verify.py" "$BUNDLE_DIR/proof/" -cp "$REPO_ROOT/v1/data/proof/expected_features.sha256" "$BUNDLE_DIR/proof/" -cp "$REPO_ROOT/v1/data/proof/generate_reference_signal.py" "$BUNDLE_DIR/proof/" +cp "$REPO_ROOT/archive/v1/data/proof/verify.py" "$BUNDLE_DIR/proof/" +cp "$REPO_ROOT/archive/v1/data/proof/expected_features.sha256" "$BUNDLE_DIR/proof/" +cp "$REPO_ROOT/archive/v1/data/proof/generate_reference_signal.py" "$BUNDLE_DIR/proof/" # Reference signal is large (~10 MB) — include metadata only python3 -c " import json, os -with open('$REPO_ROOT/v1/data/proof/sample_csi_data.json') as f: +with open('$REPO_ROOT/archive/v1/data/proof/sample_csi_data.json') as f: d = json.load(f) meta = {k: v for k, v in d.items() if k != 'frames'} meta['frame_count'] = len(d['frames']) meta['first_frame_keys'] = list(d['frames'][0].keys()) -meta['file_size_bytes'] = os.path.getsize('$REPO_ROOT/v1/data/proof/sample_csi_data.json') +meta['file_size_bytes'] = os.path.getsize('$REPO_ROOT/archive/v1/data/proof/sample_csi_data.json') with open('$BUNDLE_DIR/proof/reference_signal_metadata.json', 'w') as f: json.dump(meta, f, indent=2) " 2>/dev/null && echo " Reference signal metadata extracted." || echo " (Python not available — metadata skipped)" @@ -73,7 +73,13 @@ cd "$REPO_ROOT" # 4. Run Python proof verification # --------------------------------------------------------------- echo "[4/7] Running Python proof verification..." -python3 "$REPO_ROOT/v1/data/proof/verify.py" 2>&1 | tee "$BUNDLE_DIR/proof/verification-output.log" | tail -5 || true +# SECURITY: the verify.py emits a Pydantic schema dump on validation failure +# that includes the user's .env contents (Docker tokens, API keys, etc.). +# Redact any line matching common secret-shaped patterns before writing the +# bundled log. See ADR-110 wave 5 incident note. +python3 "$REPO_ROOT/archive/v1/data/proof/verify.py" 2>&1 | \ + python3 "$REPO_ROOT/scripts/redact-secrets.py" \ + | tee "$BUNDLE_DIR/proof/verification-output.log" | tail -5 || true # --------------------------------------------------------------- # 5. Firmware manifest @@ -89,6 +95,21 @@ if [ -d "$REPO_ROOT/firmware/esp32-csi-node/main" ]; then find "$REPO_ROOT/firmware/esp32-csi-node/main/" -type f \( -name "*.c" -o -name "*.h" \) -exec sha256sum {} \; \ > "$BUNDLE_DIR/firmware-manifest/source-hashes.txt" 2>/dev/null || true echo " Firmware source files hashed." + + # ADR-110: include pre-built S3 and C6 binary SHA-256s if archived + for target in s3-adr110 c6-adr110; do + if [ -d "$REPO_ROOT/firmware/esp32-csi-node/release_bins/$target" ]; then + sha256sum "$REPO_ROOT/firmware/esp32-csi-node/release_bins/$target/"*.bin \ + > "$BUNDLE_DIR/firmware-manifest/binary-hashes-${target}.txt" 2>/dev/null \ + && echo " Binary hashes recorded for $target." + fi + done + + # ADR-110: list which ESP-IDF target(s) the firmware supports today + cat > "$BUNDLE_DIR/firmware-manifest/supported-targets.txt" <&1 | python3 scripts/redact-secrets.py > clean.log +""" +import re +import sys + + +# Token prefix patterns — common SaaS / VCS API token shapes. +PREFIX_PATTERNS = [ + (re.compile(r'(dckr_pat_|tok_|sk-|ghp_|gho_|github_pat_|AKIA|hf_|xoxb-|xoxp-|Bearer\s+)[A-Za-z0-9_\-\.]+', + re.IGNORECASE), r'\1[REDACTED]'), +] + +# Long opaque strings (40+ alphanumeric / underscore / dash chars). +LONG_OPAQUE = re.compile(r'[A-Za-z0-9_\-]{40,}') + +# Long hex runs (20+ hex chars — covers token suffixes after `...`). +LONG_HEX = re.compile(r'[a-fA-F0-9]{20,}') + +# `field=VALUE` style assignment where field name suggests a secret. +SECRET_ASSIGNMENT = re.compile( + r'(token|password|secret|api_key|access_key|private_key|psk|bearer)' + r'(["\'\s:=]+)["\']?([A-Za-z0-9._\-/+]{12,})["\']?', + re.IGNORECASE +) + + +def redact_line(line: str) -> str: + for pat, repl in PREFIX_PATTERNS: + line = pat.sub(repl, line) + line = SECRET_ASSIGNMENT.sub(lambda m: f'{m.group(1)}={"[REDACTED]"}', line) + line = LONG_OPAQUE.sub('[REDACTED-OPAQUE]', line) + line = LONG_HEX.sub('[REDACTED-HEX]', line) + return line + + +def main() -> int: + for raw in sys.stdin.buffer: + try: + text = raw.decode('utf-8', errors='replace') + except Exception: + sys.stdout.buffer.write(b'[REDACTED-UNDECODABLE]\n') + continue + sys.stdout.write(redact_line(text)) + sys.stdout.flush() + return 0 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/v2/Cargo.lock b/v2/Cargo.lock index 3bc3ddd2..1a7b20d2 100644 --- a/v2/Cargo.lock +++ b/v2/Cargo.lock @@ -9140,6 +9140,7 @@ dependencies = [ "tracing", "tracing-subscriber", "ureq 2.12.1", + "wifi-densepose-hardware", "wifi-densepose-signal", "wifi-densepose-wifiscan", ] diff --git a/v2/crates/wifi-densepose-hardware/src/bridge.rs b/v2/crates/wifi-densepose-hardware/src/bridge.rs index 23181c84..096abf89 100644 --- a/v2/crates/wifi-densepose-hardware/src/bridge.rs +++ b/v2/crates/wifi-densepose-hardware/src/bridge.rs @@ -101,6 +101,8 @@ mod tests { rx_antennas: n_antennas, }, sequence: 42, + ppdu_type: crate::csi_frame::PpduType::HtLegacy, + adr018_flags: crate::csi_frame::Adr018Flags::default(), }, subcarriers, } diff --git a/v2/crates/wifi-densepose-hardware/src/csi_frame.rs b/v2/crates/wifi-densepose-hardware/src/csi_frame.rs index b0184742..400f91fd 100644 --- a/v2/crates/wifi-densepose-hardware/src/csi_frame.rs +++ b/v2/crates/wifi-densepose-hardware/src/csi_frame.rs @@ -85,6 +85,98 @@ pub struct CsiMetadata { pub antenna_config: AntennaConfig, /// Sequence number for ordering pub sequence: u32, + /// ADR-110: PPDU type from ADR-018 byte 18. None on pre-ADR-110 firmware + /// (or when CONFIG_CSI_FRAME_HE_TAGGING is disabled — byte stays zero + /// and pre-ADR-110 readers see the same zero, full backwards compat). + /// Byte 18 = 0 reads as PpduType::HtLegacy (the wire encoding for the + /// HT/legacy bucket); 0xFF reads as PpduType::Unknown. + pub ppdu_type: PpduType, + /// ADR-110: flags from ADR-018 byte 19 — bandwidth bits, STBC, LDPC, + /// 802.15.4-time-sync-valid bit. See [`Adr018Flags`]. + pub adr018_flags: Adr018Flags, +} + +/// PPDU type encoded in ADR-018 byte 18 (ADR-110 extension). +/// +/// Wire encoding (matches firmware `csi_collector.c`): +/// 0 = HT / legacy bucket (11b/g/HT/VHT all collapse here) +/// 1 = HE-SU (802.11ax single-user) +/// 2 = HE-MU (802.11ax multi-user) +/// 3 = HE-TB (802.11ax trigger-based) +/// 0xFF = Unknown +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +pub enum PpduType { + HtLegacy, + HeSu, + HeMu, + HeTb, + Unknown, +} + +impl PpduType { + pub fn from_byte(b: u8) -> Self { + match b { + 0 => Self::HtLegacy, + 1 => Self::HeSu, + 2 => Self::HeMu, + 3 => Self::HeTb, + _ => Self::Unknown, + } + } + pub fn to_byte(self) -> u8 { + match self { + Self::HtLegacy => 0, + Self::HeSu => 1, + Self::HeMu => 2, + Self::HeTb => 3, + Self::Unknown => 0xFF, + } + } + pub fn is_he(self) -> bool { + matches!(self, Self::HeSu | Self::HeMu | Self::HeTb) + } +} + +/// Flags encoded in ADR-018 byte 19 (ADR-110 extension). +/// +/// Wire encoding: +/// bit 0 : bandwidth wide (set = 40 MHz, clear = 20 MHz) +/// bit 1 : (reserved for 80/160 future) +/// bit 2 : STBC +/// bit 3 : LDPC (reserved — not yet populated by firmware) +/// bit 4 : 802.15.4 time-sync valid (C6 only) +/// bit 5-7 : reserved +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +pub struct Adr018Flags { + pub bw40: bool, + pub stbc: bool, + pub ldpc: bool, + pub ieee802154_sync_valid: bool, +} + +impl Adr018Flags { + pub fn from_byte(b: u8) -> Self { + Self { + bw40: (b & 0x01) != 0, + stbc: (b & 0x04) != 0, + ldpc: (b & 0x08) != 0, + ieee802154_sync_valid: (b & 0x10) != 0, + } + } + pub fn to_byte(self) -> u8 { + let mut b = 0u8; + if self.bw40 { b |= 0x01; } + if self.stbc { b |= 0x04; } + if self.ldpc { b |= 0x08; } + if self.ieee802154_sync_valid { b |= 0x10; } + b + } +} + +impl Default for Adr018Flags { + fn default() -> Self { + Self { bw40: false, stbc: false, ldpc: false, ieee802154_sync_valid: false } + } } /// WiFi channel bandwidth. @@ -159,6 +251,8 @@ mod tests { bandwidth: Bandwidth::Bw20, antenna_config: AntennaConfig::default(), sequence: 1, + ppdu_type: PpduType::HtLegacy, + adr018_flags: Adr018Flags::default(), }, subcarriers: vec![ SubcarrierData { diff --git a/v2/crates/wifi-densepose-hardware/src/esp32_parser.rs b/v2/crates/wifi-densepose-hardware/src/esp32_parser.rs index 5555ee1a..455b1451 100644 --- a/v2/crates/wifi-densepose-hardware/src/esp32_parser.rs +++ b/v2/crates/wifi-densepose-hardware/src/esp32_parser.rs @@ -31,7 +31,9 @@ use byteorder::{LittleEndian, ReadBytesExt}; use chrono::Utc; use std::io::Cursor; -use crate::csi_frame::{AntennaConfig, Bandwidth, CsiFrame, CsiMetadata, SubcarrierData}; +use crate::csi_frame::{ + Adr018Flags, AntennaConfig, Bandwidth, CsiFrame, CsiMetadata, PpduType, SubcarrierData, +}; use crate::error::ParseError; /// ESP32 CSI binary frame magic number (ADR-018). @@ -185,13 +187,20 @@ impl Esp32CsiParser { message: "Failed to read noise floor".into(), })?; - // Reserved (offset 18, 2 bytes) — skip - let _reserved = cursor - .read_u16::() - .map_err(|_| ParseError::ByteError { - offset: 18, - message: "Failed to read reserved bytes".into(), - })?; + // ADR-110: bytes 18-19 carry PPDU type + flags (previously reserved-zero, + // now opt-in via CONFIG_CSI_FRAME_HE_TAGGING in firmware). Pre-ADR-110 + // firmware sends zeros, which round-trip as PpduType::HtLegacy + + // Adr018Flags::default() — fully backwards compatible. + let ppdu_byte = cursor.read_u8().map_err(|_| ParseError::ByteError { + offset: 18, + message: "Failed to read PPDU type byte".into(), + })?; + let flags_byte = cursor.read_u8().map_err(|_| ParseError::ByteError { + offset: 19, + message: "Failed to read flags byte".into(), + })?; + let ppdu_type = PpduType::from_byte(ppdu_byte); + let adr018_flags = Adr018Flags::from_byte(flags_byte); // I/Q data: n_antennas * n_subcarriers * 2 bytes let iq_pair_count = n_antennas as usize * n_subcarriers; @@ -254,6 +263,8 @@ impl Esp32CsiParser { rx_antennas: n_antennas, }, sequence, + ppdu_type, + adr018_flags, }, subcarriers, }; @@ -302,7 +313,20 @@ mod tests { use super::*; /// Build a valid ADR-018 ESP32 CSI frame with known parameters. + /// PPDU type + flags bytes (offset 18-19) are zero — pre-ADR-110 default, + /// which round-trips as PpduType::HtLegacy + Adr018Flags::default(). fn build_test_frame(node_id: u8, n_antennas: u8, subcarrier_pairs: &[(i8, i8)]) -> Vec { + build_test_frame_with_he(node_id, n_antennas, subcarrier_pairs, 0, 0) + } + + /// ADR-110-aware variant: explicit byte 18 (PPDU type) and byte 19 (flags). + fn build_test_frame_with_he( + node_id: u8, + n_antennas: u8, + subcarrier_pairs: &[(i8, i8)], + ppdu_byte: u8, + flags_byte: u8, + ) -> Vec { let n_subcarriers = if n_antennas == 0 { subcarrier_pairs.len() } else { @@ -310,26 +334,16 @@ mod tests { }; let mut buf = Vec::new(); - - // Magic (offset 0) buf.extend_from_slice(&ESP32_CSI_MAGIC.to_le_bytes()); - // Node ID (offset 4) buf.push(node_id); - // Number of antennas (offset 5) buf.push(n_antennas); - // Number of subcarriers (offset 6, LE u16) buf.extend_from_slice(&(n_subcarriers as u16).to_le_bytes()); - // Frequency MHz (offset 8, LE u32) buf.extend_from_slice(&2437u32.to_le_bytes()); - // Sequence number (offset 12, LE u32) buf.extend_from_slice(&1u32.to_le_bytes()); - // RSSI (offset 16, i8) buf.push((-50i8) as u8); - // Noise floor (offset 17, i8) buf.push((-95i8) as u8); - // Reserved (offset 18, 2 bytes) - buf.extend_from_slice(&[0u8; 2]); - // I/Q data (offset 20) + buf.push(ppdu_byte); + buf.push(flags_byte); for (i, q) in subcarrier_pairs { buf.push(*i as u8); buf.push(*q as u8); @@ -338,6 +352,65 @@ mod tests { buf } + // ── ADR-110: byte 18-19 round-trip tests ───────────────────────────────── + + #[test] + fn adr110_pre_adr110_firmware_round_trips_as_ht_legacy_default_flags() { + // Pre-ADR-110 firmware writes zeros to bytes 18-19. The parser must + // surface that as HtLegacy + default flags so old aggregators see + // identical behavior to before the extension. + let data = build_test_frame(1, 1, &[(0, 0); 56]); + let (frame, _) = Esp32CsiParser::parse_frame(&data).unwrap(); + assert_eq!(frame.metadata.ppdu_type, PpduType::HtLegacy); + assert_eq!(frame.metadata.adr018_flags, Adr018Flags::default()); + assert!(!frame.metadata.ppdu_type.is_he()); + } + + #[test] + fn adr110_he_su_ppdu_decodes() { + let data = build_test_frame_with_he(2, 1, &[(0, 0); 56], /*PPDU*/ 1, /*flags*/ 0); + let (frame, _) = Esp32CsiParser::parse_frame(&data).unwrap(); + assert_eq!(frame.metadata.ppdu_type, PpduType::HeSu); + assert!(frame.metadata.ppdu_type.is_he()); + } + + #[test] + fn adr110_he_mu_he_tb_decode() { + let mu = build_test_frame_with_he(3, 1, &[(0, 0); 56], 2, 0); + let tb = build_test_frame_with_he(4, 1, &[(0, 0); 56], 3, 0); + let (mu_frame, _) = Esp32CsiParser::parse_frame(&mu).unwrap(); + let (tb_frame, _) = Esp32CsiParser::parse_frame(&tb).unwrap(); + assert_eq!(mu_frame.metadata.ppdu_type, PpduType::HeMu); + assert_eq!(tb_frame.metadata.ppdu_type, PpduType::HeTb); + } + + #[test] + fn adr110_unknown_ppdu_byte_decodes_as_unknown() { + let data = build_test_frame_with_he(5, 1, &[(0, 0); 56], 0xFF, 0); + let (frame, _) = Esp32CsiParser::parse_frame(&data).unwrap(); + assert_eq!(frame.metadata.ppdu_type, PpduType::Unknown); + } + + #[test] + fn adr110_flags_round_trip_all_bits() { + // All known flag bits set: bw40 (0x01) + STBC (0x04) + LDPC (0x08) + 15.4-sync (0x10) = 0x1D + let data = build_test_frame_with_he(6, 1, &[(0, 0); 56], 1, 0x1D); + let (frame, _) = Esp32CsiParser::parse_frame(&data).unwrap(); + assert!(frame.metadata.adr018_flags.bw40); + assert!(frame.metadata.adr018_flags.stbc); + assert!(frame.metadata.adr018_flags.ldpc); + assert!(frame.metadata.adr018_flags.ieee802154_sync_valid); + // Round-trip the encoder + assert_eq!(frame.metadata.adr018_flags.to_byte(), 0x1D); + } + + #[test] + fn adr110_ppdu_byte_round_trips_for_known_variants() { + for v in [PpduType::HtLegacy, PpduType::HeSu, PpduType::HeMu, PpduType::HeTb, PpduType::Unknown] { + assert_eq!(PpduType::from_byte(v.to_byte()), v, "round-trip failed for {v:?}"); + } + } + #[test] fn test_parse_valid_frame() { // 1 antenna, 56 subcarriers diff --git a/v2/crates/wifi-densepose-hardware/src/lib.rs b/v2/crates/wifi-densepose-hardware/src/lib.rs index d53f7d7f..63c45d1b 100644 --- a/v2/crates/wifi-densepose-hardware/src/lib.rs +++ b/v2/crates/wifi-densepose-hardware/src/lib.rs @@ -40,6 +40,7 @@ mod csi_frame; mod error; pub mod esp32; mod esp32_parser; +pub mod sync_packet; // ADR-081: Rust mirror of the firmware radio abstraction layer (L1) and // mesh sensing plane (L3). Lets host tests, simulators, and future @@ -55,6 +56,9 @@ pub use esp32_parser::{ RUVIEW_FEATURE_MAGIC, RUVIEW_FEATURE_STATE_MAGIC, RUVIEW_FUSED_VITALS_MAGIC, RUVIEW_TEMPORAL_MAGIC, RUVIEW_VITALS_MAGIC, }; +pub use sync_packet::{ + SyncPacket, SyncPacketFlags, SYNC_PACKET_MAGIC, SYNC_PACKET_SIZE, SYNC_PACKET_PROTO_VER, +}; pub use radio_ops::{ crc32_ieee, decode_anomaly_alert, decode_mesh, decode_node_status, encode_health, AnomalyAlert, AuthClass, CaptureProfile, MeshError, MeshHeader, MeshMsgType, MeshRole, MockRadio, NodeStatus, diff --git a/v2/crates/wifi-densepose-hardware/src/sync_packet.rs b/v2/crates/wifi-densepose-hardware/src/sync_packet.rs new file mode 100644 index 00000000..364e7cf1 --- /dev/null +++ b/v2/crates/wifi-densepose-hardware/src/sync_packet.rs @@ -0,0 +1,471 @@ +//! ADR-110 §A0.12 sync packet decoder (firmware v0.6.9+). +//! +//! Emitted by the firmware on the same UDP socket as ADR-018 CSI frames, +//! distinguished by leading magic `0xC511A110`. Pairs `(node_id, sequence)` +//! across the two UDP streams so a host aggregator can recover mesh-aligned +//! timestamps for every CSI frame — see `WITNESS-LOG-110 §A0.12` for live +//! verification, `archive/v1/src/hardware/csi_extractor.py:SyncPacketParser` +//! for the matching Python decoder. +//! +//! Wire format (32 bytes, little-endian): +//! ```text +//! [0..3] magic 0xC511A110 (LE u32) +//! [4] node_id +//! [5] proto_ver (currently 0x01) +//! [6] flags: bit 0 = is_leader +//! bit 1 = is_valid (fresh sync within VALID_WINDOW_MS) +//! bit 2 = smoothed_used (EMA filter active) +//! [7] reserved +//! [8..15] local esp_timer_get_time() (u64) +//! [16..23] mesh-aligned epoch = local + smoothed offset (u64) +//! [24..27] high-water CSI sequence (u32) — pairing key against ADR-018 frames +//! [28..31] reserved +//! ``` +//! +//! Recover the per-board offset for a given sync packet as +//! `local_us - epoch_us` (signed). Follower nodes report the EMA-smoothed +//! offset measured in §A0.10; leader nodes report `~0` modulo call-stack +//! elapsed time (`leader_epoch_us = now_us` by definition). + +use serde::{Deserialize, Serialize}; + +use crate::error::ParseError; + +/// Magic constant in the first 4 little-endian bytes of every sync packet. +pub const SYNC_PACKET_MAGIC: u32 = 0xC511_A110; +/// Total wire size of a v0.6.9+ sync packet. +pub const SYNC_PACKET_SIZE: usize = 32; +/// Wire protocol version currently emitted by firmware. +pub const SYNC_PACKET_PROTO_VER: u8 = 0x01; + +/// Decoded ADR-110 §A0.12 sync packet. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +pub struct SyncPacket { + pub node_id: u8, + pub proto_ver: u8, + pub flags: SyncPacketFlags, + /// Node-local `esp_timer_get_time()` snapshot at emission time. + pub local_us: u64, + /// Mesh-aligned epoch — `local_us + smoothed_offset`. + pub epoch_us: u64, + /// High-water ADR-018 CSI sequence number at emission time. Host + /// aggregator pairs (`node_id`, `sequence`) across the two UDP streams + /// to apply the recovered offset back to in-flight CSI frames. + pub sequence: u32, +} + +/// Flag bits packed into byte 6 of the sync packet. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)] +pub struct SyncPacketFlags { + pub is_leader: bool, + pub is_valid: bool, + pub smoothed_used: bool, +} + +impl SyncPacketFlags { + pub fn from_byte(b: u8) -> Self { + Self { + is_leader: (b & 0x01) != 0, + is_valid: (b & 0x02) != 0, + smoothed_used: (b & 0x04) != 0, + } + } + + pub fn to_byte(self) -> u8 { + let mut b = 0u8; + if self.is_leader { b |= 0x01; } + if self.is_valid { b |= 0x02; } + if self.smoothed_used { b |= 0x04; } + b + } +} + +impl SyncPacket { + /// Decode a 32-byte sync packet. Returns `ParseError::InvalidMagic` if + /// the leading u32 doesn't match `SYNC_PACKET_MAGIC` (host should + /// dispatch on the magic before calling this — see crate-level docs). + pub fn from_bytes(buf: &[u8]) -> Result { + if buf.len() < SYNC_PACKET_SIZE { + return Err(ParseError::InsufficientData { + needed: SYNC_PACKET_SIZE, + got: buf.len(), + }); + } + let magic = u32::from_le_bytes(buf[0..4].try_into().unwrap()); + if magic != SYNC_PACKET_MAGIC { + return Err(ParseError::InvalidMagic { expected: SYNC_PACKET_MAGIC, got: magic }); + } + let node_id = buf[4]; + let proto_ver = buf[5]; + let flags = SyncPacketFlags::from_byte(buf[6]); + // buf[7] reserved + let local_us = u64::from_le_bytes(buf[8..16].try_into().unwrap()); + let epoch_us = u64::from_le_bytes(buf[16..24].try_into().unwrap()); + let sequence = u32::from_le_bytes(buf[24..28].try_into().unwrap()); + // buf[28..32] reserved + Ok(Self { + node_id, + proto_ver, + flags, + local_us, + epoch_us, + sequence, + }) + } + + /// Recover the signed offset between this node's local monotonic clock + /// and the mesh epoch (`local_us - epoch_us`). For followers this is + /// the EMA-smoothed offset; for leaders this is approximately 0 (a few + /// µs of call-stack elapsed only). + pub fn local_minus_epoch_us(&self) -> i64 { + (self.local_us as i64) - (self.epoch_us as i64) + } + + /// Given a CSI frame's node-local `esp_timer_get_time()` snapshot, + /// recover the mesh-aligned timestamp using this sync packet as the + /// reference point. + /// + /// Math (all in node-local µs, see ADR-110 §A0.12): + /// + /// ```text + /// offset = epoch_us - local_us (signed; this packet) + /// mesh_epoch(frame) = local_at_frame_us + offset + /// = local_at_frame_us + (epoch_us - local_us) + /// ``` + /// + /// On the leader this gives `≈ local_at_frame_us`. On a follower this + /// gives the mesh-aligned time aligned to the leader's clock within + /// the §A0.10 measured 104 µs stdev (the same EMA-smoothed offset + /// the firmware applied when it built this sync packet's `epoch_us`). + /// + /// Use this on the host side whenever a CSI frame arrives with + /// ADR-018 byte 19 bit 4 set: look up the matching node's most-recent + /// `SyncPacket`, call `apply_to_local(frame.local_us)`, stamp the + /// result on the frame for downstream multistatic fusion. + pub fn apply_to_local(&self, local_at_frame_us: u64) -> u64 { + // Compute the offset as a signed delta in the µs domain. Adding it + // back to the frame's local snapshot recovers the mesh epoch. + let offset = (self.epoch_us as i64).wrapping_sub(self.local_us as i64); + (local_at_frame_us as i64).wrapping_add(offset) as u64 + } + + /// Recover the mesh-aligned timestamp for an in-flight CSI frame + /// **using its ADR-018 sequence number** as the timeline anchor. + /// + /// CSI frames carry no per-frame `local_us` field (ADR-018 v1 wire + /// format reserves no slot for it — see WITNESS-LOG-110 §A0.11), + /// but they do carry a 32-bit sequence number. The firmware emits + /// a sync packet alongside CSI frames, stamping the sequence + /// high-water observed at emit time into [`SyncPacket::sequence`]. + /// + /// Given a frame's sequence and the node's observed CSI frame rate, + /// estimate the node-local time at the frame and apply the mesh + /// offset: + /// + /// ```text + /// Δframes = frame_seq - sync.sequence (wrapping) + /// Δus = Δframes × 1_000_000 / fps_hz (node-local) + /// local_at = sync.local_us + Δus + /// mesh = local_at + (sync.epoch_us - sync.local_us) + /// ``` + /// + /// `fps_hz` must be > 0; pass the firmware's `CSI_MIN_SEND_INTERVAL_US` + /// inverse (≈ 20 fps) or a measured rate from the broadcast-tick task. + /// The estimate is exact when the frame rate is stable (a node holding + /// 20 fps within ±1 frame for the sync→frame interval gives + /// |error| < 1/fps_hz ≈ 50 ms × the per-frame jitter ratio). + pub fn mesh_aligned_us_for_sequence(&self, frame_seq: u32, fps_hz: f64) -> u64 { + debug_assert!(fps_hz > 0.0, "fps_hz must be positive"); + let dframes = (frame_seq.wrapping_sub(self.sequence)) as i64; + let dus = (dframes as f64 * 1_000_000.0 / fps_hz) as i64; + let local_at = (self.local_us as i64).wrapping_add(dus) as u64; + self.apply_to_local(local_at) + } + + /// Serialize back to wire bytes (32 bytes, little-endian). + pub fn to_bytes(&self) -> [u8; SYNC_PACKET_SIZE] { + let mut out = [0u8; SYNC_PACKET_SIZE]; + out[0..4].copy_from_slice(&SYNC_PACKET_MAGIC.to_le_bytes()); + out[4] = self.node_id; + out[5] = self.proto_ver; + out[6] = self.flags.to_byte(); + // out[7] reserved zero + out[8..16].copy_from_slice(&self.local_us.to_le_bytes()); + out[16..24].copy_from_slice(&self.epoch_us.to_le_bytes()); + out[24..28].copy_from_slice(&self.sequence.to_le_bytes()); + // out[28..32] reserved zero + out + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// Reproduces the COM9 follower sync-pkt #1 captured in WITNESS-LOG-110 §A0.12. + #[test] + fn follower_typical_packet_roundtrips() { + let pkt = SyncPacket { + node_id: 9, + proto_ver: 1, + flags: SyncPacketFlags { is_leader: false, is_valid: true, smoothed_used: true }, + local_us: 28_798_450, + epoch_us: 27_634_885, + sequence: 20, + }; + let wire = pkt.to_bytes(); + let decoded = SyncPacket::from_bytes(&wire).unwrap(); + assert_eq!(decoded, pkt); + // The 1.16-second boot delta §A0.10 measured between COM9 and COM12. + assert_eq!(decoded.local_minus_epoch_us(), 1_163_565); + assert_eq!(decoded.flags.to_byte(), 0x06); + } + + /// COM12 leader case from WITNESS-LOG-110 §A0.12: flags=0x03, epoch ≈ local. + #[test] + fn leader_packet_has_local_close_to_epoch() { + let pkt = SyncPacket { + node_id: 12, + proto_ver: 1, + flags: SyncPacketFlags { is_leader: true, is_valid: true, smoothed_used: false }, + local_us: 28_864_932, + epoch_us: 28_864_939, + sequence: 20, + }; + let wire = pkt.to_bytes(); + let decoded = SyncPacket::from_bytes(&wire).unwrap(); + assert_eq!(decoded.flags.to_byte(), 0x03); + assert_eq!(decoded.local_minus_epoch_us(), -7); // leader has zero offset modulo call-stack + assert!(decoded.flags.is_leader); + assert!(decoded.flags.is_valid); + assert!(!decoded.flags.smoothed_used); + } + + #[test] + fn magic_mismatch_is_typed_error() { + let mut wire = SyncPacket { + node_id: 1, proto_ver: 1, flags: SyncPacketFlags::default(), + local_us: 0, epoch_us: 0, sequence: 0, + }.to_bytes(); + wire[0] = 0x01; // corrupt magic low byte + let err = SyncPacket::from_bytes(&wire).unwrap_err(); + match err { + ParseError::InvalidMagic { got, .. } => assert_ne!(got, SYNC_PACKET_MAGIC), + other => panic!("expected InvalidMagic, got {other:?}"), + } + } + + #[test] + fn short_packet_is_typed_error() { + let wire = [0u8; 16]; // half a packet + let err = SyncPacket::from_bytes(&wire).unwrap_err(); + match err { + ParseError::InsufficientData { needed, got } => { + assert_eq!(needed, SYNC_PACKET_SIZE); + assert_eq!(got, 16); + } + other => panic!("expected InsufficientData, got {other:?}"), + } + } + + /// Every (leader, valid, smoothed_used) triple round-trips independently. + #[test] + fn all_flag_combinations_roundtrip() { + for &is_leader in &[false, true] { + for &is_valid in &[false, true] { + for &smoothed_used in &[false, true] { + let flags = SyncPacketFlags { is_leader, is_valid, smoothed_used }; + let pkt = SyncPacket { + node_id: 1, proto_ver: 1, flags, + local_us: 1234, epoch_us: 5678, sequence: 99, + }; + let wire = pkt.to_bytes(); + let decoded = SyncPacket::from_bytes(&wire).unwrap(); + assert_eq!(decoded.flags, flags); + assert_eq!(decoded.flags.to_byte(), flags.to_byte()); + } + } + } + } + + /// A host dispatches CSI vs sync purely on the leading u32. The two + /// magics must therefore never collide. + #[test] + fn sync_and_csi_magics_differ() { + assert_ne!(SYNC_PACKET_MAGIC, crate::esp32_parser::ESP32_CSI_MAGIC); + } + + /// Applying a sync packet to its own local_us must recover its own + /// epoch_us. Foundational identity for the math. + #[test] + fn apply_to_local_recovers_packet_epoch() { + let pkt = SyncPacket { + node_id: 9, proto_ver: 1, + flags: SyncPacketFlags { is_leader: false, is_valid: true, smoothed_used: true }, + local_us: 28_798_450, epoch_us: 27_634_885, sequence: 20, + }; + assert_eq!(pkt.apply_to_local(pkt.local_us), pkt.epoch_us); + } + + /// A CSI frame's local timestamp arriving after the sync packet + /// gets the same offset applied — the µs delta between sync and frame + /// is preserved on both clocks. + #[test] + fn apply_to_local_preserves_inter_frame_delta() { + let pkt = SyncPacket { + node_id: 9, proto_ver: 1, + flags: SyncPacketFlags { is_leader: false, is_valid: true, smoothed_used: true }, + local_us: 28_798_450, epoch_us: 27_634_885, sequence: 20, + }; + // Frame arrives 100 ms after the sync packet on the follower's local clock. + let local_at_frame = pkt.local_us + 100_000; + let mesh_epoch = pkt.apply_to_local(local_at_frame); + // Mesh epoch should also be 100 ms after the sync packet's epoch. + assert_eq!(mesh_epoch, pkt.epoch_us + 100_000); + // Offset must equal local - epoch on both clocks. + assert_eq!(local_at_frame - mesh_epoch, pkt.local_us - pkt.epoch_us); + } + + /// Leader sync packet has near-zero offset, so apply_to_local is + /// approximately identity (modulo the few µs call-stack delta). + #[test] + fn apply_to_local_on_leader_is_near_identity() { + let pkt = SyncPacket { + node_id: 12, proto_ver: 1, + flags: SyncPacketFlags { is_leader: true, is_valid: true, smoothed_used: false }, + local_us: 28_864_932, epoch_us: 28_864_939, sequence: 20, + }; + let frame_local = 30_000_000u64; + let mesh = pkt.apply_to_local(frame_local); + assert!((mesh as i64 - frame_local as i64).abs() <= 100, + "leader apply should be within 100 µs of identity, got {} delta", + mesh as i64 - frame_local as i64); + } + + /// At the sync packet's own sequence number, the interpolated mesh + /// time must equal `epoch_us` exactly. + #[test] + fn mesh_aligned_for_sequence_identity_at_sync_point() { + let pkt = SyncPacket { + node_id: 9, proto_ver: 1, + flags: SyncPacketFlags { is_leader: false, is_valid: true, smoothed_used: true }, + local_us: 28_798_450, epoch_us: 27_634_885, sequence: 20, + }; + assert_eq!(pkt.mesh_aligned_us_for_sequence(20, 20.0), pkt.epoch_us); + } + + /// 20 frames after the sync packet at 20 Hz → mesh time advances by 1 s, + /// preserving the leader/follower clock offset. + #[test] + fn mesh_aligned_for_sequence_extrapolates_forward() { + let pkt = SyncPacket { + node_id: 9, proto_ver: 1, + flags: SyncPacketFlags { is_leader: false, is_valid: true, smoothed_used: true }, + local_us: 28_798_450, epoch_us: 27_634_885, sequence: 20, + }; + // 20 frames at 20 fps = 1 000 000 µs + let mesh = pkt.mesh_aligned_us_for_sequence(40, 20.0); + assert_eq!(mesh, pkt.epoch_us + 1_000_000); + } + + /// Sequence wraparound (u32 overflow) must extrapolate forward by one + /// frame, not jump backward by 2^32. The wrapping_sub semantics in + /// the implementation guard this. + #[test] + fn mesh_aligned_for_sequence_handles_seq_wraparound() { + let pkt = SyncPacket { + node_id: 9, proto_ver: 1, + flags: SyncPacketFlags { is_leader: false, is_valid: true, smoothed_used: true }, + local_us: 10_000, epoch_us: 10_000, sequence: u32::MAX, + }; + // Next sequence after u32::MAX is 0 (wrap). Δframes = 1, not -2^32. + let mesh = pkt.mesh_aligned_us_for_sequence(0, 20.0); + assert_eq!(mesh, pkt.epoch_us + 50_000); // 1 frame at 20 fps = 50 ms + } + + /// End-to-end ADR-110 pipeline sanity: + /// (1) firmware emits sync packet (bytes built here as a stand-in) + /// (2) host wire-decodes via from_bytes + /// (3) a CSI frame arrives 100 sequences later (≈ 5 s @ 20 fps) + /// (4) mesh_aligned_us_for_sequence recovers its mesh timestamp + /// Asserts that the recovered mesh time matches sync.epoch_us + Δus exactly, + /// and cross-checks against apply_to_local. This is the contract every + /// downstream multistatic-fusion consumer relies on. + #[test] + fn end_to_end_sync_decode_then_frame_mesh_recovery() { + let pkt = SyncPacket { + node_id: 9, + proto_ver: 1, + flags: SyncPacketFlags { is_leader: false, is_valid: true, smoothed_used: true }, + local_us: 28_798_450, + epoch_us: 27_634_885, + sequence: 20, + }; + let wire = pkt.to_bytes(); + assert_eq!(wire.len(), SYNC_PACKET_SIZE); + let decoded = SyncPacket::from_bytes(&wire).unwrap(); + assert_eq!(decoded, pkt); + + // 5 s after sync at 20 fps = 100 frames later + let frame_seq = pkt.sequence + 100; + let mesh_us = decoded.mesh_aligned_us_for_sequence(frame_seq, 20.0); + assert_eq!(mesh_us, pkt.epoch_us + 5_000_000); + + // Same mesh time via direct apply_to_local — both paths must agree + let local_at_frame = pkt.local_us + 5_000_000; + assert_eq!(decoded.apply_to_local(local_at_frame), mesh_us); + } + + #[test] + fn wire_size_constant_is_correct() { + let pkt = SyncPacket { + node_id: 0, proto_ver: 1, flags: SyncPacketFlags::default(), + local_us: 0, epoch_us: 0, sequence: 0, + }; + assert_eq!(pkt.to_bytes().len(), SYNC_PACKET_SIZE); + assert_eq!(SYNC_PACKET_SIZE, 32); + } + + /// ADR-110 iter 21 — cross-language wire-format conformance gate. + /// + /// These exact bytes are ALSO pinned in the Python test + /// `test_canonical_wire_bytes_match_rust_decoder` in + /// `archive/v1/tests/unit/test_esp32_binary_parser.py`. If this + /// canonical hex stops matching what Python emits for the same + /// SyncPacket fields, ONE of the decoders has drifted from the wire. + /// + /// Canonical packet: COM9 sync-pkt #1 from §A0.12 live capture. + #[test] + fn canonical_wire_bytes_match_python_decoder() { + // Exact bytes matching the Python pin (hex-decoded by hand to bytes). + let canonical: [u8; 32] = [ + 0x10, 0xa1, 0x11, 0xc5, // magic 0xC511A110 (LE u32) + 0x09, // node_id = 9 + 0x01, // proto_ver = 1 + 0x06, // flags: bit1=is_valid, bit2=smoothed_used + 0x00, // reserved + 0xf2, 0x6d, 0xb7, 0x01, 0x00, 0x00, 0x00, 0x00, // local_us = 28_798_450 + 0xc5, 0xac, 0xa5, 0x01, 0x00, 0x00, 0x00, 0x00, // epoch_us = 27_634_885 + 0x14, 0x00, 0x00, 0x00, // sequence = 20 + 0x00, 0x00, 0x00, 0x00, // reserved + ]; + let decoded = SyncPacket::from_bytes(&canonical).unwrap(); + assert_eq!(decoded.node_id, 9); + assert_eq!(decoded.proto_ver, 1); + assert_eq!(decoded.flags.to_byte(), 0x06); + assert!(!decoded.flags.is_leader); + assert!(decoded.flags.is_valid); + assert!(decoded.flags.smoothed_used); + assert_eq!(decoded.local_us, 28_798_450); + assert_eq!(decoded.epoch_us, 27_634_885); + assert_eq!(decoded.sequence, 20); + // §A0.10's measured 1.16-second boot delta. + assert_eq!(decoded.local_minus_epoch_us(), 1_163_565); + + // Round-trip: re-encoding the decoded struct must produce the same + // canonical bytes — this is what catches any drift in to_bytes. + let re_encoded = decoded.to_bytes(); + assert_eq!(re_encoded, canonical, + "Rust to_bytes drifted from the canonical pin — Python decoder will break"); + } +} diff --git a/v2/crates/wifi-densepose-sensing-server/Cargo.toml b/v2/crates/wifi-densepose-sensing-server/Cargo.toml index 0f21baf9..fed20336 100644 --- a/v2/crates/wifi-densepose-sensing-server/Cargo.toml +++ b/v2/crates/wifi-densepose-sensing-server/Cargo.toml @@ -50,6 +50,9 @@ wifi-densepose-wifiscan = { version = "0.3.0", path = "../wifi-densepose-wifisca # build without vcpkg/openblas (issue #366, #415). wifi-densepose-signal = { version = "0.3.0", path = "../wifi-densepose-signal", default-features = false } +# Hardware crate — SyncPacket decoder for ADR-110 §A0.12 mesh-aligned timestamps. +wifi-densepose-hardware = { version = "0.3.0", path = "../wifi-densepose-hardware" } + # midstream — real-time introspection / low-latency tap (ADR-099 D1). # Two crates only, on purpose: scheduler / neural-solver / strange-loop are # explicitly out of scope of ADR-099 (D5). @@ -65,6 +68,26 @@ ureq = { version = "2", default-features = false, features = ["tls", "json" sha2 = "0.10" thiserror = "1" +# ADR-115 §3.8 — MQTT publisher (HA-DISCO). +# Gated behind the `mqtt` feature so the default binary stays small for users +# who don't need Home Assistant integration. `rumqttc` is the chosen Rust MQTT +# client (ADR-115 §10 references). `rustls` is preferred over openssl on +# Windows to keep parity with the rest of the workspace (`ureq` above also +# uses rustls). +rumqttc = { version = "0.24", default-features = false, features = ["use-rustls"], optional = true } + +[features] +default = [] +# Enables the ADR-115 §2 MQTT auto-discovery publisher. Without this feature +# all `--mqtt-*` CLI flags still parse (cli.rs declares them unconditionally), +# but enabling `--mqtt` at runtime logs a `WARN` and the publisher is a no-op. +mqtt = ["dep:rumqttc"] +# ADR-115 §3.11 — Matter Bridge (HA-FABRIC). Same gating principle: flags +# parse unconditionally; the bridge is a no-op without this feature. +# matter-rs is added in P7; intentionally absent in P1 to keep the dep +# surface small until the SDK choice is validated. +matter = [] + [dev-dependencies] tempfile = "3.10" # `tower::ServiceExt::oneshot` for in-process Router tests (bearer_auth). diff --git a/v2/crates/wifi-densepose-sensing-server/src/cli.rs b/v2/crates/wifi-densepose-sensing-server/src/cli.rs index 6a8844a3..0a773626 100644 --- a/v2/crates/wifi-densepose-sensing-server/src/cli.rs +++ b/v2/crates/wifi-densepose-sensing-server/src/cli.rs @@ -102,4 +102,216 @@ pub struct Args { /// Start field model calibration on boot (empty room required) #[arg(long)] pub calibrate: bool, + + // ─── ADR-115 §3.8 — MQTT publisher (HA-DISCO) ────────────────────────── + /// Enable MQTT publisher with HA auto-discovery + #[arg(long, env = "RUVIEW_MQTT")] + pub mqtt: bool, + + /// MQTT broker host + #[arg(long, env = "RUVIEW_MQTT_HOST", default_value = "localhost")] + pub mqtt_host: String, + + /// MQTT broker port (defaults: 1883 plain / 8883 with TLS) + #[arg(long, env = "RUVIEW_MQTT_PORT")] + pub mqtt_port: Option, + + /// MQTT username + #[arg(long, env = "RUVIEW_MQTT_USERNAME")] + pub mqtt_username: Option, + + /// Environment variable holding the MQTT password + #[arg(long, default_value = "MQTT_PASSWORD")] + pub mqtt_password_env: String, + + /// MQTT client ID (default: wifi-densepose-) + #[arg(long, env = "RUVIEW_MQTT_CLIENT_ID")] + pub mqtt_client_id: Option, + + /// Discovery topic prefix (ADR-115 §9.2 — accepted: `homeassistant`) + #[arg(long, env = "RUVIEW_MQTT_PREFIX", default_value = "homeassistant")] + pub mqtt_prefix: String, + + /// Enable TLS to the broker + #[arg(long, env = "RUVIEW_MQTT_TLS")] + pub mqtt_tls: bool, + + /// CA bundle for TLS + #[arg(long, value_name = "PATH")] + pub mqtt_ca_file: Option, + + /// Client certificate for mTLS + #[arg(long, value_name = "PATH")] + pub mqtt_client_cert: Option, + + /// Client key for mTLS + #[arg(long, value_name = "PATH")] + pub mqtt_client_key: Option, + + /// Discovery refresh interval (seconds) + #[arg(long, default_value = "600")] + pub mqtt_refresh_secs: u64, + + /// Vitals publish rate (Hz) — HR/BR + #[arg(long, default_value = "0.2")] + pub mqtt_rate_vitals: f64, + + /// Motion publish rate (Hz) + #[arg(long, default_value = "1.0")] + pub mqtt_rate_motion: f64, + + /// Person count publish rate (Hz) + #[arg(long, default_value = "1.0")] + pub mqtt_rate_count: f64, + + /// RSSI publish rate (Hz) + #[arg(long, default_value = "0.1")] + pub mqtt_rate_rssi: f64, + + /// Publish pose keypoints over MQTT (off by default for bandwidth) + #[arg(long)] + pub mqtt_publish_pose: bool, + + /// Pose publish rate (Hz) when --mqtt-publish-pose is set + #[arg(long, default_value = "1.0")] + pub mqtt_rate_pose: f64, + + // ─── ADR-115 §3.10 — Privacy mode ────────────────────────────────────── + /// Strip biometrics (HR/BR/pose) before any MQTT or Matter publish. + /// Discovery for those entities is suppressed entirely — the controller + /// never sees them exist. Implements the ADR-106 primitive-isolation + /// contract at the integration boundary. + #[arg(long, env = "RUVIEW_PRIVACY_MODE")] + pub privacy_mode: bool, + + // ─── ADR-115 §3.11 — Matter Bridge (HA-FABRIC) ───────────────────────── + /// Enable Matter Bridge + #[arg(long, env = "RUVIEW_MATTER")] + pub matter: bool, + + /// Write Matter setup code + QR string to this file on first start + #[arg(long, value_name = "PATH")] + pub matter_setup_file: Option, + + /// Wipe stored Matter fabric credentials before starting + #[arg(long)] + pub matter_reset: bool, + + /// Matter vendor ID (default: dev VID 0xFFF1 per ADR-115 §9.9) + #[arg(long, default_value = "0xFFF1")] + pub matter_vendor_id: String, + + /// Matter product ID (default: 0x8001) + #[arg(long, default_value = "0x8001")] + pub matter_product_id: String, + + // ─── ADR-115 §3.12 — Semantic Inference (HA-MIND) ───────────────────── + /// Enable semantic inference layer (sleeping/distress/room-active/etc). + /// Default ON — primitives are the primary product surface. + #[arg(long, default_value_t = true)] + pub semantic: bool, + + /// Per-primitive thresholds file + #[arg(long, value_name = "PATH")] + pub semantic_thresholds_file: Option, + + /// Zone-tag map (e.g. {"bathroom": ["zone_3"]}) + #[arg(long, value_name = "PATH")] + pub semantic_zones_file: Option, + + /// Days of history for personalised baselines + #[arg(long, default_value = "14")] + pub semantic_baseline_window_days: u32, + + /// Disable a specific semantic primitive (e.g. `sleeping`); repeatable. + /// Valid names: sleeping, distress, room_active, elderly_anomaly, + /// meeting, bathroom, fall_risk, bed_exit, no_movement, multi_room. + #[arg(long = "no-semantic", value_name = "PRIMITIVE")] + pub no_semantic: Vec, +} + +#[cfg(test)] +mod tests { + use super::*; + use clap::Parser; + + /// MQTT flags default safely (disabled). + #[test] + fn mqtt_defaults_disabled() { + let args = Args::parse_from(["sensing-server"]); + assert!(!args.mqtt, "--mqtt must default to false"); + assert_eq!(args.mqtt_host, "localhost"); + assert_eq!(args.mqtt_prefix, "homeassistant"); + assert_eq!(args.mqtt_refresh_secs, 600); + assert_eq!(args.mqtt_rate_vitals, 0.2); + assert_eq!(args.mqtt_rate_motion, 1.0); + assert_eq!(args.mqtt_rate_count, 1.0); + assert_eq!(args.mqtt_rate_rssi, 0.1); + assert!(!args.mqtt_publish_pose); + assert_eq!(args.mqtt_rate_pose, 1.0); + assert!(!args.mqtt_tls); + assert!(args.mqtt_username.is_none()); + assert!(args.mqtt_port.is_none()); + } + + #[test] + fn privacy_mode_defaults_off() { + let args = Args::parse_from(["sensing-server"]); + assert!(!args.privacy_mode); + } + + #[test] + fn matter_defaults_off_dev_vid() { + let args = Args::parse_from(["sensing-server"]); + assert!(!args.matter); + assert_eq!(args.matter_vendor_id, "0xFFF1"); + assert_eq!(args.matter_product_id, "0x8001"); + } + + #[test] + fn semantic_defaults_on() { + let args = Args::parse_from(["sensing-server"]); + assert!(args.semantic); + assert!(args.no_semantic.is_empty()); + assert_eq!(args.semantic_baseline_window_days, 14); + } + + #[test] + fn mqtt_all_flags_compose() { + let args = Args::parse_from([ + "sensing-server", + "--mqtt", + "--mqtt-host", "broker.example.com", + "--mqtt-port", "8883", + "--mqtt-username", "ruview", + "--mqtt-prefix", "homeassistant", + "--mqtt-tls", + "--mqtt-refresh-secs", "300", + "--mqtt-rate-vitals", "0.5", + "--mqtt-publish-pose", + "--mqtt-rate-pose", "2.0", + "--privacy-mode", + ]); + assert!(args.mqtt); + assert_eq!(args.mqtt_host, "broker.example.com"); + assert_eq!(args.mqtt_port, Some(8883)); + assert_eq!(args.mqtt_username.as_deref(), Some("ruview")); + assert!(args.mqtt_tls); + assert_eq!(args.mqtt_refresh_secs, 300); + assert_eq!(args.mqtt_rate_vitals, 0.5); + assert!(args.mqtt_publish_pose); + assert_eq!(args.mqtt_rate_pose, 2.0); + assert!(args.privacy_mode); + } + + #[test] + fn no_semantic_repeatable() { + let args = Args::parse_from([ + "sensing-server", + "--no-semantic", "sleeping", + "--no-semantic", "meeting", + "--no-semantic", "fall_risk", + ]); + assert_eq!(args.no_semantic, vec!["sleeping", "meeting", "fall_risk"]); + } } diff --git a/v2/crates/wifi-densepose-sensing-server/src/main.rs b/v2/crates/wifi-densepose-sensing-server/src/main.rs index 58fdb84e..03e459ea 100644 --- a/v2/crates/wifi-densepose-sensing-server/src/main.rs +++ b/v2/crates/wifi-densepose-sensing-server/src/main.rs @@ -288,6 +288,46 @@ struct NodeInfo { position: [f64; 3], amplitude: Vec, subcarrier_count: usize, + /// ADR-110 iter 23 — cross-board sync snapshot for this node. + /// `None` when no fresh sync packet has been observed (no mesh peer + /// reachable, or this node is a singleton). Populated from + /// `NodeState::latest_sync` and the iter 18 fps EMA. + #[serde(skip_serializing_if = "Option::is_none")] + sync: Option, +} + +/// ADR-110 iter 23 — per-node mesh-sync snapshot embedded in NodeInfo. +/// Surfaces what was previously only visible in the debug log so UI clients +/// can render leader / follower / offset / measured-fps live. +#[derive(Debug, Clone, Serialize, Deserialize)] +struct NodeSyncSnapshot { + /// Smoothed local-vs-mesh offset in µs (negative when this node's clock + /// is behind the leader's — see §A0.10's measured -1.16 s on the bench). + offset_us: i64, + /// True when this node is the elected mesh leader. + is_leader: bool, + /// True when this node has heard a fresh leader beacon within the + /// firmware's VALID_WINDOW_MS gate (3 s). + is_valid: bool, + /// True once the EMA-smoothed offset has seeded (one full beacon round-trip). + smoothed: bool, + /// Sync packet's sequence high-water — used by the host to pair CSI + /// frames against this snapshot for §A0.12 mesh-time recovery. + sequence: u32, + /// Per-node measured CSI frame rate (iter 18 EMA). 20.0 until the + /// EMA has at least 5 samples; the actually-observed rate after that. + csi_fps_ema: f64, + /// How many CSI frames have contributed to `csi_fps_ema`. Clients can + /// treat <5 as "not yet trustworthy" and fall back to 20 Hz. + csi_fps_samples: u32, + /// ADR-110 iter 34 — milliseconds since the host last received a sync + /// packet from this node. Lets UI dashboards render sync-age decay + /// (badge fades after 5 s, drops off after the 9 s mesh_aligned_us + /// staleness gate). `None` only when the host never had Instant data + /// for this node, which shouldn't happen in normal flow but is + /// modeled defensively. + #[serde(skip_serializing_if = "Option::is_none")] + staleness_ms: Option, } #[derive(Debug, Clone, Serialize, Deserialize)] @@ -366,6 +406,19 @@ struct NodeState { latest_vitals: VitalSigns, pub(crate) last_frame_time: Option, edge_vitals: Option, + /// ADR-110 §A0.12: Latest sync packet received from this node. When a + /// CSI frame arrives with byte 19 bit 4 set (`adr018_flags.ieee802154_sync_valid`), + /// the host can recover a mesh-aligned timestamp via + /// `latest_sync.epoch_us + (now_local - latest_sync.local_us)`. + latest_sync: Option, + /// Last time a sync packet from this node was received (for staleness). + latest_sync_at: Option, + /// ADR-110 iter 18: EMA-tracked CSI frame rate for this node. + /// Replaces the hardcoded 20 Hz fallback in + /// `mesh_aligned_us_for_csi_frame` once `csi_fps_samples ≥ 5`. + csi_fps_ema: f64, + /// Number of inter-frame deltas observed (need ≥5 before trusting EMA). + csi_fps_samples: u32, /// Latest extracted features for cross-node fusion. latest_features: Option, // ── RuVector Phase 2: Temporal smoothing & coherence gating ── @@ -406,7 +459,149 @@ const NOVELTY_HISTORY_CAPACITY: usize = 64; /// subcarrier ordering / normalisation so banks reject stale data. const NOVELTY_SKETCH_VERSION: u16 = 1; +/// ADR-110 iter 18 — EMA update for per-node CSI fps tracking. +/// +/// Returns the new EMA value, or `None` if the delta is implausible +/// (≤ 0, or > 1 second — likely a connection gap, not a real frame +/// rate sample). α = 1/8 fixed shift, ~8-sample effective window, +/// matching the firmware-side ESP-NOW offset smoother in §A0.10. +/// +/// Free function for testability — every transformation that doesn't +/// touch the rest of `NodeState` lives outside the `impl` block. +pub(crate) fn update_csi_fps_ema(prev_fps: f64, dt_sec: f64) -> Option { + if !(dt_sec > 0.0 && dt_sec < 1.0) { + return None; + } + let instantaneous = 1.0 / dt_sec; + // y[n] = y[n-1] + (x - y[n-1]) / 8 + Some(prev_fps + (instantaneous - prev_fps) / 8.0) +} + +#[cfg(test)] +mod fps_ema_tests { + use super::update_csi_fps_ema; + + #[test] + fn steady_10hz_converges_toward_10() { + let mut fps = 20.0; + for _ in 0..40 { + fps = update_csi_fps_ema(fps, 0.100).unwrap(); + } + assert!((fps - 10.0).abs() < 0.1, + "expected ~10 Hz after 40 samples at 100 ms intervals, got {fps}"); + } + + #[test] + fn steady_20hz_stays_near_20() { + let mut fps = 20.0; + for _ in 0..20 { + fps = update_csi_fps_ema(fps, 0.050).unwrap(); + } + assert!((fps - 20.0).abs() < 0.05, "expected ~20 Hz, got {fps}"); + } + + #[test] + fn nonpositive_dt_rejected() { + assert!(update_csi_fps_ema(15.0, 0.0).is_none()); + assert!(update_csi_fps_ema(15.0, -0.1).is_none()); + } + + #[test] + fn long_gap_rejected_as_implausible() { + assert!(update_csi_fps_ema(20.0, 2.0).is_none()); + } +} + impl NodeState { + /// ADR-110 §A0.12 timestamp recovery: given a CSI frame's node-local + /// `esp_timer_get_time()` snapshot, return the mesh-aligned epoch + /// computed from this node's most recent sync packet — or `None` + /// if no sync has been received yet, or the last one is too stale + /// (older than 3 × VALID_WINDOW_MS = 9 s, matching the firmware's own + /// staleness gate). + pub(crate) fn mesh_aligned_us(&self, local_at_frame_us: u64) -> Option { + let sync = self.latest_sync.as_ref()?; + let seen_at = self.latest_sync_at?; + // Drop stale syncs — firmware emits at ~0.5 Hz default, anything + // older than 9 s likely means the mesh transport dropped. + if seen_at.elapsed() > std::time::Duration::from_secs(9) { + return None; + } + Some(sync.apply_to_local(local_at_frame_us)) + } + + /// ADR-110 §A0.12 sequence-based mesh-time recovery for an in-flight + /// ADR-018 CSI frame. The frame carries no `local_us` (the wire + /// format has no slot), but it carries a sequence number that the + /// sync packet's `sequence` high-water can be paired against. Uses + /// 20 Hz as the default CSI rate (the firmware's + /// `CSI_MIN_SEND_INTERVAL_US`-implied ceiling). Returns `None` if + /// no fresh sync has been observed for this node. + pub(crate) fn mesh_aligned_us_for_csi_frame(&self, frame_sequence: u32) -> Option { + let sync = self.latest_sync.as_ref()?; + let seen_at = self.latest_sync_at?; + if seen_at.elapsed() > std::time::Duration::from_secs(9) { + return None; + } + // Iter 18: use the measured per-node fps once we have ≥5 inter-frame + // samples; until then fall back to the 20 Hz firmware ceiling. The + // §A0.12 capture showed real bench fps ≈ 10, so the measured value + // is significantly more accurate than the constant fallback. + let fps = if self.csi_fps_samples >= 5 { self.csi_fps_ema } else { 20.0 }; + Some(sync.mesh_aligned_us_for_sequence(frame_sequence, fps)) + } + + /// ADR-110 iter 18 — update the per-node observed-fps EMA from a fresh + /// CSI frame arrival. Call once per accepted CSI frame from + /// `udp_receiver_task`. Uses `last_frame_time` as the previous-frame + /// anchor; the first frame after init seeds the timer without producing + /// a sample (no prior dt to measure). + /// ADR-110 iter 32 — apply a freshly-decoded sync packet to this node. + /// Overwrites `latest_sync` with the new packet and stamps + /// `latest_sync_at` so the staleness gate in `mesh_aligned_us_for_csi_frame` + /// can age it out after 9 s. Used by `udp_receiver_task` on every + /// successful magic-dispatched sync datagram; extracted so the dispatch + /// path is testable without spinning up the tokio UDP socket. + pub(crate) fn apply_sync_packet( + &mut self, + pkt: wifi_densepose_hardware::SyncPacket, + now: std::time::Instant, + ) { + self.latest_sync = Some(pkt); + self.latest_sync_at = Some(now); + } + + /// ADR-110 iter 30 — pure snapshot of this node's mesh-sync state. + /// Returns `None` when no sync packet has been observed. Used by both + /// the WebSocket broadcaster (iter 23) and the REST handlers (iter 29); + /// extracted here so tests can build a `NodeState`, populate + /// `latest_sync`, and assert the snapshot shape without spinning up + /// the axum router. + pub(crate) fn sync_snapshot(&self) -> Option { + let sync = self.latest_sync.as_ref()?; + Some(NodeSyncSnapshot { + offset_us: sync.local_minus_epoch_us(), + is_leader: sync.flags.is_leader, + is_valid: sync.flags.is_valid, + smoothed: sync.flags.smoothed_used, + sequence: sync.sequence, + csi_fps_ema: self.csi_fps_ema, + csi_fps_samples: self.csi_fps_samples, + staleness_ms: self.latest_sync_at.map(|t| t.elapsed().as_millis() as u64), + }) + } + + pub(crate) fn observe_csi_frame_arrival(&mut self, now: std::time::Instant) { + if let Some(prev) = self.last_frame_time { + let dt = now.duration_since(prev).as_secs_f64(); + if let Some(new_ema) = update_csi_fps_ema(self.csi_fps_ema, dt) { + self.csi_fps_ema = new_ema; + self.csi_fps_samples = self.csi_fps_samples.saturating_add(1); + } + } + self.last_frame_time = Some(now); + } + pub(crate) fn new() -> Self { Self { frame_history: VecDeque::new(), @@ -429,6 +624,10 @@ impl NodeState { latest_vitals: VitalSigns::default(), last_frame_time: None, edge_vitals: None, + latest_sync: None, + latest_sync_at: None, + csi_fps_ema: 20.0, + csi_fps_samples: 0, latest_features: None, prev_keypoints: None, motion_energy_history: VecDeque::with_capacity(COHERENCE_WINDOW), @@ -2007,6 +2206,7 @@ async fn windows_wifi_task(state: SharedState, tick_ms: u64) { position: [0.0, 0.0, 0.0], amplitude: multi_ap_frame.amplitudes, subcarrier_count: obs_count, + sync: None, // multi-BSSID scan path — no mesh peer }], features, classification, @@ -2162,6 +2362,7 @@ async fn windows_wifi_fallback_tick(state: &SharedState, seq: u32) { position: [0.0, 0.0, 0.0], amplitude: vec![signal_pct], subcarrier_count: 1, + sync: None, // synthetic-RSSI fallback path — no mesh peer }], features, classification, @@ -4127,6 +4328,145 @@ async fn sona_activate( } /// GET /api/v1/nodes — per-node health and feature info. +/// ADR-110 iter 29 — per-node mesh sync snapshot via HTTP. +/// +/// GET /api/v1/nodes/:id/sync +/// 200 → Json(NodeSyncSnapshot) when latest_sync is present +/// 404 → {"error": "no_sync", "node_id": N} otherwise +/// +/// Complements the WebSocket `sync` field (iter 23) for clients that +/// can't hold a streaming connection (curl scripts, Home Assistant REST +/// sensors, automation rule probes). +async fn node_sync_endpoint( + State(state): State, + Path(id): Path, +) -> Result, (StatusCode, Json)> { + let s = state.read().await; + let ns = s.node_states.get(&id).ok_or_else(|| { + (StatusCode::NOT_FOUND, Json(serde_json::json!({ + "error": "unknown_node", "node_id": id, + }))) + })?; + ns.sync_snapshot().map(Json).ok_or_else(|| { + (StatusCode::NOT_FOUND, Json(serde_json::json!({ + "error": "no_sync", "node_id": id, + "hint": "node hasn't emitted a sync packet yet (no mesh peer or not v0.6.9+)", + }))) + }) +} + +/// ADR-110 iter 29 — fleet-wide mesh state via HTTP. +/// +/// GET /api/v1/mesh +/// 200 → { "nodes": { "": NodeSyncSnapshot, ... }, "total": N } +/// Nodes without a recent sync are omitted from the map; an empty +/// `nodes` object means no mesh peers reachable. +/// ADR-110 iter 36 — Prometheus exposition format for mesh state. +/// +/// GET /api/v1/mesh/metrics → text/plain +/// wifi_densepose_mesh_offset_us{node="N"} +/// wifi_densepose_mesh_is_leader{node="N"} 0|1 +/// wifi_densepose_mesh_is_valid{node="N"} 0|1 +/// wifi_densepose_mesh_smoothed{node="N"} 0|1 +/// wifi_densepose_mesh_sequence{node="N"} +/// wifi_densepose_mesh_csi_fps{node="N"} +/// wifi_densepose_mesh_csi_fps_samples{node="N"} +/// wifi_densepose_mesh_staleness_ms{node="N"} +/// +/// Spec: . +/// Each metric is a gauge labeled by node_id. Nodes without a fresh sync +/// are simply absent from the output (Prometheus handles missing series +/// natively — the scrape just reports them as stale after the configured +/// staleness duration). +async fn mesh_metrics_endpoint(State(state): State) -> impl IntoResponse { + use std::fmt::Write; + let s = state.read().await; + let mut body = String::with_capacity(1024); + + // Each metric: HELP + TYPE header + one line per node that has a snapshot. + let metrics: &[(&str, &str, &str)] = &[ + ("wifi_densepose_mesh_offset_us", + "Cross-board mesh-aligned offset, microseconds (signed)", "gauge"), + ("wifi_densepose_mesh_is_leader", + "1 if this node is the elected mesh leader, else 0", "gauge"), + ("wifi_densepose_mesh_is_valid", + "1 if this node has heard a fresh leader beacon, else 0", "gauge"), + ("wifi_densepose_mesh_smoothed", + "1 once the firmware-side EMA filter has seeded, else 0", "gauge"), + ("wifi_densepose_mesh_sequence", + "High-water CSI sequence at sync emit time", "gauge"), + ("wifi_densepose_mesh_csi_fps", + "Per-node measured CSI frame rate (Hz)", "gauge"), + ("wifi_densepose_mesh_csi_fps_samples", + "How many inter-frame deltas the fps EMA has seen", "gauge"), + ("wifi_densepose_mesh_staleness_ms", + "Milliseconds since the host last received this node's sync packet", "gauge"), + ]; + + // Collect (id, snapshot) pairs once so each metric loop reads the same set. + let snaps: Vec<(u8, NodeSyncSnapshot)> = s.node_states.iter() + .filter_map(|(&id, ns)| ns.sync_snapshot().map(|snap| (id, snap))) + .collect(); + + // Iter 37: fleet cardinality summary — Ops dashboards want the + // "how many leaders / followers / no-sync" tally at a glance + // without scraping every per-node series and counting. + let (leaders, followers) = fleet_role_counts(&snaps); + let no_sync = s.node_states.len().saturating_sub(snaps.len()) as u64; + let _ = writeln!(body, + "# HELP wifi_densepose_mesh_node_total Per-state node count across the fleet"); + let _ = writeln!(body, "# TYPE wifi_densepose_mesh_node_total gauge"); + let _ = writeln!(body, "wifi_densepose_mesh_node_total{{state=\"leader\"}} {leaders}"); + let _ = writeln!(body, "wifi_densepose_mesh_node_total{{state=\"follower\"}} {followers}"); + let _ = writeln!(body, "wifi_densepose_mesh_node_total{{state=\"no_sync\"}} {no_sync}"); + + for (name, help, kind) in metrics { + let _ = writeln!(body, "# HELP {name} {help}"); + let _ = writeln!(body, "# TYPE {name} {kind}"); + for (id, snap) in &snaps { + let value = match *name { + "wifi_densepose_mesh_offset_us" => snap.offset_us.to_string(), + "wifi_densepose_mesh_is_leader" => bool_metric(snap.is_leader), + "wifi_densepose_mesh_is_valid" => bool_metric(snap.is_valid), + "wifi_densepose_mesh_smoothed" => bool_metric(snap.smoothed), + "wifi_densepose_mesh_sequence" => snap.sequence.to_string(), + "wifi_densepose_mesh_csi_fps" => format!("{:.3}", snap.csi_fps_ema), + "wifi_densepose_mesh_csi_fps_samples" => snap.csi_fps_samples.to_string(), + "wifi_densepose_mesh_staleness_ms" => + snap.staleness_ms.map(|n| n.to_string()).unwrap_or_else(|| "0".into()), + _ => continue, + }; + let _ = writeln!(body, "{name}{{node=\"{id}\"}} {value}"); + } + } + ([(axum::http::header::CONTENT_TYPE, "text/plain; version=0.0.4")], body) +} + +fn bool_metric(b: bool) -> String { (if b { 1 } else { 0 }).to_string() } + +/// ADR-110 iter 37 — count (leaders, followers) in a populated snapshot set. +/// Free function for testability — same pattern as iter 18's `update_csi_fps_ema`. +pub(crate) fn fleet_role_counts(snaps: &[(u8, NodeSyncSnapshot)]) -> (u64, u64) { + let leaders = snaps.iter().filter(|(_, s)| s.is_leader).count() as u64; + let followers = (snaps.len() as u64).saturating_sub(leaders); + (leaders, followers) +} + +async fn mesh_endpoint(State(state): State) -> Json { + let s = state.read().await; + let mut nodes = serde_json::Map::new(); + for (&id, ns) in s.node_states.iter() { + if let Some(snap) = ns.sync_snapshot() { + nodes.insert(id.to_string(), serde_json::to_value(snap).unwrap()); + } + } + let total = nodes.len(); + Json(serde_json::json!({ + "nodes": serde_json::Value::Object(nodes), + "total": total, + })) +} + async fn nodes_endpoint(State(state): State) -> Json { let s = state.read().await; let now = std::time::Instant::now(); @@ -4316,6 +4656,9 @@ async fn udp_receiver_task(state: SharedState, udp_port: u16) { position: [2.0, 0.0, 1.5], amplitude: vec![], subcarrier_count: 0, + // Vitals-only path; still expose the sync snapshot + // if the node also speaks ESP-NOW. + sync: n.sync_snapshot(), }) .collect(); @@ -4432,6 +4775,37 @@ async fn udp_receiver_task(state: SharedState, udp_port: u16) { continue; } + // ADR-110 §A0.12: Try sync packet (magic 0xC511_A110). + // A 32-byte UDP datagram carrying mesh-aligned epoch + sequence + // high-water from the node's c6_sync_espnow EMA-smoothed offset. + // Stored per-node so subsequent CSI frames with byte 19 bit 4 + // set can have an aligned timestamp recovered downstream. + if len >= wifi_densepose_hardware::SYNC_PACKET_SIZE { + let magic = u32::from_le_bytes([buf[0], buf[1], buf[2], buf[3]]); + if magic == wifi_densepose_hardware::SYNC_PACKET_MAGIC { + match wifi_densepose_hardware::SyncPacket::from_bytes(&buf[..len]) { + Ok(sync) => { + debug!("ESP32 sync from {src}: node={} leader={} valid={} smoothed={} \ + seq={} offset_us={}", + sync.node_id, sync.flags.is_leader, sync.flags.is_valid, + sync.flags.smoothed_used, sync.sequence, + sync.local_minus_epoch_us()); + let mut s = state.write().await; + let node_id = sync.node_id; + let ns = s.node_states.entry(node_id) + .or_insert_with(NodeState::new); + ns.apply_sync_packet(sync, std::time::Instant::now()); + continue; + } + Err(e) => { + debug!("Sync packet decode error from {src}: {e}"); + // Fall through — magic matched but decode failed; not a CSI frame. + continue; + } + } + } + } + // ADR-040: Try WASM output packet (magic 0xC511_0004). if let Some(wasm_output) = parse_wasm_output(&buf[..len]) { debug!( @@ -4506,7 +4880,10 @@ async fn udp_receiver_task(state: SharedState, udp_port: u16) { let adaptive_model_clone = s.adaptive_model.clone(); let ns = s.node_states.entry(node_id).or_insert_with(NodeState::new); - ns.last_frame_time = Some(std::time::Instant::now()); + // ADR-110 iter 19 — feed the per-node fps EMA from real + // CSI arrivals. The helper sets `last_frame_time` as a + // side effect, so the previous bare assignment is gone. + ns.observe_csi_frame_arrival(std::time::Instant::now()); // ADR-084 Pass 3: cluster-Pi novelty sensor. // Score this frame's feature vector against the per-node @@ -4659,6 +5036,8 @@ async fn udp_receiver_task(state: SharedState, udp_port: u16) { .map(|a| a.iter().take(56).cloned().collect()) .unwrap_or_default(), subcarrier_count: n.frame_history.back().map_or(0, |a| a.len()), + // ADR-110 iter 23 / iter 30 — single source of truth. + sync: n.sync_snapshot(), }) .collect(); @@ -4821,6 +5200,7 @@ async fn simulated_data_task(state: SharedState, tick_ms: u64) { position: [2.0, 0.0, 1.5], amplitude: frame_amplitudes, subcarrier_count: frame_n_sub as usize, + sync: None, // simulated frame path — no mesh peer }], features: features.clone(), classification, @@ -5800,6 +6180,10 @@ async fn main() { .route("/api/v1/sensing/latest", get(latest)) // Per-node health endpoint .route("/api/v1/nodes", get(nodes_endpoint)) + // ADR-110 iter 29 — per-node mesh sync state for HTTP clients. + .route("/api/v1/nodes/:id/sync", get(node_sync_endpoint)) + .route("/api/v1/mesh", get(mesh_endpoint)) + .route("/api/v1/mesh/metrics", get(mesh_metrics_endpoint)) // Vital sign endpoints .route("/api/v1/vital-signs", get(vital_signs_endpoint)) .route("/api/v1/edge-vitals", get(edge_vitals_endpoint)) @@ -5946,6 +6330,272 @@ async fn main() { info!("Server shut down cleanly"); } +#[cfg(test)] +mod node_sync_snapshot_serialization_tests { + //! ADR-110 iter 24 — JSON public-API contract for the iter 23 + //! NodeSyncSnapshot field. Any future rename / removal here must be + //! intentional and update both Rust + UI/automation consumers. + + use super::*; + + fn sample_sync() -> NodeSyncSnapshot { + NodeSyncSnapshot { + offset_us: 1_163_565, + is_leader: false, + is_valid: true, + smoothed: true, + sequence: 20, + csi_fps_ema: 10.0, + csi_fps_samples: 47, + staleness_ms: Some(120), + } + } + + fn sample_node(sync: Option) -> NodeInfo { + NodeInfo { + node_id: 9, + rssi_dbm: -38.0, + position: [2.0, 0.0, 1.5], + amplitude: vec![], + subcarrier_count: 0, + sync, + } + } + + #[test] + fn sync_present_serializes_all_seven_fields() { + let v = serde_json::to_value(sample_node(Some(sample_sync()))).unwrap(); + let s = v.get("sync").expect("sync key must be present"); + // All eight contract fields named exactly as iter 23/34 documented. + for key in ["offset_us", "is_leader", "is_valid", "smoothed", + "sequence", "csi_fps_ema", "csi_fps_samples", + "staleness_ms"] { + assert!(s.get(key).is_some(), + "sync object missing field `{}` — UI contract broken", key); + } + // Spot-check values round-trip. + assert_eq!(s["offset_us"], 1_163_565); + assert_eq!(s["is_leader"], false); + assert_eq!(s["sequence"], 20); + assert_eq!(s["csi_fps_samples"], 47); + } + + #[test] + fn sync_absent_omits_the_key_entirely() { + // skip_serializing_if = "Option::is_none" must drop the key, not + // emit `"sync": null`. The non-mesh paths rely on this for + // backwards compatibility with pre-iter-23 UI clients. + let v = serde_json::to_value(sample_node(None)).unwrap(); + assert!(v.get("sync").is_none(), + "expected `sync` key omitted when None, got {:?}", v.get("sync")); + // The base NodeInfo fields are still there. + assert_eq!(v["node_id"], 9); + assert_eq!(v["rssi_dbm"], -38.0); + } + + #[test] + fn sync_round_trips_through_serde() { + let original = sample_node(Some(sample_sync())); + let json = serde_json::to_string(&original).unwrap(); + let parsed: NodeInfo = serde_json::from_str(&json).unwrap(); + // Field-level equality on the sync sub-object. + let s_orig = original.sync.unwrap(); + let s_parsed = parsed.sync.expect("sync should survive round-trip"); + assert_eq!(s_parsed.offset_us, s_orig.offset_us); + assert_eq!(s_parsed.is_leader, s_orig.is_leader); + assert_eq!(s_parsed.is_valid, s_orig.is_valid); + assert_eq!(s_parsed.smoothed, s_orig.smoothed); + assert_eq!(s_parsed.sequence, s_orig.sequence); + assert!((s_parsed.csi_fps_ema - s_orig.csi_fps_ema).abs() < 1e-9); + assert_eq!(s_parsed.csi_fps_samples, s_orig.csi_fps_samples); + } +} + +#[cfg(test)] +mod sync_snapshot_helper_tests { + //! ADR-110 iter 30 — covers the pure helper that backs both + //! `/api/v1/nodes/:id/sync` and `/api/v1/mesh` REST endpoints and + //! the WebSocket sensing_update broadcast. Tests at this layer keep + //! the public-API contract honest without spinning up the axum + //! router or constructing a full AppStateInner. + + use super::*; + use wifi_densepose_hardware::{SyncPacket, SyncPacketFlags}; + + fn populated_sync(node_id: u8) -> SyncPacket { + SyncPacket { + node_id, + proto_ver: 1, + flags: SyncPacketFlags { is_leader: false, is_valid: true, smoothed_used: true }, + local_us: 28_798_450, + epoch_us: 27_634_885, + sequence: 20, + } + } + + #[test] + fn fresh_node_with_no_sync_returns_none() { + // Mirrors the REST 404 "no_sync" branch. + let ns = NodeState::new(); + assert!(ns.sync_snapshot().is_none()); + } + + #[test] + fn node_with_latest_sync_produces_correct_snapshot() { + // Mirrors the REST 200 OK branch + the WebSocket sync field. + let mut ns = NodeState::new(); + ns.latest_sync = Some(populated_sync(9)); + ns.latest_sync_at = Some(std::time::Instant::now()); + // Pretend the fps EMA has settled (iter 18 5-sample warmup). + ns.csi_fps_ema = 10.5; + ns.csi_fps_samples = 42; + + let snap = ns.sync_snapshot().expect("populated state must produce a snapshot"); + assert_eq!(snap.offset_us, 1_163_565); // §A0.10 measured boot delta + assert!(!snap.is_leader); + assert!(snap.is_valid); + assert!(snap.smoothed); + assert_eq!(snap.sequence, 20); + assert!((snap.csi_fps_ema - 10.5).abs() < 1e-9); + assert_eq!(snap.csi_fps_samples, 42); + } + + #[test] + fn apply_sync_packet_populates_a_fresh_node() { + // Mirrors what udp_receiver_task does on the very first sync + // packet from a previously-unseen node. + let mut ns = NodeState::new(); + assert!(ns.latest_sync.is_none()); + assert!(ns.latest_sync_at.is_none()); + + let now = std::time::Instant::now(); + ns.apply_sync_packet(populated_sync(9), now); + + let sync = ns.latest_sync.as_ref().expect("must be populated"); + assert_eq!(sync.node_id, 9); + assert_eq!(sync.sequence, 20); + // latest_sync_at must be exactly the Instant we passed (no clock skew). + assert_eq!(ns.latest_sync_at, Some(now)); + // sync_snapshot now produces a value (REST 200 OK path). + assert!(ns.sync_snapshot().is_some()); + } + + #[test] + fn apply_sync_packet_overwrites_older_data() { + // Subsequent packets must replace, not accumulate. Otherwise the + // §A0.10-smoothed offset would lag the latest beacon. + let mut ns = NodeState::new(); + let t0 = std::time::Instant::now(); + ns.apply_sync_packet(populated_sync(9), t0); + + // Second packet: same node, advanced sequence + offset. + let mut second = populated_sync(9); + second.sequence = 40; + second.local_us = 30_000_000; + second.epoch_us = 28_834_900; + let t1 = t0 + std::time::Duration::from_secs(2); + ns.apply_sync_packet(second, t1); + + let cur = ns.latest_sync.as_ref().unwrap(); + assert_eq!(cur.sequence, 40); // newer sequence persisted + assert_eq!(cur.local_us, 30_000_000); // newer local persisted + assert_eq!(ns.latest_sync_at, Some(t1)); // staleness clock reset + } + + #[test] + fn snapshot_staleness_ms_tracks_apply_time() { + // Iter 34: staleness_ms = (Instant::now() - latest_sync_at).as_millis(). + // We can't pass a synthetic "now" through sync_snapshot, but we can + // pin latest_sync_at to a past instant and assert the value lands + // in a plausible window. + let mut ns = NodeState::new(); + ns.latest_sync = Some(populated_sync(9)); + ns.latest_sync_at = std::time::Instant::now() + .checked_sub(std::time::Duration::from_millis(750)); + + let snap = ns.sync_snapshot().unwrap(); + let st = snap.staleness_ms.expect("staleness_ms must be present"); + // Should be approximately 750 ms — give a generous ±500 ms tolerance + // for any test-runner scheduling delay between checked_sub() and + // elapsed() within sync_snapshot. + assert!(st >= 740 && st < 1250, + "expected ~750 ms staleness, got {} ms", st); + } + + #[test] + fn fleet_role_counts_classifies_correctly() { + // Iter 37 — verify the leader/follower split that drives the + // Prometheus `wifi_densepose_mesh_node_total{state=...}` gauge. + // Local fixture rather than reaching across test modules. + fn snap(is_leader: bool) -> NodeSyncSnapshot { + NodeSyncSnapshot { + offset_us: 0, is_leader, is_valid: true, smoothed: true, + sequence: 0, csi_fps_ema: 10.0, csi_fps_samples: 10, + staleness_ms: Some(0), + } + } + assert_eq!(super::fleet_role_counts(&[]), (0, 0)); + let snaps = vec![(12u8, snap(true)), (9, snap(false)), (3, snap(false))]; + assert_eq!(super::fleet_role_counts(&snaps), (1, 2)); + // Edge: all leaders (election would prevent this but gauge math must hold). + assert_eq!(super::fleet_role_counts(&[(1u8, snap(true)), (2, snap(true))]), (2, 0)); + } + + #[test] + fn bool_metric_returns_zero_or_one_as_text() { + // Locks the Prometheus exposition convention: gauges holding a + // boolean state MUST emit literal "0" or "1", never "false"/"true". + // If anyone changes the helper to format!("{}", b), Prometheus will + // 400-reject the scrape — catch it here instead of in production. + assert_eq!(super::bool_metric(true), "1"); + assert_eq!(super::bool_metric(false), "0"); + } + + #[test] + fn mesh_aligned_us_honors_9s_staleness_gate() { + // The receive helper stores latest_sync_at = Instant::now() each + // beacon. mesh_aligned_us_for_csi_frame returns None once that + // Instant is older than 9 s (3 × VALID_WINDOW_MS). Verify both + // sides of that boundary without sleeping — set latest_sync_at + // to past instants directly. + let mut ns = NodeState::new(); + let now = std::time::Instant::now(); + ns.latest_sync = Some(populated_sync(9)); + + // Fresh: 1 s old → should return Some. + ns.latest_sync_at = now.checked_sub(std::time::Duration::from_secs(1)); + assert!(ns.mesh_aligned_us_for_csi_frame(20).is_some(), + "1 s old sync must produce a mesh-aligned timestamp"); + + // Just inside the gate: 8 s old → should still return Some. + ns.latest_sync_at = now.checked_sub(std::time::Duration::from_secs(8)); + assert!(ns.mesh_aligned_us_for_csi_frame(20).is_some(), + "8 s old sync must still be inside the 9 s gate"); + + // Just outside the gate: 10 s old → must return None. + ns.latest_sync_at = now.checked_sub(std::time::Duration::from_secs(10)); + assert!(ns.mesh_aligned_us_for_csi_frame(20).is_none(), + "10 s old sync must trigger the 9 s staleness gate"); + } + + #[test] + fn snapshot_reflects_leader_state() { + // Same data shape that /api/v1/mesh emits for a leader node. + let mut ns = NodeState::new(); + let mut s = populated_sync(12); + s.flags = SyncPacketFlags { is_leader: true, is_valid: true, smoothed_used: false }; + s.local_us = 28_864_932; + s.epoch_us = 28_864_939; // -7 µs delta on the leader + ns.latest_sync = Some(s); + ns.latest_sync_at = Some(std::time::Instant::now()); + + let snap = ns.sync_snapshot().unwrap(); + assert!(snap.is_leader); + assert_eq!(snap.offset_us, -7); // call-stack µs only + assert!(!snap.smoothed); + } +} + #[cfg(test)] mod novelty_tests { use super::*;