Merge PR #85: v0.3.0 — RuvSense multistatic, CRV, QUIC, 15 crates published

feat: ADR-032/033 security hardening + CRV signal-line + QUIC transport (v0.3.0)
2026-03-02 08:46:29 -05:00
parent 0aab555821 381b51a382
commit 7c2e7e2b27
11 changed files with 155 additions and 53 deletions
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -10,6 +10,7 @@ WiFi DensePose turns commodity WiFi signals into real-time human pose estimation
 2. [Installation](#installation)
   - [Docker (Recommended)](#docker-recommended)
   - [From Source (Rust)](#from-source-rust)
+   - [From crates.io](#from-cratesio-individual-crates)
   - [From Source (Python)](#from-source-python)
   - [Guided Installer](#guided-installer)
 3. [Quick Start](#quick-start)
@@ -19,12 +20,14 @@ WiFi DensePose turns commodity WiFi signals into real-time human pose estimation
   - [Simulated Mode (No Hardware)](#simulated-mode-no-hardware)
   - [Windows WiFi (RSSI Only)](#windows-wifi-rssi-only)
   - [ESP32-S3 (Full CSI)](#esp32-s3-full-csi)
+   - [ESP32 Multistatic Mesh (Advanced)](#esp32-multistatic-mesh-advanced)
 5. [REST API Reference](#rest-api-reference)
 6. [WebSocket Streaming](#websocket-streaming)
 7. [Web UI](#web-ui)
 8. [Vital Sign Detection](#vital-sign-detection)
 9. [CLI Reference](#cli-reference)
 10. [Training a Model](#training-a-model)
+    - [CRV Signal-Line Protocol](#crv-signal-line-protocol)
 11. [RVF Model Containers](#rvf-model-containers)
 12. [Hardware Setup](#hardware-setup)
    - [ESP32-S3 Mesh](#esp32-s3-mesh)
@@ -79,12 +82,41 @@ cd wifi-densepose/rust-port/wifi-densepose-rs
 # Build
 cargo build --release

-# Verify (runs 700+ tests)
+# Verify (runs 1,100+ tests)
 cargo test --workspace
 ```

 The compiled binary is at `target/release/sensing-server`.

+### From crates.io (Individual Crates)
+
+All 15 crates are published to crates.io at v0.3.0. Add individual crates to your own Rust project:
+
+```bash
+# Core types and traits
+cargo add wifi-densepose-core
+
+# Signal processing (includes RuvSense multistatic sensing)
+cargo add wifi-densepose-signal
+
+# Neural network inference
+cargo add wifi-densepose-nn
+
+# Mass Casualty Assessment Tool
+cargo add wifi-densepose-mat
+
+# ESP32 hardware + TDM protocol + QUIC transport
+cargo add wifi-densepose-hardware
+
+# RuVector integration (add --features crv for CRV signal-line protocol)
+cargo add wifi-densepose-ruvector --features crv
+
+# WebAssembly bindings
+cargo add wifi-densepose-wasm
+```
+
+See the full crate list and dependency order in [CLAUDE.md](../CLAUDE.md#crate-publishing-order).
+
 ### From Source (Python)

 ```bash
@@ -231,6 +263,27 @@ docker run -p 3000:3000 -p 3001:3001 -p 5005:5005/udp ruvnet/wifi-densepose:late

 The ESP32 nodes stream binary CSI frames over UDP to port 5005. See [Hardware Setup](#esp32-s3-mesh) for flashing instructions.

+### ESP32 Multistatic Mesh (Advanced)
+
+For higher accuracy with through-wall tracking, deploy 3-6 ESP32-S3 nodes in a **multistatic mesh** configuration. Each node acts as both transmitter and receiver, creating multiple sensing paths through the environment.
+
+```bash
+# Start the aggregator with multistatic mode
+./target/release/sensing-server --source esp32 --udp-port 5005 --http-port 3000 --ws-port 3001
+```
+
+The mesh uses a **Time-Division Multiplexing (TDM)** protocol so nodes take turns transmitting, avoiding self-interference. Key features:
+
+| Feature | Description |
+|---------|-------------|
+| TDM coordination | Nodes cycle through TX/RX slots (configurable guard intervals) |
+| Channel hopping | Automatic 2.4/5 GHz band cycling for multiband fusion |
+| QUIC transport | TLS 1.3-encrypted streams on aggregator nodes (ADR-032a) |
+| Manual crypto fallback | HMAC-SHA256 beacon auth on constrained ESP32-S3 nodes |
+| Attention-weighted fusion | Cross-viewpoint attention with geometric diversity bias |
+
+See [ADR-029](adr/ADR-029-ruvsense-multistatic-sensing-mode.md) and [ADR-032](adr/ADR-032-multistatic-mesh-security-hardening.md) for the full design.
+
 ---

 ## REST API Reference
@@ -369,7 +422,7 @@ The system extracts breathing rate and heart rate from CSI signal fluctuations u

 **Requirements:**
 - CSI-capable hardware (ESP32-S3 or research NIC) for accurate readings
- Subject within ~3-5 meters of an access point
+- Subject within ~3-5 meters of an access point (up to ~8 m with multistatic mesh)
 - Relatively stationary subject (large movements mask vital sign oscillations)

 **Simulated mode** produces synthetic vital sign data for testing.
@@ -493,6 +546,26 @@ MERIDIAN components (all pure Rust, +12K parameters):

 See [ADR-027](adr/ADR-027-cross-environment-domain-generalization.md) for the full design.

+### CRV Signal-Line Protocol
+
+The CRV (Coordinate Remote Viewing) signal-line protocol (ADR-033) maps a 6-stage cognitive sensing methodology onto WiFi CSI processing. This enables structured anomaly classification and multi-person disambiguation.
+
+| Stage | CRV Term | WiFi Mapping |
+|-------|----------|-------------|
+| I | Gestalt | Detrended autocorrelation → periodicity / chaos / transient classification |
+| II | Sensory | 6-modality CSI feature encoding (texture, temperature, luminosity, etc.) |
+| III | Topology | AP mesh topology graph with link quality weights |
+| IV | Coherence | Phase phasor coherence gate (Accept/PredictOnly/Reject/Recalibrate) |
+| V | Interrogation | Person-specific signal extraction with targeted subcarrier selection |
+| VI | Partition | Multi-person partition with cross-room convergence scoring |
+
+```bash
+# Enable CRV in your Cargo.toml
+cargo add wifi-densepose-ruvector --features crv
+```
+
+See [ADR-033](adr/ADR-033-crv-signal-line-sensing-integration.md) for the full design.
+
 ---

 ## RVF Model Containers
@@ -535,7 +608,7 @@ A 3-6 node ESP32-S3 mesh provides full CSI at 20 Hz. Total cost: ~$54 for a 3-no
 **What you need:**
 - 3-6x ESP32-S3 development boards (~$8 each)
 - A WiFi router (the CSI source)
- A computer running the sensing server
+- A computer running the sensing server (aggregator)

 **Flashing firmware:**

@@ -557,6 +630,33 @@ python scripts/provision.py --port COM7 \

 Replace `192.168.1.20` with the IP of the machine running the sensing server.

+**Mesh key provisioning (secure mode):**
+
+For multistatic mesh deployments with authenticated beacons (ADR-032), provision a shared mesh key:
+
+```bash
+python scripts/provision.py --port COM7 \
+  --ssid "YourWiFi" --password "YourPassword" --target-ip 192.168.1.20 \
+  --mesh-key "$(openssl rand -hex 32)"
+```
+
+All nodes in a mesh must share the same 256-bit mesh key for HMAC-SHA256 beacon authentication. The key is stored in ESP32 NVS flash and zeroed on firmware erase.
+
+**TDM slot assignment:**
+
+Each node in a multistatic mesh needs a unique TDM slot ID (0-based):
+
+```bash
+# Node 0 (slot 0) — first transmitter
+python scripts/provision.py --port COM7 --tdm-slot 0 --tdm-total 3
+
+# Node 1 (slot 1)
+python scripts/provision.py --port COM8 --tdm-slot 1 --tdm-total 3
+
+# Node 2 (slot 2)
+python scripts/provision.py --port COM9 --tdm-slot 2 --tdm-total 3
+```
+
 **Start the aggregator:**

 ```bash
@@ -567,7 +667,7 @@ Replace `192.168.1.20` with the IP of the machine running the sensing server.
 docker run -p 3000:3000 -p 3001:3001 -p 5005:5005/udp ruvnet/wifi-densepose:latest --source esp32
 ```

-See [ADR-018](../docs/adr/ADR-018-esp32-dev-implementation.md) and [Tutorial #34](https://github.com/ruvnet/wifi-densepose/issues/34).
+See [ADR-018](../docs/adr/ADR-018-esp32-dev-implementation.md), [ADR-029](../docs/adr/ADR-029-ruvsense-multistatic-sensing-mode.md), and [Tutorial #34](https://github.com/ruvnet/wifi-densepose/issues/34).

 ### Intel 5300 / Atheros NIC

@@ -626,7 +726,7 @@ docker run -p 3000:3000 -p 3001:3001 ruvnet/wifi-densepose:latest

 ### Build: Rust compilation errors

-Ensure Rust 1.70+ is installed:
+Ensure Rust 1.75+ is installed (1.85+ recommended):
 ```bash
 rustup update stable
 rustc --version
@@ -656,7 +756,7 @@ No. Consumer WiFi exposes only RSSI (one number per access point), not CSI (56+
 Accuracy depends on hardware and environment. With a 3-node ESP32 mesh in a single room, the system tracks 17 COCO keypoints. The core algorithm follows the CMU "DensePose From WiFi" paper ([arXiv:2301.00250](https://arxiv.org/abs/2301.00250)). The MERIDIAN domain generalization system (ADR-027) reduces cross-environment accuracy loss from 40-70% to under 15% via 10-second automatic calibration.

 **Q: Does it work through walls?**
-Yes. WiFi signals penetrate non-metallic materials (drywall, wood, concrete up to ~30cm). Metal walls/doors significantly attenuate the signal. The effective through-wall range is approximately 5 meters.
+Yes. WiFi signals penetrate non-metallic materials (drywall, wood, concrete up to ~30cm). Metal walls/doors significantly attenuate the signal. With a single AP the effective through-wall range is approximately 5 meters. With a 3-6 node multistatic mesh (ADR-029), attention-weighted cross-viewpoint fusion extends the effective range to ~8 meters through standard residential walls.

 **Q: How many people can it track?**
 Each access point can distinguish ~3-5 people with 56 subcarriers. Multi-AP deployments multiply linearly (e.g., 4 APs cover ~15-20 people). There is no hard software limit; the practical ceiling is signal physics.
@@ -671,7 +771,7 @@ The Rust implementation (v2) is 810x faster than Python (v1) for the full CSI pi

 ## Further Reading

- [Architecture Decision Records](../docs/adr/) - 27 ADRs covering all design decisions
+- [Architecture Decision Records](../docs/adr/) - 33 ADRs covering all design decisions
 - [WiFi-Mat Disaster Response Guide](wifi-mat-user-guide.md) - Search & rescue module
 - [Build Guide](build-guide.md) - Detailed build instructions
 - [RuVector](https://github.com/ruvnet/ruvector) - Signal intelligence crate ecosystem
--- a/rust-port/wifi-densepose-rs/Cargo.lock
+++ b/rust-port/wifi-densepose-rs/Cargo.lock
@@ -3231,6 +3231,8 @@ dependencies = [
 [[package]]
 name = "ruvector-crv"
 version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eda8d6533ed1337e75f0bcc9e6e31cff44cc32aa24f9673492b2fad3af09a120"
 dependencies = [
 "ruvector-attention 0.1.32",
 "ruvector-gnn",
@@ -4517,11 +4519,11 @@ dependencies = [

 [[package]]
 name = "wifi-densepose-api"
-version = "0.2.0"
+version = "0.3.0"

 [[package]]
 name = "wifi-densepose-cli"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
 "anyhow",
 "assert_cmd",
@@ -4546,11 +4548,11 @@ dependencies = [

 [[package]]
 name = "wifi-densepose-config"
-version = "0.2.0"
+version = "0.3.0"

 [[package]]
 name = "wifi-densepose-core"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
 "async-trait",
 "chrono",
@@ -4566,11 +4568,11 @@ dependencies = [

 [[package]]
 name = "wifi-densepose-db"
-version = "0.2.0"
+version = "0.3.0"

 [[package]]
 name = "wifi-densepose-hardware"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
 "approx",
 "byteorder",
@@ -4588,7 +4590,7 @@ dependencies = [

 [[package]]
 name = "wifi-densepose-mat"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
 "anyhow",
 "approx",
@@ -4619,7 +4621,7 @@ dependencies = [

 [[package]]
 name = "wifi-densepose-nn"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
 "anyhow",
 "candle-core",
@@ -4642,7 +4644,7 @@ dependencies = [

 [[package]]
 name = "wifi-densepose-ruvector"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
 "approx",
 "criterion",
@@ -4660,7 +4662,7 @@ dependencies = [

 [[package]]
 name = "wifi-densepose-sensing-server"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
 "axum",
 "chrono",
@@ -4678,7 +4680,7 @@ dependencies = [

 [[package]]
 name = "wifi-densepose-signal"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
 "chrono",
 "criterion",
@@ -4701,7 +4703,7 @@ dependencies = [

 [[package]]
 name = "wifi-densepose-train"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
 "anyhow",
 "approx",
@@ -4739,7 +4741,7 @@ dependencies = [

 [[package]]
 name = "wifi-densepose-vitals"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
 "serde",
 "serde_json",
@@ -4748,7 +4750,7 @@ dependencies = [

 [[package]]
 name = "wifi-densepose-wasm"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
 "chrono",
 "console_error_panic_hook",
@@ -4770,7 +4772,7 @@ dependencies = [

 [[package]]
 name = "wifi-densepose-wifiscan"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
 "serde",
 "tokio",
--- a/rust-port/wifi-densepose-rs/Cargo.toml
+++ b/rust-port/wifi-densepose-rs/Cargo.toml
@@ -19,7 +19,7 @@ members = [
 ]

 [workspace.package]
-version = "0.2.0"
+version = "0.3.0"
 edition = "2021"
 authors = ["rUv <ruv@ruv.net>", "WiFi-DensePose Contributors"]
 license = "MIT OR Apache-2.0"
@@ -120,21 +120,16 @@ ruvector-gnn = { version = "2.0.5", default-features = false }


 # Internal crates
-wifi-densepose-core = { version = "0.2.0", path = "crates/wifi-densepose-core" }
-wifi-densepose-signal = { version = "0.2.0", path = "crates/wifi-densepose-signal" }
-wifi-densepose-nn = { version = "0.2.0", path = "crates/wifi-densepose-nn" }
-wifi-densepose-api = { version = "0.2.0", path = "crates/wifi-densepose-api" }
-wifi-densepose-db = { version = "0.2.0", path = "crates/wifi-densepose-db" }
-wifi-densepose-config = { version = "0.2.0", path = "crates/wifi-densepose-config" }
-wifi-densepose-hardware = { version = "0.2.0", path = "crates/wifi-densepose-hardware" }
-wifi-densepose-wasm = { version = "0.2.0", path = "crates/wifi-densepose-wasm" }
-wifi-densepose-mat = { version = "0.2.0", path = "crates/wifi-densepose-mat" }
-wifi-densepose-ruvector = { version = "0.2.0", path = "crates/wifi-densepose-ruvector" }
-
-# Patch ruvector-crv to fix RuvectorLayer::new() Result API mismatch
-# with ruvector-gnn 2.0.5 (upstream ruvector-crv 0.1.1 was built against 2.0.1).
-[patch.crates-io]
-ruvector-crv = { path = "patches/ruvector-crv" }
+wifi-densepose-core = { version = "0.3.0", path = "crates/wifi-densepose-core" }
+wifi-densepose-signal = { version = "0.3.0", path = "crates/wifi-densepose-signal" }
+wifi-densepose-nn = { version = "0.3.0", path = "crates/wifi-densepose-nn" }
+wifi-densepose-api = { version = "0.3.0", path = "crates/wifi-densepose-api" }
+wifi-densepose-db = { version = "0.3.0", path = "crates/wifi-densepose-db" }
+wifi-densepose-config = { version = "0.3.0", path = "crates/wifi-densepose-config" }
+wifi-densepose-hardware = { version = "0.3.0", path = "crates/wifi-densepose-hardware" }
+wifi-densepose-wasm = { version = "0.3.0", path = "crates/wifi-densepose-wasm" }
+wifi-densepose-mat = { version = "0.3.0", path = "crates/wifi-densepose-mat" }
+wifi-densepose-ruvector = { version = "0.3.0", path = "crates/wifi-densepose-ruvector" }

 [profile.release]
 lto = true
--- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-cli/Cargo.toml
+++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-cli/Cargo.toml
@@ -21,7 +21,7 @@ mat = []

 [dependencies]
 # Internal crates
-wifi-densepose-mat = { version = "0.2.0", path = "../wifi-densepose-mat" }
+wifi-densepose-mat = { version = "0.3.0", path = "../wifi-densepose-mat" }

 # CLI framework
 clap = { version = "4.4", features = ["derive", "env", "cargo"] }
--- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-mat/Cargo.toml
+++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-mat/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "wifi-densepose-mat"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2021"
 authors = ["rUv <ruv@ruv.net>", "WiFi-DensePose Contributors"]
 description = "Mass Casualty Assessment Tool - WiFi-based disaster survivor detection"
@@ -24,9 +24,9 @@ serde = ["dep:serde", "chrono/serde", "geo/use-serde"]

 [dependencies]
 # Workspace dependencies
-wifi-densepose-core = { version = "0.2.0", path = "../wifi-densepose-core" }
-wifi-densepose-signal = { version = "0.2.0", path = "../wifi-densepose-signal" }
-wifi-densepose-nn = { version = "0.2.0", path = "../wifi-densepose-nn" }
+wifi-densepose-core = { version = "0.3.0", path = "../wifi-densepose-core" }
+wifi-densepose-signal = { version = "0.3.0", path = "../wifi-densepose-signal" }
+wifi-densepose-nn = { version = "0.3.0", path = "../wifi-densepose-nn" }
 ruvector-solver = { workspace = true, optional = true }
 ruvector-temporal-tensor = { workspace = true, optional = true }

--- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-ruvector/Cargo.toml
+++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-ruvector/Cargo.toml
@@ -10,17 +10,21 @@ keywords = ["wifi", "csi", "ruvector", "signal-processing", "disaster-detection"
 categories = ["science", "computer-vision"]
 readme = "README.md"

+[features]
+default = []
+crv = ["dep:ruvector-crv", "dep:ruvector-gnn", "dep:serde", "dep:serde_json"]
+
 [dependencies]
 ruvector-mincut = { workspace = true }
 ruvector-attn-mincut = { workspace = true }
 ruvector-temporal-tensor = { workspace = true }
 ruvector-solver = { workspace = true }
 ruvector-attention = { workspace = true }
-ruvector-crv = { workspace = true }
-ruvector-gnn = { workspace = true }
+ruvector-crv = { workspace = true, optional = true }
+ruvector-gnn = { workspace = true, optional = true }
 thiserror = { workspace = true }
-serde = { workspace = true }
-serde_json = { workspace = true }
+serde = { workspace = true, optional = true }
+serde_json = { workspace = true, optional = true }

 [dev-dependencies]
 approx = "0.5"
--- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-ruvector/src/lib.rs
+++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-ruvector/src/lib.rs
@@ -26,6 +26,7 @@

 #![warn(missing_docs)]

+#[cfg(feature = "crv")]
 pub mod crv;
 pub mod mat;
 pub mod signal;
--- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-sensing-server/Cargo.toml
+++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-sensing-server/Cargo.toml
@@ -41,7 +41,7 @@ chrono = { version = "0.4", features = ["serde"] }
 clap = { workspace = true }

 # Multi-BSSID WiFi scanning pipeline (ADR-022 Phase 3)
-wifi-densepose-wifiscan = { version = "0.2.0", path = "../wifi-densepose-wifiscan" }
+wifi-densepose-wifiscan = { version = "0.3.0", path = "../wifi-densepose-wifiscan" }

 [dev-dependencies]
 tempfile = "3.10"
--- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-signal/Cargo.toml
+++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-signal/Cargo.toml
@@ -37,7 +37,7 @@ midstreamer-temporal-compare = { workspace = true }
 midstreamer-attractor = { workspace = true }

 # Internal
-wifi-densepose-core = { version = "0.2.0", path = "../wifi-densepose-core" }
+wifi-densepose-core = { version = "0.3.0", path = "../wifi-densepose-core" }

 [dev-dependencies]
 criterion = { version = "0.5", features = ["html_reports"] }
--- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-train/Cargo.toml
+++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-train/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "wifi-densepose-train"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2021"
 authors = ["rUv <ruv@ruv.net>", "WiFi-DensePose Contributors"]
 license = "MIT OR Apache-2.0"
@@ -27,8 +27,8 @@ cuda = ["tch-backend"]

 [dependencies]
 # Internal crates
-wifi-densepose-signal = { version = "0.2.0", path = "../wifi-densepose-signal" }
-wifi-densepose-nn = { version = "0.2.0", path = "../wifi-densepose-nn" }
+wifi-densepose-signal = { version = "0.3.0", path = "../wifi-densepose-signal" }
+wifi-densepose-nn = { version = "0.3.0", path = "../wifi-densepose-nn" }

 # Core
 thiserror.workspace = true
--- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-wasm/Cargo.toml
+++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-wasm/Cargo.toml
@@ -59,7 +59,7 @@ uuid = { version = "1.6", features = ["v4", "serde", "js"] }
 getrandom = { version = "0.2", features = ["js"] }

 # Optional: wifi-densepose-mat integration
-wifi-densepose-mat = { version = "0.2.0", path = "../wifi-densepose-mat", optional = true, features = ["serde"] }
+wifi-densepose-mat = { version = "0.3.0", path = "../wifi-densepose-mat", optional = true, features = ["serde"] }

 [dev-dependencies]
 wasm-bindgen-test = "0.3"