mirror of
https://github.com/ruvnet/RuView.git
synced 2026-04-28 14:09:33 +00:00
d53e29506e
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.
110 lines
4.2 KiB
C
110 lines
4.2 KiB
C
/**
|
|
* @file rv_feature_state.h
|
|
* @brief ADR-081 Layer 4 — Compact on-wire feature state packet.
|
|
*
|
|
* The default upstream payload from a node. Replaces raw ADR-018 CSI as the
|
|
* primary stream; ADR-018 raw frames remain available as a debug stream
|
|
* gated by the controller / channel plan.
|
|
*
|
|
* Magic numbers in use across the firmware:
|
|
* 0xC5110001 — ADR-018 raw CSI frame (csi_collector.h)
|
|
* 0xC5110002 — ADR-039 vitals packet (edge_processing.h)
|
|
* 0xC5110003 — ADR-069 feature vector (edge_processing.h)
|
|
* 0xC5110004 — ADR-063 fused vitals (edge_processing.h)
|
|
* 0xC5110005 — ADR-039 compressed CSI (edge_processing.h)
|
|
* 0xC5110006 — ADR-081 feature state (this file) ← new
|
|
*/
|
|
|
|
#ifndef RV_FEATURE_STATE_H
|
|
#define RV_FEATURE_STATE_H
|
|
|
|
#include <stdint.h>
|
|
#include <stdbool.h>
|
|
#include <stddef.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/** Magic number for ADR-081 rv_feature_state_t. */
|
|
#define RV_FEATURE_STATE_MAGIC 0xC5110006u
|
|
|
|
/** Quality flag bits. */
|
|
#define RV_QFLAG_PRESENCE_VALID (1u << 0)
|
|
#define RV_QFLAG_RESPIRATION_VALID (1u << 1)
|
|
#define RV_QFLAG_HEARTBEAT_VALID (1u << 2)
|
|
#define RV_QFLAG_ANOMALY_TRIGGERED (1u << 3)
|
|
#define RV_QFLAG_ENV_SHIFT_DETECTED (1u << 4)
|
|
#define RV_QFLAG_DEGRADED_MODE (1u << 5)
|
|
#define RV_QFLAG_CALIBRATING (1u << 6)
|
|
#define RV_QFLAG_RECOMMEND_RECAL (1u << 7)
|
|
|
|
/**
|
|
* Compact per-node sensing state. Sent at 1-10 Hz by default, replacing the
|
|
* raw ADR-018 stream as the primary upstream payload.
|
|
*
|
|
* Mode field carries the rv_capture_profile_t value of the dominant window
|
|
* — receivers can use it to weight features (a sample emitted under
|
|
* RV_PROFILE_FAST_MOTION will have a stale respiration_bpm, etc.).
|
|
*
|
|
* CRC32 is the IEEE polynomial computed over bytes [0 .. sizeof - 4].
|
|
*/
|
|
typedef struct __attribute__((packed)) {
|
|
uint32_t magic; /**< RV_FEATURE_STATE_MAGIC. */
|
|
uint8_t node_id; /**< Source node id. */
|
|
uint8_t mode; /**< rv_capture_profile_t at emit time. */
|
|
uint16_t seq; /**< Monotonic per-node sequence. */
|
|
uint64_t ts_us; /**< Node-local microseconds. */
|
|
float motion_score; /**< 0..1, 100 ms window. */
|
|
float presence_score; /**< 0..1, 1 s window. */
|
|
float respiration_bpm; /**< Breaths per minute. */
|
|
float respiration_conf; /**< 0..1. */
|
|
float heartbeat_bpm; /**< Beats per minute. */
|
|
float heartbeat_conf; /**< 0..1. */
|
|
float anomaly_score; /**< 0..1, z-score-derived. */
|
|
float env_shift_score; /**< 0..1, baseline drift. */
|
|
float node_coherence; /**< 0..1, multi-link agreement. */
|
|
uint16_t quality_flags; /**< RV_QFLAG_* bitmap. */
|
|
uint16_t reserved;
|
|
uint32_t crc32; /**< IEEE CRC32 over bytes [0..end-4]. */
|
|
} rv_feature_state_t;
|
|
|
|
_Static_assert(sizeof(rv_feature_state_t) == 60,
|
|
"rv_feature_state_t must be 60 bytes on the wire");
|
|
|
|
/**
|
|
* Compute IEEE CRC32 over a byte buffer.
|
|
*
|
|
* Provided here (not in a separate util) because the firmware does not yet
|
|
* have a shared CRC32 helper — only zlib's via lwIP, which is not always
|
|
* exposed. This implementation is bit-by-bit; ~80 bytes/packet at low
|
|
* cadence has negligible CPU cost.
|
|
*
|
|
* @param data Input buffer.
|
|
* @param len Input length in bytes.
|
|
* @return IEEE CRC32 of the input.
|
|
*/
|
|
uint32_t rv_feature_state_crc32(const uint8_t *data, size_t len);
|
|
|
|
/**
|
|
* Finalize an rv_feature_state_t by populating magic, seq, ts_us, and crc32.
|
|
* Caller fills the remaining fields in-place before calling this. After
|
|
* finalize() the packet is ready to send on the wire.
|
|
*
|
|
* @param pkt Packet to finalize (caller-owned).
|
|
* @param node_id Source node id (typically csi_collector_get_node_id()).
|
|
* @param seq Monotonic sequence (caller-managed).
|
|
* @param ts_us Node-local microseconds (typically esp_timer_get_time()).
|
|
* @param mode Active rv_capture_profile_t.
|
|
*/
|
|
void rv_feature_state_finalize(rv_feature_state_t *pkt,
|
|
uint8_t node_id,
|
|
uint16_t seq,
|
|
uint64_t ts_us,
|
|
uint8_t mode);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* RV_FEATURE_STATE_H */
|