mirror of
https://github.com/ruvnet/RuView.git
synced 2026-04-28 05:59:32 +00:00
5a7f431b0e
* 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>
325 lines
9.4 KiB
Text
325 lines
9.4 KiB
Text
menu "CSI Node Configuration"
|
|
|
|
config CSI_NODE_ID
|
|
int "Node ID (0-255)"
|
|
default 1
|
|
range 0 255
|
|
help
|
|
Unique identifier for this ESP32 CSI node.
|
|
|
|
config CSI_TARGET_IP
|
|
string "Aggregator IP address"
|
|
default "192.168.1.100"
|
|
help
|
|
IP address of the UDP aggregator host.
|
|
|
|
config CSI_TARGET_PORT
|
|
int "Aggregator UDP port"
|
|
default 5005
|
|
range 1024 65535
|
|
help
|
|
UDP port the aggregator listens on.
|
|
|
|
config CSI_WIFI_SSID
|
|
string "WiFi SSID"
|
|
default "wifi-densepose"
|
|
help
|
|
SSID of the WiFi network to connect to.
|
|
|
|
config CSI_WIFI_PASSWORD
|
|
string "WiFi Password"
|
|
default ""
|
|
help
|
|
Password for the WiFi network. Leave empty for open networks.
|
|
|
|
config CSI_WIFI_CHANNEL
|
|
int "WiFi Channel (1-13)"
|
|
default 6
|
|
range 1 13
|
|
help
|
|
WiFi channel to listen on for CSI data.
|
|
|
|
endmenu
|
|
|
|
menu "Edge Intelligence (ADR-039)"
|
|
|
|
config EDGE_TIER
|
|
int "Edge processing tier (0=raw, 1=basic, 2=full)"
|
|
default 2
|
|
range 0 2
|
|
help
|
|
0 = Raw passthrough (no on-device DSP).
|
|
1 = Basic presence/motion detection.
|
|
2 = Full pipeline (vitals, compression, multi-person).
|
|
|
|
config EDGE_VITAL_INTERVAL_MS
|
|
int "Vitals packet send interval (ms)"
|
|
default 1000
|
|
range 100 10000
|
|
help
|
|
How often to send vitals packets over UDP.
|
|
|
|
config EDGE_TOP_K
|
|
int "Top-K subcarriers to track"
|
|
default 8
|
|
range 1 32
|
|
help
|
|
Number of highest-variance subcarriers to use for DSP.
|
|
|
|
config EDGE_FALL_THRESH
|
|
int "Fall detection threshold (x1000)"
|
|
default 15000
|
|
range 100 50000
|
|
help
|
|
Phase acceleration threshold for fall detection.
|
|
Value is divided by 1000 to get rad/s². Default 15000 = 15.0 rad/s².
|
|
Raise to reduce false positives in high-traffic environments.
|
|
Normal walking produces accelerations of 2-5 rad/s².
|
|
Stored as integer; divided by 1000 at runtime.
|
|
|
|
config EDGE_POWER_DUTY
|
|
int "Power duty cycle percentage"
|
|
default 100
|
|
range 10 100
|
|
help
|
|
Active duty cycle for battery-powered nodes.
|
|
100 = always on. 50 = active half the time.
|
|
|
|
endmenu
|
|
|
|
menu "Adaptive Controller (ADR-081)"
|
|
|
|
config ADAPTIVE_FAST_LOOP_MS
|
|
int "Fast loop period (ms)"
|
|
default 200
|
|
range 50 2000
|
|
help
|
|
Period of the fast control loop. The fast loop reads radio
|
|
health and edge-derived motion/presence/anomaly scores and
|
|
updates the active capture profile. Default 200 ms matches
|
|
the ADR-081 spec.
|
|
|
|
config ADAPTIVE_MEDIUM_LOOP_MS
|
|
int "Medium loop period (ms)"
|
|
default 1000
|
|
range 200 30000
|
|
help
|
|
Period of the medium control loop. The medium loop is where
|
|
channel selection and role transitions happen (when
|
|
enable_channel_switch / enable_role_change are on).
|
|
|
|
config ADAPTIVE_SLOW_LOOP_MS
|
|
int "Slow loop period (ms)"
|
|
default 30000
|
|
range 1000 300000
|
|
help
|
|
Period of the slow control loop. The slow loop publishes
|
|
HEALTH messages and may request CALIBRATION_START on
|
|
sustained drift.
|
|
|
|
config ADAPTIVE_AGGRESSIVE
|
|
bool "Aggressive adaptation"
|
|
default n
|
|
help
|
|
When enabled, the controller reacts to motion / anomaly
|
|
sooner and uses a tighter cadence in SENSE_ACTIVE. Default
|
|
off matches today's conservative behavior.
|
|
|
|
config ADAPTIVE_ENABLE_CHANNEL_SWITCH
|
|
bool "Allow controller to change WiFi channel"
|
|
default n
|
|
help
|
|
When disabled, the controller never calls set_channel() —
|
|
channel hopping (ADR-029) and channel override (ADR-060)
|
|
remain in charge. Enable only after Phase 3 follow-up
|
|
work has wired the channel-plan mesh message.
|
|
|
|
config ADAPTIVE_ENABLE_ROLE_CHANGE
|
|
bool "Allow controller to change mesh role"
|
|
default n
|
|
help
|
|
When disabled, the controller never advertises a different
|
|
role to the swarm bridge. Enable after the mesh-plane
|
|
ROLE_ASSIGN protocol is in place.
|
|
|
|
config ADAPTIVE_MOTION_THRESH_PERMIL
|
|
int "Motion threshold (per-mille)"
|
|
default 200
|
|
range 1 1000
|
|
help
|
|
Motion score above which the controller transitions to
|
|
SENSE_ACTIVE and selects RV_PROFILE_FAST_MOTION. Expressed
|
|
in per-mille (200 = 0.20).
|
|
|
|
config ADAPTIVE_ANOMALY_THRESH_PERMIL
|
|
int "Anomaly threshold (per-mille)"
|
|
default 600
|
|
range 1 1000
|
|
help
|
|
Anomaly score above which the controller transitions to
|
|
ALERT. Per-mille (600 = 0.60).
|
|
|
|
config ADAPTIVE_MIN_PKT_YIELD
|
|
int "Minimum packet yield before DEGRADED (pps)"
|
|
default 5
|
|
range 0 100
|
|
help
|
|
CSI callback rate (per second) below which the controller
|
|
falls back to DEGRADED mode and pins the radio to
|
|
RV_PROFILE_PASSIVE_LOW_RATE. 0 disables the degraded gate.
|
|
|
|
endmenu
|
|
|
|
menu "AMOLED Display (ADR-045)"
|
|
|
|
config DISPLAY_ENABLE
|
|
bool "Enable AMOLED display support"
|
|
default y
|
|
help
|
|
Enable RM67162 QSPI AMOLED display and LVGL UI.
|
|
Auto-detects at boot; gracefully skips if no display hardware.
|
|
Requires SPIRAM for frame buffers.
|
|
|
|
config DISPLAY_FPS_LIMIT
|
|
int "Display refresh rate limit (FPS)"
|
|
default 30
|
|
range 10 60
|
|
depends on DISPLAY_ENABLE
|
|
help
|
|
Maximum display refresh rate. Lower values save CPU.
|
|
|
|
config DISPLAY_BRIGHTNESS
|
|
int "Default backlight brightness (%)"
|
|
default 80
|
|
range 0 100
|
|
depends on DISPLAY_ENABLE
|
|
|
|
config DISPLAY_QSPI_CS
|
|
int "QSPI CS GPIO"
|
|
default 6
|
|
depends on DISPLAY_ENABLE
|
|
|
|
config DISPLAY_QSPI_CLK
|
|
int "QSPI CLK GPIO"
|
|
default 47
|
|
depends on DISPLAY_ENABLE
|
|
|
|
config DISPLAY_QSPI_D0
|
|
int "QSPI D0 GPIO"
|
|
default 18
|
|
depends on DISPLAY_ENABLE
|
|
|
|
config DISPLAY_QSPI_D1
|
|
int "QSPI D1 GPIO"
|
|
default 7
|
|
depends on DISPLAY_ENABLE
|
|
|
|
config DISPLAY_QSPI_D2
|
|
int "QSPI D2 GPIO"
|
|
default 48
|
|
depends on DISPLAY_ENABLE
|
|
|
|
config DISPLAY_QSPI_D3
|
|
int "QSPI D3 GPIO"
|
|
default 5
|
|
depends on DISPLAY_ENABLE
|
|
|
|
config DISPLAY_TOUCH_SDA
|
|
int "Touch I2C SDA GPIO"
|
|
default 3
|
|
depends on DISPLAY_ENABLE
|
|
|
|
config DISPLAY_TOUCH_SCL
|
|
int "Touch I2C SCL GPIO"
|
|
default 2
|
|
depends on DISPLAY_ENABLE
|
|
|
|
config DISPLAY_TOUCH_INT
|
|
int "Touch INT GPIO"
|
|
default 21
|
|
depends on DISPLAY_ENABLE
|
|
|
|
config DISPLAY_TOUCH_RST
|
|
int "Touch RST GPIO"
|
|
default 17
|
|
depends on DISPLAY_ENABLE
|
|
|
|
config DISPLAY_BL_PIN
|
|
int "Backlight PWM GPIO"
|
|
default 38
|
|
depends on DISPLAY_ENABLE
|
|
|
|
endmenu
|
|
|
|
menu "WASM Programmable Sensing (ADR-040)"
|
|
|
|
config WASM_ENABLE
|
|
bool "Enable WASM Tier 3 runtime"
|
|
default y
|
|
help
|
|
Enable the WASM3 interpreter for hot-loadable sensing modules.
|
|
Requires WASM3 source in components/wasm3/wasm3-src/.
|
|
Adds ~120 KB flash and ~20 KB SRAM.
|
|
|
|
config WASM_MAX_MODULES
|
|
int "Maximum concurrent WASM modules"
|
|
default 4
|
|
range 1 8
|
|
help
|
|
Number of WASM module slots. Each slot can hold one
|
|
loaded .wasm binary (stored in PSRAM, max 128 KB each).
|
|
|
|
config WASM_VERIFY_SIGNATURE
|
|
bool "Require Ed25519 signature verification for WASM uploads"
|
|
default y
|
|
help
|
|
When enabled, uploaded .wasm binaries must include a valid
|
|
Ed25519 signature. Uses the same signing key as OTA firmware.
|
|
Disable with provision.py --no-wasm-verify for lab/dev use.
|
|
|
|
config WASM_TIMER_INTERVAL_MS
|
|
int "WASM on_timer() interval (ms)"
|
|
default 1000
|
|
range 100 60000
|
|
help
|
|
How often to call on_timer() on running WASM modules.
|
|
Default 1000 ms = 1 Hz.
|
|
|
|
endmenu
|
|
|
|
menu "Mock CSI (QEMU Testing)"
|
|
config CSI_MOCK_ENABLED
|
|
bool "Enable mock CSI generator (for QEMU testing)"
|
|
default n
|
|
help
|
|
Replace real WiFi CSI with synthetic frame generator.
|
|
Use with QEMU emulation for automated testing.
|
|
|
|
config CSI_MOCK_SKIP_WIFI_CONNECT
|
|
bool "Skip WiFi STA connection"
|
|
depends on CSI_MOCK_ENABLED
|
|
default y
|
|
help
|
|
Skip WiFi initialization when using mock CSI.
|
|
|
|
config CSI_MOCK_SCENARIO
|
|
int "Mock scenario (0-9, 255=all)"
|
|
depends on CSI_MOCK_ENABLED
|
|
default 255
|
|
range 0 255
|
|
help
|
|
0=empty, 1=static, 2=walking, 3=fall, 4=multi-person,
|
|
5=channel-sweep, 6=mac-filter, 7=ring-overflow,
|
|
8=boundary-rssi, 9=zero-length, 255=run all.
|
|
|
|
config CSI_MOCK_SCENARIO_DURATION_MS
|
|
int "Scenario duration (ms)"
|
|
depends on CSI_MOCK_ENABLED
|
|
default 5000
|
|
range 1000 60000
|
|
|
|
config CSI_MOCK_LOG_FRAMES
|
|
bool "Log every mock frame (verbose)"
|
|
depends on CSI_MOCK_ENABLED
|
|
default n
|
|
endmenu
|