History

rUv 5a7f431b0e ADR-081: Implement 5-layer adaptive CSI mesh firmware kernel (#404 ) * ADR-081: adaptive CSI mesh firmware kernel + scaffolding Introduces a 5-layer firmware kernel that reframes the existing ESP32 modules as components of a chipset-agnostic architecture and authorizes adaptive control + a compact feature-state stream as the default upstream. Layers: L1 Radio Abstraction Layer — rv_radio_ops_t vtable + ESP32 binding L2 Adaptive Controller — fast/medium/slow loops (200ms/1s/30s) L3 Mesh Sensing Plane — anchor/observer/relay/coordinator (spec) L4 On-device Feature Extr. — rv_feature_state_t (magic 0xC5110006) L5 Rust handoff — feature_state default; debug raw gated Files: docs/adr/ADR-081-adaptive-csi-mesh-firmware-kernel.md (new) firmware/esp32-csi-node/main/rv_radio_ops.h (new) firmware/esp32-csi-node/main/rv_radio_ops_esp32.c (new) firmware/esp32-csi-node/main/rv_feature_state.{h,c} (new) firmware/esp32-csi-node/main/adaptive_controller.{h,c} (new) firmware/esp32-csi-node/main/main.c (wire L1+L2) firmware/esp32-csi-node/main/CMakeLists.txt (add 4 sources) firmware/esp32-csi-node/main/Kconfig.projbuild (controller knobs) CHANGELOG.md (Unreleased) Default policy is conservative: enable_channel_switch and enable_role_change are off, so behavior matches today's firmware unless an operator opts in via menuconfig. The pure adaptive_controller_decide() is exposed for offline unit tests. Reuses (does not rewrite): csi_collector, edge_processing (ADR-039), swarm_bridge (ADR-066), secure_tdm (ADR-032), wasm_runtime (ADR-040). * ADR-081: implement Layers 1/2/4 end-to-end + host tests + QEMU hooks Turns the ADR-081 scaffolding into a working adaptive CSI mesh kernel: Layer 1 radio abstraction has an ESP32 binding and a mock binding; Layer 2 adaptive controller runs on FreeRTOS timers; Layer 4 feature-state packet is emitted at 5 Hz by default, replacing raw ADR-018 CSI as the default upstream. New files: firmware/esp32-csi-node/main/adaptive_controller_decide.c (pure policy) firmware/esp32-csi-node/main/rv_radio_ops_mock.c (QEMU binding) firmware/esp32-csi-node/tests/host/Makefile (host tests) firmware/esp32-csi-node/tests/host/test_adaptive_controller.c firmware/esp32-csi-node/tests/host/test_rv_feature_state.c firmware/esp32-csi-node/tests/host/esp_err.h (shim) firmware/esp32-csi-node/tests/host/.gitignore Modified: adaptive_controller.c — includes pure decide.c; emit_feature_state() wired into fast loop (200 ms = 5 Hz) rv_radio_ops_esp32.c — get_health() fills pkt_yield + send_fail csi_collector.{c,h} — pkt_yield/send_fail accessors (ADR-081 L1) rv_feature_state.h — packed size corrected to 60 bytes (was incorrectly 80 in initial commit) main.c — mock binding registered under mock CSI CMakeLists.txt — rv_radio_ops_mock.c under CSI_MOCK_ENABLED scripts/validate_qemu_output.py — 3 new ADR-081 checks (17/18/19) docs/adr/ADR-081-.md — status → Accepted (partial); implementation-status matrix; measured benchmarks (decide 3.2 ns, CRC32 614 ns); bandwidth 300 B/s @ 5 Hz (99.7% vs raw); verification section CHANGELOG.md — artifact-level entries Tests (host, gcc -O2 -std=c11): test_adaptive_controller: 18/18 pass, decide() = 3.2 ns/call test_rv_feature_state: 15/15 pass, CRC32(56 B) = 614 ns/pkt, 87 MB/s sizeof(rv_feature_state_t) == 60 asserted IEEE CRC32 known vectors verified Deferred (tracked in ADR-081 roadmap Phase 3/4): Layer 3 mesh-plane message types, role-assignment FSM, Rust-side mirror trait in crates/wifi-densepose-hardware/src/radio_ops.rs. ADR-081: Layer 3 mesh plane + Rust mirror trait — all 5 layers landed Fully implements the remaining deferred pieces of the adaptive CSI mesh firmware kernel. All 5 layers (Radio Abstraction, Adaptive Controller, Mesh Sensing Plane, On-device Feature Extraction, Rust handoff) are now implemented and host-tested end-to-end. Layer 3 — Mesh Sensing Plane (firmware/esp32-csi-node/main/rv_mesh.{h,c}): * 4 node roles: Unassigned / Anchor / Observer / FusionRelay / Coordinator * 7 message types: TIME_SYNC, ROLE_ASSIGN, CHANNEL_PLAN, CALIBRATION_START, FEATURE_DELTA, HEALTH, ANOMALY_ALERT * 3 auth classes: None / HMAC-SHA256-session / Ed25519-batch * Payload types: rv_node_status_t (28 B), rv_anomaly_alert_t (28 B), rv_time_sync_t (16 B), rv_role_assign_t (16 B), rv_channel_plan_t (24 B), rv_calibration_start_t (20 B) * 16-byte envelope + payload + IEEE CRC32 trailer * Pure rv_mesh_encode()/rv_mesh_decode() plus typed convenience encoders * rv_mesh_send_health() + rv_mesh_send_anomaly() helpers Controller wiring (adaptive_controller.c): * Slow loop (30 s default) now emits HEALTH * apply_decision() emits ANOMALY_ALERT on transitions to ALERT / DEGRADED * Role + mesh epoch tracked in module state; epoch bumps on role change Layer 5 — Rust mirror (crates/wifi-densepose-hardware/src/radio_ops.rs): * RadioOps trait mirrors rv_radio_ops_t vtable * MockRadio backend for offline tests * MeshHeader / NodeStatus / AnomalyAlert types mirror rv_mesh.h * Byte-identical IEEE CRC32 (poly 0xEDB88320) verified against firmware test vectors (0xCBF43926 for "123456789") * decode_mesh / decode_node_status / decode_anomaly_alert / encode_health * 8 unit tests, including mesh_constants_match_firmware which asserts MESH_MAGIC/VERSION/HEADER_SIZE/MAX_PAYLOAD match rv_mesh.h byte-for-byte * Exported from lib.rs * signal/ruvector/train/mat crates untouched — satisfies ADR-081 portability acceptance test Tests (all passing): test_adaptive_controller: 18/18 (C, decide() 3.2 ns/call) test_rv_feature_state: 15/15 (C, CRC32 87 MB/s) test_rv_mesh: 27/27 (C, roundtrip 1.0 µs) radio_ops::tests (Rust): 8/8 --- total: 68/68 assertions green --- Docs: * ADR-081 status flipped to Accepted * Implementation-status matrix updated; L3 + Rust mirror both marked Implemented * Benchmarks table extended with rv_mesh encode+decode roundtrip * Verification section updated with cargo test invocation * CHANGELOG: two new entries for L3 mesh plane + Rust mirror Remaining follow-ups (Phase 3.5 polish, not blocking): * Mesh RX path (UDP listener + dispatch) on the firmware * Ed25519 signing for CHANNEL_PLAN / CALIBRATION_START * Hardware validation on COM7 * Add test_rv_mesh to host-test .gitignore Fixes an untracked-file warning from the repo stop-hook: the compiled binary was built by make but the .gitignore update was missed in `8dfb031`. No source changes. * Fix implicit decl of emit_feature_state in adaptive_controller fast_loop_cb calls emit_feature_state() at line 224, but the static definition is at line 256. GCC treats the implicit declaration as non-static, then the real static definition conflicts, and -Werror=all promotes both to hard build errors. Add a forward declaration above the first use. Unblocks ESP32-S3 firmware build and all QEMU matrix jobs. Co-Authored-By: claude-flow <ruv@ruv.net> --------- Co-authored-by: Claude <noreply@anthropic.com>		2026-04-20 10:38:23 -04:00
..
benches	feat: ADR-032a midstreamer QUIC transport + secure TDM + temporal gesture + attractor drift	2026-03-01 22:22:19 -05:00
src	ADR-081: Implement 5-layer adaptive CSI mesh firmware kernel (#404 )	2026-04-20 10:38:23 -04:00
Cargo.toml	fix: security hardening — replace fake HMAC, add path traversal protection, OTA auth (ADR-050)	2026-03-06 13:11:04 -05:00
README.md	feat: ADR-024 Contrastive CSI Embedding Model — all 7 phases (#52 )	2026-03-01 01:44:38 -05:00

README.md

wifi-densepose-hardware

Hardware interface abstractions for WiFi CSI sensors (ESP32, Intel 5300, Atheros).

Overview

wifi-densepose-hardware provides platform-agnostic parsers for WiFi CSI data from multiple hardware sources. All parsing operates on byte buffers with no C FFI or hardware dependencies at compile time, making the crate fully portable and deterministic -- the same bytes in always produce the same parsed output.

Features

ESP32 binary parser -- Parses ADR-018 binary CSI frames streamed over UDP from ESP32 and ESP32-S3 devices.
UDP aggregator -- Receives and aggregates CSI frames from multiple ESP32 nodes (ADR-018 Layer 2). Provided as a standalone binary.
Bridge -- Converts hardware CsiFrame into the CsiData format expected by the detection pipeline (ADR-018 Layer 3).
No mock data -- Parsers either parse real bytes or return explicit ParseError values. There are no synthetic fallbacks.
Pure byte-buffer parsing -- No FFI to ESP-IDF or kernel modules. Safe to compile and test on any platform.

Feature flags

Flag	Default	Description
`std`	yes	Standard library support
`esp32`	no	ESP32 serial CSI frame parsing
`intel5300`	no	Intel 5300 CSI Tool log parsing
`linux-wifi`	no	Linux WiFi interface for commodity sensing

Quick Start

use wifi_densepose_hardware::{CsiFrame, Esp32CsiParser, ParseError};

// Parse ESP32 CSI data from raw UDP bytes
let raw_bytes: &[u8] = &[/* ADR-018 binary frame */];
match Esp32CsiParser::parse_frame(raw_bytes) {
    Ok((frame, consumed)) => {
        println!("Parsed {} subcarriers ({} bytes)",
                 frame.subcarrier_count(), consumed);
        let (amplitudes, phases) = frame.to_amplitude_phase();
        // Feed into detection pipeline...
    }
    Err(ParseError::InsufficientData { needed, got }) => {
        eprintln!("Need {} bytes, got {}", needed, got);
    }
    Err(e) => eprintln!("Parse error: {}", e),
}

Architecture

wifi-densepose-hardware/src/
  lib.rs            -- Re-exports: CsiFrame, Esp32CsiParser, ParseError, CsiData
  csi_frame.rs      -- CsiFrame, CsiMetadata, SubcarrierData, Bandwidth, AntennaConfig
  esp32_parser.rs   -- Esp32CsiParser (ADR-018 binary protocol)
  error.rs          -- ParseError
  bridge.rs         -- CsiData bridge to detection pipeline
  aggregator/       -- UDP multi-node frame aggregator (binary)

Crate	Role
`wifi-densepose-core`	Foundation types (`CsiFrame` definitions)
`wifi-densepose-signal`	Consumes parsed CSI data for processing
`wifi-densepose-mat`	Uses hardware adapters for disaster detection
`wifi-densepose-vitals`	Vital sign extraction from parsed frames

License

MIT OR Apache-2.0