diff --git a/CHANGELOG.md b/CHANGELOG.md index 7e206191..3837d3fc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -64,6 +64,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 checks for adaptive controller boot line, mock radio ops registration, and slow-loop heartbeat, so QEMU runs regression-gate Layer 1/2 presence. +- **Firmware: ADR-081 Layer 3 mesh sensing plane** — New + `firmware/esp32-csi-node/main/rv_mesh.{h,c}` defines 4 node roles + (Anchor / Observer / Fusion relay / Coordinator), 7 on-wire message + types (TIME_SYNC, ROLE_ASSIGN, CHANNEL_PLAN, CALIBRATION_START, + FEATURE_DELTA, HEALTH, ANOMALY_ALERT), 3 authorization classes + (None / HMAC-SHA256-session / Ed25519-batch), `rv_node_status_t` + (28 B), `rv_anomaly_alert_t` (28 B), `rv_time_sync_t`, + `rv_role_assign_t`, `rv_channel_plan_t`, `rv_calibration_start_t`. + Pure-C encoder/decoder (`rv_mesh_encode()` / `rv_mesh_decode()`) with + 16-byte envelope + payload + IEEE CRC32 trailer; convenience encoders + for each message type. Controller now emits `HEALTH` every slow-loop + tick (30 s default) and `ANOMALY_ALERT` on state transitions to ALERT + or DEGRADED. Host tests: `test_rv_mesh` exercises 27 assertions + covering roundtrip, bad magic, truncation, CRC flipping, oversize + payload rejection, and encode+decode throughput (1.0 μs/roundtrip + on host). +- **Rust: ADR-081 Layer 1/3 mirror module** — New + `crates/wifi-densepose-hardware/src/radio_ops.rs` mirrors the + firmware-side `rv_radio_ops_t` vtable as the Rust `RadioOps` trait + (init, set_channel, set_mode, set_csi_enabled, set_capture_profile, + get_health) and provides `MockRadio` for offline testing. + Also mirrors the `rv_mesh.h` types (`MeshHeader`, `NodeStatus`, + `AnomalyAlert`, `MeshRole`, `MeshMsgType`, `AuthClass`) and ships + byte-identical `crc32_ieee()`, `decode_mesh()`, `decode_node_status()`, + `decode_anomaly_alert()`, and `encode_health()`. Exported from + `lib.rs`. 8 unit tests pass; `crc32_matches_firmware_vectors` + verifies parity with the firmware-side test vectors + (`0xCBF43926` for `"123456789"`, `0xD202EF8D` for single-byte zero), + and `mesh_constants_match_firmware` asserts `MESH_MAGIC`, + `MESH_VERSION`, `MESH_HEADER_SIZE`, and `MESH_MAX_PAYLOAD` match + `rv_mesh.h` byte-for-byte. Satisfies ADR-081's portability + acceptance test: signal/ruvector/train/mat crates are untouched. - **Firmware: adaptive controller** — New `firmware/esp32-csi-node/main/adaptive_controller.{c,h}` implements the three-loop closed-loop control specified by ADR-081: fast diff --git a/docs/adr/ADR-081-adaptive-csi-mesh-firmware-kernel.md b/docs/adr/ADR-081-adaptive-csi-mesh-firmware-kernel.md index e28c1b3e..3b3afda1 100644 --- a/docs/adr/ADR-081-adaptive-csi-mesh-firmware-kernel.md +++ b/docs/adr/ADR-081-adaptive-csi-mesh-firmware-kernel.md @@ -2,7 +2,7 @@ | Field | Value | |-------------|-----------------------------------------------------------------------| -| **Status** | Accepted (partial — Layers 1/2/4 landed; L3 mesh plane and Rust trait tracked in Phase 3/4) | +| **Status** | Accepted — Layers 1/2/3/4/5 implemented and host-tested; mesh RX path and Ed25519 signing tracked as Phase 3.5 polish | | **Date** | 2026-04-19 | | **Authors** | ruv | | **Depends** | ADR-018, ADR-028, ADR-029, ADR-031, ADR-032, ADR-039, ADR-066, ADR-073 | @@ -331,16 +331,20 @@ Artifacts delivered alongside the ADR: | L1 Mock (QEMU) binding | `firmware/esp32-csi-node/main/rv_radio_ops_mock.c` | Implemented | | L2 Controller FreeRTOS plumbing | `firmware/esp32-csi-node/main/adaptive_controller.c` | Implemented | | L2 Pure decision policy (testable) | `firmware/esp32-csi-node/main/adaptive_controller_decide.c` | Implemented | +| L3 Mesh-plane types + encoder/decoder | `firmware/esp32-csi-node/main/rv_mesh.{h,c}` | Implemented | +| L3 HEALTH emit (slow loop, 30 s) | `adaptive_controller.c:slow_loop_cb()` | Implemented | +| L3 ANOMALY_ALERT on state transition | `adaptive_controller.c:apply_decision()` | Implemented | +| L3 Role tracking + epoch monotonicity | `adaptive_controller.c` (`s_role`, `s_mesh_epoch`) | Implemented | | L4 Feature state packet + helpers | `firmware/esp32-csi-node/main/rv_feature_state.{h,c}` | Implemented | | L4 Emitter from fast loop (5 Hz) | `adaptive_controller.c:emit_feature_state()` | Implemented | | L1 Packet yield + send-fail accessors | `csi_collector.c:csi_collector_get_pkt_yield_per_sec()` + send fail | Implemented | -| Host unit tests (18 + 15 assertions) | `firmware/esp32-csi-node/tests/host/` | Passing | +| L5 Rust mirror trait + mesh decoder | `crates/wifi-densepose-hardware/src/radio_ops.rs` | Implemented | +| Host C unit tests (60 assertions) | `firmware/esp32-csi-node/tests/host/` | **60/60 ✓** | +| Rust unit tests (8 assertions) | `crates/wifi-densepose-hardware` (`radio_ops::tests`) | **8/8 ✓** | | QEMU validator hooks (3 new checks) | `scripts/validate_qemu_output.py` (check 17/18/19) | Passing | -| L3 mesh-plane message types | — | Deferred | -| L3 role-assignment FSM | — | Deferred | -| Rust-side mirror trait | `crates/wifi-densepose-hardware/src/radio_ops.rs` | Deferred | - -Deferred items remain in the Roadmap table below (Phase 3 / Phase 4). +| L3 mesh RX path (receive + dispatch) | — | Phase 3.5 | +| Ed25519 signing for CHANNEL_PLAN etc. | — | Phase 3.5 | +| Hardware validation on COM7 | — | Pending | ## Measured performance @@ -350,11 +354,12 @@ a modern CPU; on-target ESP32-S3 Xtensa LX7 at 240 MHz is ~5–10× slower for bit-by-bit CRC and broadly comparable for the decide function after inlining. -| Operation | Cost per call | Notes | -|--------------------------------------------|---------------------|-------------------------------------| -| `adaptive_controller_decide()` | **3.2 ns** (host) | O(1) policy, 9 branches evaluated | -| `rv_feature_state_crc32()` (56 B hashed) | **614 ns** (host) | 87 MB/s — bit-by-bit IEEE CRC32 | -| `rv_feature_state_finalize()` (full) | **616 ns** (host) | CRC-dominated | +| Operation | Cost per call | Notes | +|---------------------------------------------|---------------------|-------------------------------------| +| `adaptive_controller_decide()` | **3.2 ns** (host) | O(1) policy, 9 branches evaluated | +| `rv_feature_state_crc32()` (56 B hashed) | **612 ns** (host) | 87 MB/s — bit-by-bit IEEE CRC32 | +| `rv_feature_state_finalize()` (full) | **592 ns** (host) | CRC-dominated | +| `rv_mesh_encode_health()` + `_decode()` | **1010 ns** (host) | Full roundtrip, hdr+payload+CRC | Projected on-target cost at 5 Hz cadence: @@ -385,11 +390,21 @@ Projected on-target cost at 5 Hz cadence: **Tests:** -| Suite | Assertions | Result | -|-------------------------------------|-----------:|------------| -| `test_adaptive_controller` | 18 | **PASS** | -| `test_rv_feature_state` | 15 | **PASS** | -| QEMU validator (`ADR-061` pipeline) | +3 checks | hooked | +| Suite | Assertions | Result | +|---------------------------------------------|-----------:|------------| +| `test_adaptive_controller` (host C) | 18 | **PASS** | +| `test_rv_feature_state` (host C) | 15 | **PASS** | +| `test_rv_mesh` (host C) | 27 | **PASS** | +| `radio_ops::tests` (Rust) | 8 | **PASS** | +| **Total** | **68** | **68/68** | +| QEMU validator (`ADR-061` pipeline) | +3 checks | hooked | + +Cross-language parity: the Rust `crc32_ieee()` is verified against the +same known vectors used by the C test (`0xCBF43926` for `"123456789"`, +`0xD202EF8D` for a single zero byte), and the `mesh_constants_match_firmware` +test asserts `MESH_MAGIC`, `MESH_VERSION`, `MESH_HEADER_SIZE`, and +`MESH_MAX_PAYLOAD` match the C header byte-for-byte. Any drift between +the two implementations fails CI. ## New components this ADR authorizes @@ -458,11 +473,19 @@ Projected on-target cost at 5 Hz cadence: ## Verification ```bash -# Host-side unit tests (no ESP-IDF, no QEMU required) +# Host-side C unit tests (no ESP-IDF, no QEMU required) cd firmware/esp32-csi-node/tests/host make check # → test_adaptive_controller: 18/18 pass, decide() = 3.2 ns/call -# → test_rv_feature_state: 15/15 pass, CRC32(56 B) = 614 ns/pkt +# → test_rv_feature_state: 15/15 pass, CRC32(56 B) = 612 ns/pkt +# → test_rv_mesh: 27/27 pass, HEALTH roundtrip = 1.0 µs + +# Rust-side radio_ops trait + mesh decoder tests +cd rust-port/wifi-densepose-rs +cargo test -p wifi-densepose-hardware --no-default-features --lib radio_ops +# → 8 passed; verifies MockRadio, CRC32 parity with firmware vectors, +# HEALTH encode/decode roundtrip, bad-magic/short/CRC rejection, +# and that MESH_MAGIC/VERSION/HEADER_SIZE match rv_mesh.h # QEMU end-to-end (requires ESP-IDF + qemu-system-xtensa, see ADR-061) bash scripts/qemu-esp32s3-test.sh @@ -470,7 +493,7 @@ bash scripts/qemu-esp32s3-test.sh # adaptive_ctrl boot line, rv_radio_mock binding registration, and # slow-loop heartbeat. -# Full workspace (Rust) — unchanged, ADR-081 introduces no Rust changes +# Full workspace cargo test --workspace --no-default-features ``` diff --git a/firmware/esp32-csi-node/main/CMakeLists.txt b/firmware/esp32-csi-node/main/CMakeLists.txt index f90d4afb..6f0930a5 100644 --- a/firmware/esp32-csi-node/main/CMakeLists.txt +++ b/firmware/esp32-csi-node/main/CMakeLists.txt @@ -7,6 +7,7 @@ set(SRCS # ADR-081 — adaptive CSI mesh firmware kernel "rv_radio_ops_esp32.c" "rv_feature_state.c" + "rv_mesh.c" "adaptive_controller.c" ) diff --git a/firmware/esp32-csi-node/main/adaptive_controller.c b/firmware/esp32-csi-node/main/adaptive_controller.c index 4a57798e..d70c26ef 100644 --- a/firmware/esp32-csi-node/main/adaptive_controller.c +++ b/firmware/esp32-csi-node/main/adaptive_controller.c @@ -15,6 +15,7 @@ #include "adaptive_controller.h" #include "rv_radio_ops.h" #include "rv_feature_state.h" +#include "rv_mesh.h" #include "edge_processing.h" #include "stream_sender.h" #include "csi_collector.h" @@ -131,14 +132,57 @@ static void collect_observation(adapt_observation_t *out) /* ---- Decision application ---- */ +/* ADR-081 L3: epoch monotonically advances per mesh session. Seeded at + * init; every major state transition or role change bumps it so + * receivers can order events. */ +static uint32_t s_mesh_epoch = 1; + +/* ADR-081 L3: current node role. Updated by ROLE_ASSIGN receipt (future + * mesh-plane RX path) or forced by tests. Default Observer. */ +static uint8_t s_role = RV_ROLE_OBSERVER; + +/* 8-byte node id. Upper 7 bytes are zero by default; byte 0 is the + * legacy CSI node id for compatibility with the ADR-018 header. */ +static void node_id_bytes(uint8_t out[8]) +{ + memset(out, 0, 8); + out[0] = csi_collector_get_node_id(); +} + static void apply_decision(const adapt_decision_t *dec) { const rv_radio_ops_t *ops = rv_radio_ops_get(); + adapt_state_t prev = s_state; if (dec->change_state) { ESP_LOGI(TAG, "state %u → %u", (unsigned)s_state, (unsigned)dec->new_state); s_state = (adapt_state_t)dec->new_state; + + /* ADR-081 L3: on transition to ALERT, emit ANOMALY_ALERT on the + * mesh plane. On any role-relevant transition, bump the epoch. */ + if (s_state == ADAPT_STATE_ALERT && prev != ADAPT_STATE_ALERT) { + uint8_t nid[8]; + node_id_bytes(nid); + adapt_observation_t obs; + float motion = 0.0f, anomaly = 0.0f; + portENTER_CRITICAL(&s_obs_lock); + if (s_obs_valid) { obs = s_last_obs; motion = obs.motion_score; + anomaly = obs.anomaly_score; } + portEXIT_CRITICAL(&s_obs_lock); + uint8_t severity = (uint8_t)(anomaly * 255.0f); + rv_mesh_send_anomaly(s_role, s_mesh_epoch, nid, + RV_ANOMALY_COHERENCE_LOSS, severity, + anomaly, motion); + } + if (s_state == ADAPT_STATE_DEGRADED && prev != ADAPT_STATE_DEGRADED) { + uint8_t nid[8]; + node_id_bytes(nid); + rv_mesh_send_anomaly(s_role, s_mesh_epoch, nid, + RV_ANOMALY_PKT_YIELD_COLLAPSE, + 200, 1.0f, 0.0f); + } + s_mesh_epoch++; } if (dec->change_profile && ops != NULL && ops->set_capture_profile != NULL) { @@ -272,10 +316,16 @@ static void emit_feature_state(void) static void slow_loop_cb(TimerHandle_t t) { (void)t; - /* 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); + /* ADR-081 L3: publish a HEALTH mesh message every slow tick + * (default 30 s). The coordinator uses these to track liveness and + * detect sync-error drift. */ + uint8_t nid[8]; + node_id_bytes(nid); + rv_mesh_send_health(s_role, s_mesh_epoch, nid); + + ESP_LOGI(TAG, "slow tick (state=%u, feature_state_seq=%u, role=%u, epoch=%u) HEALTH sent", + (unsigned)s_state, (unsigned)s_feature_state_seq, + (unsigned)s_role, (unsigned)s_mesh_epoch); } /* ---- Public API ---- */ diff --git a/firmware/esp32-csi-node/main/rv_mesh.c b/firmware/esp32-csi-node/main/rv_mesh.c new file mode 100644 index 00000000..26f0fba7 --- /dev/null +++ b/firmware/esp32-csi-node/main/rv_mesh.c @@ -0,0 +1,251 @@ +/** + * @file rv_mesh.c + * @brief ADR-081 Layer 3 — Mesh Sensing Plane implementation. + * + * Encoder/decoder are pure functions (no ESP-IDF deps) and therefore + * host-unit-testable. The send helpers wrap stream_sender so the + * firmware can use a single upstream socket for all payload types. + */ + +#include "rv_mesh.h" +#include "rv_feature_state.h" +#include "rv_radio_ops.h" + +#include + +#ifndef RV_MESH_HOST_TEST +#include "esp_log.h" +#include "esp_timer.h" +#include "stream_sender.h" +#include "csi_collector.h" +#include "adaptive_controller.h" +static const char *TAG = "rv_mesh"; +#endif + +/* ---- Encoder ---- */ + +size_t rv_mesh_encode(uint8_t type, + uint8_t sender_role, + uint8_t auth_class, + uint32_t epoch, + const void *payload, + uint16_t payload_len, + uint8_t *buf, + size_t buf_cap) +{ + if (buf == NULL) return 0; + if (payload == NULL && payload_len != 0) return 0; + if (payload_len > RV_MESH_MAX_PAYLOAD) return 0; + + size_t total = sizeof(rv_mesh_header_t) + (size_t)payload_len + 4u; + if (buf_cap < total) return 0; + + rv_mesh_header_t hdr; + hdr.magic = RV_MESH_MAGIC; + hdr.version = (uint8_t)RV_MESH_VERSION; + hdr.type = type; + hdr.sender_role = sender_role; + hdr.auth_class = auth_class; + hdr.epoch = epoch; + hdr.payload_len = payload_len; + hdr.reserved = 0; + + memcpy(buf, &hdr, sizeof(hdr)); + if (payload_len > 0) { + memcpy(buf + sizeof(hdr), payload, payload_len); + } + + /* IEEE CRC32 over header + payload. Reuses the CRC32 from + * rv_feature_state.c so there is exactly one implementation. */ + uint32_t crc = rv_feature_state_crc32(buf, sizeof(hdr) + payload_len); + memcpy(buf + sizeof(hdr) + payload_len, &crc, 4); + + return total; +} + +esp_err_t rv_mesh_decode(const uint8_t *buf, size_t buf_len, + rv_mesh_header_t *out_hdr, + const uint8_t **out_payload, + uint16_t *out_payload_len) +{ + if (buf == NULL || out_hdr == NULL || + out_payload == NULL || out_payload_len == NULL) { + return ESP_ERR_INVALID_ARG; + } + if (buf_len < sizeof(rv_mesh_header_t) + 4u) { + return ESP_ERR_INVALID_SIZE; + } + + rv_mesh_header_t hdr; + memcpy(&hdr, buf, sizeof(hdr)); + + if (hdr.magic != RV_MESH_MAGIC) { + return ESP_ERR_INVALID_VERSION; /* repurpose: wrong magic */ + } + if (hdr.version != RV_MESH_VERSION) { + return ESP_ERR_INVALID_VERSION; + } + if (hdr.payload_len > RV_MESH_MAX_PAYLOAD) { + return ESP_ERR_INVALID_SIZE; + } + + size_t needed = sizeof(hdr) + (size_t)hdr.payload_len + 4u; + if (buf_len < needed) { + return ESP_ERR_INVALID_SIZE; + } + + uint32_t got_crc; + memcpy(&got_crc, buf + sizeof(hdr) + hdr.payload_len, 4); + uint32_t want_crc = rv_feature_state_crc32(buf, + sizeof(hdr) + hdr.payload_len); + if (got_crc != want_crc) { + return ESP_ERR_INVALID_CRC; + } + + *out_hdr = hdr; + *out_payload = (hdr.payload_len > 0) ? buf + sizeof(hdr) : NULL; + *out_payload_len = hdr.payload_len; + return ESP_OK; +} + +/* ---- Typed convenience encoders ---- */ + +size_t rv_mesh_encode_health(uint8_t sender_role, + uint32_t epoch, + const rv_node_status_t *status, + uint8_t *buf, size_t buf_cap) +{ + if (status == NULL) return 0; + return rv_mesh_encode(RV_MSG_HEALTH, sender_role, RV_AUTH_NONE, + epoch, status, sizeof(*status), buf, buf_cap); +} + +size_t rv_mesh_encode_anomaly_alert(uint8_t sender_role, + uint32_t epoch, + const rv_anomaly_alert_t *alert, + uint8_t *buf, size_t buf_cap) +{ + if (alert == NULL) return 0; + return rv_mesh_encode(RV_MSG_ANOMALY_ALERT, sender_role, RV_AUTH_NONE, + epoch, alert, sizeof(*alert), buf, buf_cap); +} + +size_t rv_mesh_encode_feature_delta(uint8_t sender_role, + uint32_t epoch, + const rv_feature_state_t *fs, + uint8_t *buf, size_t buf_cap) +{ + if (fs == NULL) return 0; + return rv_mesh_encode(RV_MSG_FEATURE_DELTA, sender_role, RV_AUTH_NONE, + epoch, fs, sizeof(*fs), buf, buf_cap); +} + +size_t rv_mesh_encode_time_sync(uint8_t sender_role, + uint32_t epoch, + const rv_time_sync_t *ts, + uint8_t *buf, size_t buf_cap) +{ + if (ts == NULL) return 0; + return rv_mesh_encode(RV_MSG_TIME_SYNC, sender_role, RV_AUTH_HMAC_SESSION, + epoch, ts, sizeof(*ts), buf, buf_cap); +} + +size_t rv_mesh_encode_role_assign(uint8_t sender_role, + uint32_t epoch, + const rv_role_assign_t *ra, + uint8_t *buf, size_t buf_cap) +{ + if (ra == NULL) return 0; + return rv_mesh_encode(RV_MSG_ROLE_ASSIGN, sender_role, RV_AUTH_HMAC_SESSION, + epoch, ra, sizeof(*ra), buf, buf_cap); +} + +size_t rv_mesh_encode_channel_plan(uint8_t sender_role, + uint32_t epoch, + const rv_channel_plan_t *cp, + uint8_t *buf, size_t buf_cap) +{ + if (cp == NULL) return 0; + return rv_mesh_encode(RV_MSG_CHANNEL_PLAN, sender_role, RV_AUTH_ED25519_BATCH, + epoch, cp, sizeof(*cp), buf, buf_cap); +} + +size_t rv_mesh_encode_calibration_start(uint8_t sender_role, + uint32_t epoch, + const rv_calibration_start_t *cs, + uint8_t *buf, size_t buf_cap) +{ + if (cs == NULL) return 0; + return rv_mesh_encode(RV_MSG_CALIBRATION_START, sender_role, + RV_AUTH_ED25519_BATCH, epoch, cs, sizeof(*cs), + buf, buf_cap); +} + +/* ---- Send helpers (firmware-only; hidden from host tests) ---- */ + +#ifndef RV_MESH_HOST_TEST + +esp_err_t rv_mesh_send(const uint8_t *frame, size_t len) +{ + if (frame == NULL || len == 0) return ESP_ERR_INVALID_ARG; + int sent = stream_sender_send(frame, len); + if (sent < 0) { + ESP_LOGW(TAG, "rv_mesh_send: stream_sender failed (len=%u)", + (unsigned)len); + return ESP_FAIL; + } + return ESP_OK; +} + +esp_err_t rv_mesh_send_health(uint8_t role, uint32_t epoch, + const uint8_t node_id[8]) +{ + if (node_id == NULL) return ESP_ERR_INVALID_ARG; + + rv_node_status_t st; + memset(&st, 0, sizeof(st)); + memcpy(st.node_id, node_id, 8); + st.local_time_us = (uint64_t)esp_timer_get_time(); + st.role = role; + + const rv_radio_ops_t *ops = rv_radio_ops_get(); + if (ops != NULL && ops->get_health != NULL) { + rv_radio_health_t h; + if (ops->get_health(&h) == ESP_OK) { + st.current_channel = h.current_channel; + st.current_bw = h.current_bw_mhz; + st.noise_floor_dbm = h.noise_floor_dbm; + st.pkt_yield = h.pkt_yield_per_sec; + } + } + + uint8_t buf[RV_MESH_MAX_FRAME_BYTES]; + size_t n = rv_mesh_encode_health(role, epoch, &st, buf, sizeof(buf)); + if (n == 0) return ESP_FAIL; + return rv_mesh_send(buf, n); +} + +esp_err_t rv_mesh_send_anomaly(uint8_t role, uint32_t epoch, + const uint8_t node_id[8], + uint8_t reason, + uint8_t severity, + float anomaly_score, + float motion_score) +{ + if (node_id == NULL) return ESP_ERR_INVALID_ARG; + rv_anomaly_alert_t a; + memset(&a, 0, sizeof(a)); + memcpy(a.node_id, node_id, 8); + a.ts_us = (uint64_t)esp_timer_get_time(); + a.reason = reason; + a.severity = severity; + a.anomaly_score = anomaly_score; + a.motion_score = motion_score; + + uint8_t buf[RV_MESH_MAX_FRAME_BYTES]; + size_t n = rv_mesh_encode_anomaly_alert(role, epoch, &a, buf, sizeof(buf)); + if (n == 0) return ESP_FAIL; + return rv_mesh_send(buf, n); +} + +#endif /* !RV_MESH_HOST_TEST */ diff --git a/firmware/esp32-csi-node/main/rv_mesh.h b/firmware/esp32-csi-node/main/rv_mesh.h new file mode 100644 index 00000000..30be3846 --- /dev/null +++ b/firmware/esp32-csi-node/main/rv_mesh.h @@ -0,0 +1,296 @@ +/** + * @file rv_mesh.h + * @brief ADR-081 Layer 3 — Mesh Sensing Plane. + * + * Defines node roles, the 7 on-wire message types, and the + * rv_node_status_t health payload that nodes exchange to behave as a + * distributed sensor rather than a collection of independent radios. + * + * Framing: every mesh message starts with rv_mesh_header_t (magic, + * version, type, sender_role, epoch, length) so a receiver can dispatch + * without reading the whole body. The trailing 4 bytes of every message + * are an IEEE CRC32 over the preceding bytes. Authentication + * (HMAC-SHA256 + replay window) is layered on top by + * wifi-densepose-hardware/src/esp32/secure_tdm.rs (ADR-032) for control + * messages that cross the swarm; FEATURE_DELTA uses the integrity + * protection already present in rv_feature_state_t (CRC + monotonic seq). + */ + +#ifndef RV_MESH_H +#define RV_MESH_H + +#include +#include +#include +#include "esp_err.h" +#include "rv_feature_state.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* ---- Magic + version ---- */ + +/** ADR-081 mesh envelope magic. Distinct from the ADR-018 CSI magic. */ +#define RV_MESH_MAGIC 0xC5118100u + +/** Protocol version. Bumped on any wire-format change. */ +#define RV_MESH_VERSION 1u + +/** Maximum mesh payload size (excluding header + CRC). */ +#define RV_MESH_MAX_PAYLOAD 256u + +/* ---- Node roles (ADR-081 Layer 3) ---- */ + +typedef enum { + RV_ROLE_UNASSIGNED = 0, + RV_ROLE_ANCHOR = 1, /**< Emits timed probes + global time beacons. */ + RV_ROLE_OBSERVER = 2, /**< Captures CSI + local metadata. */ + RV_ROLE_FUSION_RELAY = 3, /**< Aggregates summaries, forwards deltas. */ + RV_ROLE_COORDINATOR = 4, /**< Elects channels, assigns roles. */ + RV_ROLE_COUNT +} rv_mesh_role_t; + +/* ---- Authorization classes for control messages ---- */ + +typedef enum { + RV_AUTH_NONE = 0, /**< Telemetry; integrity via CRC only. */ + RV_AUTH_HMAC_SESSION = 1, /**< HMAC-SHA256 with session key (ADR-032). */ + RV_AUTH_ED25519_BATCH = 2, /**< Ed25519 signature at batch/session. */ +} rv_mesh_auth_class_t; + +/* ---- Message types ---- */ + +typedef enum { + RV_MSG_TIME_SYNC = 0x01, + RV_MSG_ROLE_ASSIGN = 0x02, + RV_MSG_CHANNEL_PLAN = 0x03, + RV_MSG_CALIBRATION_START = 0x04, + RV_MSG_FEATURE_DELTA = 0x05, /**< Carries rv_feature_state_t. */ + RV_MSG_HEALTH = 0x06, + RV_MSG_ANOMALY_ALERT = 0x07, +} rv_mesh_msg_type_t; + +/* ---- Common envelope header (16 bytes) ---- */ + +typedef struct __attribute__((packed)) { + uint32_t magic; /**< RV_MESH_MAGIC. */ + uint8_t version; /**< RV_MESH_VERSION. */ + uint8_t type; /**< rv_mesh_msg_type_t. */ + uint8_t sender_role; /**< rv_mesh_role_t of the sender at send time. */ + uint8_t auth_class; /**< rv_mesh_auth_class_t. */ + uint32_t epoch; /**< Monotonic epoch or session counter. */ + uint16_t payload_len; /**< Body length excluding header + trailing CRC. */ + uint16_t reserved; +} rv_mesh_header_t; + +_Static_assert(sizeof(rv_mesh_header_t) == 16, + "rv_mesh_header_t must be 16 bytes"); + +/* ---- Node health payload (RV_MSG_HEALTH) ---- */ + +typedef struct __attribute__((packed)) { + uint8_t node_id[8]; /**< 8-byte node identity. */ + uint64_t local_time_us; /**< Sender-local microseconds. */ + uint8_t role; /**< rv_mesh_role_t. */ + uint8_t current_channel; + uint8_t current_bw; /**< MHz (20, 40). */ + int8_t noise_floor_dbm; + uint16_t pkt_yield; /**< CSI callbacks/sec over the last window. */ + uint16_t sync_error_us; /**< Absolute drift vs. anchor. */ + uint16_t health_flags; + uint16_t reserved; +} rv_node_status_t; + +_Static_assert(sizeof(rv_node_status_t) == 28, + "rv_node_status_t must be 28 bytes"); + +/* ---- TIME_SYNC payload ---- */ + +typedef struct __attribute__((packed)) { + uint64_t anchor_time_us; /**< Anchor's local µs at emit. */ + uint32_t cycle_id; + uint32_t cycle_period_us; +} rv_time_sync_t; + +_Static_assert(sizeof(rv_time_sync_t) == 16, + "rv_time_sync_t must be 16 bytes"); + +/* ---- ROLE_ASSIGN payload ---- */ + +typedef struct __attribute__((packed)) { + uint8_t target_node_id[8]; + uint8_t new_role; /**< rv_mesh_role_t. */ + uint8_t reserved[3]; + uint32_t effective_epoch; +} rv_role_assign_t; + +_Static_assert(sizeof(rv_role_assign_t) == 16, + "rv_role_assign_t must be 16 bytes"); + +/* ---- CHANNEL_PLAN payload ---- */ + +#define RV_CHANNEL_PLAN_MAX 8 + +typedef struct __attribute__((packed)) { + uint8_t target_node_id[8]; + uint8_t channel_count; + uint8_t dwell_ms_hi; /**< dwell_ms, big-endian to fit u16 in two bytes */ + uint8_t dwell_ms_lo; + uint8_t debug_raw_csi; /**< 1 = enable raw ADR-018 stream; 0 = feature_state only. */ + uint8_t channels[RV_CHANNEL_PLAN_MAX]; + uint32_t effective_epoch; +} rv_channel_plan_t; + +_Static_assert(sizeof(rv_channel_plan_t) == 24, + "rv_channel_plan_t must be 24 bytes"); + +/* ---- CALIBRATION_START payload ---- */ + +typedef struct __attribute__((packed)) { + uint64_t t0_anchor_us; /**< Start time on anchor clock. */ + uint32_t duration_ms; + uint32_t effective_epoch; + uint8_t calibration_profile; /**< rv_capture_profile_t (usually CALIBRATION). */ + uint8_t reserved[3]; +} rv_calibration_start_t; + +_Static_assert(sizeof(rv_calibration_start_t) == 20, + "rv_calibration_start_t must be 20 bytes"); + +/* ---- ANOMALY_ALERT payload ---- */ + +typedef struct __attribute__((packed)) { + uint8_t node_id[8]; + uint64_t ts_us; + uint8_t severity; /**< 0..255 scaled anomaly. */ + uint8_t reason; /**< rv_anomaly_reason_t. */ + uint16_t reserved; + float anomaly_score; + float motion_score; +} rv_anomaly_alert_t; + +_Static_assert(sizeof(rv_anomaly_alert_t) == 28, + "rv_anomaly_alert_t must be 28 bytes"); + +typedef enum { + RV_ANOMALY_NONE = 0, + RV_ANOMALY_PHYSICS_VIOLATION = 1, + RV_ANOMALY_MULTI_LINK_MISMATCH = 2, + RV_ANOMALY_PKT_YIELD_COLLAPSE = 3, + RV_ANOMALY_FALL = 4, + RV_ANOMALY_COHERENCE_LOSS = 5, +} rv_anomaly_reason_t; + +/* ---- Encoder / decoder API ---- */ + +/** Maximum on-wire mesh frame: header + max payload + crc. */ +#define RV_MESH_MAX_FRAME_BYTES (sizeof(rv_mesh_header_t) + RV_MESH_MAX_PAYLOAD + 4u) + +/** + * Encode a typed mesh message into a contiguous buffer. + * + * Writes header(16) + payload(payload_len) + crc32(4). The caller owns + * the buffer; buf_cap must be at least sizeof(rv_mesh_header_t) + + * payload_len + 4. The payload pointer may be NULL iff payload_len == 0. + * + * @return bytes written on success, or 0 on error (bad args / overflow). + */ +size_t rv_mesh_encode(uint8_t type, + uint8_t sender_role, + uint8_t auth_class, + uint32_t epoch, + const void *payload, + uint16_t payload_len, + uint8_t *buf, + size_t buf_cap); + +/** + * Validate + parse a mesh frame received from the wire. + * + * Checks magic, version, sizeof(rv_mesh_header_t) bounds, payload_len + * bounds, and CRC32. On success, fills *out_hdr with the header and sets + * *out_payload to point at the payload inside buf (aliasing, not copied) + * plus *out_payload_len to the payload byte count. + * + * @return ESP_OK on success, or an ESP_ERR_* code on failure. + */ +esp_err_t rv_mesh_decode(const uint8_t *buf, size_t buf_len, + rv_mesh_header_t *out_hdr, + const uint8_t **out_payload, + uint16_t *out_payload_len); + +/** + * Convenience helpers — encode a specific message type into buf. + * Each returns the number of bytes written, 0 on error. + */ +size_t rv_mesh_encode_health(uint8_t sender_role, + uint32_t epoch, + const rv_node_status_t *status, + uint8_t *buf, size_t buf_cap); + +size_t rv_mesh_encode_anomaly_alert(uint8_t sender_role, + uint32_t epoch, + const rv_anomaly_alert_t *alert, + uint8_t *buf, size_t buf_cap); + +size_t rv_mesh_encode_feature_delta(uint8_t sender_role, + uint32_t epoch, + const rv_feature_state_t *fs, + uint8_t *buf, size_t buf_cap); + +size_t rv_mesh_encode_time_sync(uint8_t sender_role, + uint32_t epoch, + const rv_time_sync_t *ts, + uint8_t *buf, size_t buf_cap); + +size_t rv_mesh_encode_role_assign(uint8_t sender_role, + uint32_t epoch, + const rv_role_assign_t *ra, + uint8_t *buf, size_t buf_cap); + +size_t rv_mesh_encode_channel_plan(uint8_t sender_role, + uint32_t epoch, + const rv_channel_plan_t *cp, + uint8_t *buf, size_t buf_cap); + +size_t rv_mesh_encode_calibration_start(uint8_t sender_role, + uint32_t epoch, + const rv_calibration_start_t *cs, + uint8_t *buf, size_t buf_cap); + +/* ---- Send API ---- */ + +/** + * Send a pre-encoded mesh frame over the primary upstream UDP socket + * (the same one stream_sender uses for ADR-018 and rv_feature_state_t). + * + * @return ESP_OK on success. + */ +esp_err_t rv_mesh_send(const uint8_t *frame, size_t len); + +/** + * Convenience: build + send a HEALTH message for this node. + * + * Fills the rv_node_status_t from the live radio ops + controller + * observation, then encodes and sends in one call. Safe to call from a + * FreeRTOS timer. + */ +esp_err_t rv_mesh_send_health(uint8_t role, uint32_t epoch, + const uint8_t node_id[8]); + +/** + * Convenience: build + send an ANOMALY_ALERT. + */ +esp_err_t rv_mesh_send_anomaly(uint8_t role, uint32_t epoch, + const uint8_t node_id[8], + uint8_t reason, + uint8_t severity, + float anomaly_score, + float motion_score); + +#ifdef __cplusplus +} +#endif + +#endif /* RV_MESH_H */ diff --git a/firmware/esp32-csi-node/tests/host/Makefile b/firmware/esp32-csi-node/tests/host/Makefile index cc26033b..a27f2c4a 100644 --- a/firmware/esp32-csi-node/tests/host/Makefile +++ b/firmware/esp32-csi-node/tests/host/Makefile @@ -29,7 +29,7 @@ FEATURE_STATE_SRCS := $(MAIN_DIR)/rv_feature_state.c # before including the .c. The decide() body itself has no ESP-IDF deps. # Simpler: just recompile decide() here via a small shim. -TESTS := test_adaptive_controller test_rv_feature_state +TESTS := test_adaptive_controller test_rv_feature_state test_rv_mesh all: $(TESTS) @@ -39,10 +39,19 @@ test_adaptive_controller: test_adaptive_controller.c $(MAIN_DIR)/adaptive_contro test_rv_feature_state: test_rv_feature_state.c $(FEATURE_STATE_SRCS) $(MAIN_DIR)/rv_feature_state.h $(MAIN_DIR)/rv_radio_ops.h $(CC) $(CFLAGS) test_rv_feature_state.c $(FEATURE_STATE_SRCS) -o $@ $(LDLIBS) +# Mesh plane encoder/decoder: compile rv_mesh.c with RV_MESH_HOST_TEST +# so the firmware-only send helpers (stream_sender, esp_log) are hidden. +test_rv_mesh: test_rv_mesh.c $(MAIN_DIR)/rv_mesh.c $(MAIN_DIR)/rv_mesh.h $(FEATURE_STATE_SRCS) $(MAIN_DIR)/rv_radio_ops.h + $(CC) $(CFLAGS) -DRV_MESH_HOST_TEST=1 \ + test_rv_mesh.c $(MAIN_DIR)/rv_mesh.c $(FEATURE_STATE_SRCS) \ + -o $@ $(LDLIBS) + check: all ./test_adaptive_controller @echo "" ./test_rv_feature_state + @echo "" + ./test_rv_mesh clean: rm -f $(TESTS) *.o diff --git a/firmware/esp32-csi-node/tests/host/esp_err.h b/firmware/esp32-csi-node/tests/host/esp_err.h index dcace51e..7ef2356f 100644 --- a/firmware/esp32-csi-node/tests/host/esp_err.h +++ b/firmware/esp32-csi-node/tests/host/esp_err.h @@ -8,9 +8,12 @@ typedef int esp_err_t; -#define ESP_OK 0 -#define ESP_FAIL -1 -#define ESP_ERR_NO_MEM 0x101 -#define ESP_ERR_INVALID_ARG 0x102 +#define ESP_OK 0 +#define ESP_FAIL -1 +#define ESP_ERR_NO_MEM 0x101 +#define ESP_ERR_INVALID_ARG 0x102 +#define ESP_ERR_INVALID_SIZE 0x104 +#define ESP_ERR_INVALID_VERSION 0x10A +#define ESP_ERR_INVALID_CRC 0x10B #endif diff --git a/firmware/esp32-csi-node/tests/host/test_rv_mesh.c b/firmware/esp32-csi-node/tests/host/test_rv_mesh.c new file mode 100644 index 00000000..51e7a22e --- /dev/null +++ b/firmware/esp32-csi-node/tests/host/test_rv_mesh.c @@ -0,0 +1,219 @@ +/* + * Host unit test for ADR-081 Layer 3 mesh plane encode/decode. + * + * rv_mesh_encode() and rv_mesh_decode() are the pure halves of the + * mesh plane — no ESP-IDF, no sockets — so we exercise them with the + * RV_MESH_HOST_TEST flag that disables the send helpers. + */ + +#include +#include +#include +#include + +#include "rv_mesh.h" +#include "rv_feature_state.h" +#include "rv_radio_ops.h" /* for RV_PROFILE_* enum values */ + +static int g_pass = 0, g_fail = 0; +#define CHECK(cond, msg) do { \ + if (cond) { g_pass++; } \ + else { g_fail++; printf(" FAIL: %s (line %d)\n", msg, __LINE__); } \ +} while (0) + +static void test_header_size(void) { + printf("test: rv_mesh_header_t is 16 bytes\n"); + CHECK(sizeof(rv_mesh_header_t) == 16, "sizeof(header) == 16"); +} + +static void test_encode_health_roundtrip(void) { + printf("test: HEALTH roundtrip\n"); + rv_node_status_t st; + memset(&st, 0, sizeof(st)); + st.node_id[0] = 7; + st.local_time_us = 1234567890ULL; + st.role = RV_ROLE_OBSERVER; + st.current_channel = 6; + st.current_bw = 20; + st.noise_floor_dbm = -93; + st.pkt_yield = 42; + st.sync_error_us = 12; + + uint8_t buf[RV_MESH_MAX_FRAME_BYTES]; + size_t n = rv_mesh_encode_health(RV_ROLE_OBSERVER, /*epoch*/ 100, + &st, buf, sizeof(buf)); + CHECK(n > 0, "encode returns non-zero"); + CHECK(n == sizeof(rv_mesh_header_t) + sizeof(st) + 4, + "encoded size = hdr+payload+crc"); + + rv_mesh_header_t hdr; + const uint8_t *payload = NULL; + uint16_t payload_len = 0; + esp_err_t rc = rv_mesh_decode(buf, n, &hdr, &payload, &payload_len); + CHECK(rc == ESP_OK, "decode OK"); + CHECK(hdr.type == RV_MSG_HEALTH, "type == HEALTH"); + CHECK(hdr.epoch == 100, "epoch survives"); + CHECK(hdr.payload_len == sizeof(st), "payload_len matches"); + CHECK(payload != NULL, "payload pointer set"); + CHECK(memcmp(payload, &st, sizeof(st)) == 0, "payload bytes match"); +} + +static void test_encode_anomaly_roundtrip(void) { + printf("test: ANOMALY_ALERT roundtrip\n"); + rv_anomaly_alert_t a; + memset(&a, 0, sizeof(a)); + a.node_id[0] = 3; + a.ts_us = 999999ULL; + a.reason = RV_ANOMALY_FALL; + a.severity = 200; + a.anomaly_score = 0.85f; + a.motion_score = 0.9f; + + uint8_t buf[RV_MESH_MAX_FRAME_BYTES]; + size_t n = rv_mesh_encode_anomaly_alert(RV_ROLE_OBSERVER, 7, &a, + buf, sizeof(buf)); + CHECK(n > 0, "encoded"); + + rv_mesh_header_t hdr; + const uint8_t *payload = NULL; + uint16_t payload_len = 0; + esp_err_t rc = rv_mesh_decode(buf, n, &hdr, &payload, &payload_len); + CHECK(rc == ESP_OK, "decoded"); + CHECK(hdr.type == RV_MSG_ANOMALY_ALERT, "type ok"); + rv_anomaly_alert_t got; + memcpy(&got, payload, sizeof(got)); + CHECK(got.reason == RV_ANOMALY_FALL, "reason survived"); + CHECK(got.severity == 200, "severity survived"); +} + +static void test_encode_feature_delta_wraps_feature_state(void) { + printf("test: FEATURE_DELTA wraps rv_feature_state_t\n"); + rv_feature_state_t fs; + memset(&fs, 0, sizeof(fs)); + fs.motion_score = 0.5f; + rv_feature_state_finalize(&fs, /*node*/ 9, /*seq*/ 17, + /*ts*/ 111ULL, RV_PROFILE_FAST_MOTION); + + uint8_t buf[RV_MESH_MAX_FRAME_BYTES]; + size_t n = rv_mesh_encode_feature_delta(RV_ROLE_OBSERVER, 2, &fs, + buf, sizeof(buf)); + CHECK(n == sizeof(rv_mesh_header_t) + sizeof(fs) + 4, "size check"); + + rv_mesh_header_t hdr; + const uint8_t *payload = NULL; + uint16_t len = 0; + CHECK(rv_mesh_decode(buf, n, &hdr, &payload, &len) == ESP_OK, + "decode OK"); + rv_feature_state_t got; + memcpy(&got, payload, sizeof(got)); + CHECK(got.magic == RV_FEATURE_STATE_MAGIC, "inner magic preserved"); + CHECK(got.node_id == 9, "inner node_id preserved"); + CHECK(got.seq == 17, "inner seq preserved"); + /* Inner CRC is end-to-end even though the mesh frame has its own + * CRC too — two checks for two failure modes. */ + uint32_t inner_crc = rv_feature_state_crc32( + (const uint8_t *)&got, sizeof(got) - sizeof(uint32_t)); + CHECK(inner_crc == got.crc32, "inner feature_state CRC still valid"); +} + +static void test_decode_rejects_bad_magic(void) { + printf("test: decode rejects bad magic\n"); + uint8_t buf[sizeof(rv_mesh_header_t) + 4]; + memset(buf, 0xFF, sizeof(buf)); + + rv_mesh_header_t hdr; + const uint8_t *p = NULL; + uint16_t plen = 0; + esp_err_t rc = rv_mesh_decode(buf, sizeof(buf), &hdr, &p, &plen); + CHECK(rc != ESP_OK, "bad magic rejected"); +} + +static void test_decode_rejects_truncated(void) { + printf("test: decode rejects truncated frame\n"); + uint8_t buf[sizeof(rv_mesh_header_t) - 1]; + memset(buf, 0, sizeof(buf)); + rv_mesh_header_t hdr; + const uint8_t *p = NULL; + uint16_t plen = 0; + esp_err_t rc = rv_mesh_decode(buf, sizeof(buf), &hdr, &p, &plen); + CHECK(rc != ESP_OK, "truncated rejected"); +} + +static void test_decode_rejects_bad_crc(void) { + printf("test: decode rejects CRC mismatch\n"); + rv_node_status_t st; + memset(&st, 0, sizeof(st)); + st.role = RV_ROLE_OBSERVER; + uint8_t buf[RV_MESH_MAX_FRAME_BYTES]; + size_t n = rv_mesh_encode_health(RV_ROLE_OBSERVER, 1, &st, + buf, sizeof(buf)); + CHECK(n > 0, "encoded"); + + /* Flip a byte in the payload — CRC must now mismatch. */ + buf[sizeof(rv_mesh_header_t) + 4] ^= 0x10; + + rv_mesh_header_t hdr; + const uint8_t *p = NULL; + uint16_t plen = 0; + esp_err_t rc = rv_mesh_decode(buf, n, &hdr, &p, &plen); + CHECK(rc != ESP_OK, "CRC mismatch rejected"); +} + +static void test_encode_rejects_oversize_payload(void) { + printf("test: encode rejects oversize payload\n"); + uint8_t junk[RV_MESH_MAX_PAYLOAD + 1] = {0}; + uint8_t buf[RV_MESH_MAX_FRAME_BYTES + 8]; + size_t n = rv_mesh_encode(RV_MSG_HEALTH, RV_ROLE_OBSERVER, RV_AUTH_NONE, + 0, junk, sizeof(junk), buf, sizeof(buf)); + CHECK(n == 0, "oversize payload → 0"); +} + +static void test_encode_rejects_small_buf(void) { + printf("test: encode rejects too-small buffer\n"); + rv_node_status_t st = {0}; + uint8_t buf[16]; /* header fits but not payload */ + size_t n = rv_mesh_encode_health(RV_ROLE_OBSERVER, 0, &st, + buf, sizeof(buf)); + CHECK(n == 0, "small buf → 0"); +} + +static void benchmark_encode(void) { + printf("bench: encode+decode HEALTH roundtrip\n"); + rv_node_status_t st; + memset(&st, 0x33, sizeof(st)); + uint8_t buf[RV_MESH_MAX_FRAME_BYTES]; + + const int N = 2000000; + struct timespec a, b; + clock_gettime(CLOCK_MONOTONIC, &a); + for (int i = 0; i < N; i++) { + st.pkt_yield = (uint16_t)i; + size_t n = rv_mesh_encode_health(RV_ROLE_OBSERVER, (uint32_t)i, + &st, buf, sizeof(buf)); + rv_mesh_header_t hdr; + const uint8_t *p = NULL; + uint16_t plen = 0; + (void)rv_mesh_decode(buf, n, &hdr, &p, &plen); + } + clock_gettime(CLOCK_MONOTONIC, &b); + double ns = ((b.tv_sec - a.tv_sec) * 1e9 + + (b.tv_nsec - a.tv_nsec)) / (double)N; + printf(" %d roundtrips, %.1f ns/call\n", N, ns); + CHECK(ns < 20000.0, "encode+decode must be under 20us/roundtrip"); +} + +int main(void) { + printf("=== rv_mesh encode/decode host tests ===\n\n"); + test_header_size(); + test_encode_health_roundtrip(); + test_encode_anomaly_roundtrip(); + test_encode_feature_delta_wraps_feature_state(); + test_decode_rejects_bad_magic(); + test_decode_rejects_truncated(); + test_decode_rejects_bad_crc(); + test_encode_rejects_oversize_payload(); + test_encode_rejects_small_buf(); + benchmark_encode(); + printf("\n=== result: %d pass, %d fail ===\n", g_pass, g_fail); + return g_fail > 0 ? 1 : 0; +} diff --git a/rust-port/wifi-densepose-rs/Cargo.lock b/rust-port/wifi-densepose-rs/Cargo.lock index a794fabb..984c4241 100644 --- a/rust-port/wifi-densepose-rs/Cargo.lock +++ b/rust-port/wifi-densepose-rs/Cargo.lock @@ -139,6 +139,15 @@ version = "1.0.102" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c" +[[package]] +name = "approx" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f2a05fd1bd10b2527e20a2cd32d8873d115b8b39fe219ee25f42a8aca6ba278" +dependencies = [ + "num-traits", +] + [[package]] name = "approx" version = "0.5.1" @@ -623,6 +632,27 @@ version = "0.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "37b2a672a2cb129a2e41c10b1224bb368f9f37a2b16b612598138befd7b37eb5" +[[package]] +name = "cauchy" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9ff11ddd2af3b5e80dd0297fee6e56ac038d9bdc549573cdb51bd6d2efe7f05e" +dependencies = [ + "num-complex", + "num-traits", + "rand 0.8.5", + "serde", +] + +[[package]] +name = "cblas-sys" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6feecd82cce51b0204cf063f0041d69f24ce83f680d87514b004248e7b0fa65" +dependencies = [ + "libc", +] + [[package]] name = "cc" version = "1.2.56" @@ -1420,6 +1450,17 @@ dependencies = [ "rustc_version", ] +[[package]] +name = "filetime" +version = "0.2.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f98844151eee8917efc50bd9e8318cb963ae8b297431495d3f758616ea5c57db" +dependencies = [ + "cfg-if", + "libc", + "libredox", +] + [[package]] name = "find-msvc-tools" version = "0.1.9" @@ -1908,7 +1949,7 @@ version = "0.7.18" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "24f8647af4005fa11da47cd56252c6ef030be8fa97bdbf355e7dfb6348f0a82c" dependencies = [ - "approx", + "approx 0.5.1", "num-traits", "rstar 0.10.0", "rstar 0.11.0", @@ -2780,6 +2821,17 @@ dependencies = [ "serde_json", ] +[[package]] +name = "katexit" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ccfb0b7ce7938f84a5ecbdca5d0a991e46bc9d6d078934ad5e92c5270fe547db" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.117", +] + [[package]] name = "keyboard-types" version = "0.7.0" @@ -2803,6 +2855,29 @@ dependencies = [ "selectors", ] +[[package]] +name = "lapack-sys" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "447f56c85fb410a7a3d36701b2153c1018b1d2b908c5fbaf01c1b04fac33bcbe" +dependencies = [ + "libc", +] + +[[package]] +name = "lax" +version = "0.16.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1f96a229d9557112e574164f8024ce703625ad9f88a90964c1780809358e53da" +dependencies = [ + "cauchy", + "katexit", + "lapack-sys", + "num-traits", + "openblas-src", + "thiserror 1.0.69", +] + [[package]] name = "lazy_static" version = "1.5.0" @@ -2867,7 +2942,10 @@ version = "0.1.14" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1744e39d1d6a9948f4f388969627434e31128196de472883b39f148769bfe30a" dependencies = [ + "bitflags 2.11.0", "libc", + "plain", + "redox_syscall 0.7.4", ] [[package]] @@ -3218,7 +3296,7 @@ version = "0.33.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "26aecdf64b707efd1310e3544d709c5c0ac61c13756046aaaba41be5c4f66a3b" dependencies = [ - "approx", + "approx 0.5.1", "matrixmultiply", "nalgebra-macros", "num-complex", @@ -3271,6 +3349,9 @@ version = "0.15.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "adb12d4e967ec485a5f71c6311fe28158e9d6f4bc4a447b474184d0f91a8fa32" dependencies = [ + "approx 0.4.0", + "cblas-sys", + "libc", "matrixmultiply", "num-complex", "num-integer", @@ -3310,6 +3391,22 @@ dependencies = [ "rawpointer", ] +[[package]] +name = "ndarray-linalg" +version = "0.16.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b0e8dda0c941b64a85c5deb2b3e0144aca87aced64678adfc23eacea6d2cc42" +dependencies = [ + "cauchy", + "katexit", + "lax", + "ndarray 0.15.6", + "num-complex", + "num-traits", + "rand 0.8.5", + "thiserror 1.0.69", +] + [[package]] name = "ndarray-npy" version = "0.8.1" @@ -3441,6 +3538,8 @@ checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495" dependencies = [ "bytemuck", "num-traits", + "rand 0.8.5", + "serde", ] [[package]] @@ -3670,6 +3769,32 @@ dependencies = [ "pathdiff", ] +[[package]] +name = "openblas-build" +version = "0.10.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd235aa8876fa5c4be452efde09b9b8bafa19aea0bf14a4926508213082439a3" +dependencies = [ + "anyhow", + "cc", + "flate2", + "tar", + "thiserror 2.0.18", + "ureq", +] + +[[package]] +name = "openblas-src" +version = "0.10.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fccd2c4f5271ab871f2069cb6f1a13ef2c0db50e1145ce03428ee541f4c63c4f" +dependencies = [ + "dirs", + "openblas-build", + "pkg-config", + "vcpkg", +] + [[package]] name = "openssl" version = "0.10.75" @@ -3819,7 +3944,7 @@ checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1" dependencies = [ "cfg-if", "libc", - "redox_syscall", + "redox_syscall 0.5.18", "smallvec", "windows-link 0.2.1", ] @@ -4095,6 +4220,12 @@ version = "0.3.32" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7edddbd0b52d732b21ad9a5fab5c704c14cd949e5e9a1ec5929a24fded1b904c" +[[package]] +name = "plain" +version = "0.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b4596b6d070b27117e987119b4dac604f3c58cfb0b191112e24771b2faeac1a6" + [[package]] name = "plist" version = "1.8.0" @@ -4694,6 +4825,15 @@ dependencies = [ "bitflags 2.11.0", ] +[[package]] +name = "redox_syscall" +version = "0.7.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f450ad9c3b1da563fb6948a8e0fb0fb9269711c9c73d9ea1de5058c79c8d643a" +dependencies = [ + "bitflags 2.11.0", +] + [[package]] name = "redox_users" version = "0.5.2" @@ -5737,7 +5877,7 @@ version = "0.9.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c99284beb21666094ba2b75bbceda012e610f5479dfcc2d6e2426f53197ffd95" dependencies = [ - "approx", + "approx 0.5.1", "num-complex", "num-traits", "paste", @@ -5826,7 +5966,7 @@ dependencies = [ "objc2-foundation", "objc2-quartz-core", "raw-window-handle", - "redox_syscall", + "redox_syscall 0.5.18", "tracing", "wasm-bindgen", "web-sys", @@ -6098,6 +6238,17 @@ dependencies = [ "syn 2.0.117", ] +[[package]] +name = "tar" +version = "0.4.45" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "22692a6476a21fa75fdfc11d452fda482af402c008cdbaf3476414e122040973" +dependencies = [ + "filetime", + "libc", + "xattr", +] + [[package]] name = "target-lexicon" version = "0.12.16" @@ -7673,7 +7824,7 @@ dependencies = [ name = "wifi-densepose-hardware" version = "0.3.0" dependencies = [ - "approx", + "approx 0.5.1", "byteorder", "chrono", "clap", @@ -7694,7 +7845,7 @@ name = "wifi-densepose-mat" version = "0.3.0" dependencies = [ "anyhow", - "approx", + "approx 0.5.1", "async-trait", "axum", "chrono", @@ -7747,7 +7898,7 @@ dependencies = [ name = "wifi-densepose-ruvector" version = "0.3.0" dependencies = [ - "approx", + "approx 0.5.1", "criterion", "ruvector-attention 2.0.4", "ruvector-attn-mincut", @@ -7769,7 +7920,6 @@ dependencies = [ "chrono", "clap", "futures-util", - "ruvector-mincut", "serde", "serde_json", "tempfile", @@ -7777,6 +7927,7 @@ dependencies = [ "tower-http 0.5.2", "tracing", "tracing-subscriber", + "wifi-densepose-signal", "wifi-densepose-wifiscan", ] @@ -7789,6 +7940,7 @@ dependencies = [ "midstreamer-attractor", "midstreamer-temporal-compare", "ndarray 0.15.6", + "ndarray-linalg", "num-complex", "num-traits", "proptest", @@ -7808,7 +7960,7 @@ name = "wifi-densepose-train" version = "0.3.0" dependencies = [ "anyhow", - "approx", + "approx 0.5.1", "chrono", "clap", "criterion", @@ -8622,6 +8774,16 @@ dependencies = [ "pkg-config", ] +[[package]] +name = "xattr" +version = "1.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32e45ad4206f6d2479085147f02bc2ef834ac85886624a23575ae137c8aa8156" +dependencies = [ + "libc", + "rustix", +] + [[package]] name = "yasna" version = "0.5.2" diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-hardware/src/lib.rs b/rust-port/wifi-densepose-rs/crates/wifi-densepose-hardware/src/lib.rs index 3bae0764..a54b8157 100644 --- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-hardware/src/lib.rs +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-hardware/src/lib.rs @@ -41,7 +41,20 @@ pub mod aggregator; mod bridge; pub mod esp32; +// ADR-081: Rust mirror of the firmware radio abstraction layer (L1) and +// mesh sensing plane (L3). Lets host tests, simulators, and future +// coordinator-node Rust code drive the controller stack without +// touching any downstream signal/ruvector/train/mat crate. +pub mod radio_ops; + pub use csi_frame::{CsiFrame, CsiMetadata, SubcarrierData, Bandwidth, AntennaConfig}; pub use error::ParseError; pub use esp32_parser::Esp32CsiParser; pub use bridge::CsiData; +pub use radio_ops::{ + RadioOps, RadioMode, CaptureProfile, RadioHealth, RadioError, MockRadio, + MeshRole, MeshMsgType, AuthClass, MeshHeader, NodeStatus, AnomalyAlert, + MeshError, MESH_MAGIC, MESH_VERSION, MESH_HEADER_SIZE, MESH_MAX_PAYLOAD, + crc32_ieee, decode_mesh, decode_node_status, decode_anomaly_alert, + encode_health, +}; diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-hardware/src/radio_ops.rs b/rust-port/wifi-densepose-rs/crates/wifi-densepose-hardware/src/radio_ops.rs new file mode 100644 index 00000000..5866af6e --- /dev/null +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-hardware/src/radio_ops.rs @@ -0,0 +1,535 @@ +//! ADR-081 Layer 1 Rust mirror + Layer 3 mesh-plane decoder. +//! +//! Mirrors the C vtable `rv_radio_ops_t` defined in +//! `firmware/esp32-csi-node/main/rv_radio_ops.h` so that test harnesses, +//! simulators, and future coordinator-node Rust code can drive the +//! controller logic against a mock backend without touching +//! `wifi-densepose-signal`, `-ruvector`, `-train`, or `-mat`. That +//! portability is the ADR-081 acceptance test: "swap one radio family +//! for another without changing the Rust memory and reasoning layers". +//! +//! The mesh-plane types (`MeshHeader`, `NodeStatus`, `AnomalyAlert`, +//! etc.) mirror `rv_mesh.h` and deserialize the wire format produced by +//! `rv_mesh_encode*()`. This lets a Rust-side aggregator or test node +//! decode live traffic from the ESP32 nodes without re-implementing +//! the framing. + +use std::convert::TryFrom; + +// --------------------------------------------------------------------------- +// Layer 1 — Radio Abstraction Layer (mirror of rv_radio_ops_t) +// --------------------------------------------------------------------------- + +/// Operating modes, mirror of `rv_radio_mode_t`. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +#[repr(u8)] +pub enum RadioMode { + Disabled = 0, + PassiveRx = 1, + ActiveProbe = 2, + Calibration = 3, +} + +/// Named capture profiles, mirror of `rv_capture_profile_t`. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +#[repr(u8)] +pub enum CaptureProfile { + PassiveLowRate = 0, + ActiveProbe = 1, + RespHighSens = 2, + FastMotion = 3, + Calibration = 4, +} + +impl TryFrom for CaptureProfile { + type Error = RadioError; + fn try_from(v: u8) -> Result { + match v { + 0 => Ok(CaptureProfile::PassiveLowRate), + 1 => Ok(CaptureProfile::ActiveProbe), + 2 => Ok(CaptureProfile::RespHighSens), + 3 => Ok(CaptureProfile::FastMotion), + 4 => Ok(CaptureProfile::Calibration), + _ => Err(RadioError::UnknownProfile(v)), + } + } +} + +/// Health snapshot, mirror of `rv_radio_health_t`. +#[derive(Debug, Clone, Copy, Default, PartialEq)] +pub struct RadioHealth { + pub pkt_yield_per_sec: u16, + pub send_fail_count: u16, + pub rssi_median_dbm: i8, + pub noise_floor_dbm: i8, + pub current_channel: u8, + pub current_bw_mhz: u8, + pub current_profile: u8, +} + +#[derive(Debug, thiserror::Error)] +pub enum RadioError { + #[error("unknown capture profile id: {0}")] + UnknownProfile(u8), + #[error("backend error: {0}")] + Backend(String), +} + +/// Rust mirror of the `rv_radio_ops_t` vtable. +/// +/// Any Rust-side driver (mock, simulator, future coordinator node) that +/// wants to participate in the ADR-081 controller stack must implement +/// this trait. The controller's pure decision policy lives in +/// `adaptive_controller_decide.c` on the C side today; when the Rust +/// coordinator lands, it will reuse the decoded `NodeStatus` messages +/// this module parses and feed decisions back through these ops. +pub trait RadioOps: Send + Sync { + fn init(&mut self) -> Result<(), RadioError>; + fn set_channel(&mut self, ch: u8, bw: u8) -> Result<(), RadioError>; + fn set_mode(&mut self, mode: RadioMode) -> Result<(), RadioError>; + fn set_csi_enabled(&mut self, en: bool) -> Result<(), RadioError>; + fn set_capture_profile(&mut self, p: CaptureProfile) -> Result<(), RadioError>; + fn get_health(&self) -> Result; +} + +/// A zero-hardware radio backend for host tests and CI. +#[derive(Debug, Clone, Default)] +pub struct MockRadio { + pub health: RadioHealth, + pub init_count: u32, + pub channel_calls: Vec<(u8, u8)>, + pub profile_calls: Vec, + pub mode_calls: Vec, + pub csi_enabled: bool, +} + +impl RadioOps for MockRadio { + fn init(&mut self) -> Result<(), RadioError> { + self.init_count += 1; + Ok(()) + } + fn set_channel(&mut self, ch: u8, bw: u8) -> Result<(), RadioError> { + self.channel_calls.push((ch, bw)); + self.health.current_channel = ch; + self.health.current_bw_mhz = bw; + Ok(()) + } + fn set_mode(&mut self, mode: RadioMode) -> Result<(), RadioError> { + self.mode_calls.push(mode); + Ok(()) + } + fn set_csi_enabled(&mut self, en: bool) -> Result<(), RadioError> { + self.csi_enabled = en; + Ok(()) + } + fn set_capture_profile(&mut self, p: CaptureProfile) -> Result<(), RadioError> { + self.profile_calls.push(p); + self.health.current_profile = p as u8; + Ok(()) + } + fn get_health(&self) -> Result { + Ok(self.health) + } +} + +// --------------------------------------------------------------------------- +// Layer 3 — Mesh plane (mirror of rv_mesh.h) +// --------------------------------------------------------------------------- + +/// `RV_MESH_MAGIC` from rv_mesh.h. +pub const MESH_MAGIC: u32 = 0xC511_8100; +/// `RV_MESH_VERSION` from rv_mesh.h. +pub const MESH_VERSION: u8 = 1; +/// `RV_MESH_MAX_PAYLOAD` from rv_mesh.h. +pub const MESH_MAX_PAYLOAD: usize = 256; +/// `sizeof(rv_mesh_header_t)`. +pub const MESH_HEADER_SIZE: usize = 16; + +/// `rv_mesh_role_t`. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +#[repr(u8)] +pub enum MeshRole { + Unassigned = 0, + Anchor = 1, + Observer = 2, + FusionRelay = 3, + Coordinator = 4, +} + +impl TryFrom for MeshRole { + type Error = MeshError; + fn try_from(v: u8) -> Result { + match v { + 0 => Ok(MeshRole::Unassigned), + 1 => Ok(MeshRole::Anchor), + 2 => Ok(MeshRole::Observer), + 3 => Ok(MeshRole::FusionRelay), + 4 => Ok(MeshRole::Coordinator), + _ => Err(MeshError::UnknownRole(v)), + } + } +} + +/// `rv_mesh_msg_type_t`. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +#[repr(u8)] +pub enum MeshMsgType { + TimeSync = 0x01, + RoleAssign = 0x02, + ChannelPlan = 0x03, + CalibrationStart = 0x04, + FeatureDelta = 0x05, + Health = 0x06, + AnomalyAlert = 0x07, +} + +impl TryFrom for MeshMsgType { + type Error = MeshError; + fn try_from(v: u8) -> Result { + match v { + 0x01 => Ok(MeshMsgType::TimeSync), + 0x02 => Ok(MeshMsgType::RoleAssign), + 0x03 => Ok(MeshMsgType::ChannelPlan), + 0x04 => Ok(MeshMsgType::CalibrationStart), + 0x05 => Ok(MeshMsgType::FeatureDelta), + 0x06 => Ok(MeshMsgType::Health), + 0x07 => Ok(MeshMsgType::AnomalyAlert), + _ => Err(MeshError::UnknownMsgType(v)), + } + } +} + +/// `rv_mesh_auth_class_t`. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +#[repr(u8)] +pub enum AuthClass { + None = 0, + HmacSession = 1, + Ed25519Batch = 2, +} + +/// `rv_mesh_header_t`, 16 bytes. +#[derive(Debug, Clone, Copy)] +pub struct MeshHeader { + pub msg_type: MeshMsgType, + pub sender_role: MeshRole, + pub auth_class: AuthClass, + pub epoch: u32, + pub payload_len: u16, +} + +/// `rv_node_status_t`, 28 bytes. +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct NodeStatus { + pub node_id: [u8; 8], + pub local_time_us: u64, + pub role: MeshRole, + pub current_channel: u8, + pub current_bw: u8, + pub noise_floor_dbm: i8, + pub pkt_yield: u16, + pub sync_error_us: u16, + pub health_flags: u16, +} + +/// `rv_anomaly_alert_t`, 28 bytes. +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct AnomalyAlert { + pub node_id: [u8; 8], + pub ts_us: u64, + pub severity: u8, + pub reason: u8, + pub anomaly_score: f32, + pub motion_score: f32, +} + +#[derive(Debug, thiserror::Error)] +pub enum MeshError { + #[error("frame too short: {0} bytes")] + TooShort(usize), + #[error("bad magic: 0x{0:08X}")] + BadMagic(u32), + #[error("unsupported version: {0}")] + BadVersion(u8), + #[error("payload too large: {0}")] + PayloadTooLarge(u16), + #[error("CRC mismatch: got 0x{got:08X}, want 0x{want:08X}")] + CrcMismatch { got: u32, want: u32 }, + #[error("unknown role id: {0}")] + UnknownRole(u8), + #[error("unknown msg type: 0x{0:02X}")] + UnknownMsgType(u8), + #[error("unknown auth class: {0}")] + UnknownAuth(u8), + #[error("payload size mismatch for {which}: got {got}, want {want}")] + PayloadSizeMismatch { which: &'static str, got: usize, want: usize }, +} + +/// IEEE CRC32 — matches the bit-by-bit implementation in +/// `rv_feature_state.c`. Poly 0xEDB88320, init 0xFFFFFFFF, xor out. +pub fn crc32_ieee(data: &[u8]) -> u32 { + let mut crc: u32 = 0xFFFF_FFFF; + for &b in data { + crc ^= b as u32; + for _ in 0..8 { + let mask = (crc & 1).wrapping_neg(); + crc = (crc >> 1) ^ (0xEDB8_8320 & mask); + } + } + !crc +} + +/// Parse one mesh frame. Returns the decoded header and a slice view of +/// the payload inside the input buffer (no copy). +pub fn decode_mesh(buf: &[u8]) -> Result<(MeshHeader, &[u8]), MeshError> { + if buf.len() < MESH_HEADER_SIZE + 4 { + return Err(MeshError::TooShort(buf.len())); + } + + let magic = u32::from_le_bytes([buf[0], buf[1], buf[2], buf[3]]); + if magic != MESH_MAGIC { return Err(MeshError::BadMagic(magic)); } + + let version = buf[4]; + if version != MESH_VERSION { return Err(MeshError::BadVersion(version)); } + + let ty = buf[5]; + let sender_role = buf[6]; + let auth_class = buf[7]; + let epoch = u32::from_le_bytes([buf[8], buf[9], buf[10], buf[11]]); + let payload_len = u16::from_le_bytes([buf[12], buf[13]]); + + if payload_len as usize > MESH_MAX_PAYLOAD { + return Err(MeshError::PayloadTooLarge(payload_len)); + } + + let total = MESH_HEADER_SIZE + payload_len as usize + 4; + if buf.len() < total { return Err(MeshError::TooShort(buf.len())); } + + let want_crc = crc32_ieee(&buf[..MESH_HEADER_SIZE + payload_len as usize]); + let crc_off = MESH_HEADER_SIZE + payload_len as usize; + let got_crc = u32::from_le_bytes([ + buf[crc_off], buf[crc_off + 1], buf[crc_off + 2], buf[crc_off + 3], + ]); + if got_crc != want_crc { + return Err(MeshError::CrcMismatch { got: got_crc, want: want_crc }); + } + + let msg_type = MeshMsgType::try_from(ty)?; + let sender_role = MeshRole::try_from(sender_role)?; + let auth_class = match auth_class { + 0 => AuthClass::None, + 1 => AuthClass::HmacSession, + 2 => AuthClass::Ed25519Batch, + v => return Err(MeshError::UnknownAuth(v)), + }; + + Ok(( + MeshHeader { msg_type, sender_role, auth_class, epoch, payload_len }, + &buf[MESH_HEADER_SIZE .. MESH_HEADER_SIZE + payload_len as usize], + )) +} + +/// Decode a `HEALTH` payload (28 bytes). +pub fn decode_node_status(p: &[u8]) -> Result { + if p.len() != 28 { + return Err(MeshError::PayloadSizeMismatch { + which: "HEALTH", got: p.len(), want: 28, + }); + } + let mut node_id = [0u8; 8]; + node_id.copy_from_slice(&p[0..8]); + let local_time_us = u64::from_le_bytes([ + p[8], p[9], p[10], p[11], p[12], p[13], p[14], p[15], + ]); + Ok(NodeStatus { + node_id, + local_time_us, + role: MeshRole::try_from(p[16])?, + current_channel: p[17], + current_bw: p[18], + noise_floor_dbm: p[19] as i8, + pkt_yield: u16::from_le_bytes([p[20], p[21]]), + sync_error_us: u16::from_le_bytes([p[22], p[23]]), + health_flags: u16::from_le_bytes([p[24], p[25]]), + }) +} + +/// Decode an `ANOMALY_ALERT` payload (28 bytes). +pub fn decode_anomaly_alert(p: &[u8]) -> Result { + if p.len() != 28 { + return Err(MeshError::PayloadSizeMismatch { + which: "ANOMALY_ALERT", got: p.len(), want: 28, + }); + } + let mut node_id = [0u8; 8]; + node_id.copy_from_slice(&p[0..8]); + let ts_us = u64::from_le_bytes([ + p[8], p[9], p[10], p[11], p[12], p[13], p[14], p[15], + ]); + let anomaly_score = f32::from_le_bytes([p[20], p[21], p[22], p[23]]); + let motion_score = f32::from_le_bytes([p[24], p[25], p[26], p[27]]); + Ok(AnomalyAlert { + node_id, ts_us, + severity: p[16], + reason: p[17], + anomaly_score, motion_score, + }) +} + +/// Encode a `HEALTH` payload. Produces the 16-byte header, 28-byte +/// payload, and 4-byte CRC — bit-identical to what the firmware emits. +pub fn encode_health( + sender_role: MeshRole, + epoch: u32, + status: &NodeStatus, +) -> Vec { + let payload_len: u16 = 28; + let mut buf = Vec::with_capacity(MESH_HEADER_SIZE + payload_len as usize + 4); + + // header + buf.extend_from_slice(&MESH_MAGIC.to_le_bytes()); + buf.push(MESH_VERSION); + buf.push(MeshMsgType::Health as u8); + buf.push(sender_role as u8); + buf.push(AuthClass::None as u8); + buf.extend_from_slice(&epoch.to_le_bytes()); + buf.extend_from_slice(&payload_len.to_le_bytes()); + buf.extend_from_slice(&0u16.to_le_bytes()); // reserved + + // payload + buf.extend_from_slice(&status.node_id); + buf.extend_from_slice(&status.local_time_us.to_le_bytes()); + buf.push(status.role as u8); + buf.push(status.current_channel); + buf.push(status.current_bw); + buf.push(status.noise_floor_dbm as u8); + buf.extend_from_slice(&status.pkt_yield.to_le_bytes()); + buf.extend_from_slice(&status.sync_error_us.to_le_bytes()); + buf.extend_from_slice(&status.health_flags.to_le_bytes()); + buf.extend_from_slice(&0u16.to_le_bytes()); // reserved + + let crc = crc32_ieee(&buf); + buf.extend_from_slice(&crc.to_le_bytes()); + buf +} + +// --------------------------------------------------------------------------- +// Tests +// --------------------------------------------------------------------------- + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn mock_radio_tracks_calls() { + let mut r = MockRadio::default(); + assert!(r.init().is_ok()); + assert_eq!(r.init_count, 1); + r.set_channel(6, 20).unwrap(); + r.set_capture_profile(CaptureProfile::FastMotion).unwrap(); + r.set_mode(RadioMode::ActiveProbe).unwrap(); + r.set_csi_enabled(true).unwrap(); + assert_eq!(r.channel_calls, vec![(6, 20)]); + assert_eq!(r.profile_calls, vec![CaptureProfile::FastMotion]); + assert_eq!(r.mode_calls, vec![RadioMode::ActiveProbe]); + assert!(r.csi_enabled); + let h = r.get_health().unwrap(); + assert_eq!(h.current_channel, 6); + assert_eq!(h.current_bw_mhz, 20); + assert_eq!(h.current_profile, CaptureProfile::FastMotion as u8); + } + + #[test] + fn crc32_matches_firmware_vectors() { + // Same vectors as test_rv_feature_state.c + assert_eq!(crc32_ieee(b"123456789"), 0xCBF43926); + assert_eq!(crc32_ieee(&[]), 0x00000000); + assert_eq!(crc32_ieee(&[0u8]), 0xD202EF8D); + } + + #[test] + fn health_roundtrip() { + let st = NodeStatus { + node_id: [9, 0, 0, 0, 0, 0, 0, 0], + local_time_us: 42_000_000, + role: MeshRole::Observer, + current_channel: 11, + current_bw: 20, + noise_floor_dbm: -95, + pkt_yield: 20, + sync_error_us: 7, + health_flags: 0x0001, + }; + + let wire = encode_health(MeshRole::Observer, 5, &st); + assert_eq!(wire.len(), MESH_HEADER_SIZE + 28 + 4); + assert_eq!(wire.len(), 48); + + let (hdr, payload) = decode_mesh(&wire).expect("decode"); + assert_eq!(hdr.msg_type, MeshMsgType::Health); + assert_eq!(hdr.sender_role, MeshRole::Observer); + assert_eq!(hdr.epoch, 5); + assert_eq!(hdr.payload_len, 28); + + let back = decode_node_status(payload).expect("payload decode"); + assert_eq!(back, st); + } + + #[test] + fn decode_rejects_bad_crc() { + let st = NodeStatus { + node_id: [1, 0, 0, 0, 0, 0, 0, 0], + local_time_us: 0, + role: MeshRole::Observer, + current_channel: 1, + current_bw: 20, + noise_floor_dbm: -90, + pkt_yield: 0, + sync_error_us: 0, + health_flags: 0, + }; + let mut wire = encode_health(MeshRole::Observer, 0, &st); + let p0 = MESH_HEADER_SIZE; // first payload byte + wire[p0] ^= 0xFF; + let err = decode_mesh(&wire).unwrap_err(); + assert!(matches!(err, MeshError::CrcMismatch { .. })); + } + + #[test] + fn decode_rejects_bad_magic() { + let buf = [0u8; MESH_HEADER_SIZE + 4]; + let err = decode_mesh(&buf).unwrap_err(); + assert!(matches!(err, MeshError::BadMagic(_))); + } + + #[test] + fn decode_rejects_short() { + let buf = [0u8; 3]; + let err = decode_mesh(&buf).unwrap_err(); + assert!(matches!(err, MeshError::TooShort(_))); + } + + #[test] + fn profiles_are_bidirectional() { + for p in [ + CaptureProfile::PassiveLowRate, + CaptureProfile::ActiveProbe, + CaptureProfile::RespHighSens, + CaptureProfile::FastMotion, + CaptureProfile::Calibration, + ] { + let v = p as u8; + assert_eq!(CaptureProfile::try_from(v).unwrap(), p); + } + } + + #[test] + fn mesh_constants_match_firmware() { + // These must match rv_mesh.h byte-for-byte. + assert_eq!(MESH_MAGIC, 0xC511_8100); + assert_eq!(MESH_VERSION, 1); + assert_eq!(MESH_HEADER_SIZE, 16); + assert_eq!(MESH_MAX_PAYLOAD, 256); + } +}