mirror of https://github.com/ruvnet/RuView.git synced 2026-06-02 00:58:56 +02:00

Files

T

ruv 8504638187 feat(signal): ADR-135 — empty-room baseline calibration

Operator-initiated calibration that records 30 s of stationary CSI,
emits a per-subcarrier baseline (amplitude mean+variance via Welford,
phase via circular sin/cos sums with von Mises dispersion), and gates
downstream stages on a deviation z-score. Plugs into multistatic
coherence gating, motion/presence detection, and the new ADR-134 CIR
estimator as a reference-subtracted input.

API surface (under wifi_densepose_signal):
  CalibrationConfig::{ht20, ht40, he20, he40}
  CalibrationRecorder { record(), finalize(), frames_recorded() }
  BaselineCalibration {
    subcarriers: Vec<SubcarrierBaseline>,
    deviation(&CsiFrame), subtract_in_place(&mut CsiFrame),
    to_bytes(), from_bytes()
  }
  CalibrationDeviationScore { amplitude_z_median, amplitude_z_max,
                              phase_drift_median, motion_flagged }
  CalibrationError { SubcarrierMismatch, TierMismatch,
                     InsufficientFrames, VersionMismatch, TruncatedBuffer }

Binary baseline format: magic 0xCA1B_0001 + u8 version=1 + u8 tier +
captured_at_unix_s (i64) + frame_count (u64) + num_subcarriers (u32) +
[SubcarrierBaseline; N] as 16 bytes each (amp_mean, amp_variance,
phase_mean, phase_dispersion as f32 LE). Hand-written serialisation so
the format is stable across Rust toolchain versions without serde drift.

CLI: new `wifi-densepose calibrate` subcommand binds a UDP listener
(0xC511_0001 frames), streams them through CalibrationRecorder, prints
a real-time z-score banner per ADR-135 §risk 1 (operator-may-be-moving),
aborts on sustained high deviation, and writes the binary baseline to
disk. Local UDP packet parser duplicated from sensing-server (per ADR
discussion — avoids cross-crate API churn).

Witness: cross-platform-deterministic SHA-256 over the per-subcarrier
quantised baseline profile (u16 LE at 1e-2/1e-4/1e-3, no sort) using
the lesson learnt from the CIR PR #837 libm-jitter fix. Hash:
d6bce07ecb1648e6936561df44bf4a3bfc17bb0ba5f692646b2301d105b52f67

CI guard: new "ADR-135 calibration witness proof (determinism guard)"
step under the Rust Workspace Tests job, adjacent to the existing
ADR-134 CIR guard. Regressions are unambiguously attributable.

Hardware-in-loop validation: full 600-frame capture exercised via the
new scripts/synth-csi-udp.py emitter targeting 127.0.0.1:5005. The CLI
binary received 600 frames at 20 Hz, z_med stable at ~0.7, motion
correctly NOT flagged, finalised baseline written to baseline.bin (860
bytes) with correct magic + version + timestamp in the header. Live
ESP32 capture from COM9 is operator follow-up — requires provisioning
the firmware's UDP target IP to match the host running the CLI.

Test results (cargo test -p wifi-densepose-signal --no-default-features):
  lib:                    382 pass / 0 fail / 1 ignored
  calibration_synthetic:   17 pass / 0 fail
  calibration_drift:        5 pass / 0 fail
  calibration_roundtrip:   10 pass / 0 fail
  cir_*:                    9 pass + 6 documented P2 ignores
  doctest:                 10 pass

Bench: 20 Criterion combinations registered
(recorder_record / recorder_finalize / deviation / record_600 /
to_bytes across HT20/HT40/HE20/HE40 tiers).

Witness: bash scripts/verify-calibration-proof.sh → VERDICT: PASS

Co-Authored-By: claude-flow <ruv@ruv.net>

2026-05-28 18:57:08 -04:00

9.9 KiB

Raw Blame History

Architecture Decision Records

This folder contains 45 Architecture Decision Records (ADRs) that document every significant technical choice in the RuView / WiFi-DensePose project.

Why ADRs?

Building a system that turns WiFi signals into human pose estimation involves hundreds of non-obvious decisions: which signal processing algorithms to use, how to bridge ESP32 firmware to a Rust pipeline, whether to run inference on-device or on a server, how to handle multi-person separation with limited subcarriers.

ADRs capture the context, options considered, decision made, and consequences for each of these choices. They serve three purposes:

Institutional memory — Six months from now, anyone (human or AI) can read why we chose IIR bandpass filters over FIR for vital sign extraction, not just see the code.
AI-assisted development — When an AI agent works on this codebase, ADRs give it the constraints and rationale it needs to make changes that align with the existing architecture. Without them, AI-generated code tends to drift — reinventing patterns that already exist, contradicting earlier decisions, or optimizing for the wrong tradeoffs.
Review checkpoints — Each ADR is a reviewable artifact. When a proposed change touches the architecture, the ADR forces the author to articulate tradeoffs before writing code, not after.

ADRs and Domain-Driven Design

The project uses Domain-Driven Design (DDD) to organize code into bounded contexts — each with its own language, types, and responsibilities. ADRs and DDD work together:

ADRs define boundaries: ADR-029 (RuvSense) established multistatic sensing as a separate bounded context from single-node CSI. ADR-042 (CHCI) defined a new aggregate root for coherent channel imaging.
DDD models define the language: The RuvSense domain model defines terms like "coherence gate", "dwell time", and "TDM slot" that ADRs reference precisely.
Together they prevent drift: An AI agent reading ADR-039 knows that edge processing tiers are configured via NVS keys, not compile-time flags — because the ADR says so. The DDD model tells it which aggregate owns that configuration.

How ADRs are structured

Each ADR follows a consistent format:

Context — What problem or gap prompted this decision
Decision — What we chose to do and how
Consequences — What improved, what got harder, and what risks remain
References — Related ADRs, papers, and code paths

Statuses: Proposed (under discussion), Accepted (approved and/or implemented), Superseded (replaced by a later ADR).

ADR Index

Hardware and firmware

ADR	Title	Status
ADR-012	ESP32 CSI Sensor Mesh for Distributed Sensing	Accepted (partial)
ADR-018	ESP32 Development Implementation Path	Proposed
ADR-028	ESP32 Capability Audit and Witness Record	Accepted
ADR-029	RuvSense Multistatic Sensing Mode (TDM, channel hopping)	Proposed
ADR-032	Multistatic Mesh Security Hardening	Accepted
ADR-039	ESP32-S3 Edge Intelligence Pipeline (on-device vitals)	Accepted (hardware-validated)
ADR-040	WASM Programmable Sensing (Tier 3)	Accepted
ADR-041	WASM Module Collection (65 edge modules)	Accepted (hardware-validated)
ADR-044	Provisioning Tool Enhancements	Proposed
ADR-110	ESP32-C6 firmware extension — Wi-Fi 6 / 802.15.4 / TWT / LP-core	Accepted, P1-P10 complete, firmware-side substrate closed at v0.7.0-esp32. Companion docs: `WITNESS-LOG-110` (13 §A0.x entries · 99.56 % cross-board RX · 104.1 µs smoothed sync stdev · ≤100 µs target met), `ADR-110-REVIEW-GUIDE` (one-page reviewer tour), `ADR-110-BRANCH-STATE` (coordination map vs `feat/adr-115-ha-mqtt-matter`). Host decoders + tests: Python `SyncPacketParser` (10) + Rust `wifi_densepose_hardware::SyncPacket` (15), cross-language hex pin gates drift.

Signal processing and sensing

ADR	Title	Status
ADR-013	Feature-Level Sensing on Commodity Gear	Accepted
ADR-014	SOTA Signal Processing Algorithms	Accepted
ADR-021	Vital Sign Detection (breathing, heart rate)	Partial
ADR-030	Persistent Field Model and Drift Detection	Proposed
ADR-033	CRV Signal Line Sensing Integration	Proposed
ADR-037	Multi-Person Pose Detection from Single ESP32	Proposed
ADR-042	Coherent Human Channel Imaging (beyond CSI)	Proposed
ADR-134	First-Class Channel Impulse Response (CIR) Support	Proposed
ADR-135	Empty-Room Baseline Calibration (per-subcarrier Welford statistics)	Proposed

Machine learning and training

ADR	Title	Status
ADR-005	SONA Self-Learning for Pose Estimation	Partial
ADR-006	GNN-Enhanced CSI Pattern Recognition	Partial
ADR-015	Public Dataset Strategy (MM-Fi, Wi-Pose)	Accepted
ADR-016	RuVector Training Pipeline Integration	Accepted
ADR-017	RuVector Signal + MAT Integration	Proposed
ADR-020	Migrate AI Inference to Rust (ONNX Runtime)	Accepted
ADR-023	Trained DensePose Model with RuVector Pipeline	Proposed
ADR-024	Project AETHER: Contrastive CSI Embeddings	Required
ADR-027	Project MERIDIAN: Cross-Environment Generalization	Proposed

Platform and UI

ADR	Title	Status
ADR-019	Sensing-Only UI with Gaussian Splats	Accepted
ADR-022	Windows WiFi Enhanced Fidelity (multi-BSSID)	Partial
ADR-025	macOS CoreWLAN WiFi Sensing	Proposed
ADR-031	RuView Sensing-First RF Mode	Proposed
ADR-034	Expo React Native Mobile App	Accepted
ADR-035	Live Sensing UI Accuracy and Data Transparency	Accepted
ADR-036	Training Pipeline UI Integration	Proposed
ADR-043	Sensing Server UI API Completion (14 endpoints)	Accepted
ADR-115	Home Assistant integration via MQTT auto-discovery + Matter bridge (HA-DISCO + HA-FABRIC + HA-MIND)	Accepted (MQTT track) / Proposed (Matter SDK P8b)

Architecture and infrastructure

ADR	Title	Status
ADR-001	WiFi-Mat Disaster Detection Architecture	Accepted
ADR-002	RuVector RVF Integration Strategy	Superseded
ADR-003	RVF Cognitive Containers for CSI	Proposed
ADR-004	HNSW Vector Search for Fingerprinting	Partial
ADR-007	Post-Quantum Cryptography for Sensing	Proposed
ADR-008	Distributed Consensus for Multi-AP	Proposed
ADR-009	RVF WASM Runtime for Edge Deployment	Proposed
ADR-010	Witness Chains for Audit Trail Integrity	Proposed
ADR-011	Proof-of-Reality and Mock Elimination	Proposed
ADR-026	Survivor Track Lifecycle (MAT crate)	Accepted
ADR-038	Sublinear GOAP for Roadmap Optimization	Proposed
ADR-095	rvCSI — Edge RF Sensing Runtime Platform	Proposed
ADR-096	rvCSI — Crate Topology, the napi-c Shim, and the napi-rs Node Surface	Proposed
ADR-097	Adopt rvCSI as RuView's primary CSI runtime (phased adoption)	Proposed
ADR-098	Evaluate `ruvnet/midstream` for RuView's CSI / WebSocket / mesh pipeline	Rejected
ADR-099	Adopt midstream as RuView's real-time introspection + low-latency tap	Proposed

DDD Domain Models — Bounded context definitions, aggregate roots, and ubiquitous language
User Guide — Setup, API reference, and hardware instructions
Build Guide — Building from source

9.9 KiB Raw Blame History