frank/ruvnet--RuView
1
0
Fork 0
mirror of https://github.com/ruvnet/RuView synced 2026-08-03 19:21:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

ADR-081: implement Layers 1/2/4 end-to-end + host tests + QEMU hooks

Browse Source 
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.
This commit is contained in:
Claude
2026-04-19 03:43:08 +00:00
parent 9648a47fdc
commit d53e29506e
18 changed files with 966 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files
firmware/esp32-csi-node/main/CMakeLists.txt
+2 -2
View File
@@ -12,9 +12,9 @@ set(SRCS
set(REQUIRES "")
# ADR-061: Mock CSI generator for QEMU testing
# ADR-061: Mock CSI generator for QEMU testing + ADR-081 mock radio binding
if(CONFIG_CSI_MOCK_ENABLED)
list(APPEND SRCS "mock_csi.c")
list(APPEND SRCS "mock_csi.c" "rv_radio_ops_mock.c")
endif()
# ADR-045: AMOLED display support (compile-time optional)
firmware/esp32-csi-node/main/adaptive_controller.c
+85 -76
View File
@@ -14,7 +14,10 @@
#include "adaptive_controller.h"
#include "rv_radio_ops.h"
#include "rv_feature_state.h"
#include "edge_processing.h"
#include "stream_sender.h"
#include "csi_collector.h"
#include <string.h>
#include "freertos/FreeRTOS.h"
@@ -86,78 +89,10 @@ static void apply_defaults(adapt_config_t *cfg)
cfg->min_pkt_yield = CONFIG_ADAPTIVE_MIN_PKT_YIELD;
}
/* ---- Pure decision function (unit-testable) ---- */
void adaptive_controller_decide(const adapt_config_t *cfg,
adapt_state_t current,
const adapt_observation_t *obs,
adapt_decision_t *out)
{
if (cfg == NULL || obs == NULL || out == NULL) {
return;
}
memset(out, 0, sizeof(*out));
out->new_state = (uint8_t)current;
out->new_profile = RV_PROFILE_PASSIVE_LOW_RATE;
/* Degraded gate: any of pkt yield collapse, severe coherence loss → DEGRADED. */
if (obs->pkt_yield_per_sec < cfg->min_pkt_yield ||
obs->node_coherence < 0.20f) {
if (current != ADAPT_STATE_DEGRADED) {
out->change_state = true;
out->new_state = ADAPT_STATE_DEGRADED;
}
out->change_profile = (current != ADAPT_STATE_DEGRADED);
out->new_profile = RV_PROFILE_PASSIVE_LOW_RATE;
out->suggested_vital_interval_ms = 2000;
return;
}
/* Anomaly trumps motion. */
if (obs->anomaly_score >= cfg->anomaly_threshold) {
if (current != ADAPT_STATE_ALERT) {
out->change_state = true;
out->new_state = ADAPT_STATE_ALERT;
}
out->change_profile = true;
out->new_profile = RV_PROFILE_FAST_MOTION;
out->suggested_vital_interval_ms = 100;
return;
}
/* Motion → SENSE_ACTIVE with FAST_MOTION profile. */
if (obs->motion_score >= cfg->motion_threshold) {
if (current != ADAPT_STATE_SENSE_ACTIVE) {
out->change_state = true;
out->new_state = ADAPT_STATE_SENSE_ACTIVE;
}
out->change_profile = true;
out->new_profile = RV_PROFILE_FAST_MOTION;
out->suggested_vital_interval_ms = cfg->aggressive ? 100 : 200;
return;
}
/* Stable environment with valid presence → high-sensitivity respiration mode. */
if (obs->presence_score >= 0.5f && obs->motion_score < 0.05f) {
if (current != ADAPT_STATE_SENSE_IDLE) {
out->change_state = true;
out->new_state = ADAPT_STATE_SENSE_IDLE;
}
out->change_profile = true;
out->new_profile = RV_PROFILE_RESP_HIGH_SENS;
out->suggested_vital_interval_ms = 1000;
return;
}
/* Default: passive low rate. */
if (current != ADAPT_STATE_SENSE_IDLE) {
out->change_state = true;
out->new_state = ADAPT_STATE_SENSE_IDLE;
}
out->change_profile = (current != ADAPT_STATE_SENSE_IDLE);
out->new_profile = RV_PROFILE_PASSIVE_LOW_RATE;
out->suggested_vital_interval_ms = cfg->aggressive ? 500 : 1000;
}
/* Pure decision policy lives in its own file so it can link under
* host unit tests without FreeRTOS. It is part of this translation
* unit via #include to preserve a single object at build time. */
#include "adaptive_controller_decide.c"
/* ---- Observation collection ---- */
@@ -237,6 +172,12 @@ static void fast_loop_cb(TimerHandle_t t)
adapt_decision_t dec;
adaptive_controller_decide(&s_cfg, s_state, &obs, &dec);
apply_decision(&dec);
/* ADR-081 Layer 4/5: emit compact feature state on every fast tick
* (default 200 ms → 5 Hz, within the 1–10 Hz spec). Replaces raw
* ADR-018 CSI as the default upstream; raw remains available as a
* debug stream gated by the channel plan. */
emit_feature_state();
}
static void medium_loop_cb(TimerHandle_t t)
@@ -260,13 +201,81 @@ static void medium_loop_cb(TimerHandle_t t)
}
}
/* ADR-081 Layer 4: emit one rv_feature_state_t packet onto the wire.
*
* Pulls from the latest observation + latest vitals + the active capture
* profile. Send is best-effort — stream_sender will report its own
* failures; we don't re-queue. At 5 Hz default cadence this is 300 B/s
* per node, vs. ~100 KB/s for raw ADR-018 CSI. */
static uint16_t s_feature_state_seq = 0;
static void emit_feature_state(void)
{
rv_feature_state_t pkt;
memset(&pkt, 0, sizeof(pkt));
adapt_observation_t obs;
bool have_obs = false;
portENTER_CRITICAL(&s_obs_lock);
if (s_obs_valid) {
obs = s_last_obs;
have_obs = true;
}
portEXIT_CRITICAL(&s_obs_lock);
if (have_obs) {
pkt.motion_score = obs.motion_score;
pkt.presence_score = obs.presence_score;
pkt.anomaly_score = obs.anomaly_score;
pkt.node_coherence = obs.node_coherence;
}
/* Fill vitals from edge_processing's latest packet. */
edge_vitals_pkt_t v;
if (edge_get_vitals(&v)) {
pkt.respiration_bpm = (float)v.breathing_rate / 100.0f;
pkt.heartbeat_bpm = (float)v.heartrate / 10000.0f;
/* Confidence proxies: presence score for resp, 1.0 if heart BPM
* is within physiological range. */
pkt.respiration_conf = (v.breathing_rate > 0) ? v.presence_score : 0.0f;
pkt.heartbeat_conf = (v.heartrate > 400000u && v.heartrate < 1800000u)
? 0.8f : 0.0f;
if (pkt.respiration_bpm > 0.0f) pkt.quality_flags |= RV_QFLAG_RESPIRATION_VALID;
if (pkt.heartbeat_bpm > 0.0f) pkt.quality_flags |= RV_QFLAG_HEARTBEAT_VALID;
if (pkt.presence_score >= 0.5f) pkt.quality_flags |= RV_QFLAG_PRESENCE_VALID;
if (v.flags & 0x02) pkt.quality_flags |= RV_QFLAG_ANOMALY_TRIGGERED; /* fall bit */
}
if (s_state == ADAPT_STATE_DEGRADED) pkt.quality_flags |= RV_QFLAG_DEGRADED_MODE;
if (s_state == ADAPT_STATE_CALIBRATION) pkt.quality_flags |= RV_QFLAG_CALIBRATING;
/* Active profile, for receiver-side weighting. */
const rv_radio_ops_t *ops = rv_radio_ops_get();
uint8_t profile = RV_PROFILE_PASSIVE_LOW_RATE;
if (ops != NULL && ops->get_health != NULL) {
rv_radio_health_t h;
if (ops->get_health(&h) == ESP_OK) profile = h.current_profile;
}
rv_feature_state_finalize(&pkt,
csi_collector_get_node_id(),
s_feature_state_seq++,
(uint64_t)esp_timer_get_time(),
profile);
int sent = stream_sender_send((const uint8_t *)&pkt, sizeof(pkt));
if (sent < 0) {
ESP_LOGW(TAG, "feature_state emit failed");
}
}
static void slow_loop_cb(TimerHandle_t t)
{
(void)t;
/* Slow loop: publish a HEALTH message, request CALIBRATION_START on
* sustained drift. Both routed through swarm_bridge once the mesh
* plane lands. Today we log a rollover so operators see the cadence. */
ESP_LOGI(TAG, "slow tick (state=%u)", (unsigned)s_state);
/* Slow loop: log a heartbeat and (future Phase 3) publish HEALTH
* messages + request CALIBRATION_START on sustained drift. */
ESP_LOGI(TAG, "slow tick (state=%u, feature_state_seq=%u)",
(unsigned)s_state, (unsigned)s_feature_state_seq);
}
/* ---- Public API ---- */
firmware/esp32-csi-node/main/adaptive_controller_decide.c
+83
View File
@@ -0,0 +1,83 @@
/**
* @file adaptive_controller_decide.c
* @brief ADR-081 Layer 2 — pure decision policy.
*
* Extracted so host unit tests can link this without ESP-IDF / FreeRTOS.
* adaptive_controller.c includes this file; the host Makefile links it
* directly against the test harness.
*/
#include <string.h>
#include "adaptive_controller.h"
#include "rv_radio_ops.h"
void adaptive_controller_decide(const adapt_config_t *cfg,
adapt_state_t current,
const adapt_observation_t *obs,
adapt_decision_t *out)
{
if (cfg == NULL || obs == NULL || out == NULL) {
return;
}
memset(out, 0, sizeof(*out));
out->new_state = (uint8_t)current;
out->new_profile = RV_PROFILE_PASSIVE_LOW_RATE;
/* Degraded gate: pkt yield collapse or severe coherence loss → DEGRADED. */
if (obs->pkt_yield_per_sec < cfg->min_pkt_yield ||
obs->node_coherence < 0.20f) {
if (current != ADAPT_STATE_DEGRADED) {
out->change_state = true;
out->new_state = ADAPT_STATE_DEGRADED;
}
out->change_profile = (current != ADAPT_STATE_DEGRADED);
out->new_profile = RV_PROFILE_PASSIVE_LOW_RATE;
out->suggested_vital_interval_ms = 2000;
return;
}
/* Anomaly trumps motion. */
if (obs->anomaly_score >= cfg->anomaly_threshold) {
if (current != ADAPT_STATE_ALERT) {
out->change_state = true;
out->new_state = ADAPT_STATE_ALERT;
}
out->change_profile = true;
out->new_profile = RV_PROFILE_FAST_MOTION;
out->suggested_vital_interval_ms = 100;
return;
}
/* Motion → SENSE_ACTIVE with FAST_MOTION profile. */
if (obs->motion_score >= cfg->motion_threshold) {
if (current != ADAPT_STATE_SENSE_ACTIVE) {
out->change_state = true;
out->new_state = ADAPT_STATE_SENSE_ACTIVE;
}
out->change_profile = true;
out->new_profile = RV_PROFILE_FAST_MOTION;
out->suggested_vital_interval_ms = cfg->aggressive ? 100 : 200;
return;
}
/* Stable presence + quiet → high-sensitivity respiration. */
if (obs->presence_score >= 0.5f && obs->motion_score < 0.05f) {
if (current != ADAPT_STATE_SENSE_IDLE) {
out->change_state = true;
out->new_state = ADAPT_STATE_SENSE_IDLE;
}
out->change_profile = true;
out->new_profile = RV_PROFILE_RESP_HIGH_SENS;
out->suggested_vital_interval_ms = 1000;
return;
}
/* Default: passive low rate. */
if (current != ADAPT_STATE_SENSE_IDLE) {
out->change_state = true;
out->new_state = ADAPT_STATE_SENSE_IDLE;
}
out->change_profile = (current != ADAPT_STATE_SENSE_IDLE);
out->new_profile = RV_PROFILE_PASSIVE_LOW_RATE;
out->suggested_vital_interval_ms = cfg->aggressive ? 500 : 1000;
}
firmware/esp32-csi-node/main/csi_collector.c
+37
View File
@@ -308,6 +308,43 @@ uint8_t csi_collector_get_node_id(void)
return s_node_id;
}
/* ---- ADR-081: packet yield accessor for the radio abstraction layer ---- */
uint16_t csi_collector_get_pkt_yield_per_sec(void)
{
/* Simple sliding window: record the callback count at ~1 s ago, return
* the delta. Called from adaptive_controller's fast loop (200 ms), so
* we update the snapshot every ~5 calls. */
static int64_t s_yield_window_start_us = 0;
static uint32_t s_yield_window_start_cb = 0;
static uint16_t s_last_yield = 0;
int64_t now = esp_timer_get_time();
if (s_yield_window_start_us == 0) {
s_yield_window_start_us = now;
s_yield_window_start_cb = s_cb_count;
return 0;
}
int64_t elapsed = now - s_yield_window_start_us;
if (elapsed < 1000000LL) {
return s_last_yield;
}
uint32_t delta = s_cb_count - s_yield_window_start_cb;
/* Scale back to per-second if the window ran long (shouldn't, but be safe). */
uint64_t per_sec = ((uint64_t)delta * 1000000ULL) / (uint64_t)elapsed;
if (per_sec > 0xFFFFu) per_sec = 0xFFFFu;
s_last_yield = (uint16_t)per_sec;
s_yield_window_start_us = now;
s_yield_window_start_cb = s_cb_count;
return s_last_yield;
}
uint16_t csi_collector_get_send_fail_count(void)
{
uint32_t f = s_send_fail;
return (f > 0xFFFFu) ? 0xFFFFu : (uint16_t)f;
}
/* ---- ADR-029: Channel hopping ---- */
void csi_collector_set_hop_table(const uint8_t *channels, uint8_t hop_count, uint32_t dwell_ms)
firmware/esp32-csi-node/main/csi_collector.h
+19
View File
@@ -94,4 +94,23 @@ void csi_collector_start_hop_timer(void);
*/
esp_err_t csi_inject_ndp_frame(void);
/**
* Get the recent CSI callback rate (per second).
*
* Computed as a sliding 1-second window over the internal s_cb_count
* counter. Used by the ADR-081 radio abstraction layer to fill the
* pkt_yield_per_sec field of rv_radio_health_t.
*
* @return Callbacks observed in the trailing ~1 second.
*/
uint16_t csi_collector_get_pkt_yield_per_sec(void);
/**
* Get the cumulative UDP send-failure counter since boot.
*
* @return Number of stream_sender_send() failures recorded by the
* CSI callback path.
*/
uint16_t csi_collector_get_send_fail_count(void);
#endif /* CSI_COLLECTOR_H */
firmware/esp32-csi-node/main/main.c
+10 -5
View File
@@ -280,16 +280,21 @@ void app_main(void)
ESP_LOGI(TAG, "Mock CSI mode: skipping swarm bridge");
#endif
/* ADR-081 Layer 1: register the ESP32 radio ops binding now that
* csi_collector_init() has run. Skipped under mock CSI; a future
* mock binding can register itself instead. */
#ifndef CONFIG_CSI_MOCK_ENABLED
/* ADR-081 Layer 1: register the active radio ops binding.
* - Real hardware: ESP32 binding wrapping csi_collector + esp_wifi.
* - QEMU / offline: mock binding wrapping mock_csi.c.
* Either way, the layers above (adaptive controller, mesh plane,
* feature extraction) address the radio through the same vtable —
* this is the portability acceptance test in ADR-081. */
#ifdef CONFIG_CSI_MOCK_ENABLED
rv_radio_ops_mock_register();
#else
rv_radio_ops_esp32_register();
#endif
const rv_radio_ops_t *radio_ops = rv_radio_ops_get();
if (radio_ops != NULL && radio_ops->init != NULL) {
radio_ops->init();
}
#endif
/* ADR-081 Layer 2: start the adaptive controller. NULL config → use
* Kconfig defaults. Default policy is conservative: no channel
firmware/esp32-csi-node/main/rv_feature_state.h
+2 -2
View File
@@ -69,8 +69,8 @@ typedef struct __attribute__((packed)) {
uint32_t crc32; /**< IEEE CRC32 over bytes [0..end-4]. */
} rv_feature_state_t;
_Static_assert(sizeof(rv_feature_state_t) == 80,
"rv_feature_state_t must be 80 bytes on the wire");
_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.
firmware/esp32-csi-node/main/rv_radio_ops.h
+7
View File
@@ -128,6 +128,13 @@ const rv_radio_ops_t *rv_radio_ops_get(void);
*/
void rv_radio_ops_esp32_register(void);
/**
* Register the mock binding (QEMU / offline) as the active radio ops.
*
* Defined in rv_radio_ops_mock.c; only built when CONFIG_CSI_MOCK_ENABLED.
*/
void rv_radio_ops_mock_register(void);
#ifdef __cplusplus
}
#endif
firmware/esp32-csi-node/main/rv_radio_ops_esp32.c
+5 -6
View File
@@ -142,12 +142,11 @@ static int esp32_get_health(rv_radio_health_t *out)
}
memset(out, 0, sizeof(*out));
/* pkt_yield and send_fail are filled by the adaptive controller from
* its own counters today (csi_collector keeps statics that are not yet
* exposed). The binding fills the fields it owns directly. */
out->current_channel = s_current_channel;
out->current_bw_mhz = s_current_bw;
out->current_profile = s_current_profile;
out->pkt_yield_per_sec = csi_collector_get_pkt_yield_per_sec();
out->send_fail_count = csi_collector_get_send_fail_count();
out->current_channel = s_current_channel;
out->current_bw_mhz = s_current_bw;
out->current_profile = s_current_profile;
wifi_ap_record_t ap = {0};
if (esp_wifi_sta_get_ap_info(&ap) == ESP_OK) {
firmware/esp32-csi-node/main/rv_radio_ops_mock.c
+98
View File
@@ -0,0 +1,98 @@
/**
* @file rv_radio_ops_mock.c
* @brief ADR-081 Layer 1 — Mock binding for QEMU / offline testing.
*
* When CONFIG_CSI_MOCK_ENABLED is set (ADR-061 QEMU flow), there is no
* real WiFi driver to wrap. This binding provides the same ops table as
* the ESP32 binding but records state into in-process statics and
* accepts every call. It exists primarily to satisfy ADR-081's
* portability acceptance test: a second binding must compile against
* the same controller and mesh-plane code without modification.
*
* Only compiled when CONFIG_CSI_MOCK_ENABLED is set. Registered from
* main.c in the mock branch.
*/
#include "sdkconfig.h"
#ifdef CONFIG_CSI_MOCK_ENABLED
#include "rv_radio_ops.h"
#include "mock_csi.h"
#include <string.h>
#include "esp_err.h"
#include "esp_log.h"
static const char *TAG = "rv_radio_mock";
static uint8_t s_channel = 6;
static uint8_t s_bw = 20;
static uint8_t s_profile = RV_PROFILE_PASSIVE_LOW_RATE;
static uint8_t s_mode = RV_RADIO_MODE_PASSIVE_RX;
static bool s_csi_on = true;
static int mock_init(void)
{
ESP_LOGI(TAG, "mock radio ops: init");
return ESP_OK;
}
static int mock_set_channel(uint8_t ch, uint8_t bw)
{
s_channel = ch;
s_bw = (bw == 40) ? 40 : 20;
return ESP_OK;
}
static int mock_set_mode(uint8_t mode)
{
s_mode = mode;
return ESP_OK;
}
static int mock_set_csi_enabled(bool en)
{
s_csi_on = en;
return ESP_OK;
}
static int mock_set_capture_profile(uint8_t profile_id)
{
if (profile_id >= RV_PROFILE_COUNT) return ESP_ERR_INVALID_ARG;
s_profile = profile_id;
return ESP_OK;
}
static int mock_get_health(rv_radio_health_t *out)
{
if (out == NULL) return ESP_ERR_INVALID_ARG;
memset(out, 0, sizeof(*out));
/* Mock yield: mirror mock_csi's generator rate so the adaptive
* controller sees a sensible pkt_yield in QEMU. */
out->pkt_yield_per_sec = 20; /* MOCK_CSI_INTERVAL_MS = 50 → 20 Hz */
out->rssi_median_dbm = -55;
out->noise_floor_dbm = -95;
out->current_channel = s_channel;
out->current_bw_mhz = s_bw;
out->current_profile = s_profile;
return ESP_OK;
}
static const rv_radio_ops_t s_mock_ops = {
.init = mock_init,
.set_channel = mock_set_channel,
.set_mode = mock_set_mode,
.set_csi_enabled = mock_set_csi_enabled,
.set_capture_profile = mock_set_capture_profile,
.get_health = mock_get_health,
};
void rv_radio_ops_mock_register(void)
{
rv_radio_ops_register(&s_mock_ops);
ESP_LOGI(TAG, "mock radio ops registered (QEMU / offline mode)");
}
#endif /* CONFIG_CSI_MOCK_ENABLED */