mirror of
https://github.com/ruvnet/RuView
synced 2026-07-21 17:13:19 +00:00
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
This commit is contained in:
Claude
Generated
+172
-10
@@ -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"
|
||||
|
||||
@@ -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,
|
||||
};
|
||||
|
||||
@@ -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<u8> for CaptureProfile {
|
||||
type Error = RadioError;
|
||||
fn try_from(v: u8) -> Result<Self, Self::Error> {
|
||||
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<RadioHealth, RadioError>;
|
||||
}
|
||||
|
||||
/// 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<CaptureProfile>,
|
||||
pub mode_calls: Vec<RadioMode>,
|
||||
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<RadioHealth, RadioError> {
|
||||
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<u8> for MeshRole {
|
||||
type Error = MeshError;
|
||||
fn try_from(v: u8) -> Result<Self, Self::Error> {
|
||||
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<u8> for MeshMsgType {
|
||||
type Error = MeshError;
|
||||
fn try_from(v: u8) -> Result<Self, Self::Error> {
|
||||
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<NodeStatus, MeshError> {
|
||||
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<AnomalyAlert, MeshError> {
|
||||
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<u8> {
|
||||
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);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user