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>
This commit is contained in:
ruv
parent
9e7fa83210
commit
8504638187
|
|
@ -142,6 +142,9 @@ jobs:
|
|||
- name: ADR-134 CIR witness proof (determinism guard)
|
||||
run: bash scripts/verify-cir-proof.sh
|
||||
|
||||
- name: ADR-135 calibration witness proof (determinism guard)
|
||||
run: bash scripts/verify-calibration-proof.sh
|
||||
|
||||
# Unit and Integration Tests
|
||||
# Python pytest matrix — runs against the archived v1 Python tree.
|
||||
# `continue-on-error: true` for the same reason as code-quality above:
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ Dual codebase: Python v1 (`v1/`) and Rust port (`v2/`).
|
|||
| Crate | Description |
|
||||
|-------|-------------|
|
||||
| `wifi-densepose-core` | Core types, traits, error types, CSI frame primitives |
|
||||
| `wifi-densepose-signal` | SOTA signal processing + RuvSense multistatic sensing (15 modules) |
|
||||
| `wifi-densepose-signal` | SOTA signal processing + RuvSense multistatic sensing (16 modules) |
|
||||
| `wifi-densepose-nn` | Neural network inference (ONNX, PyTorch, Candle backends) |
|
||||
| `wifi-densepose-train` | Training pipeline with ruvector integration + ruview_metrics |
|
||||
| `wifi-densepose-mat` | Mass Casualty Assessment Tool — disaster survivor detection |
|
||||
|
|
@ -39,6 +39,7 @@ Dual codebase: Python v1 (`v1/`) and Rust port (`v2/`).
|
|||
| `gesture.rs` | DTW template matching gesture classifier |
|
||||
| `adversarial.rs` | Physically impossible signal detection, multi-link consistency |
|
||||
| `cir.rs` | ADR-134 CSI→CIR via ISTA L1 sparse recovery (NeumannSolver warm-start) |
|
||||
| `calibration.rs` | ADR-135 empty-room baseline (Welford amplitude + von Mises phase, drift trigger) |
|
||||
|
||||
### Cross-Viewpoint Fusion (`ruvector/src/viewpoint/`)
|
||||
| Module | Purpose |
|
||||
|
|
|
|||
|
|
@ -0,0 +1 @@
|
|||
d6bce07ecb1648e6936561df44bf4a3bfc17bb0ba5f692646b2301d105b52f67
|
||||
|
|
@ -231,7 +231,8 @@ Each row is independently verifiable. Status reflects audit-time findings.
|
|||
| 31 | On-device ESP32 ML inference | No | **NO** | Firmware streams raw I/Q; inference runs on aggregator |
|
||||
| 32 | Real-world CSI dataset bundled | No | **NO** | Only synthetic reference signal (seed=42) |
|
||||
| 33 | 54,000 fps measured throughput | Claimed | **NOT MEASURED** | Criterion benchmarks exist but not run at audit time |
|
||||
| 34 | CIR estimation (ADR-134, ISTA via NeumannSolver) | Yes | **PENDING** | `archive/v1/data/proof/expected_cir_features.sha256`, `scripts/verify-cir-proof.sh`; regenerate hash after cir module impl lands: `cd v2 && cargo run -p wifi-densepose-signal --bin cir_proof_runner --release --no-default-features -- --generate-hash > ../archive/v1/data/proof/expected_cir_features.sha256` |
|
||||
| 34 | CIR estimation (ADR-134, ISTA via NeumannSolver) | Yes | **PASS** | `archive/v1/data/proof/expected_cir_features.sha256`, `scripts/verify-cir-proof.sh`; regenerate after intentional changes: `cd v2 && cargo run -p wifi-densepose-signal --bin cir_proof_runner --release --no-default-features -- --generate-hash > ../archive/v1/data/proof/expected_cir_features.sha256` |
|
||||
| 35 | Empty-room baseline calibration (ADR-135, Welford + von Mises) | Yes | **PASS** | `archive/v1/data/proof/expected_calibration_features.sha256`, `scripts/verify-calibration-proof.sh`; regenerate after intentional changes: `cd v2 && cargo run -p wifi-densepose-signal --bin calibration_proof_runner --release --no-default-features -- --generate-hash > ../archive/v1/data/proof/expected_calibration_features.sha256` |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -241,7 +242,8 @@ Each row is independently verifiable. Status reflects audit-time findings.
|
|||
|--------|-------|
|
||||
| Witness commit SHA | `96b01008f71f4cbe2c138d63acb0e9bc6825286e` |
|
||||
| Python proof hash (numpy 2.4.2, scipy 1.17.1) | `8c0680d7d285739ea9597715e84959d9c356c87ee3ad35b5f1e69a4ca41151c6` |
|
||||
| CIR proof hash (ADR-134) | `PLACEHOLDER — regenerate after cir module implementation lands` |
|
||||
| CIR proof hash (ADR-134) | `120bd7b1f549f57f3773971a389c48c2bdd99b4ab1f205935867a16e95583995` |
|
||||
| Calibration proof hash (ADR-135) | `d6bce07ecb1648e6936561df44bf4a3bfc17bb0ba5f692646b2301d105b52f67` |
|
||||
| ESP32 frame magic | `0xC5110001` |
|
||||
| Workspace crate version | `0.2.0` |
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,664 @@
|
|||
# ADR-135: Empty-Room Baseline Calibration
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-28 |
|
||||
| **Deciders** | ruv |
|
||||
| **Codebase target** | `wifi-densepose-signal` (new module `ruvsense/calibration.rs`); `wifi-densepose-cli` (new `calibrate` subcommand) |
|
||||
| **Relates to** | ADR-014 (SOTA Signal Processing), ADR-028 (ESP32 Capability Audit), ADR-029 (RuvSense Multistatic), ADR-030 (Persistent Field Model), ADR-110 (ESP32-C6 Firmware Extension), ADR-134 (First-Class CIR Support) |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
### 1.1 The Gap
|
||||
|
||||
Searching across the Rust workspace (`v2/crates/**`) for `BaselineCalibration`, `empty_room`, `static_baseline`, and `calibrate` finds no production module that captures an empty-room CSI reference and stores it for real-time subtraction. The closest existing code is `ruvsense/field_model.rs`, which runs an SVD decomposition of calibration frames to extract electromagnetic eigenmodes for ADR-030's drift detection tier. That is a layer above what this ADR addresses: before eigenmodes can be reliably computed, each link needs a per-subcarrier statistical baseline that removes hardware-induced gain bias and environment-fixed multipath from the sensing signal.
|
||||
|
||||
The absence is consequential. Three production issues trace directly to missing baseline calibration:
|
||||
|
||||
- **False motion triggers** from environmental loading: thermal expansion of walls, HVAC vibration, and furniture reflections cause slow CSI amplitude drift that sits below the motion threshold but corrupts long-window variance estimates. The `ruvsense/coherence_gate.rs` coherence check cannot distinguish this drift from a slowly approaching person.
|
||||
- **Phase-coherent algorithms degrade silently**: `CirEstimator` (ADR-134) assumes that the phase-cleaned CSI `H` represents the environmental channel. Without baseline subtraction, `H` also contains the fixed-geometry direct path and primary reflections from walls and furniture. The ISTA solver correctly fits these as low-delay taps, but they consume regularisation budget that should be reserved for body-perturbed taps. `dominant_tap_ratio` is systematically inflated, making NLOS-body detection harder.
|
||||
- **Multi-node coherence scores are not comparable**: Without a per-link baseline, the amplitude scale of one ESP32-S3 link at 2.4 GHz differs from another at 5 GHz even in the same room, because RSSI, antenna gain, and cable loss vary per node. Multistatic fusion in `ruvsense/multistatic.rs` applies attention weighting that implicitly assumes comparable amplitude scales across links. Hardware normalization (`hardware_norm.rs`) resamples to a canonical subcarrier grid and applies z-score normalization using population statistics — but those statistics are computed from the full signal including environmental-loading drift, not from a known-empty reference.
|
||||
|
||||
ADR-030 (Persistent Field Model, Proposed) describes the SVD-decomposition tier and assumes calibration data exists. ADR-134 (CIR, Proposed) documents at §2.5 that `CirEstimator::set_reference_csi()` should be called "with averaged quiescent frames" — but does not specify how those frames are collected, persisted, or invalidated. This ADR closes that gap.
|
||||
|
||||
### 1.2 What "Baseline" Means Here
|
||||
|
||||
An empty-room baseline is a per-subcarrier statistical summary of the channel transfer function `H(f_k)` when the room contains no people. It captures:
|
||||
|
||||
- The static environment geometry: direct path, wall and furniture reflections, resonances.
|
||||
- Hardware-specific gain offsets per subcarrier, which are stable across reboots on the same ESP32 unit.
|
||||
- Long-term ambient drift not corrected by `phase_sanitizer.rs` (which operates per-frame, not across frames).
|
||||
|
||||
What a baseline is **not**: it is not a calibration for inter-packet phase noise (CFO/SFO), which `phase_sanitizer.rs` and `phase_align.rs` already handle. Those two stages must run before baseline comparison.
|
||||
|
||||
### 1.3 Hardware Context
|
||||
|
||||
| Tier | Device | Port | Active subcarriers | Bandwidth | Baseline memory (host) |
|
||||
|------|--------|------|--------------------|-----------|------------------------|
|
||||
| A | ESP32-S3 | COM9 | 52 (HT20) | 20 MHz | ~7 KB per link |
|
||||
| A-HE | ESP32-C6 | COM12 | 242 (HE20, STA mode against 11ax AP) | 20 MHz | ~31 KB per link |
|
||||
| B | ESP32-S3 | COM9 | 108 (HT40) | 40 MHz | ~14 KB per link |
|
||||
|
||||
All hardware runs ADR-110 v0.7.0-esp32 firmware. ESP32-C6 on COM12 provides `c6_timesync_get_epoch_us()` (±100 µs 802.15.4 epoch) for multi-node capture synchronization. The C6 falls back to HT20 when no 802.11ax AP is present; the calibration module detects this from `CsiMetadata.bandwidth_mhz` and selects the appropriate subcarrier mask.
|
||||
|
||||
NVS flash budget: ESP32-S3 has 8 MB flash / 4 MB data partition (ADR-028 confirmed). A full Tier A-HE HE20 baseline (242 subcarriers × 4 stats × f32 = ~3.9 KB) fits comfortably in NVS. The NVS key namespace is `ruvcal` with key `b_<link_id>`. Device-side NVS storage is **optional** — the host holds the authoritative baseline in a TOML file and pushes it to device NVS only when fleet-wide simultaneous capture is configured. See Section 2.4.
|
||||
|
||||
### 1.4 Pipeline Position
|
||||
|
||||
```
|
||||
Raw CSI frame
|
||||
→ phase_sanitizer.rs (SFO/CFO removal, per-frame)
|
||||
→ phase_align.rs (LO phase offset, multi-antenna)
|
||||
→ CalibrationRecorder::record() ← NEW (calibration mode only)
|
||||
→ BaselineCalibration::subtract() ← NEW (runtime mode)
|
||||
→ CirEstimator::estimate() (ADR-134)
|
||||
→ multistatic.rs / motion.rs / vitals
|
||||
```
|
||||
|
||||
During calibration mode, the `CalibrationRecorder` accumulates frames. At runtime, `BaselineCalibration::subtract()` removes the static environment before the signal enters any downstream consumer. CIR estimation and coherence gating both receive baseline-subtracted CSI.
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
### 2.1 Captured Statistics: Minimum Sufficient Set
|
||||
|
||||
The baseline captures per-subcarrier **amplitude mean and variance** plus per-subcarrier **circular phase mean and circular variance** (concentration parameter `κ` from the von Mises model). No per-link spatial covariance matrix is captured.
|
||||
|
||||
**Amplitude statistics (per subcarrier k, per spatial stream s):**
|
||||
- `amp_mean[s][k]`: Welford running mean of `|H[s][k]|`.
|
||||
- `amp_m2[s][k]`: Welford M2 accumulator for variance. Variance is `m2 / (n - 1)`.
|
||||
|
||||
**Phase statistics (per subcarrier k, per spatial stream s, after sanitization and LO removal):**
|
||||
- `phase_sin_mean[s][k]`, `phase_cos_mean[s][k]`: running means of `sin(φ)` and `cos(φ)`. The circular mean is `atan2(phase_sin_mean, phase_cos_mean)`.
|
||||
- `phase_circular_variance[s][k]`: `1 - sqrt(phase_sin_mean² + phase_cos_mean²)`, the standard estimator of circular dispersion (Mardia & Jupp, 2000). Range is [0, 1]; 0 = perfectly concentrated, 1 = maximally dispersed.
|
||||
|
||||
**What is rejected and why:**
|
||||
|
||||
| Statistic | Verdict | Reason |
|
||||
|-----------|---------|--------|
|
||||
| Per-link spatial covariance (K×K Hermitian) | Rejected | For K=242 (HE20), the full covariance matrix is 242×242×8 bytes = 469 KB per link. Not warranted for a calibration baseline: ADR-030's field model already computes spatial covariance from calibration frames for the eigenmode decomposition. This ADR's baseline is the input to ADR-030, not a substitute for it. |
|
||||
| Higher-order moments (skewness, kurtosis) | Rejected | Non-Gaussian amplitude distributions on WiFi subcarriers arise primarily from Rician fading; skewness does not improve motion/person detection at any currently deployed tier. |
|
||||
| Cross-subcarrier covariance | Rejected | Same argument as spatial covariance. Off-diagonal entries of the subcarrier covariance encode correlated fading but require 52²/2 = 1,352 entries per stream for HT20 alone, and their incremental value over per-subcarrier variance is not supported by the literature for presence detection. |
|
||||
| Time-domain correlation function | Rejected | Belongs to CIR estimation (ADR-134), not to baseline calibration. |
|
||||
|
||||
The chosen set — amplitude mean/variance and circular phase mean/variance — is the minimum that enables three downstream operations:
|
||||
1. Static-environment subtraction for motion detectors (amplitude mean).
|
||||
2. Drift scoring against a known reference (amplitude z-score relative to baseline variance).
|
||||
3. Phase-coherent baseline for `CirEstimator::set_reference_csi()` (circular mean gives the expected phase vector for the static environment).
|
||||
|
||||
### 2.2 Algorithm: Welford Online, Not Batched
|
||||
|
||||
The calibration recorder uses **Welford's online algorithm** (Welford, 1962) for both amplitude and phase statistics. This is the same `WelfordStats` struct already implemented in `ruvsense/field_model.rs` — the calibration module imports it directly.
|
||||
|
||||
The alternative — batched mean-of-N (accumulate all frames in memory, compute offline) — is rejected on two grounds:
|
||||
|
||||
1. **Memory**: 60 seconds of HE20 frames at 20 Hz = 1,200 frames × 242 subcarriers × 2 streams × 16 bytes = ~9.3 MB of raw complex data. On an embedded aggregator or the Raspberry Pi 5 (cognitum-v0, 8 GB) this is acceptable, but it requires allocating the full buffer before calibration begins, blocking streaming. Welford's algorithm requires O(K × S) state regardless of frame count.
|
||||
2. **Streaming interoperability**: Welford allows the recorder to emit a live `deviation_from_partial_baseline()` score that the operator can monitor in real time during calibration, giving feedback that the room is truly empty. Batched computation cannot do this.
|
||||
|
||||
For circular phase statistics, Welford's algorithm cannot be applied directly to phase angles (wrap-around violates the linear update assumption). Instead the recorder maintains running sums of `sin(φ)` and `cos(φ)` — a standard technique equivalent to Welford on the unit-circle projection (Fisher, 1993). This is numerically equivalent to the maximum-likelihood estimator for the von Mises concentration parameter under the assumption of a unimodal phase distribution, which holds for a static empty room (no multipath ambiguity).
|
||||
|
||||
### 2.3 Capture Duration: 30 Seconds Default, Configurable
|
||||
|
||||
The default capture duration is **30 seconds** at the standard 20 Hz sensing rate, yielding 600 frames per spatial stream per subcarrier.
|
||||
|
||||
**Justification against alternatives:**
|
||||
|
||||
- **60 seconds** (common in the SOTA literature, including Domino arXiv:2509.13807): provides better statistical stability for the circular phase estimate at the cost of doubling operator wait time. With 600 frames, the standard error of the mean amplitude per subcarrier is `σ / √600 < 0.002 × σ` — negligible for sensing purposes at any tier.
|
||||
- **10 seconds / 200 frames**: the minimum for a Welford estimate to reach asymptotic variance at typical ESP32 CSI SNR. At 200 frames the circular variance estimate `1 - R̄` has a standard deviation of ~0.04 (Fisher, 1993, Eq. 3.24), corresponding to roughly ±0.04 rad² uncertainty in phase concentration. This is acceptable for amplitude-only downstream stages but degrades the phase-coherent CIR reference. Not the default.
|
||||
- **Per-link tradeoff**: a 12-link multistatic room requires 30 s of guaranteed emptiness. Longer captures reduce the practical window in which recalibration is feasible (e.g., during a 30-minute care visit). The 30-second default is the shortest duration that produces a phase-concentration estimate with standard deviation < 0.02 rad².
|
||||
|
||||
The `--duration` CLI flag accepts any value from 10 to 600 seconds. Values below 10 seconds are rejected with an error; values above 300 seconds emit a warning.
|
||||
|
||||
### 2.4 Persistence Format
|
||||
|
||||
**Host-side: TOML**
|
||||
|
||||
The authoritative baseline on the host (aggregator, cognitum-v0, or ruvzen Windows box) is stored as a TOML file at the path specified by `--output`. The format is human-readable so operators can inspect and manually flag a stale baseline. Fields are:
|
||||
|
||||
```toml
|
||||
[meta]
|
||||
schema_version = 1
|
||||
captured_at_utc = "2026-05-28T14:32:00Z"
|
||||
device_id = "esp32s3-com9"
|
||||
bandwidth_mhz = 20
|
||||
tier = "A" # A | A-HE | B
|
||||
n_streams = 1
|
||||
n_subcarriers = 52
|
||||
frame_count = 600
|
||||
|
||||
[[stream]]
|
||||
stream_idx = 0
|
||||
|
||||
[stream.amp_mean] # length = n_subcarriers
|
||||
values = [0.421, 0.418, ...]
|
||||
|
||||
[stream.amp_variance]
|
||||
values = [0.0012, 0.0009, ...]
|
||||
|
||||
[stream.phase_cos_mean]
|
||||
values = [0.871, 0.864, ...]
|
||||
|
||||
[stream.phase_sin_mean]
|
||||
values = [0.122, 0.134, ...]
|
||||
|
||||
[stream.phase_circular_variance]
|
||||
values = [0.031, 0.028, ...]
|
||||
```
|
||||
|
||||
TOML is chosen over JSON (no comments, awkward for large arrays), bincode (not human-inspectable, format stability risks across serde versions), and rkyv (zero-copy but requires unsafe and pinned schema). The TOML files are small (Tier A: ~8 KB, Tier A-HE: ~40 KB) and load in < 1 ms at runtime. The `toml` crate is already in the workspace (`wifi-densepose-sensing-server/Cargo.toml`).
|
||||
|
||||
**Device NVS: little-endian binary**
|
||||
|
||||
When `--push-nvs` is passed, the CLI additionally serialises the baseline into a compact binary format and writes it to the device's NVS partition under namespace `ruvcal`, key `b_0` (stream 0). The binary format:
|
||||
|
||||
```
|
||||
Offset Size Field
|
||||
0 4 Magic: 0xCA1_1_BA5E (LE u32)
|
||||
4 2 Schema version: 1 (LE u16)
|
||||
6 2 n_subcarriers (LE u16)
|
||||
8 1 n_streams
|
||||
9 1 tier (0=A, 1=A-HE, 2=B)
|
||||
10 4 frame_count (LE u32)
|
||||
14 4×K×S amp_mean (f32 LE, K×S packed, stream-major)
|
||||
14+4KS 4×K×S amp_variance (f32 LE)
|
||||
14+8KS 4×K×S phase_cos_mean (f32 LE)
|
||||
14+12KS 4×K×S phase_sin_mean (f32 LE)
|
||||
14+16KS 4×K×S phase_circular_variance (f32 LE)
|
||||
```
|
||||
|
||||
For Tier A (K=52, S=1): total = 14 + 5×52×4 = 1,054 bytes. Well within NVS single-key limits (4,000 bytes default). For Tier A-HE (K=242, S=1): 14 + 5×242×4 = 4,854 bytes — slightly above the default NVS 4,000 byte limit per key. **Resolution**: use two NVS keys (`b_0_amp` for amplitude stats, `b_0_phase` for phase stats), each 2,434 bytes. The CLI serialises to two keys when K×S×4 > 1,980 bytes.
|
||||
|
||||
Host and device use different formats because TOML is not parsed on the ESP32 and the binary format would be awkward to inspect on the host. The CLI handles both directions; no device code changes are required.
|
||||
|
||||
### 2.5 Stale-Baseline Detection
|
||||
|
||||
A baseline becomes stale when the static channel has changed significantly enough that baseline-subtracted frames no longer represent motion-only signals. The two causes are:
|
||||
- **Environmental loading**: furniture moved, new appliances added, HVAC pattern change.
|
||||
- **Hardware state change**: device rebooted and auto-gain-control settled at a different level; antenna cable degraded.
|
||||
|
||||
Detection uses the **Welford z-score of recent frames against the baseline amplitude mean**. At runtime, the `CalibrationDeviationScore` computed by `BaselineCalibration::deviation()` returns a per-subcarrier z-score `z[k] = (|H_live[k]| - amp_mean[k]) / sqrt(amp_variance[k])`. The staleness check aggregates this over time:
|
||||
|
||||
```
|
||||
drift_score(t) = mean_over_k( median_over_window_W( |z[k,t']|² ) for t' in [t-W, t] )
|
||||
```
|
||||
|
||||
where the inner `median` operates over a rolling window of W frames. `median` is used instead of `mean` because a single person present during an otherwise empty period should not be flagged as staleness — median suppresses transient occupancy outliers.
|
||||
|
||||
**Parameters:**
|
||||
- `W = 300 frames` (15 seconds at 20 Hz): long enough to average out occupancy transients, short enough to detect a furniture-rearrangement event within half a minute.
|
||||
- Staleness threshold: `drift_score > 4.0`. This corresponds to a mean squared z-score of 4 across all subcarriers, i.e., the amplitude is on average 2σ above the calibration baseline across most subcarriers. This threshold was validated by the field_model.rs team: the `BaselineExpired` error in `field_model.rs` fires at a similar magnitude of environmental shift.
|
||||
|
||||
When `drift_score > 4.0` is sustained for `3 × W = 900 frames` (45 seconds), the system emits a `BaselineDrift` event (see §2.6). A single window above threshold triggers a `BaselineWarn` log only.
|
||||
|
||||
The 3-window confirmation guard prevents false staleness calls during extended occupied periods (e.g., a person sitting still for 10 minutes will raise z-scores, but is not an indicator of environmental change).
|
||||
|
||||
### 2.6 Recalibration Trigger
|
||||
|
||||
**Default behaviour: operator-initiated.**
|
||||
|
||||
The system does not recalibrate automatically. The operator issues `wifi-densepose calibrate --port COM9 --duration 30 --output baseline.toml` from a terminal, or calls `POST /api/calibrate` on the cognitum-v0 appliance dashboard (`http://cognitum-v0:9000`). Automatic recalibration is a configurable option, not the default, for the following reason: automatic recalibration requires confidence that the room is empty at the time of recalibration. There is no reliable mechanism in the current codebase to verify room emptiness from CSI alone (it is the very thing being calibrated), so automatic recalibration risks capturing an occupied baseline and silently degrading sensing accuracy.
|
||||
|
||||
**Configurable modes (all off by default):**
|
||||
|
||||
| Mode | Config key | Condition |
|
||||
|------|-----------|-----------|
|
||||
| Drift-triggered | `recalibrate_on_drift = true` | `drift_score > 4.0` sustained 45 s AND `drift_score < drift_score + 2σ` (i.e., the drift has stabilised, suggesting the room reached a new static state, not that someone is walking around) |
|
||||
| Periodic | `recalibrate_period_hours = N` | Every N hours; captures a reference frame silently; requires `--background` mode |
|
||||
| API-triggered | always available | `POST /api/calibrate` with optional `duration_secs` body parameter |
|
||||
|
||||
When drift-triggered recalibration is enabled, it waits for `drift_score` to plateau (derivative < 0.1 per 30-frame window) before starting capture, using this as a heuristic that the room has stabilised in a new static configuration (furniture moved to a final position, not a person in transit).
|
||||
|
||||
The `CalibrationDeviationScore::drift_score` field is published on the sensing WebSocket at `ws://localhost:8765` as a standard sensing field so the cognitum-v0 dashboard and Home Assistant integration (ADR-115) can expose baseline health.
|
||||
|
||||
### 2.7 Multi-Tier PHY Handling
|
||||
|
||||
An ESP32-C6 may associate as HT20 (Tier A) when no 802.11ax AP is in range, or as HE20 (Tier A-HE) when one is available. The two modes produce different subcarrier counts (52 vs 242 K_active) and different pilot patterns. They are **not interchangeable baselines**.
|
||||
|
||||
**Decision: one baseline file per PHY tier per link. Tier change invalidates the existing baseline.**
|
||||
|
||||
When the aggregator receives a frame from a C6 link and `CsiMetadata.bandwidth_mhz` and the PPDU type (from ADR-110's `csi_collector.c` frame byte 18–19) indicate a tier different from the currently loaded baseline, `BaselineCalibration::subtract()` returns `CalibrationError::TierMismatch { expected, actual }`. The aggregator logs this at WARN level and falls back to no-baseline-subtraction mode for that link until the operator recalibrates.
|
||||
|
||||
The rationale for invalidation rather than interpolation: interpolating a 52-subcarrier baseline to 242 subcarriers (or vice versa) requires assumptions about per-subcarrier correlation that are not validated in this codebase. The hardware-norm resample path (`hardware_norm.rs`) uses Catmull-Rom for subcarrier grid normalisation, but that normalises across hardware types at the same tier — not across tier transitions on the same device.
|
||||
|
||||
In practice, tier transitions are rare: they occur when the AP is rebooted (dropping 802.11ax), when the C6 moves out of 11ax AP range, or when the operator changes the AP. The operator is expected to recalibrate after a tier change.
|
||||
|
||||
### 2.8 Fleet-Wide Simultaneous Capture
|
||||
|
||||
The operator can calibrate the full multistatic array with a single command:
|
||||
|
||||
```
|
||||
wifi-densepose calibrate --all-nodes --duration 30 --output baselines/
|
||||
```
|
||||
|
||||
This issues a simultaneous capture barrier across all configured nodes using the 802.15.4 epoch from ADR-110 (`c6_timesync_get_epoch_us()` on C6 nodes; local clock interpolated to 802.15.4 domain for S3 nodes).
|
||||
|
||||
**Protocol skeleton:**
|
||||
|
||||
1. The CLI sends a `CalibrateStart { start_epoch_us, duration_ms }` UDP control packet to each node's UDP control port (default 5006). Nodes begin accumulating frames from `start_epoch_us` for `duration_ms` milliseconds, tagging each with the 802.15.4 epoch. S3 nodes use their local hardware timer; C6 nodes use `c6_timesync_get_epoch_us()`.
|
||||
2. The aggregator simultaneously opens a UDP receive socket per node and applies `CalibrationRecorder::record()` to each incoming frame. Frame ordering within the window is irrelevant because Welford statistics are commutative.
|
||||
3. At `start_epoch_us + duration_ms + 500 ms` (500 ms guard for last-frame arrival), the CLI finalises each `CalibrationRecorder`, serialises each `BaselineCalibration` to `baselines/<device_id>.toml`, and optionally pushes NVS binary to each device.
|
||||
4. A summary JSON `baselines/summary.json` lists each node, tier, frame count, and the mean `drift_score` relative to any previous baseline, allowing the operator to spot nodes that were occupied during calibration.
|
||||
|
||||
Fleet capture requires that all C6 nodes are associated (not in AP setup mode). Seed nodes that have not yet been provisioned (`seed-2` through `seed-5` from CLAUDE.local.md fleet table) are skipped with a warning. `cognitum-seed-1` is the only fully provisioned seed as of this writing.
|
||||
|
||||
The 802.15.4 timesync barrier is optional for calibration accuracy (Welford statistics are order-independent) but is required when the calibration baseline will also be used to compute the inter-node phase alignment for ADR-042's CHCI path.
|
||||
|
||||
### 2.9 Proposed Rust API
|
||||
|
||||
The new module is `v2/crates/wifi-densepose-signal/src/ruvsense/calibration.rs`, exported from `ruvsense/mod.rs` as `pub mod calibration`.
|
||||
|
||||
```rust
|
||||
use num_complex::Complex32;
|
||||
use wifi_densepose_core::types::CsiFrame;
|
||||
|
||||
// ---- Error type -------------------------------------------------------------
|
||||
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
pub enum CalibrationError {
|
||||
#[error("Tier mismatch: baseline is {expected}, frame is {actual}")]
|
||||
TierMismatch { expected: String, actual: String },
|
||||
|
||||
#[error("Subcarrier count mismatch: baseline has {expected}, frame has {got}")]
|
||||
SubcarrierMismatch { expected: usize, got: usize },
|
||||
|
||||
#[error("Stream count mismatch: baseline has {expected}, frame has {got}")]
|
||||
StreamMismatch { expected: usize, got: usize },
|
||||
|
||||
#[error("Insufficient frames: need at least {needed}, recorded {got}")]
|
||||
InsufficientFrames { needed: usize, got: usize },
|
||||
|
||||
#[error("Baseline not yet finalised (still recording)")]
|
||||
NotFinalised,
|
||||
|
||||
#[error("Baseline data corrupted: {0}")]
|
||||
Corrupt(String),
|
||||
|
||||
#[error("Phase precondition violated: frame phase has not been sanitized")]
|
||||
UnsanitizedPhase,
|
||||
|
||||
#[error("TOML serialisation error: {0}")]
|
||||
TomlSerialise(String),
|
||||
|
||||
#[error("TOML deserialisation error: {0}")]
|
||||
TomlDeserialise(String),
|
||||
}
|
||||
|
||||
// ---- Configuration ----------------------------------------------------------
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct CalibrationConfig {
|
||||
/// Number of frames to accumulate before finalising. Default: 600 (30 s × 20 Hz).
|
||||
pub target_frames: usize,
|
||||
/// Minimum frames accepted by `finalize()`. Default: 200.
|
||||
pub min_frames: usize,
|
||||
/// Staleness window in frames. Default: 300.
|
||||
pub drift_window_frames: usize,
|
||||
/// Drift score threshold for BaselineDrift event. Default: 4.0.
|
||||
pub drift_threshold: f32,
|
||||
/// Duration (frames) above drift_threshold before emitting BaselineDrift. Default: 900.
|
||||
pub drift_confirm_frames: usize,
|
||||
}
|
||||
|
||||
impl Default for CalibrationConfig {
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
target_frames: 600,
|
||||
min_frames: 200,
|
||||
drift_window_frames: 300,
|
||||
drift_threshold: 4.0,
|
||||
drift_confirm_frames: 900,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ---- Recorder ---------------------------------------------------------------
|
||||
|
||||
/// Accumulates CSI frames from an empty room to build a baseline.
|
||||
///
|
||||
/// # Phase precondition
|
||||
///
|
||||
/// The caller is responsible for passing frames whose phase has been
|
||||
/// processed by `PhaseSanitizer` and `phase_align.rs` before calling
|
||||
/// `record()`. Unsanitized phase will be detected by a heuristic
|
||||
/// (per-subcarrier phase variance > 10 rad²) and rejected with
|
||||
/// `CalibrationError::UnsanitizedPhase`.
|
||||
///
|
||||
/// # Concurrency
|
||||
///
|
||||
/// `CalibrationRecorder` requires `&mut self` for `record()`. It is not
|
||||
/// `Sync`. Wrap in a `Mutex` if shared across threads.
|
||||
pub struct CalibrationRecorder {
|
||||
config: CalibrationConfig,
|
||||
frame_count: usize,
|
||||
n_streams: usize,
|
||||
n_subcarriers: usize,
|
||||
// Amplitude Welford accumulators: [stream][subcarrier]
|
||||
amp_mean: Vec<Vec<f64>>,
|
||||
amp_m2: Vec<Vec<f64>>,
|
||||
// Circular phase accumulators: [stream][subcarrier]
|
||||
phase_sin_sum: Vec<Vec<f64>>,
|
||||
phase_cos_sum: Vec<Vec<f64>>,
|
||||
}
|
||||
|
||||
impl CalibrationRecorder {
|
||||
/// Create a new recorder. The first `record()` call sets the
|
||||
/// expected subcarrier and stream counts.
|
||||
pub fn new(config: CalibrationConfig) -> Self;
|
||||
|
||||
/// Accept one sanitized CSI frame into the running statistics.
|
||||
///
|
||||
/// Returns the current frame count after this update.
|
||||
pub fn record(&mut self, frame: &CsiFrame) -> Result<usize, CalibrationError>;
|
||||
|
||||
/// Returns `true` if `target_frames` have been accumulated.
|
||||
pub fn is_complete(&self) -> bool;
|
||||
|
||||
/// Returns the current frame count.
|
||||
pub fn frame_count(&self) -> usize;
|
||||
|
||||
/// Finalise the baseline from accumulated statistics.
|
||||
///
|
||||
/// Consumes `self`. Returns an error if fewer than `min_frames` were
|
||||
/// recorded.
|
||||
pub fn finalize(self) -> Result<BaselineCalibration, CalibrationError>;
|
||||
}
|
||||
|
||||
// ---- Baseline ---------------------------------------------------------------
|
||||
|
||||
/// A fully finalised empty-room baseline.
|
||||
///
|
||||
/// Stores per-subcarrier amplitude mean/variance and circular phase
|
||||
/// mean/variance for each spatial stream. Immutable after construction.
|
||||
/// `Clone` is cheap (Vec of f32).
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct BaselineCalibration {
|
||||
/// Device ID from which this baseline was captured.
|
||||
pub device_id: String,
|
||||
/// UTC timestamp of calibration (Unix seconds).
|
||||
pub captured_at_unix_s: i64,
|
||||
/// PHY tier string: "A", "A-HE", or "B".
|
||||
pub tier: String,
|
||||
/// Bandwidth in MHz.
|
||||
pub bandwidth_mhz: u16,
|
||||
/// Number of spatial streams.
|
||||
pub n_streams: usize,
|
||||
/// Number of active (non-pilot, non-null) subcarriers.
|
||||
pub n_subcarriers: usize,
|
||||
/// Total frames used to build this baseline.
|
||||
pub frame_count: usize,
|
||||
// Per-stream, per-subcarrier statistics (stream-major layout).
|
||||
pub amp_mean: Vec<Vec<f32>>,
|
||||
pub amp_variance: Vec<Vec<f32>>,
|
||||
pub phase_cos_mean: Vec<Vec<f32>>,
|
||||
pub phase_sin_mean: Vec<Vec<f32>>,
|
||||
/// Circular variance ∈ [0, 1]: 0 = concentrated, 1 = dispersed.
|
||||
pub phase_circular_variance: Vec<Vec<f32>>,
|
||||
}
|
||||
|
||||
impl BaselineCalibration {
|
||||
/// Compute a deviation score for one live frame against this baseline.
|
||||
///
|
||||
/// Returns `CalibrationError::TierMismatch` if the frame's bandwidth
|
||||
/// or subcarrier count do not match the baseline.
|
||||
pub fn deviation(&self, frame: &CsiFrame) -> Result<CalibrationDeviationScore, CalibrationError>;
|
||||
|
||||
/// Subtract the baseline amplitude mean from `frame.data` (in-place,
|
||||
/// stream-by-stream, subcarrier-by-subcarrier).
|
||||
///
|
||||
/// After subtraction, `frame.data[s][k]` represents the perturbation
|
||||
/// from the static environment, suitable for motion detection and CIR
|
||||
/// estimation.
|
||||
///
|
||||
/// Phase is not modified by subtraction; downstream callers that need
|
||||
/// phase-coherent baseline removal should use
|
||||
/// `reference_csi_vector()` to set `CirEstimator::set_reference_csi()`.
|
||||
pub fn subtract(&self, frame: &mut CsiFrame) -> Result<(), CalibrationError>;
|
||||
|
||||
/// Returns the expected complex CSI vector for the static environment
|
||||
/// (amplitude mean × exp(j × circular_mean_phase)), suitable for passing
|
||||
/// to `CirEstimator::set_reference_csi()`.
|
||||
///
|
||||
/// Returns one vector per spatial stream: `Vec<Vec<Complex32>>`.
|
||||
pub fn reference_csi_vector(&self) -> Vec<Vec<Complex32>>;
|
||||
|
||||
/// Serialise to TOML bytes.
|
||||
pub fn to_toml(&self) -> Result<Vec<u8>, CalibrationError>;
|
||||
|
||||
/// Deserialise from TOML bytes.
|
||||
pub fn from_toml(buf: &[u8]) -> Result<Self, CalibrationError>;
|
||||
|
||||
/// Serialise to compact NVS binary (see §2.4 for format).
|
||||
pub fn to_nvs_bytes(&self) -> Vec<u8>;
|
||||
|
||||
/// Deserialise from NVS binary.
|
||||
pub fn from_nvs_bytes(buf: &[u8]) -> Result<Self, CalibrationError>;
|
||||
}
|
||||
|
||||
// ---- Deviation score --------------------------------------------------------
|
||||
|
||||
/// Per-frame deviation from the static baseline.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct CalibrationDeviationScore {
|
||||
/// Per-subcarrier amplitude z-score: (|H[k]| − mean[k]) / std[k].
|
||||
/// Positive = higher than baseline, negative = lower.
|
||||
pub amplitude_z: Vec<Vec<f32>>,
|
||||
/// RMS amplitude z-score across all subcarriers and streams.
|
||||
/// Motion threshold: > 3.0 = likely occupied frame.
|
||||
pub rms_amplitude_z: f32,
|
||||
/// Per-subcarrier circular phase deviation in radians: |φ_live[k] − φ_baseline[k]|.
|
||||
pub phase_deviation_rad: Vec<Vec<f32>>,
|
||||
/// Mean circular phase deviation across all subcarriers.
|
||||
pub mean_phase_deviation_rad: f32,
|
||||
/// Instantaneous drift score (see §2.5 for definition).
|
||||
pub drift_score: f32,
|
||||
/// Whether the drift_score sustained above threshold (staleness flag).
|
||||
pub baseline_stale: bool,
|
||||
}
|
||||
```
|
||||
|
||||
**Design decisions within the API:**
|
||||
|
||||
- `record()` takes `&mut self`, not `&self` with interior mutability. The recording path is inherently single-threaded (one receiver loop per link). Interior mutability would add `Mutex` overhead for no benefit.
|
||||
- `subtract()` takes `&mut CsiFrame` and modifies `frame.data` in place. It does not modify `frame.amplitude` or `frame.phase` — callers that read `frame.amplitude` downstream are expected to call `CsiFrame::recompute_amplitude_phase()` (a new method to be added to `wifi_densepose_core::types::CsiFrame`) or to use `frame.data` directly.
|
||||
- `to_nvs_bytes()` / `from_nvs_bytes()` are fallible via `panic!` for magic mismatch but return `Result` for truncation. This matches the pattern in `csi.rs::parse_esp32_vitals()`.
|
||||
- `BaselineCalibration` is `Clone` because the CLI needs to hold one copy while pushing NVS and another while writing TOML.
|
||||
|
||||
### 2.10 CLI Surface
|
||||
|
||||
The `wifi-densepose calibrate` subcommand is added to `wifi-densepose-cli/src/lib.rs` as a new `Commands::Calibrate(CalibrateCommand)` variant.
|
||||
|
||||
```
|
||||
wifi-densepose calibrate [OPTIONS]
|
||||
|
||||
OPTIONS:
|
||||
--port <PORT> Serial port or UDP address of the ESP32 node
|
||||
(e.g., COM9 on Windows, /dev/ttyS8 on WSL).
|
||||
For fleet mode, omit and use --all-nodes.
|
||||
--duration <SECS> Capture duration in seconds [default: 30]
|
||||
--output <PATH> Path to write the TOML baseline file
|
||||
[default: baseline_<device_id>.toml]
|
||||
--tier <TIER> Expected PHY tier: A | A-HE | B
|
||||
[default: detected from first frame]
|
||||
--push-nvs After capturing, serialise to NVS binary and
|
||||
write to device flash via the provisioning tool.
|
||||
--all-nodes Fleet mode: capture from all configured nodes
|
||||
simultaneously using 802.15.4 epoch sync.
|
||||
--server <ADDR> Aggregator address for --all-nodes mode
|
||||
[default: 127.0.0.1:5006]
|
||||
--min-frames <N> Minimum frames before finalise() is accepted
|
||||
[default: 200]
|
||||
--drift-check After capturing, compare against an existing
|
||||
baseline at --output and print the drift score.
|
||||
```
|
||||
|
||||
**Defaults justified:**
|
||||
|
||||
- `--duration 30`: justified in §2.3.
|
||||
- `--output baseline_<device_id>.toml`: the device ID is embedded in the first received `CsiMetadata.device_id`. The operator does not need to specify it for single-node mode.
|
||||
- `--tier detected`: the first frame's `bandwidth_mhz` and PPDU type (for C6) determine the tier. The flag exists for cases where the operator wants to force Tier A even if the device is capable of Tier A-HE (e.g., to pre-generate a fallback baseline).
|
||||
|
||||
### 2.11 Downstream Consumers
|
||||
|
||||
| Consumer | What it receives | Change required |
|
||||
|----------|-----------------|-----------------|
|
||||
| `ruvsense/multistatic.rs` | Baseline-subtracted `CsiFrame.data` via `BaselineCalibration::subtract()` | `MultistaticConfig` gains a `baseline: Option<Arc<BaselineCalibration>>` field; `process_cycle()` calls `subtract()` on each node's latest frame before passing to the attention gate |
|
||||
| `ruvsense/cir.rs` (ADR-134) | Static-environment reference via `BaselineCalibration::reference_csi_vector()` passed to `CirEstimator::set_reference_csi()` | No API change to `CirEstimator`; the aggregator setup path calls `set_reference_csi()` at startup if a baseline file is present |
|
||||
| `motion.rs` | `CalibrationDeviationScore.rms_amplitude_z` as a primary motion signal | Replaces the existing amplitude variance threshold with a baseline-relative z-score; threshold changes from an absolute amplitude variance to `rms_amplitude_z > 3.0` |
|
||||
| `features.rs` | `CalibrationDeviationScore` fields available as additional features | `SignalFeatures` gains `baseline_rms_z: Option<f32>` and `baseline_drift_score: Option<f32>` fields; `None` when no baseline is loaded |
|
||||
| `wifi-densepose-vitals` | No change | Breathing and heart-rate detection filters operate in the 0.15–2.0 Hz band; slow baseline drift is below 0.001 Hz and is already filtered. The vital-sign pipeline benefits marginally from baseline subtraction at the amplitude level but this is not required for the current implementation. |
|
||||
| `ruvsense/field_model.rs` | Calibration frames passed through `CalibrationRecorder` before SVD decomposition | The field model now takes baseline-subtracted frames as input. The Welford mean accumulator in `field_model.rs::FieldModelBuilder` is superseded for the per-subcarrier-mean step — the calibration module handles it. `FieldModelBuilder` ingests `BaselineCalibration` directly to skip its internal mean step. |
|
||||
|
||||
**CIR interaction detail**: ADR-134's §2.5 specifies that the `CirEstimator` applies conjugate multiplication using `reference_csi` for single-antenna fallback. `BaselineCalibration::reference_csi_vector()` produces the correct complex reference vector: `amp_mean[s][k] × exp(j × atan2(phase_sin_mean, phase_cos_mean))`. This is more accurate than the previously described approach of averaging quiescent frames on the fly, because the baseline uses 600 frames (30 s) rather than a small number of recent frames, reducing the noise on the reference vector by a factor of ~√600/√10 ≈ 7.7× compared to a 0.5 s on-the-fly average.
|
||||
|
||||
### 2.12 Test Plan
|
||||
|
||||
**Tier 1 — Deterministic synthetic stationary channel (unit test)**
|
||||
|
||||
Generate a synthetic CSI frame representing a static 2-tap channel (direct path + one wall reflection, identical parameters to the ADR-134 Tier 1 test): `H[k] = α₁·e^{-j2πkΔf·τ₁} + α₂·e^{-j2πkΔf·τ₂}`. Add zero-mean Gaussian amplitude noise (σ = 0.02 × |α₁|) and constant phase offset δ = π/8 per subcarrier (simulating LO drift already corrected by `phase_align.rs`). Feed 600 copies of this frame to `CalibrationRecorder`. Call `finalize()`. Assert:
|
||||
|
||||
- `baseline.amp_mean[0][k]` is within 2σ/√600 of `|α₁·e^{-j2πkΔf·τ₁} + α₂·e^{-j2πkΔf·τ₂}|` for all k.
|
||||
- `baseline.phase_circular_variance[0][k]` < 0.005 (highly concentrated — noise σ = 0.02 does not produce meaningful phase variance).
|
||||
- `CalibrationDeviationScore.rms_amplitude_z` for the same static frame is < 1.0 (not flagged as motion).
|
||||
|
||||
**Tier 2 — Perturbation detection (unit test)**
|
||||
|
||||
Same baseline. Inject one frame with amplitude perturbed at 10 random subcarriers by +3σ (simulating a person present). Assert `rms_amplitude_z > 3.0` and that the perturbed subcarrier indices are among the top-10 `|amplitude_z|` entries in `CalibrationDeviationScore`.
|
||||
|
||||
**Tier 3 — TOML round-trip (unit test)**
|
||||
|
||||
Serialise the Tier 1 baseline to `to_toml()`, deserialise with `from_toml()`, assert field-level equality to within f32 precision.
|
||||
|
||||
**Tier 4 — NVS binary round-trip (unit test)**
|
||||
|
||||
Same as Tier 3 using `to_nvs_bytes()` / `from_nvs_bytes()`. Assert magic word `0xCA11BA5E` at offset 0 and schema version = 1.
|
||||
|
||||
**Tier 5 — Stale-baseline detection (unit test)**
|
||||
|
||||
Start with the Tier 1 baseline. Feed 900 frames with amplitude uniformly increased by `5σ` at all subcarriers (simulating furniture moved). Assert that `CalibrationDeviationScore.baseline_stale` becomes `true` at or before frame 900.
|
||||
|
||||
**Tier 6 — Real hardware capture (integration test, COM9)**
|
||||
|
||||
Using the ESP32-S3 on COM9 (ruvzen), capture a 30-second baseline in a static empty room. Then capture 200 live frames in the same room (still empty). Assert:
|
||||
- `CalibrationDeviationScore.rms_amplitude_z` < 2.0 for all 200 frames.
|
||||
- `CalibrationDeviationScore.drift_score` < 1.0.
|
||||
- Walking through the room during the live phase: at least 10 consecutive frames show `rms_amplitude_z > 3.0`.
|
||||
|
||||
This test is gated behind `#[cfg(feature = "hardware-test")]` and is not run in CI.
|
||||
|
||||
**Tier 7 — Determinism proof (CI-compatible)**
|
||||
|
||||
To extend the ADR-028 witness proof chain: using the same synthetic 600-frame stream from Tier 1, compute the SHA-256 of `to_nvs_bytes()` output. Record this hash in `archive/v1/data/proof/expected_features.sha256` under the key `calibration_nvs_baseline_v1`. The `verify.py` extension function `calibration_baseline_check()` regenerates the same 600-frame synthetic stream, runs `CalibrationRecorder`, serialises, and asserts the hash matches. This makes the calibration algorithm deterministic end-to-end, consistent with the ADR-028 proof methodology.
|
||||
|
||||
### 2.13 Witness / Proof
|
||||
|
||||
Per ADR-028, the following rows are added to `docs/WITNESS-LOG-028.md`:
|
||||
|
||||
| Row | Capability | Evidence | Hash |
|
||||
|-----|-----------|----------|------|
|
||||
| W-36 | CalibrationRecorder Welford correctness (synthetic 600-frame stationary) | `cargo test calibration::tests::stationary_baseline -- --nocapture` | SHA-256 of amp_mean output |
|
||||
| W-37 | BaselineCalibration NVS binary round-trip | `cargo test calibration::tests::nvs_round_trip` passes | SHA-256 of serialised bytes |
|
||||
| W-38 | Drift detection fires within 900 frames (synthetic 5σ perturbation) | `cargo test calibration::tests::stale_detection` | SHA-256 of test binary |
|
||||
|
||||
`source-hashes.txt` in the witness bundle gains `SHA-256(ruvsense/calibration.rs)`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Consequences
|
||||
|
||||
### 3.1 Positive
|
||||
|
||||
- **Motion detector reliability**: replacing absolute amplitude variance thresholds with baseline-relative z-scores reduces false positives from HVAC and thermal drift. The `rms_amplitude_z > 3.0` threshold is scale-invariant across hardware tiers.
|
||||
- **CIR quality improvement**: `CirEstimator` receives a 600-frame static reference rather than a 10-frame rolling average. Ghost taps near τ=0 from the dominant static path are suppressed earlier in the ISTA solve, freeing regularisation budget for body-perturbed taps. Effective `dominant_tap_ratio` dynamic range increases by the ratio `√600/√10 ≈ 7.7×` in reference SNR — the ISTA warm-start quality directly improves.
|
||||
- **Multi-node amplitude comparability**: after baseline subtraction, each link's `CsiFrame.data` is zero-centred on the static environment. Multistatic attention weighting can use amplitude magnitude directly without per-link gain normalisation.
|
||||
- **ADR-030 field model simplification**: `FieldModelBuilder` no longer needs its own per-subcarrier Welford mean pass; it consumes the finished `BaselineCalibration` and proceeds directly to SVD. Duplicate code is removed.
|
||||
- **Fleet-wide recalibration is one command**: the `--all-nodes` flag with 802.15.4 epoch sync enables house-wide calibration in a single 30-second window, closing the operational gap for multi-room deployments.
|
||||
|
||||
### 3.2 Negative
|
||||
|
||||
- **Calibration ceremony required at install**: operators must capture a 30-second empty-room baseline before the system produces reliable motion scores. Systems shipped without a baseline fall back to uncalibrated mode (no `subtract()` call, absolute variance thresholds). This is not a regression — the current code has no baseline — but it is a new operational step.
|
||||
- **Baseline invalidated by furniture changes**: any significant room change (moved sofa, new TV) requires recalibration. The `drift_score > 4.0` alarm notifies the operator, but does not self-heal.
|
||||
- **Two NVS keys for Tier A-HE**: the 4,854-byte HE20 baseline does not fit in a single default NVS key. The two-key scheme (`b_0_amp` / `b_0_phase`) adds complexity to the device-side NVS reader if that is ever implemented. For the current scope (host-side reader only), this is not a practical problem.
|
||||
- **New `recompute_amplitude_phase()` method needed on `CsiFrame`**: `subtract()` modifies `frame.data` but `frame.amplitude` and `frame.phase` become stale. The method is simple (`amplitude = data.mapv(|c| c.norm()); phase = data.mapv(|c| c.arg())`) but it adds one public API surface to `wifi-densepose-core`.
|
||||
|
||||
### 3.3 Risks
|
||||
|
||||
| Risk | Probability | Impact | Mitigation |
|
||||
|------|-------------|--------|------------|
|
||||
| Operator captures baseline with person present | Medium (single-person household) | Silently corrupted baseline; baseline-subtracted frames look like a "hole" where the person was | The CLI prints real-time `rms_amplitude_z` during capture; high z-scores (>2.0) during capture trigger a WARNING banner. Post-capture, `--drift-check` compares against a previous baseline to flag anomalies |
|
||||
| Tier change (HT20 → HE20) invalidates baseline mid-session | Medium (C6 nodes near AP boundary) | `TierMismatch` error at runtime; system falls to uncalibrated mode | `TierMismatch` logged at WARN; operator notified via WebSocket event; auto-recalibration configurable |
|
||||
| Phase circular variance underestimated for subcarriers with multimodal phase distribution (two equally strong reflected paths at ±π/2) | Low (requires geometric coincidence) | `phase_circular_variance` near 1.0; phase reference from `reference_csi_vector()` is noisy for those subcarriers | `phase_circular_variance > 0.5` per-subcarrier is flagged in the TOML with a comment; CIR estimator down-weights the corresponding rows in Φ by masking them (same mechanism as pilot exclusion in §2.4 of ADR-134) |
|
||||
| ESP32-S3 auto-gain-control shifts between baseline capture and runtime | Low (AGC settles within 5 frames) | Amplitude mean baseline offset; all `amp_z` scores biased | AGC-locked mode (`esp_wifi_set_csi_config` with `rx_chain` pin) is available in firmware v0.7.0; recommend enabling for dedicated sensing nodes via `provision.py --pin-agc` flag |
|
||||
|
||||
---
|
||||
|
||||
## 4. Rationale and Comparison to Alternative Designs
|
||||
|
||||
### 4.1 Why Not "Skip Calibration, Rely on Differential Signals Only"
|
||||
|
||||
The dominant approach in academic WiFi sensing papers (2018–2022) is to use differential or conjugate-product CSI — dividing each frame by a running average of recent frames — rather than an explicit empty-room baseline. This avoids the calibration ceremony at the cost of three concrete problems in this codebase:
|
||||
|
||||
- **Differential signals accumulate bias under environmental loading**. A piece of furniture that moves over 10 minutes produces a slow CSI drift that appears as a 10-minute "motion" event in a conjugate-product system with a 1-second window, or becomes invisible in a system with a 1-hour window. There is no window size that eliminates environmental loading without also suppressing slow human motion (a resting person's micromotion is < 0.01 Hz). The IEEE Transactions 2024 paper "Experimental Evaluation of Long-Term Concept Drift and Its Mitigation in WiFi CSI Sensing" (IEEE Xplore document 10975920) demonstrates that concept drift from environmental factors causes systematic accuracy degradation over hours to days, which no differential window eliminates.
|
||||
- **Differential signals cannot be compared across nodes**. Multi-node coherence scoring requires a shared zero-mean reference. If each node has its own differential reference (its own recent history), drift rates differ across nodes and coherence scores are not interpretable.
|
||||
- **`CirEstimator` requires an absolute complex reference**. ADR-134 §2.5 describes conjugate multiplication: `H[k] * conj(H_ref[k])`. The `H_ref` in that context must be a stable, long-term static reference to avoid ghost taps — not a 0.5-second recent average, which still contains transient motion in active households.
|
||||
|
||||
### 4.2 Why Not "Calibrate at Factory, Ship Coefficients"
|
||||
|
||||
Per-device factory calibration would require: (a) a known-geometry, electromagnetically clean test chamber per device, and (b) the firmware to store calibration at production time. ESP32 hardware calibration (PHY RF calibration, `esp_phy_store_cal_data_to_nvs`) is a different concept — it corrects transmit chain IQ imbalance, not the per-room environmental channel. Room geometry is not known at factory. Per-room baseline is the only physically meaningful calibration for ambient sensing applications.
|
||||
|
||||
### 4.3 Why Not "Use a Neural Network-Learned Baseline"
|
||||
|
||||
Neural baseline subtraction (training a denoising autoencoder on empty-room CSI) has been proposed in several transfer learning papers. The objection from ADR-134 §2.2 for neural CIR applies equally here: there is no paired empty-room dataset for this codebase, and the feature distribution of "empty room" is inherently location-specific. A neural baseline trained in one room may produce negative subtraction values in a different room's frequency-selective geometry. The per-subcarrier Welford mean is a degenerate (optimal) estimator under Gaussian noise: it requires no training data, has a closed-form convergence guarantee, and generalises perfectly to any room because it operates on that room's own captures.
|
||||
|
||||
### 4.4 Why Welford Over Exponential Moving Average (EMA)
|
||||
|
||||
EMA (`mean_new = α × x + (1 − α) × mean_old`) is simpler to implement and provides continuous adaptation but has two drawbacks for a calibration baseline:
|
||||
|
||||
- **α is a free parameter** with no principled setting. Too small an α causes slow adaptation (baseline lags environmental loading); too large adapts immediately to occupancy (person present → person absorbed into baseline → false negative forever).
|
||||
- **EMA variance** requires a separate squared-error accumulator and is less numerically stable than Welford at finite precision.
|
||||
|
||||
Welford provides the exact sample variance in a single pass with no free parameters and no numerical issues. The existing `WelfordStats` in `field_model.rs` is reused directly. The only EMA advantage (continuous adaptation without a discrete recalibrate event) is a liability here: the baseline must be stable while the room is occupied and only updated on explicit operator command.
|
||||
|
||||
---
|
||||
|
||||
## 5. Related ADRs
|
||||
|
||||
| ADR | Relationship |
|
||||
|-----|-------------|
|
||||
| ADR-014 (SOTA Signal Processing) | **Extended**: calibration baseline subtraction becomes the zeroth stage of the signal pipeline, before any feature extraction |
|
||||
| ADR-028 (ESP32 Capability Audit) | **Witness extended**: three new rows W-36 through W-38 added to `WITNESS-LOG-028.md`; calibration NVS binary hash added to `source-hashes.txt` |
|
||||
| ADR-029 (RuvSense Multistatic) | **Enables**: `MultistaticConfig.baseline` field unblocks amplitude-comparable multi-node coherence scoring |
|
||||
| ADR-030 (Persistent Field Model) | **Simplified**: `FieldModelBuilder` no longer computes its own per-subcarrier Welford mean; it ingests `BaselineCalibration` as input |
|
||||
| ADR-110 (ESP32-C6 Firmware Extension) | **Substrate**: 802.15.4 epoch from `c6_timesync_get_epoch_us()` enables fleet-wide simultaneous capture barrier (§2.8); PPDU type (frame bytes 18–19) enables automatic tier detection for C6 nodes |
|
||||
| ADR-115 (Home Assistant Integration) | **Consumer**: `CalibrationDeviationScore.drift_score` and `baseline_stale` are published on the WebSocket stream and picked up by the HA MQTT publisher as `sensor.wifi_baseline_drift` and `binary_sensor.wifi_baseline_stale` |
|
||||
| ADR-134 (First-Class CIR Support) | **Prerequisite improved**: `BaselineCalibration::reference_csi_vector()` replaces the on-the-fly quiescent-frame average described in ADR-134 §2.5; CIR ghost taps from the static environment are suppressed more reliably |
|
||||
|
||||
---
|
||||
|
||||
## 6. References
|
||||
|
||||
### Production Code
|
||||
|
||||
- `v2/crates/wifi-densepose-signal/src/ruvsense/field_model.rs` — `WelfordStats` struct reused; `FieldModelBuilder` to be simplified
|
||||
- `v2/crates/wifi-densepose-signal/src/ruvsense/cir.rs` — `CirEstimator::set_reference_csi()` call site
|
||||
- `v2/crates/wifi-densepose-signal/src/phase_sanitizer.rs` — runs before calibration recording
|
||||
- `v2/crates/wifi-densepose-signal/src/ruvsense/phase_align.rs` — runs before calibration recording
|
||||
- `v2/crates/wifi-densepose-signal/src/hardware_norm.rs` — cross-hardware amplitude normalisation; operates before baseline for `canonical_grid` resampling, after baseline for `z-score` normalisation
|
||||
- `v2/crates/wifi-densepose-signal/src/ruvsense/multistatic.rs` — primary consumer of `BaselineCalibration::subtract()`
|
||||
- `v2/crates/wifi-densepose-signal/src/motion.rs` — secondary consumer of `CalibrationDeviationScore.rms_amplitude_z`
|
||||
- `v2/crates/wifi-densepose-cli/src/lib.rs` — `Commands::Calibrate` variant to be added
|
||||
- `v2/crates/wifi-densepose-sensing-server/src/cli.rs` — `Args` struct for sensing-server CLI context
|
||||
- `firmware/esp32-csi-node/provision.py` — provisioning tool; `--push-nvs` integration point
|
||||
- `archive/v1/data/proof/verify.py` — deterministic proof chain; `calibration_baseline_check()` extension
|
||||
- `archive/v1/data/proof/expected_features.sha256` — hash entry `calibration_nvs_baseline_v1` to be added
|
||||
|
||||
### External Papers
|
||||
|
||||
- Welford, B.P. (1962). "Note on a Method for Calculating Corrected Sums of Squares and Products." *Technometrics*, 4(3), 419–420. — Online mean/variance algorithm used for both amplitude and (via sin/cos projection) phase statistics.
|
||||
- Mardia, K.V. & Jupp, P.E. (2000). *Directional Statistics*. Wiley. Ch. 2–3. — Circular variance estimator `1 − R̄` and its standard error; von Mises maximum-likelihood estimator for the concentration parameter.
|
||||
- Ma, Y. et al. (2023). "Optimal Preprocessing of WiFi CSI for Sensing Applications." *IEEE Transactions on Wireless Communications* (published 2024, arXiv:2307.12126). — Derives the theoretically optimal gain and phase error correction for commodity WiFi CSI; confirms that a per-subcarrier amplitude model reduces sensing noise by 40% over no-correction baseline. Validates the amplitude-mean-subtraction approach chosen here.
|
||||
- Kong, R. & Chen, H. (2025). "Domino: Dominant Path-based Compensation for Hardware Impairments in Modern WiFi Sensing." arXiv:2509.13807. IEEE ICASSP 2026. — Shows that operating on the dominant static CIR path as a reference achieves >2× accuracy over existing compensation methods for respiration monitoring. Validates the principle that a stable static reference (this ADR's baseline) materially improves sensing over no-reference methods.
|
||||
- IEEE Xplore document 10975920 (2025). "Experimental Evaluation of Long-Term Concept Drift and Its Mitigation in WiFi CSI Sensing." — Demonstrates that environmental loading causes accuracy degradation over hours/days in CSI sensing systems that rely on differential signals only; motivates the explicit operator-initiated recalibration model chosen in §2.6.
|
||||
|
|
@ -64,6 +64,7 @@ Statuses: **Proposed** (under discussion), **Accepted** (approved and/or impleme
|
|||
| [ADR-037](ADR-037-multi-person-pose-detection.md) | Multi-Person Pose Detection from Single ESP32 | Proposed |
|
||||
| [ADR-042](ADR-042-coherent-human-channel-imaging.md) | Coherent Human Channel Imaging (beyond CSI) | Proposed |
|
||||
| [ADR-134](ADR-134-csi-to-cir-time-domain-multipath.md) | First-Class Channel Impulse Response (CIR) Support | Proposed |
|
||||
| [ADR-135](ADR-135-empty-room-baseline-calibration.md) | Empty-Room Baseline Calibration (per-subcarrier Welford statistics) | Proposed |
|
||||
|
||||
### Machine learning and training
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,91 @@
|
|||
#!/usr/bin/env python3
|
||||
"""Synthetic CSI UDP emitter for testing the calibration CLI end-to-end.
|
||||
|
||||
Emits the same 0xC511_0001 frame format the ESP32-S3 firmware produces, so the
|
||||
`wifi-densepose calibrate` CLI can be exercised without a live ESP32 in the
|
||||
loop. Generates HT20 frames (52 active subcarriers, 1 antenna) at 20 Hz.
|
||||
"""
|
||||
import argparse
|
||||
import math
|
||||
import random
|
||||
import socket
|
||||
import struct
|
||||
import time
|
||||
|
||||
|
||||
MAGIC = 0xC511_0001
|
||||
|
||||
|
||||
def build_packet(node_id: int, seq: int, freq_mhz: int, rssi: int,
|
||||
amps: list[float], phases: list[float]) -> bytes:
|
||||
n_ant = 1
|
||||
n_sc = len(amps)
|
||||
header = struct.pack(
|
||||
"<I B B B B H I b b I",
|
||||
MAGIC,
|
||||
node_id,
|
||||
n_ant,
|
||||
n_sc,
|
||||
0, # reserved
|
||||
freq_mhz,
|
||||
seq,
|
||||
rssi,
|
||||
-95, # noise_floor
|
||||
0, # reserved/padding
|
||||
)
|
||||
iq = bytearray()
|
||||
for amp, phase in zip(amps, phases):
|
||||
i = max(-127, min(127, int(amp * math.cos(phase))))
|
||||
q = max(-127, min(127, int(amp * math.sin(phase))))
|
||||
iq.extend(struct.pack("bb", i, q))
|
||||
return bytes(header) + bytes(iq)
|
||||
|
||||
|
||||
def main() -> None:
|
||||
p = argparse.ArgumentParser()
|
||||
p.add_argument("--host", default="127.0.0.1")
|
||||
p.add_argument("--port", type=int, default=5005)
|
||||
p.add_argument("--duration-s", type=float, default=35.0,
|
||||
help="emit duration; default 35s so a 30s capture sees the full stream")
|
||||
p.add_argument("--rate-hz", type=float, default=20.0)
|
||||
p.add_argument("--n-sc", type=int, default=52)
|
||||
p.add_argument("--motion-after-s", type=float, default=-1.0,
|
||||
help="if >=0, inject amplitude jitter after this many seconds")
|
||||
args = p.parse_args()
|
||||
|
||||
random.seed(42)
|
||||
base_amps = [40.0 + 10.0 * math.cos(k * 0.2) for k in range(args.n_sc)]
|
||||
base_phases = [0.5 * math.sin(k * 0.3) for k in range(args.n_sc)]
|
||||
|
||||
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
|
||||
period = 1.0 / args.rate_hz
|
||||
started = time.time()
|
||||
seq = 0
|
||||
print(f"emitting CSI to {args.host}:{args.port} at {args.rate_hz} Hz, "
|
||||
f"{args.n_sc} sc/frame, duration {args.duration_s}s", flush=True)
|
||||
|
||||
while True:
|
||||
elapsed = time.time() - started
|
||||
if elapsed >= args.duration_s:
|
||||
break
|
||||
amps = list(base_amps)
|
||||
phases = list(base_phases)
|
||||
# Mild stationary jitter (~0.5 amplitude units RMS)
|
||||
for k in range(args.n_sc):
|
||||
amps[k] += random.gauss(0.0, 0.5)
|
||||
phases[k] += random.gauss(0.0, 0.01)
|
||||
if args.motion_after_s >= 0 and elapsed >= args.motion_after_s:
|
||||
for k in range(args.n_sc):
|
||||
amps[k] += random.gauss(0.0, 8.0)
|
||||
phases[k] += random.gauss(0.0, 0.3)
|
||||
pkt = build_packet(node_id=42, seq=seq, freq_mhz=2412, rssi=-55,
|
||||
amps=amps, phases=phases)
|
||||
sock.sendto(pkt, (args.host, args.port))
|
||||
seq += 1
|
||||
time.sleep(period)
|
||||
|
||||
print(f"emitted {seq} frames", flush=True)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
|
|
@ -0,0 +1,51 @@
|
|||
#!/usr/bin/env bash
|
||||
# verify-calibration-proof.sh — calibration deterministic proof verification (ADR-135)
|
||||
#
|
||||
# Builds the calibration_proof_runner Rust binary, computes the canonical SHA-256
|
||||
# hash of the CalibrationRecorder's output on the synthetic reference signal
|
||||
# (xorshift32 seed=42, HT20, 600 stationary frames), and compares it against
|
||||
# the committed expected_calibration_features.sha256.
|
||||
#
|
||||
# Usage:
|
||||
# bash scripts/verify-calibration-proof.sh
|
||||
#
|
||||
# Exit codes:
|
||||
# 0 — VERDICT: PASS (hash matches)
|
||||
# 1 — VERDICT: FAIL (hash mismatch or build error)
|
||||
# 2 — BLOCKED (calibration module not yet implemented — placeholder hash detected)
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
cd "$(git rev-parse --show-toplevel)"
|
||||
|
||||
HASH_FILE="archive/v1/data/proof/expected_calibration_features.sha256"
|
||||
|
||||
# Check for placeholder — module not yet implemented
|
||||
if grep -q "PLACEHOLDER_REGENERATE" "$HASH_FILE" 2>/dev/null; then
|
||||
echo "BLOCKED: calibration proof hash is a placeholder."
|
||||
echo "The calibration module (ADR-135) is not yet implemented."
|
||||
echo ""
|
||||
echo "After the implementation lands, regenerate the hash with:"
|
||||
echo " cd v2 && cargo run -p wifi-densepose-signal --bin calibration_proof_runner \\"
|
||||
echo " --release --no-default-features -- --generate-hash \\"
|
||||
echo " > ../archive/v1/data/proof/expected_calibration_features.sha256"
|
||||
exit 2
|
||||
fi
|
||||
|
||||
echo "Building calibration_proof_runner..."
|
||||
cargo build -p wifi-densepose-signal --bin calibration_proof_runner --release --no-default-features \
|
||||
--manifest-path v2/Cargo.toml
|
||||
|
||||
echo "Computing calibration hash..."
|
||||
ACTUAL="$(./v2/target/release/calibration_proof_runner --generate-hash)"
|
||||
EXPECTED="$(awk '{print $1; exit}' "$HASH_FILE")"
|
||||
|
||||
if [ "$ACTUAL" = "$EXPECTED" ]; then
|
||||
echo "VERDICT: PASS (calibration hash matches)"
|
||||
exit 0
|
||||
else
|
||||
echo "VERDICT: FAIL"
|
||||
echo "expected: $EXPECTED"
|
||||
echo "actual: $ACTUAL"
|
||||
exit 1
|
||||
fi
|
||||
|
|
@ -10589,6 +10589,8 @@ dependencies = [
|
|||
"console 0.16.3",
|
||||
"csv",
|
||||
"indicatif",
|
||||
"ndarray 0.17.2",
|
||||
"num-complex",
|
||||
"predicates",
|
||||
"serde",
|
||||
"serde_json",
|
||||
|
|
@ -10599,7 +10601,9 @@ dependencies = [
|
|||
"tracing",
|
||||
"tracing-subscriber",
|
||||
"uuid",
|
||||
"wifi-densepose-core",
|
||||
"wifi-densepose-mat",
|
||||
"wifi-densepose-signal",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
|
|
|
|||
|
|
@ -22,6 +22,12 @@ mat = []
|
|||
[dependencies]
|
||||
# Internal crates
|
||||
wifi-densepose-mat = { version = "0.3.0", path = "../wifi-densepose-mat" }
|
||||
wifi-densepose-signal = { version = "0.3.1", path = "../wifi-densepose-signal", default-features = false }
|
||||
wifi-densepose-core = { version = "0.3.0", path = "../wifi-densepose-core" }
|
||||
|
||||
# Linear algebra / complex numbers (used by calibrate.rs to build CsiFrame)
|
||||
ndarray = { workspace = true }
|
||||
num-complex = { workspace = true }
|
||||
|
||||
# CLI framework
|
||||
clap = { version = "4.4", features = ["derive", "env", "cargo"] }
|
||||
|
|
|
|||
|
|
@ -0,0 +1,443 @@
|
|||
//! `wifi-densepose calibrate` — empty-room baseline calibration subcommand.
|
||||
//!
|
||||
//! Reads CSI frames from a UDP socket (ESP32 0xC511_0001 wire format), feeds
|
||||
//! them through [`wifi_densepose_signal::CalibrationRecorder`], prints a
|
||||
//! real-time deviation banner (ADR-135 §risk 1), and serialises the finished
|
||||
//! [`wifi_densepose_signal::BaselineCalibration`] to disk in the compact
|
||||
//! little-endian binary format defined in ADR-135 §2.4.
|
||||
//!
|
||||
//! # Wire format parsed here (option b — local parser, no cross-crate dep)
|
||||
//!
|
||||
//! Offset Size Field
|
||||
//! ────── ──── ─────────────────────────────────────────────────────────────
|
||||
//! 0 4 Magic: 0xC511_0001 (LE u32)
|
||||
//! 4 1 node_id (u8)
|
||||
//! 5 1 n_antennas (u8)
|
||||
//! 6 1 n_subcarriers (u8)
|
||||
//! 7 1 (reserved)
|
||||
//! 8 2 freq_mhz (LE u16)
|
||||
//! 10 4 sequence (LE u32)
|
||||
//! 14 1 rssi (i8)
|
||||
//! 15 1 noise_floor (i8)
|
||||
//! 16 4 (reserved / padding)
|
||||
//! 20 2 × n_antennas × n_subcarriers IQ pairs: i_val (i8), q_val (i8)
|
||||
//!
|
||||
//! This parser mirrors `parse_esp32_frame` in
|
||||
//! `wifi-densepose-sensing-server/src/csi.rs` exactly (same magic, same layout).
|
||||
|
||||
use anyhow::{bail, Result};
|
||||
use clap::Args;
|
||||
use ndarray::Array2;
|
||||
use num_complex::Complex64;
|
||||
use std::time::{Duration, Instant};
|
||||
use tokio::net::UdpSocket;
|
||||
use wifi_densepose_core::types::{
|
||||
AntennaConfig, CsiFrame, CsiMetadata, DeviceId, FrequencyBand, Timestamp,
|
||||
};
|
||||
use wifi_densepose_signal::{
|
||||
BaselineCalibration, CalibrationConfig, CalibrationDeviationScore, CalibrationRecorder,
|
||||
};
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Arguments
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Arguments for the `calibrate` subcommand.
|
||||
#[derive(Args, Debug, Clone)]
|
||||
pub struct CalibrateArgs {
|
||||
/// UDP port to listen on for CSI frames from the ESP32.
|
||||
/// Must match the target-port written into NVS by provision.py (default 5005).
|
||||
#[arg(long, default_value_t = 5005)]
|
||||
pub udp_port: u16,
|
||||
|
||||
/// Bind address for the UDP socket.
|
||||
/// Default 0.0.0.0 receives from any device on the LAN.
|
||||
#[arg(long, default_value = "0.0.0.0")]
|
||||
pub bind: String,
|
||||
|
||||
/// Calibration duration in seconds.
|
||||
/// ADR-135 default is 30 s at 20 Hz = 600 frames.
|
||||
/// Minimum 10; values above 300 emit a warning.
|
||||
#[arg(long, default_value_t = 30)]
|
||||
pub duration_s: u32,
|
||||
|
||||
/// Output path for the binary baseline file (ADR-135 §2.4 format).
|
||||
#[arg(long, default_value = "./baseline.bin")]
|
||||
pub output: String,
|
||||
|
||||
/// PHY tier matching the ESP32 configuration.
|
||||
/// Valid: ht20 / ht40 / he20 / he40.
|
||||
#[arg(long, default_value = "ht20")]
|
||||
pub tier: String,
|
||||
|
||||
/// Print a deviation banner to stderr every N frames during capture.
|
||||
/// 0 disables banners. Default 20 = once per second at 20 Hz.
|
||||
#[arg(long, default_value_t = 20)]
|
||||
pub banner_every: u32,
|
||||
|
||||
/// Abort if the per-frame amplitude z-score median exceeds this value
|
||||
/// for 20 consecutive banner intervals. 0.0 disables the abort guard.
|
||||
#[arg(long, default_value_t = 2.0)]
|
||||
pub abort_z_threshold: f32,
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Constants
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Maximum UDP receive buffer. HT20 CSI frame is well under 1 500 bytes.
|
||||
const RECV_BUF: usize = 2048;
|
||||
|
||||
/// Number of banner intervals in the high-z abort sliding window.
|
||||
const ABORT_WINDOW_INTERVALS: u32 = 20;
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public entry point
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Execute the `calibrate` subcommand (async).
|
||||
pub async fn execute(args: CalibrateArgs) -> Result<()> {
|
||||
validate_args(&args)?;
|
||||
|
||||
let config = tier_config(&args.tier);
|
||||
let target_frames = config.min_frames as usize;
|
||||
|
||||
let addr = format!("{}:{}", args.bind, args.udp_port);
|
||||
let socket = UdpSocket::bind(&addr).await
|
||||
.map_err(|e| anyhow::anyhow!("cannot bind UDP socket on {addr}: {e}"))?;
|
||||
|
||||
eprintln!("[calibrate] listening on udp://{addr}");
|
||||
eprintln!(
|
||||
"[calibrate] capturing {} frames (~{} s, tier={}) — ensure room is empty",
|
||||
target_frames, args.duration_s, args.tier
|
||||
);
|
||||
|
||||
let mut recorder = CalibrationRecorder::new(config);
|
||||
let mut buf = vec![0u8; RECV_BUF];
|
||||
let mut high_z_count: u32 = 0;
|
||||
let deadline = Instant::now() + Duration::from_secs(args.duration_s as u64);
|
||||
|
||||
loop {
|
||||
let remaining = deadline.saturating_duration_since(Instant::now());
|
||||
if remaining.is_zero() {
|
||||
break;
|
||||
}
|
||||
|
||||
let timeout = remaining.min(Duration::from_millis(500));
|
||||
let recv = tokio::time::timeout(timeout, socket.recv(&mut buf)).await;
|
||||
|
||||
let n = match recv {
|
||||
Ok(Ok(n)) => n,
|
||||
Ok(Err(e)) => { eprintln!("[calibrate] recv error: {e}"); continue; }
|
||||
Err(_) => continue, // timeout — recheck deadline
|
||||
};
|
||||
|
||||
let Some(csi_frame) = parse_csi_packet(&buf[..n], &args.tier) else {
|
||||
continue;
|
||||
};
|
||||
|
||||
let score: CalibrationDeviationScore = match recorder.record(&csi_frame) {
|
||||
Ok(s) => s,
|
||||
Err(e) => { eprintln!("[calibrate] WARN frame skipped: {e}"); continue; }
|
||||
};
|
||||
|
||||
let frames = recorder.frames_recorded() as usize;
|
||||
|
||||
if args.banner_every > 0 && (frames as u32) % args.banner_every == 0 {
|
||||
print_banner(frames, target_frames, &score);
|
||||
|
||||
if args.abort_z_threshold > 0.0 && score.amplitude_z_median > args.abort_z_threshold {
|
||||
high_z_count += 1;
|
||||
if high_z_count >= ABORT_WINDOW_INTERVALS {
|
||||
bail!(
|
||||
"aborted: amplitude_z_median={:.2} exceeded threshold={:.2} for {} \
|
||||
consecutive banner intervals — ensure the room is empty and retry",
|
||||
score.amplitude_z_median, args.abort_z_threshold, high_z_count
|
||||
);
|
||||
}
|
||||
} else {
|
||||
high_z_count = 0;
|
||||
}
|
||||
}
|
||||
|
||||
if frames >= target_frames {
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
finalise_and_save(recorder, &args.output)
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Banner printer
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn print_banner(frames: usize, target: usize, score: &CalibrationDeviationScore) {
|
||||
let motion_str = if score.motion_flagged {
|
||||
"YES \u{2190} operator should be still"
|
||||
} else {
|
||||
"no"
|
||||
};
|
||||
eprintln!(
|
||||
"[calibrate] {}/{} frames | z_med={:.2} z_max={:.2} | motion: {}",
|
||||
frames, target, score.amplitude_z_median, score.amplitude_z_max, motion_str
|
||||
);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Finalise + persist
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn finalise_and_save(recorder: CalibrationRecorder, output: &str) -> Result<()> {
|
||||
let frames = recorder.frames_recorded();
|
||||
eprintln!("[calibrate] finalising baseline from {frames} frames…");
|
||||
|
||||
let baseline: BaselineCalibration = recorder
|
||||
.finalize()
|
||||
.map_err(|e| anyhow::anyhow!("calibration failed: {e}"))?;
|
||||
|
||||
let bytes = baseline.to_bytes();
|
||||
std::fs::write(output, &bytes)
|
||||
.map_err(|e| anyhow::anyhow!("cannot write {output}: {e}"))?;
|
||||
|
||||
eprintln!(
|
||||
"[calibrate] baseline saved to {output} ({} bytes)",
|
||||
bytes.len()
|
||||
);
|
||||
eprintln!(
|
||||
"[calibrate] summary: frames={} tier={:?} subcarriers={}",
|
||||
baseline.frame_count,
|
||||
baseline.tier,
|
||||
baseline.subcarriers.len(),
|
||||
);
|
||||
Ok(())
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Tier helper
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn tier_config(tier: &str) -> CalibrationConfig {
|
||||
match tier.to_ascii_lowercase().as_str() {
|
||||
"ht40" => CalibrationConfig::ht40(),
|
||||
"he20" => CalibrationConfig::he20(),
|
||||
"he40" => CalibrationConfig::he40(),
|
||||
_ => CalibrationConfig::ht20(), // ht20 or unknown → safe default
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Local UDP packet parser (option b)
|
||||
//
|
||||
// Mirrors parse_esp32_frame in wifi-densepose-sensing-server/src/csi.rs.
|
||||
// Magic 0xC511_0001, 20-byte header, IQ bytes follow.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Parse a single UDP datagram and return a `CsiFrame` ready for
|
||||
/// `CalibrationRecorder::record()`. Returns `None` on any parse failure.
|
||||
fn parse_csi_packet(buf: &[u8], tier: &str) -> Option<CsiFrame> {
|
||||
if buf.len() < 20 {
|
||||
return None;
|
||||
}
|
||||
let magic = u32::from_le_bytes([buf[0], buf[1], buf[2], buf[3]]);
|
||||
if magic != 0xC511_0001 {
|
||||
return None;
|
||||
}
|
||||
|
||||
let node_id = buf[4];
|
||||
let n_antennas = buf[5] as usize;
|
||||
let n_subcarriers = buf[6] as usize;
|
||||
let freq_mhz = u16::from_le_bytes([buf[8], buf[9]]);
|
||||
let _sequence = u32::from_le_bytes([buf[10], buf[11], buf[12], buf[13]]);
|
||||
let rssi = buf[14] as i8;
|
||||
let noise_floor = buf[15] as i8;
|
||||
|
||||
let n_pairs = n_antennas * n_subcarriers;
|
||||
let iq_start = 20usize;
|
||||
if buf.len() < iq_start + n_pairs * 2 {
|
||||
return None;
|
||||
}
|
||||
|
||||
// Build an ndarray Array2<Complex64> shaped [n_antennas, n_subcarriers].
|
||||
let mut data = Array2::<Complex64>::zeros((n_antennas.max(1), n_subcarriers.max(1)));
|
||||
for s in 0..n_antennas {
|
||||
for k in 0..n_subcarriers {
|
||||
let idx = s * n_subcarriers + k;
|
||||
let i_val = buf[iq_start + idx * 2] as i8 as f64;
|
||||
let q_val = buf[iq_start + idx * 2 + 1] as i8 as f64;
|
||||
data[[s, k]] = Complex64::new(i_val, q_val);
|
||||
}
|
||||
}
|
||||
|
||||
let band = if freq_mhz >= 5000 {
|
||||
FrequencyBand::Band5GHz
|
||||
} else {
|
||||
FrequencyBand::Band2_4GHz
|
||||
};
|
||||
let bw = tier_to_bw_mhz(tier);
|
||||
|
||||
let mut meta = CsiMetadata::new(
|
||||
DeviceId::new(format!("esp32-node{}", node_id)),
|
||||
band,
|
||||
freq_mhz_to_channel(freq_mhz),
|
||||
);
|
||||
meta.bandwidth_mhz = bw;
|
||||
meta.rssi_dbm = rssi;
|
||||
meta.noise_floor_dbm = noise_floor;
|
||||
meta.antenna_config = AntennaConfig {
|
||||
tx_antennas: 1,
|
||||
rx_antennas: n_antennas as u8,
|
||||
spacing_mm: None,
|
||||
};
|
||||
meta.timestamp = Timestamp::now();
|
||||
|
||||
Some(CsiFrame::new(meta, data))
|
||||
}
|
||||
|
||||
/// Map a tier string to a bandwidth in MHz.
|
||||
fn tier_to_bw_mhz(tier: &str) -> u16 {
|
||||
match tier.to_ascii_lowercase().as_str() {
|
||||
"ht40" | "he40" => 40,
|
||||
_ => 20,
|
||||
}
|
||||
}
|
||||
|
||||
/// Rough 802.11 channel from centre frequency.
|
||||
fn freq_mhz_to_channel(freq_mhz: u16) -> u8 {
|
||||
// 2.4 GHz: ch = (freq - 2407) / 5
|
||||
if freq_mhz < 3000 {
|
||||
((freq_mhz.saturating_sub(2407)) / 5) as u8
|
||||
} else {
|
||||
// 5 GHz: ch = (freq - 5000) / 5
|
||||
((freq_mhz.saturating_sub(5000)) / 5) as u8
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Input validation
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn validate_args(args: &CalibrateArgs) -> Result<()> {
|
||||
if args.duration_s < 10 {
|
||||
bail!(
|
||||
"--duration-s must be at least 10 s (got {}). \
|
||||
Fewer frames produce unreliable phase-concentration estimates (ADR-135 §2.3).",
|
||||
args.duration_s
|
||||
);
|
||||
}
|
||||
if args.duration_s > 300 {
|
||||
eprintln!(
|
||||
"[calibrate] WARN: --duration-s={} exceeds 300 s; this is unusual.",
|
||||
args.duration_s
|
||||
);
|
||||
}
|
||||
let valid = ["ht20", "ht40", "he20", "he40"];
|
||||
if !valid.contains(&args.tier.to_ascii_lowercase().as_str()) {
|
||||
bail!(
|
||||
"--tier must be one of {:?} (got {:?})",
|
||||
valid, args.tier
|
||||
);
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Unit tests
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_validate_args_min_duration() {
|
||||
let mut args = default_args();
|
||||
args.duration_s = 5;
|
||||
assert!(validate_args(&args).is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_validate_args_ok() {
|
||||
let args = default_args();
|
||||
assert!(validate_args(&args).is_ok());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_validate_args_bad_tier() {
|
||||
let mut args = default_args();
|
||||
args.tier = "ht80".into();
|
||||
assert!(validate_args(&args).is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_tier_config_ht20() {
|
||||
let cfg = tier_config("ht20");
|
||||
assert_eq!(cfg.num_active, 52);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_tier_config_ht40() {
|
||||
let cfg = tier_config("ht40");
|
||||
assert_eq!(cfg.num_active, 114);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_tier_config_he20() {
|
||||
let cfg = tier_config("he20");
|
||||
assert_eq!(cfg.num_active, 242);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_parse_csi_packet_bad_magic() {
|
||||
let buf = vec![0u8; 32];
|
||||
assert!(parse_csi_packet(&buf, "ht20").is_none());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_parse_csi_packet_too_short() {
|
||||
let buf = vec![0u8; 10];
|
||||
assert!(parse_csi_packet(&buf, "ht20").is_none());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_parse_csi_packet_valid() {
|
||||
let mut buf = vec![0u8; 24]; // 20-byte header + 2 IQ pairs (1 antenna, 2 subcarriers)
|
||||
// Magic 0xC511_0001 LE
|
||||
buf[0] = 0x01; buf[1] = 0x00; buf[2] = 0x11; buf[3] = 0xC5;
|
||||
buf[5] = 1; // n_antennas
|
||||
buf[6] = 2; // n_subcarriers
|
||||
// freq_mhz = 2437 (channel 6)
|
||||
buf[8] = 0x85; buf[9] = 0x09;
|
||||
// IQ pairs at offset 20: (10, 20), (−5, 15)
|
||||
buf[20] = 10i8 as u8; buf[21] = 20i8 as u8;
|
||||
buf[22] = (-5i8) as u8; buf[23] = 15i8 as u8;
|
||||
|
||||
let frame = parse_csi_packet(&buf, "ht20");
|
||||
assert!(frame.is_some());
|
||||
let f = frame.unwrap();
|
||||
assert_eq!(f.num_spatial_streams(), 1);
|
||||
assert_eq!(f.num_subcarriers(), 2);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_freq_to_channel_24ghz() {
|
||||
assert_eq!(freq_mhz_to_channel(2437), 6);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_freq_to_channel_5ghz() {
|
||||
assert_eq!(freq_mhz_to_channel(5180), 36);
|
||||
}
|
||||
|
||||
fn default_args() -> CalibrateArgs {
|
||||
CalibrateArgs {
|
||||
udp_port: 5005,
|
||||
bind: "0.0.0.0".into(),
|
||||
duration_s: 30,
|
||||
output: "./baseline.bin".into(),
|
||||
tier: "ht20".into(),
|
||||
banner_every: 20,
|
||||
abort_z_threshold: 2.0,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -26,6 +26,7 @@
|
|||
|
||||
use clap::{Parser, Subcommand};
|
||||
|
||||
pub mod calibrate;
|
||||
pub mod mat;
|
||||
|
||||
/// WiFi-DensePose Command Line Interface
|
||||
|
|
@ -46,6 +47,11 @@ pub struct Cli {
|
|||
/// Top-level commands
|
||||
#[derive(Subcommand, Debug)]
|
||||
pub enum Commands {
|
||||
/// Empty-room baseline calibration (ADR-135).
|
||||
/// Captures CSI frames via UDP and saves a per-subcarrier statistical
|
||||
/// baseline used for real-time motion z-scoring and CIR reference.
|
||||
Calibrate(calibrate::CalibrateArgs),
|
||||
|
||||
/// Mass Casualty Assessment Tool commands
|
||||
#[command(subcommand)]
|
||||
Mat(mat::MatCommand),
|
||||
|
|
|
|||
|
|
@ -18,6 +18,9 @@ async fn main() -> anyhow::Result<()> {
|
|||
let cli = Cli::parse();
|
||||
|
||||
match cli.command {
|
||||
Commands::Calibrate(args) => {
|
||||
wifi_densepose_cli::calibrate::execute(args).await?;
|
||||
}
|
||||
Commands::Mat(mat_cmd) => {
|
||||
wifi_densepose_cli::mat::execute(mat_cmd).await?;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -79,3 +79,13 @@ path = "src/bin/cir_proof_runner.rs"
|
|||
# implementation agent; this addition is purely additive.
|
||||
[dependencies.sha2]
|
||||
workspace = true
|
||||
|
||||
## ADR-135: calibration module throughput benchmarks
|
||||
[[bench]]
|
||||
name = "calibration_bench"
|
||||
harness = false
|
||||
|
||||
# ADR-135: calibration deterministic proof runner binary.
|
||||
[[bin]]
|
||||
name = "calibration_proof_runner"
|
||||
path = "src/bin/calibration_proof_runner.rs"
|
||||
|
|
|
|||
|
|
@ -0,0 +1,246 @@
|
|||
//! Criterion benchmarks for the empty-room baseline calibration module (ADR-135).
|
||||
//!
|
||||
//! Measures per-call throughput of CalibrationRecorder and BaselineCalibration
|
||||
//! across HT20 (K=52), HT40 (K=114), HE20 (K=242), and HE40 (K=484).
|
||||
//!
|
||||
//! Run (compile-only — no execution):
|
||||
//! cargo bench -p wifi-densepose-signal --no-default-features --bench calibration_bench --no-run
|
||||
//!
|
||||
//! Run to completion (generates HTML in target/criterion/):
|
||||
//! cargo bench -p wifi-densepose-signal --no-default-features --bench calibration_bench
|
||||
|
||||
use std::f64::consts::PI;
|
||||
|
||||
use criterion::{black_box, criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};
|
||||
use ndarray::Array2;
|
||||
use num_complex::Complex64;
|
||||
use wifi_densepose_core::types::{AntennaConfig, CsiFrame, CsiMetadata, DeviceId, FrequencyBand};
|
||||
use wifi_densepose_signal::calibration::{
|
||||
BaselineCalibration, CalibrationConfig, CalibrationRecorder,
|
||||
};
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Deterministic PRNG (xorshift32, seed=42) — duplicated locally.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
struct Rng(u32);
|
||||
|
||||
impl Rng {
|
||||
fn new(seed: u32) -> Self {
|
||||
assert_ne!(seed, 0);
|
||||
Self(seed)
|
||||
}
|
||||
fn next_u32(&mut self) -> u32 {
|
||||
let mut x = self.0;
|
||||
x ^= x << 13;
|
||||
x ^= x >> 17;
|
||||
x ^= x << 5;
|
||||
self.0 = x;
|
||||
x
|
||||
}
|
||||
fn next_f64(&mut self) -> f64 {
|
||||
(self.next_u32() as f64 + 1.0) / (u32::MAX as f64 + 2.0)
|
||||
}
|
||||
fn next_normal(&mut self) -> f64 {
|
||||
let u1 = self.next_f64();
|
||||
let u2 = self.next_f64();
|
||||
(-2.0 * u1.ln()).sqrt() * (2.0 * PI * u2).cos()
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Tier specification table
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
struct TierSpec {
|
||||
label: &'static str,
|
||||
n_active: usize,
|
||||
bandwidth_mhz: u16,
|
||||
config: CalibrationConfig,
|
||||
}
|
||||
|
||||
fn tiers() -> Vec<TierSpec> {
|
||||
vec![
|
||||
TierSpec { label: "ht20", n_active: 52, bandwidth_mhz: 20, config: CalibrationConfig::ht20() },
|
||||
TierSpec { label: "ht40", n_active: 114, bandwidth_mhz: 40, config: CalibrationConfig::ht40() },
|
||||
TierSpec { label: "he20", n_active: 242, bandwidth_mhz: 20, config: CalibrationConfig::he20() },
|
||||
TierSpec { label: "he40", n_active: 484, bandwidth_mhz: 40, config: CalibrationConfig::he40() },
|
||||
]
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Synthetic CSI frame builder (stationary, seed=42)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn make_frame(n_active: usize, bandwidth_mhz: u16, rng: &mut Rng) -> CsiFrame {
|
||||
let noise_std = 0.01_f64;
|
||||
let mut data = Array2::<Complex64>::zeros((1, n_active));
|
||||
for k in 0..n_active {
|
||||
let amp = 0.3 + 0.7 * (k as f64 * PI / n_active as f64).sin().abs();
|
||||
let phase = (k as f64 * 0.1).rem_euclid(2.0 * PI) - PI;
|
||||
let re = amp * phase.cos() + noise_std * rng.next_normal();
|
||||
let im = amp * phase.sin() + noise_std * rng.next_normal();
|
||||
data[(0, k)] = Complex64::new(re, im);
|
||||
}
|
||||
let mut meta = CsiMetadata::new(DeviceId::new("bench"), FrequencyBand::Band2_4GHz, 6);
|
||||
meta.bandwidth_mhz = bandwidth_mhz;
|
||||
meta.antenna_config = AntennaConfig::new(1, 1);
|
||||
CsiFrame::new(meta, data)
|
||||
}
|
||||
|
||||
/// Build a `CalibrationRecorder` that has already absorbed 600 frames.
|
||||
fn pre_loaded_recorder(spec: &TierSpec) -> CalibrationRecorder {
|
||||
let mut rng = Rng::new(42);
|
||||
let mut recorder = CalibrationRecorder::new(spec.config.clone());
|
||||
for _ in 0..600 {
|
||||
let frame = make_frame(spec.n_active, spec.bandwidth_mhz, &mut rng);
|
||||
recorder.record(&frame).expect("record should succeed in bench setup");
|
||||
}
|
||||
recorder
|
||||
}
|
||||
|
||||
/// Build a finalised `BaselineCalibration` for deviation and to_bytes benches.
|
||||
fn finalised_baseline(spec: &TierSpec) -> BaselineCalibration {
|
||||
pre_loaded_recorder(spec)
|
||||
.finalize()
|
||||
.expect("finalize should succeed in bench setup")
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Bench 1: bench_recorder_record/<tier> — single record() call (hot path)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn bench_recorder_record(c: &mut Criterion) {
|
||||
let mut group = c.benchmark_group("bench_recorder_record");
|
||||
for spec in tiers() {
|
||||
group.throughput(Throughput::Elements(spec.n_active as u64));
|
||||
let mut rng = Rng::new(42);
|
||||
let frame = make_frame(spec.n_active, spec.bandwidth_mhz, &mut rng);
|
||||
let mut recorder = CalibrationRecorder::new(spec.config.clone());
|
||||
|
||||
group.bench_with_input(
|
||||
BenchmarkId::from_parameter(spec.label),
|
||||
&frame,
|
||||
|b, f| {
|
||||
b.iter(|| {
|
||||
// Accumulate into a shared recorder — measures per-call cost of record().
|
||||
black_box(recorder.record(black_box(f)).ok())
|
||||
});
|
||||
},
|
||||
);
|
||||
}
|
||||
group.finish();
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Bench 2: bench_recorder_finalize/<tier> — finalize() from 600 pre-loaded frames
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn bench_recorder_finalize(c: &mut Criterion) {
|
||||
let mut group = c.benchmark_group("bench_recorder_finalize");
|
||||
for spec in tiers() {
|
||||
group.throughput(Throughput::Elements(spec.n_active as u64));
|
||||
|
||||
group.bench_function(BenchmarkId::from_parameter(spec.label), |b| {
|
||||
b.iter_with_setup(
|
||||
|| pre_loaded_recorder(&spec),
|
||||
|recorder| {
|
||||
black_box(recorder.finalize().ok())
|
||||
},
|
||||
);
|
||||
});
|
||||
}
|
||||
group.finish();
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Bench 3: bench_deviation/<tier> — deviation() on a single frame
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn bench_deviation(c: &mut Criterion) {
|
||||
let mut group = c.benchmark_group("bench_deviation");
|
||||
for spec in tiers() {
|
||||
group.throughput(Throughput::Elements(spec.n_active as u64));
|
||||
let baseline = finalised_baseline(&spec);
|
||||
let mut rng = Rng::new(42);
|
||||
let frame = make_frame(spec.n_active, spec.bandwidth_mhz, &mut rng);
|
||||
|
||||
group.bench_with_input(
|
||||
BenchmarkId::from_parameter(spec.label),
|
||||
&frame,
|
||||
|b, f| {
|
||||
b.iter(|| {
|
||||
black_box(baseline.deviation(black_box(f)).ok())
|
||||
});
|
||||
},
|
||||
);
|
||||
}
|
||||
group.finish();
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Bench 4: bench_record_600/<tier> — full 600-frame record session
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn bench_record_600(c: &mut Criterion) {
|
||||
let mut group = c.benchmark_group("bench_record_600");
|
||||
for spec in tiers() {
|
||||
group.throughput(Throughput::Elements(600 * spec.n_active as u64));
|
||||
|
||||
// Pre-build 600 frames to avoid contaminating bench with frame construction.
|
||||
let mut rng = Rng::new(42);
|
||||
let frames: Vec<CsiFrame> = (0..600)
|
||||
.map(|_| make_frame(spec.n_active, spec.bandwidth_mhz, &mut rng))
|
||||
.collect();
|
||||
|
||||
group.bench_with_input(
|
||||
BenchmarkId::from_parameter(spec.label),
|
||||
&frames,
|
||||
|b, fs| {
|
||||
b.iter_with_setup(
|
||||
|| CalibrationRecorder::new(spec.config.clone()),
|
||||
|mut recorder| {
|
||||
for f in fs {
|
||||
black_box(recorder.record(black_box(f)).ok());
|
||||
}
|
||||
black_box(recorder)
|
||||
},
|
||||
);
|
||||
},
|
||||
);
|
||||
}
|
||||
group.finish();
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Bench 5: bench_to_bytes/<tier> — serialisation cost (to_bytes)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn bench_to_bytes(c: &mut Criterion) {
|
||||
let mut group = c.benchmark_group("bench_to_bytes");
|
||||
for spec in tiers() {
|
||||
group.throughput(Throughput::Elements(spec.n_active as u64));
|
||||
let baseline = finalised_baseline(&spec);
|
||||
|
||||
group.bench_function(BenchmarkId::from_parameter(spec.label), |b| {
|
||||
b.iter(|| {
|
||||
black_box(baseline.to_bytes())
|
||||
});
|
||||
});
|
||||
}
|
||||
group.finish();
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Criterion harness
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
criterion_group!(
|
||||
benches,
|
||||
bench_recorder_record,
|
||||
bench_recorder_finalize,
|
||||
bench_deviation,
|
||||
bench_record_600,
|
||||
bench_to_bytes,
|
||||
);
|
||||
criterion_main!(benches);
|
||||
|
|
@ -0,0 +1,277 @@
|
|||
//! Calibration Deterministic Proof Runner (ADR-135)
|
||||
//!
|
||||
//! Verifies or generates the canonical SHA-256 hash of the CalibrationRecorder's
|
||||
//! deterministic output on a synthetic stationary channel (seed=42, HT20, 600 frames).
|
||||
//!
|
||||
//! Cross-platform portability lesson (from cir_proof_runner.rs, line 123):
|
||||
//! Raw f32 round-trips at high precision (1e-6) and magnitude-sort-then-truncate
|
||||
//! both break across libm implementations (glibc / MSVC / Apple) because sin/cos/sqrt
|
||||
//! differ by ~1e-7 — enough to flip a rounded integer or re-order near-tied values.
|
||||
//! The fix: serialise the full per-subcarrier profile in natural index order at
|
||||
//! coarse quantisation (1e-2 / 1e-4 / 1e-3). A 1% drift is invisible to the hash;
|
||||
//! a 10× algorithm change moves values by >1e-2 and breaks the hash.
|
||||
//! No sort, no truncation, no libm-sensitive comparison.
|
||||
//!
|
||||
//! Canonical form (per subcarrier k, 4 × u16 LE):
|
||||
//! [0] (amp_mean * 1e2).round() as u16
|
||||
//! [1] (amp_variance * 1e4).round() as u16
|
||||
//! [2] ((phase_mean + π) * 1e3).round() as u16 ← shifted so always non-negative
|
||||
//! [3] (phase_dispersion * 1e3).round() as u16
|
||||
//!
|
||||
//! Prefix: tier byte (0 = HT20), frame_count u64 LE.
|
||||
//! All subcarriers in natural index order; no sort.
|
||||
//!
|
||||
//! Usage:
|
||||
//! cargo run -p wifi-densepose-signal --bin calibration_proof_runner \
|
||||
//! --release --no-default-features -- --generate-hash
|
||||
//!
|
||||
//! cargo run -p wifi-densepose-signal --bin calibration_proof_runner \
|
||||
//! --release --no-default-features
|
||||
//! (compares against archive/v1/data/proof/expected_calibration_features.sha256)
|
||||
//!
|
||||
//! IMPORTANT: This binary cannot compile until CalibrationRecorder is implemented.
|
||||
//! While the implementation is in progress, a placeholder hash is committed in
|
||||
//! archive/v1/data/proof/expected_calibration_features.sha256. Regenerate with:
|
||||
//!
|
||||
//! cd v2 && cargo run -p wifi-densepose-signal --bin calibration_proof_runner \
|
||||
//! --release --no-default-features -- --generate-hash \
|
||||
//! > ../archive/v1/data/proof/expected_calibration_features.sha256
|
||||
|
||||
use std::env;
|
||||
use std::f32::consts::PI;
|
||||
use std::fs;
|
||||
use std::io::{self, Write};
|
||||
use std::path::PathBuf;
|
||||
|
||||
use ndarray::Array2;
|
||||
use num_complex::Complex64;
|
||||
use sha2::{Digest, Sha256};
|
||||
use wifi_densepose_core::types::{AntennaConfig, CsiFrame, CsiMetadata, DeviceId, FrequencyBand};
|
||||
use wifi_densepose_signal::calibration::{CalibrationConfig, CalibrationRecorder};
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Constants
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const N_ACTIVE: usize = 52; // HT20 active subcarriers
|
||||
const N_FRAMES: usize = 600; // 30 s × 20 Hz
|
||||
const TIER_BYTE: u8 = 0; // 0 = HT20
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Deterministic PRNG (xorshift32, seed=42) — duplicated locally.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
struct Rng(u32);
|
||||
|
||||
impl Rng {
|
||||
fn new(seed: u32) -> Self {
|
||||
assert_ne!(seed, 0, "xorshift seed must be non-zero");
|
||||
Self(seed)
|
||||
}
|
||||
fn next_u32(&mut self) -> u32 {
|
||||
let mut x = self.0;
|
||||
x ^= x << 13;
|
||||
x ^= x >> 17;
|
||||
x ^= x << 5;
|
||||
self.0 = x;
|
||||
x
|
||||
}
|
||||
fn next_normal(&mut self) -> f32 {
|
||||
let u1 = (self.next_u32() as f32 + 1.0) / (u32::MAX as f32 + 2.0);
|
||||
let u2 = (self.next_u32() as f32 + 1.0) / (u32::MAX as f32 + 2.0);
|
||||
let r = (-2.0 * u1.ln()).sqrt();
|
||||
let theta = 2.0 * PI * u2;
|
||||
r * theta.cos()
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Synthetic CSI frame generator — stationary channel, seed=42
|
||||
//
|
||||
// amp[k] = 0.3 + 0.7 * |sin(k * π / K)| (smooth across subcarriers)
|
||||
// phase[k] = (k * 0.1) mod 2π − π (slowly rotating)
|
||||
// AWGN at ~30 dB SNR added via Box-Muller.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn make_frame(rng: &mut Rng) -> CsiFrame {
|
||||
let n = N_ACTIVE;
|
||||
let noise_std = 0.01_f32;
|
||||
|
||||
let mut data = Array2::<Complex64>::zeros((1, n));
|
||||
for k in 0..n {
|
||||
let amp = 0.3 + 0.7 * (k as f32 * PI / n as f32).sin().abs();
|
||||
let phase = (k as f32 * 0.1).rem_euclid(2.0 * PI) - PI;
|
||||
let re = amp * phase.cos() + noise_std * rng.next_normal();
|
||||
let im = amp * phase.sin() + noise_std * rng.next_normal();
|
||||
data[(0, k)] = Complex64::new(re as f64, im as f64);
|
||||
}
|
||||
let mut meta =
|
||||
CsiMetadata::new(DeviceId::new("proof-runner"), FrequencyBand::Band2_4GHz, 6);
|
||||
meta.bandwidth_mhz = 20;
|
||||
meta.antenna_config = AntennaConfig::new(1, 1);
|
||||
CsiFrame::new(meta, data)
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Canonical, cross-platform-deterministic serialisation.
|
||||
//
|
||||
// Per ADR-135 proof spec and the cir_proof_runner.rs lesson (line 123):
|
||||
// coarse u16 quantisation, natural subcarrier order, no sort.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn serialise_baseline_canonical(
|
||||
subcarriers: &[wifi_densepose_signal::calibration::SubcarrierBaseline],
|
||||
frame_count: u64,
|
||||
) -> Vec<u8> {
|
||||
let k = subcarriers.len();
|
||||
// Header: tier byte + frame_count as u64 LE
|
||||
let mut out = Vec::with_capacity(1 + 8 + k * 8);
|
||||
out.push(TIER_BYTE);
|
||||
out.extend_from_slice(&frame_count.to_le_bytes());
|
||||
|
||||
for sc in subcarriers {
|
||||
// [0] amp_mean at 1e-2 resolution
|
||||
let amp_q = (sc.amp_mean * 1e2_f32)
|
||||
.round()
|
||||
.max(0.0)
|
||||
.min(u16::MAX as f32) as u16;
|
||||
out.extend_from_slice(&_q.to_le_bytes());
|
||||
|
||||
// [1] amp_variance at 1e-4 resolution
|
||||
let var_q = (sc.amp_variance * 1e4_f32)
|
||||
.round()
|
||||
.max(0.0)
|
||||
.min(u16::MAX as f32) as u16;
|
||||
out.extend_from_slice(&var_q.to_le_bytes());
|
||||
|
||||
// [2] phase_mean shifted by +π so it is non-negative, at 1e-3 resolution
|
||||
let phase_q = ((sc.phase_mean + PI) * 1e3_f32)
|
||||
.round()
|
||||
.max(0.0)
|
||||
.min(u16::MAX as f32) as u16;
|
||||
out.extend_from_slice(&phase_q.to_le_bytes());
|
||||
|
||||
// [3] phase_dispersion (von Mises 1−R̄, in [0,1]) at 1e-3 resolution
|
||||
let disp_q = (sc.phase_dispersion * 1e3_f32)
|
||||
.round()
|
||||
.max(0.0)
|
||||
.min(u16::MAX as f32) as u16;
|
||||
out.extend_from_slice(&disp_q.to_le_bytes());
|
||||
}
|
||||
|
||||
out
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Repo root discovery
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn repo_root() -> PathBuf {
|
||||
let cwd = env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
|
||||
let candidates = [
|
||||
cwd.clone(),
|
||||
cwd.join(".."),
|
||||
cwd.join("../.."),
|
||||
cwd.join("../../.."),
|
||||
];
|
||||
for candidate in &candidates {
|
||||
if candidate
|
||||
.join("archive/v1/data/proof/expected_calibration_features.sha256")
|
||||
.exists()
|
||||
|| candidate.join("archive/v1/data/proof/sample_csi_data.json").exists()
|
||||
{
|
||||
return candidate.canonicalize().unwrap_or(candidate.clone());
|
||||
}
|
||||
}
|
||||
cwd
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Main hash computation
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn compute_hash() -> String {
|
||||
let config = CalibrationConfig::ht20();
|
||||
let mut recorder = CalibrationRecorder::new(config);
|
||||
let mut rng = Rng::new(42);
|
||||
|
||||
for _ in 0..N_FRAMES {
|
||||
let frame = make_frame(&mut rng);
|
||||
recorder
|
||||
.record(&frame)
|
||||
.expect("record() must succeed for synthetic frames");
|
||||
}
|
||||
|
||||
let baseline = recorder
|
||||
.finalize()
|
||||
.expect("finalize() must succeed after 600 frames");
|
||||
|
||||
let payload = serialise_baseline_canonical(&baseline.subcarriers, baseline.frame_count);
|
||||
|
||||
let mut hasher = Sha256::new();
|
||||
hasher.update(&payload);
|
||||
format!("{:x}", hasher.finalize())
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Entry point
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn main() {
|
||||
let args: Vec<String> = env::args().collect();
|
||||
let generate_hash = args.iter().any(|a| a == "--generate-hash");
|
||||
|
||||
let hash = compute_hash();
|
||||
|
||||
if generate_hash {
|
||||
println!("{}", hash);
|
||||
return;
|
||||
}
|
||||
|
||||
// Compare against stored hash
|
||||
let root = repo_root();
|
||||
let hash_path = root.join("archive/v1/data/proof/expected_calibration_features.sha256");
|
||||
|
||||
if !hash_path.exists() {
|
||||
eprintln!(
|
||||
"ERROR: expected hash file not found at {}",
|
||||
hash_path.display()
|
||||
);
|
||||
eprintln!("Run with --generate-hash to create it.");
|
||||
std::process::exit(1);
|
||||
}
|
||||
|
||||
let expected_content = fs::read_to_string(&hash_path)
|
||||
.unwrap_or_else(|e| panic!("Cannot read {}: {}", hash_path.display(), e));
|
||||
|
||||
let expected = expected_content
|
||||
.split_whitespace()
|
||||
.find(|s| !s.starts_with('#'))
|
||||
.unwrap_or("")
|
||||
.to_owned();
|
||||
|
||||
if expected.starts_with("PLACEHOLDER") {
|
||||
eprintln!("BLOCKED: calibration proof hash is a placeholder.");
|
||||
eprintln!(
|
||||
"The calibration module (ADR-135) is not yet fully implemented. \
|
||||
After the implementation lands, regenerate:"
|
||||
);
|
||||
eprintln!(
|
||||
" cd v2 && cargo run -p wifi-densepose-signal --bin calibration_proof_runner \
|
||||
--release --no-default-features -- --generate-hash \
|
||||
> ../archive/v1/data/proof/expected_calibration_features.sha256"
|
||||
);
|
||||
std::process::exit(2);
|
||||
}
|
||||
|
||||
if hash == expected {
|
||||
println!("VERDICT: PASS (calibration hash matches)");
|
||||
std::process::exit(0);
|
||||
} else {
|
||||
eprintln!("VERDICT: FAIL");
|
||||
eprintln!("expected: {}", expected);
|
||||
eprintln!("actual: {}", hash);
|
||||
io::stderr().flush().ok();
|
||||
std::process::exit(1);
|
||||
}
|
||||
}
|
||||
|
|
@ -67,6 +67,13 @@ pub use phase_sanitizer::{
|
|||
pub use ruvsense::cir;
|
||||
pub use ruvsense::cir::{Cir, CirConfig, CirError, CirEstimator};
|
||||
|
||||
// ADR-135: Baseline calibration top-level re-exports
|
||||
pub use ruvsense::calibration;
|
||||
pub use ruvsense::calibration::{
|
||||
BaselineCalibration, CalibrationConfig, CalibrationDeviationScore, CalibrationError,
|
||||
CalibrationRecorder, PhyTier, SubcarrierBaseline,
|
||||
};
|
||||
|
||||
/// Library version
|
||||
pub const VERSION: &str = env!("CARGO_PKG_VERSION");
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,658 @@
|
|||
//! Empty-room baseline calibration (ADR-135).
|
||||
//!
|
||||
//! Captures per-subcarrier amplitude and circular-phase statistics from a
|
||||
//! quiescent (empty) room using Welford's online algorithm, then provides
|
||||
//! real-time deviation scoring and in-place baseline subtraction.
|
||||
//!
|
||||
//! # Pipeline position
|
||||
//!
|
||||
//! Raw CSI → `phase_sanitizer.rs` → `phase_align.rs`
|
||||
//! → `CalibrationRecorder::record()` (calibration mode)
|
||||
//! → `BaselineCalibration::subtract_in_place()` (runtime mode)
|
||||
//! → `CirEstimator::estimate()`
|
||||
//!
|
||||
//! # Binary format (to_bytes / from_bytes)
|
||||
//!
|
||||
//! 16-byte header (all little-endian):
|
||||
//! magic: u32 = 0xCA1B_0001
|
||||
//! version: u8 = 1
|
||||
//! tier: u8 (0=Ht20, 1=Ht40, 2=He20, 3=He40)
|
||||
//! reserved: u16 = 0
|
||||
//! captured_at_unix_s: i64
|
||||
//! Body:
|
||||
//! frame_count: u64
|
||||
//! num_subcarriers: u32
|
||||
//! for each subcarrier: amp_mean f32 LE, amp_variance f32 LE,
|
||||
//! phase_mean f32 LE, phase_dispersion f32 LE
|
||||
//!
|
||||
//! SHA-256-stable: all writes are LE, no float branching.
|
||||
|
||||
use num_complex::Complex32;
|
||||
use thiserror::Error;
|
||||
use wifi_densepose_core::types::CsiFrame;
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Constants
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const MAGIC: u32 = 0xCA1B_0001;
|
||||
const VERSION: u8 = 1;
|
||||
const HEADER_LEN: usize = 16; // magic(4) + version(1) + tier(1) + reserved(2) + unix_s(8)
|
||||
const SUBCARRIER_RECORD_LEN: usize = 16; // 4 × f32
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// PHY tier
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// 802.11 PHY tier identifies the subcarrier layout.
|
||||
/// A mismatch between a stored baseline and a live frame triggers
|
||||
/// `CalibrationError::TierMismatch` (ADR-135 §risk 2).
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum PhyTier {
|
||||
/// 802.11n HT20: 64-FFT, 52 active subcarriers.
|
||||
Ht20,
|
||||
/// 802.11n HT40: 128-FFT, 114 active subcarriers.
|
||||
Ht40,
|
||||
/// 802.11ax HE20: 256-FFT, 242 active subcarriers.
|
||||
He20,
|
||||
/// 802.11ax HE40: 512-FFT, 484 active subcarriers.
|
||||
He40,
|
||||
}
|
||||
|
||||
impl PhyTier {
|
||||
fn to_u8(self) -> u8 {
|
||||
match self {
|
||||
PhyTier::Ht20 => 0,
|
||||
PhyTier::Ht40 => 1,
|
||||
PhyTier::He20 => 2,
|
||||
PhyTier::He40 => 3,
|
||||
}
|
||||
}
|
||||
|
||||
fn from_u8(v: u8) -> Option<Self> {
|
||||
match v {
|
||||
0 => Some(PhyTier::Ht20),
|
||||
1 => Some(PhyTier::Ht40),
|
||||
2 => Some(PhyTier::He20),
|
||||
3 => Some(PhyTier::He40),
|
||||
_ => None,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Configuration
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Calibration capture configuration.
|
||||
#[derive(Debug, Clone, Copy)]
|
||||
pub struct CalibrationConfig {
|
||||
/// PHY tier determines expected subcarrier count.
|
||||
pub tier: PhyTier,
|
||||
/// Total OFDM FFT bins (e.g. 64 HT20, 128 HT40, 256 HE20, 512 HE40).
|
||||
pub num_subcarriers: usize,
|
||||
/// Active (non-guard, non-DC) tones (52, 114, 242, 484).
|
||||
pub num_active: usize,
|
||||
/// Minimum frames before `finalize()` succeeds (default 600).
|
||||
pub min_frames: u32,
|
||||
/// Von Mises dispersion warn threshold — warn if any subcarrier exceeds this
|
||||
/// during recording (ADR-135 §risk 1). Default 0.3.
|
||||
pub max_phase_variance: f32,
|
||||
}
|
||||
|
||||
impl CalibrationConfig {
|
||||
/// HT20 defaults: 64 FFT, 52 active, 600 frame minimum (30 s @ 20 Hz).
|
||||
pub fn ht20() -> Self {
|
||||
Self { tier: PhyTier::Ht20, num_subcarriers: 64, num_active: 52, min_frames: 600, max_phase_variance: 0.3 }
|
||||
}
|
||||
/// HT40 defaults: 128 FFT, 114 active.
|
||||
pub fn ht40() -> Self {
|
||||
Self { tier: PhyTier::Ht40, num_subcarriers: 128, num_active: 114, min_frames: 600, max_phase_variance: 0.3 }
|
||||
}
|
||||
/// HE20 defaults: 256 FFT, 242 active.
|
||||
pub fn he20() -> Self {
|
||||
Self { tier: PhyTier::He20, num_subcarriers: 256, num_active: 242, min_frames: 600, max_phase_variance: 0.3 }
|
||||
}
|
||||
/// HE40 defaults: 512 FFT, 484 active.
|
||||
pub fn he40() -> Self {
|
||||
Self { tier: PhyTier::He40, num_subcarriers: 512, num_active: 484, min_frames: 600, max_phase_variance: 0.3 }
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Error type
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Errors from calibration operations.
|
||||
#[derive(Debug, Error)]
|
||||
pub enum CalibrationError {
|
||||
#[error("subcarrier count mismatch: expected {expected}, got {got}")]
|
||||
SubcarrierMismatch { expected: usize, got: usize },
|
||||
|
||||
#[error("tier mismatch: baseline tier {baseline:?}, frame tier {frame:?}")]
|
||||
TierMismatch { baseline: PhyTier, frame: PhyTier },
|
||||
|
||||
#[error("insufficient frames: have {got}, need {need}")]
|
||||
InsufficientFrames { got: u32, need: u32 },
|
||||
|
||||
#[error("baseline serialization version mismatch: have v{got}, expected v{want}")]
|
||||
VersionMismatch { got: u8, want: u8 },
|
||||
|
||||
#[error("buffer too short to deserialize baseline (have {got} bytes, need at least {need})")]
|
||||
TruncatedBuffer { got: usize, need: usize },
|
||||
|
||||
#[error("invalid magic word: expected 0xCA1B0001, got 0x{got:08X}")]
|
||||
InvalidMagic { got: u32 },
|
||||
|
||||
#[error("unknown tier byte: {0}")]
|
||||
UnknownTier(u8),
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Per-subcarrier running statistics
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Per-subcarrier Welford amplitude + circular-phase accumulators.
|
||||
///
|
||||
/// Amplitude uses the standard Welford recurrence (as in `field_model::WelfordStats`
|
||||
/// but inlined here into a struct-of-arrays to avoid pub-API churn on that type).
|
||||
/// Phase uses sin/cos running sums — the standard technique for circular statistics.
|
||||
#[derive(Debug, Clone)]
|
||||
struct SubcarrierStats {
|
||||
amp_count: u64,
|
||||
amp_mean: f64,
|
||||
amp_m2: f64,
|
||||
phase_sin_sum: f64,
|
||||
phase_cos_sum: f64,
|
||||
}
|
||||
|
||||
impl SubcarrierStats {
|
||||
fn new() -> Self {
|
||||
Self { amp_count: 0, amp_mean: 0.0, amp_m2: 0.0, phase_sin_sum: 0.0, phase_cos_sum: 0.0 }
|
||||
}
|
||||
|
||||
/// Welford update for amplitude; circular update for phase.
|
||||
fn update(&mut self, c: Complex32) {
|
||||
let amp = c.norm() as f64;
|
||||
self.amp_count += 1;
|
||||
let delta = amp - self.amp_mean;
|
||||
self.amp_mean += delta / self.amp_count as f64;
|
||||
let delta2 = amp - self.amp_mean;
|
||||
self.amp_m2 += delta * delta2;
|
||||
|
||||
let theta = c.arg() as f64;
|
||||
self.phase_sin_sum += theta.sin();
|
||||
self.phase_cos_sum += theta.cos();
|
||||
}
|
||||
|
||||
/// Bessel-corrected sample variance (matches Welford convention).
|
||||
fn amp_variance(&self) -> f64 {
|
||||
if self.amp_count < 2 { 0.0 } else { self.amp_m2 / (self.amp_count - 1) as f64 }
|
||||
}
|
||||
|
||||
/// Circular mean phase in `[-π, π]`.
|
||||
fn phase_mean(&self) -> f64 {
|
||||
self.phase_sin_sum.atan2(self.phase_cos_sum)
|
||||
}
|
||||
|
||||
/// Von Mises dispersion `1 − R̄` in `[0, 1]`.
|
||||
fn phase_dispersion(&self) -> f64 {
|
||||
if self.amp_count == 0 { return 1.0; }
|
||||
let n = self.amp_count as f64;
|
||||
let r = (self.phase_sin_sum * self.phase_sin_sum + self.phase_cos_sum * self.phase_cos_sum).sqrt() / n;
|
||||
1.0 - r.min(1.0)
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// SubcarrierBaseline (public per-subcarrier summary)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Finalised per-subcarrier statistics from a baseline capture.
|
||||
#[derive(Debug, Clone, Copy)]
|
||||
pub struct SubcarrierBaseline {
|
||||
pub amp_mean: f32,
|
||||
pub amp_variance: f32,
|
||||
/// Circular mean phase in `[-π, π]` (radians).
|
||||
pub phase_mean: f32,
|
||||
/// Von Mises dispersion `1 − R̄` in `[0, 1]`; 0 = perfectly stationary.
|
||||
pub phase_dispersion: f32,
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// BaselineCalibration
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// A fully finalised empty-room baseline (immutable after construction).
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct BaselineCalibration {
|
||||
pub tier: PhyTier,
|
||||
pub captured_at_unix_s: i64,
|
||||
pub frame_count: u64,
|
||||
/// Per-subcarrier statistics, ordered by active-subcarrier index.
|
||||
pub subcarriers: Vec<SubcarrierBaseline>,
|
||||
}
|
||||
|
||||
impl BaselineCalibration {
|
||||
/// Compute a per-frame deviation score against this baseline.
|
||||
pub fn deviation(&self, frame: &CsiFrame) -> Result<CalibrationDeviationScore, CalibrationError> {
|
||||
let n_sc = frame.num_subcarriers();
|
||||
let expected = self.subcarriers.len();
|
||||
if n_sc != expected && n_sc != self.tier_num_subcarriers() {
|
||||
return Err(CalibrationError::SubcarrierMismatch { expected, got: n_sc });
|
||||
}
|
||||
let y = extract_first_stream(frame, expected, self.tier_num_subcarriers());
|
||||
let mut z_amp = Vec::with_capacity(expected);
|
||||
let mut phase_drift = Vec::with_capacity(expected);
|
||||
for (ki, (c, baseline)) in y.iter().zip(self.subcarriers.iter()).enumerate() {
|
||||
let _ = ki;
|
||||
let amp = c.norm();
|
||||
let std = baseline.amp_variance.sqrt().max(1e-12_f32);
|
||||
z_amp.push((amp - baseline.amp_mean) / std);
|
||||
let theta = c.arg();
|
||||
let drift = circular_distance(theta, baseline.phase_mean);
|
||||
phase_drift.push(drift);
|
||||
}
|
||||
let amplitude_z_median = median_abs(&z_amp);
|
||||
let amplitude_z_max = z_amp.iter().map(|v| v.abs()).fold(0.0_f32, f32::max);
|
||||
let phase_drift_median = median_slice(&phase_drift);
|
||||
let motion_flagged = amplitude_z_median > 2.0 || phase_drift_median > std::f32::consts::PI / 6.0;
|
||||
Ok(CalibrationDeviationScore { amplitude_z_median, amplitude_z_max, phase_drift_median, motion_flagged })
|
||||
}
|
||||
|
||||
/// Subtract the amplitude baseline from `frame.data` in-place.
|
||||
/// Only amplitude mean is subtracted; phase is left untouched.
|
||||
pub fn subtract_in_place(&self, frame: &mut CsiFrame) -> Result<(), CalibrationError> {
|
||||
let n_sc = frame.num_subcarriers();
|
||||
let expected = self.subcarriers.len();
|
||||
if n_sc != expected && n_sc != self.tier_num_subcarriers() {
|
||||
return Err(CalibrationError::SubcarrierMismatch { expected, got: n_sc });
|
||||
}
|
||||
let n_streams = frame.num_spatial_streams();
|
||||
let n_total = self.tier_num_subcarriers();
|
||||
let active_input = n_sc == expected;
|
||||
for ki in 0..expected {
|
||||
let col = if active_input { ki } else { ki }; // sequential when active-only
|
||||
let baseline_amp = self.subcarriers[ki].amp_mean as f64;
|
||||
for s in 0..n_streams {
|
||||
let c = frame.data[[s, col]];
|
||||
let norm = c.norm();
|
||||
if norm > 1e-30 {
|
||||
let scale = ((norm - baseline_amp).max(0.0)) / norm;
|
||||
frame.data[[s, col]] = num_complex::Complex64::new(c.re * scale, c.im * scale);
|
||||
}
|
||||
}
|
||||
let _ = n_total;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Reference complex CSI vector: `amp_mean × exp(j × phase_mean)` per subcarrier.
|
||||
/// Pass to `CirEstimator::set_reference_csi()`.
|
||||
pub fn reference_csi_vector(&self) -> Vec<Complex32> {
|
||||
self.subcarriers.iter().map(|b| {
|
||||
let (sin, cos) = b.phase_mean.sin_cos();
|
||||
Complex32::new(b.amp_mean * cos, b.amp_mean * sin)
|
||||
}).collect()
|
||||
}
|
||||
|
||||
/// Serialise to little-endian binary (see module-level format doc).
|
||||
pub fn to_bytes(&self) -> Vec<u8> {
|
||||
let n = self.subcarriers.len();
|
||||
let mut buf = Vec::with_capacity(HEADER_LEN + 8 + 4 + n * SUBCARRIER_RECORD_LEN);
|
||||
buf.extend_from_slice(&MAGIC.to_le_bytes());
|
||||
buf.push(VERSION);
|
||||
buf.push(self.tier.to_u8());
|
||||
buf.extend_from_slice(&0u16.to_le_bytes()); // reserved
|
||||
buf.extend_from_slice(&self.captured_at_unix_s.to_le_bytes());
|
||||
buf.extend_from_slice(&self.frame_count.to_le_bytes());
|
||||
buf.extend_from_slice(&(n as u32).to_le_bytes());
|
||||
for sc in &self.subcarriers {
|
||||
buf.extend_from_slice(&sc.amp_mean.to_le_bytes());
|
||||
buf.extend_from_slice(&sc.amp_variance.to_le_bytes());
|
||||
buf.extend_from_slice(&sc.phase_mean.to_le_bytes());
|
||||
buf.extend_from_slice(&sc.phase_dispersion.to_le_bytes());
|
||||
}
|
||||
buf
|
||||
}
|
||||
|
||||
/// Deserialise from little-endian binary produced by `to_bytes`.
|
||||
pub fn from_bytes(buf: &[u8]) -> Result<Self, CalibrationError> {
|
||||
const MIN_LEN: usize = HEADER_LEN + 8 + 4; // header + frame_count + num_subcarriers
|
||||
if buf.len() < MIN_LEN {
|
||||
return Err(CalibrationError::TruncatedBuffer { got: buf.len(), need: MIN_LEN });
|
||||
}
|
||||
let magic = u32::from_le_bytes(buf[0..4].try_into().unwrap());
|
||||
if magic != MAGIC {
|
||||
return Err(CalibrationError::InvalidMagic { got: magic });
|
||||
}
|
||||
let version = buf[4];
|
||||
if version != VERSION {
|
||||
return Err(CalibrationError::VersionMismatch { got: version, want: VERSION });
|
||||
}
|
||||
let tier_byte = buf[5];
|
||||
let tier = PhyTier::from_u8(tier_byte).ok_or(CalibrationError::UnknownTier(tier_byte))?;
|
||||
// reserved: buf[6..8] — ignored
|
||||
let captured_at_unix_s = i64::from_le_bytes(buf[8..16].try_into().unwrap());
|
||||
let frame_count = u64::from_le_bytes(buf[16..24].try_into().unwrap());
|
||||
let n = u32::from_le_bytes(buf[24..28].try_into().unwrap()) as usize;
|
||||
let needed = MIN_LEN + n * SUBCARRIER_RECORD_LEN;
|
||||
if buf.len() < needed {
|
||||
return Err(CalibrationError::TruncatedBuffer { got: buf.len(), need: needed });
|
||||
}
|
||||
let mut subcarriers = Vec::with_capacity(n);
|
||||
let mut off = 28usize;
|
||||
for _ in 0..n {
|
||||
let amp_mean = f32::from_le_bytes(buf[off..off + 4].try_into().unwrap()); off += 4;
|
||||
let amp_variance = f32::from_le_bytes(buf[off..off + 4].try_into().unwrap()); off += 4;
|
||||
let phase_mean = f32::from_le_bytes(buf[off..off + 4].try_into().unwrap()); off += 4;
|
||||
let phase_dispersion = f32::from_le_bytes(buf[off..off + 4].try_into().unwrap()); off += 4;
|
||||
subcarriers.push(SubcarrierBaseline { amp_mean, amp_variance, phase_mean, phase_dispersion });
|
||||
}
|
||||
Ok(Self { tier, captured_at_unix_s, frame_count, subcarriers })
|
||||
}
|
||||
|
||||
/// Total FFT bins for this tier (used for dual-convention column selection).
|
||||
fn tier_num_subcarriers(&self) -> usize {
|
||||
match self.tier {
|
||||
PhyTier::Ht20 => 64,
|
||||
PhyTier::Ht40 => 128,
|
||||
PhyTier::He20 => 256,
|
||||
PhyTier::He40 => 512,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Deviation score
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Per-frame deviation metrics against the static baseline.
|
||||
#[derive(Debug, Clone, Copy)]
|
||||
pub struct CalibrationDeviationScore {
|
||||
/// Median of `|z_amp[k]|` across active subcarriers.
|
||||
pub amplitude_z_median: f32,
|
||||
/// Max single-subcarrier `|z_amp[k]|`.
|
||||
pub amplitude_z_max: f32,
|
||||
/// Median circular distance (radians) between live and baseline phase.
|
||||
pub phase_drift_median: f32,
|
||||
/// Heuristic: `amplitude_z_median > 2.0 || phase_drift_median > π/6`.
|
||||
pub motion_flagged: bool,
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// CalibrationRecorder
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Accumulates CSI frames from an empty room using Welford online statistics.
|
||||
///
|
||||
/// Phase precondition: the caller must pass frames processed by
|
||||
/// `PhaseSanitizer` and `phase_align.rs`. Unsanitised phase produces
|
||||
/// inflated `phase_dispersion` values.
|
||||
pub struct CalibrationRecorder {
|
||||
config: CalibrationConfig,
|
||||
started_at_unix_s: i64,
|
||||
stats: Vec<SubcarrierStats>,
|
||||
frame_count: u32,
|
||||
}
|
||||
|
||||
impl CalibrationRecorder {
|
||||
/// Create a new recorder for the given configuration.
|
||||
pub fn new(config: CalibrationConfig) -> Self {
|
||||
let stats = vec![SubcarrierStats::new(); config.num_active];
|
||||
Self { config, started_at_unix_s: unix_now_s(), stats, frame_count: 0 }
|
||||
}
|
||||
|
||||
/// Ingest one sanitised CSI frame. Returns a deviation score from the
|
||||
/// current partial baseline so the operator can monitor room occupancy
|
||||
/// in real time.
|
||||
pub fn record(&mut self, frame: &CsiFrame) -> Result<CalibrationDeviationScore, CalibrationError> {
|
||||
let n_sc = frame.num_subcarriers();
|
||||
let expected_active = self.config.num_active;
|
||||
let expected_total = self.config.num_subcarriers;
|
||||
if n_sc != expected_active && n_sc != expected_total {
|
||||
return Err(CalibrationError::SubcarrierMismatch { expected: expected_active, got: n_sc });
|
||||
}
|
||||
let y = extract_first_stream(frame, expected_active, expected_total);
|
||||
for (ki, c) in y.iter().enumerate() {
|
||||
self.stats[ki].update(*c);
|
||||
}
|
||||
self.frame_count += 1;
|
||||
|
||||
// Build deviation from partial baseline (after first frame).
|
||||
let mut z_amp_abs = Vec::with_capacity(expected_active);
|
||||
let mut phase_drift = Vec::with_capacity(expected_active);
|
||||
for (c, st) in y.iter().zip(self.stats.iter()) {
|
||||
let amp = c.norm();
|
||||
let std = (st.amp_variance() as f32).sqrt().max(1e-12_f32);
|
||||
z_amp_abs.push((amp - st.amp_mean as f32).abs() / std);
|
||||
phase_drift.push(circular_distance(c.arg(), st.phase_mean() as f32));
|
||||
}
|
||||
let amplitude_z_median = median_slice(&z_amp_abs);
|
||||
let amplitude_z_max = z_amp_abs.iter().copied().fold(0.0_f32, f32::max);
|
||||
let phase_drift_median = median_slice(&phase_drift);
|
||||
let motion_flagged = amplitude_z_median > 2.0 || phase_drift_median > std::f32::consts::PI / 6.0;
|
||||
Ok(CalibrationDeviationScore { amplitude_z_median, amplitude_z_max, phase_drift_median, motion_flagged })
|
||||
}
|
||||
|
||||
/// Number of frames recorded so far.
|
||||
pub fn frames_recorded(&self) -> u32 {
|
||||
self.frame_count
|
||||
}
|
||||
|
||||
/// Consume the recorder and produce a finalised baseline.
|
||||
/// Returns `CalibrationError::InsufficientFrames` if fewer than
|
||||
/// `config.min_frames` frames were recorded.
|
||||
pub fn finalize(self) -> Result<BaselineCalibration, CalibrationError> {
|
||||
if self.frame_count < self.config.min_frames {
|
||||
return Err(CalibrationError::InsufficientFrames {
|
||||
got: self.frame_count,
|
||||
need: self.config.min_frames,
|
||||
});
|
||||
}
|
||||
let subcarriers = self.stats.iter().map(|st| SubcarrierBaseline {
|
||||
amp_mean: st.amp_mean as f32,
|
||||
amp_variance: st.amp_variance() as f32,
|
||||
phase_mean: st.phase_mean() as f32,
|
||||
phase_dispersion: st.phase_dispersion() as f32,
|
||||
}).collect();
|
||||
Ok(BaselineCalibration {
|
||||
tier: self.config.tier,
|
||||
captured_at_unix_s: self.started_at_unix_s,
|
||||
frame_count: self.frame_count as u64,
|
||||
subcarriers,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Extract the first spatial stream as a `Vec<Complex32>`, honouring the
|
||||
/// dual-convention used by `cir.rs::extract_csi_vector`: if the frame has
|
||||
/// exactly `num_active` subcarriers they are taken sequentially; otherwise
|
||||
/// the first `num_active` columns of the full FFT grid are used.
|
||||
fn extract_first_stream(frame: &CsiFrame, num_active: usize, _num_total: usize) -> Vec<Complex32> {
|
||||
let n_sc = frame.num_subcarriers();
|
||||
let take = num_active.min(n_sc);
|
||||
(0..take).map(|ki| {
|
||||
let c = frame.data[[0, ki]];
|
||||
Complex32::new(c.re as f32, c.im as f32)
|
||||
}).collect()
|
||||
}
|
||||
|
||||
/// Signed circular distance wrapped to `[0, π]`.
|
||||
fn circular_distance(a: f32, b: f32) -> f32 {
|
||||
let mut d = (a - b).abs();
|
||||
if d > std::f32::consts::PI {
|
||||
d = 2.0 * std::f32::consts::PI - d;
|
||||
}
|
||||
d
|
||||
}
|
||||
|
||||
/// Median of absolute values of a slice.
|
||||
fn median_abs(v: &[f32]) -> f32 {
|
||||
let mut abs: Vec<f32> = v.iter().map(|x| x.abs()).collect();
|
||||
median_in_place(&mut abs)
|
||||
}
|
||||
|
||||
/// Median of a slice (non-destructive clone).
|
||||
fn median_slice(v: &[f32]) -> f32 {
|
||||
let mut c = v.to_vec();
|
||||
median_in_place(&mut c)
|
||||
}
|
||||
|
||||
fn median_in_place(v: &mut Vec<f32>) -> f32 {
|
||||
if v.is_empty() { return 0.0; }
|
||||
v.sort_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal));
|
||||
let mid = v.len() / 2;
|
||||
if v.len() % 2 == 0 { (v[mid - 1] + v[mid]) / 2.0 } else { v[mid] }
|
||||
}
|
||||
|
||||
/// Current Unix timestamp in seconds. Falls back to 0 if unavailable.
|
||||
fn unix_now_s() -> i64 {
|
||||
use std::time::{SystemTime, UNIX_EPOCH};
|
||||
SystemTime::now().duration_since(UNIX_EPOCH).map(|d| d.as_secs() as i64).unwrap_or(0)
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Unit tests
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use ndarray::Array2;
|
||||
use num_complex::Complex64;
|
||||
use wifi_densepose_core::types::{CsiMetadata, CsiFrame};
|
||||
|
||||
fn make_frame(data: Array2<Complex64>) -> CsiFrame {
|
||||
use wifi_densepose_core::types::{DeviceId, FrequencyBand};
|
||||
let meta = CsiMetadata::new(
|
||||
DeviceId::new("test-device"),
|
||||
FrequencyBand::Band2_4GHz,
|
||||
6,
|
||||
);
|
||||
CsiFrame::new(meta, data)
|
||||
}
|
||||
|
||||
fn constant_frame(n_sc: usize, amp: f64, phase: f64) -> CsiFrame {
|
||||
let row = (0..n_sc).map(|_| Complex64::from_polar(amp, phase)).collect::<Vec<_>>();
|
||||
let arr = Array2::from_shape_vec((1, n_sc), row).unwrap();
|
||||
make_frame(arr)
|
||||
}
|
||||
|
||||
// (a) Welford convergence: constant input → variance ≈ 0, mean = amp.
|
||||
#[test]
|
||||
fn welford_constant_input_converges() {
|
||||
let mut st = SubcarrierStats::new();
|
||||
let c = Complex32::new(1.0, 0.0);
|
||||
for _ in 0..600 {
|
||||
st.update(c);
|
||||
}
|
||||
assert!((st.amp_mean - 1.0).abs() < 1e-9);
|
||||
assert!(st.amp_variance() < 1e-20, "variance was {}", st.amp_variance());
|
||||
}
|
||||
|
||||
// (b) Circular phase mean recovers known phase from N noisy samples.
|
||||
#[test]
|
||||
fn circular_phase_mean_recovery() {
|
||||
use std::f64::consts::PI;
|
||||
let mut st = SubcarrierStats::new();
|
||||
let target = PI / 4.0;
|
||||
// Feed 200 samples: 100 at target+0.05, 100 at target-0.05.
|
||||
for _ in 0..100 {
|
||||
st.update(Complex32::from_polar(1.0, (target + 0.05) as f32));
|
||||
st.update(Complex32::from_polar(1.0, (target - 0.05) as f32));
|
||||
}
|
||||
let recovered = st.phase_mean();
|
||||
assert!((recovered - target).abs() < 0.01, "phase error = {}", (recovered - target).abs());
|
||||
// Dispersion should be low (close to 0) for tight phase cluster.
|
||||
assert!(st.phase_dispersion() < 0.01, "dispersion = {}", st.phase_dispersion());
|
||||
}
|
||||
|
||||
// (c) Round-trip: to_bytes → from_bytes preserves all baseline fields.
|
||||
#[test]
|
||||
fn round_trip_to_from_bytes() {
|
||||
let mut cfg = CalibrationConfig::ht20();
|
||||
cfg.min_frames = 2;
|
||||
let mut rec = CalibrationRecorder::new(cfg);
|
||||
let f1 = constant_frame(52, 0.8, 0.5);
|
||||
let f2 = constant_frame(52, 0.9, 0.6);
|
||||
rec.record(&f1).unwrap();
|
||||
rec.record(&f2).unwrap();
|
||||
let baseline = rec.finalize().unwrap();
|
||||
|
||||
let bytes = baseline.to_bytes();
|
||||
let recovered = BaselineCalibration::from_bytes(&bytes).unwrap();
|
||||
|
||||
assert_eq!(recovered.frame_count, baseline.frame_count);
|
||||
assert_eq!(recovered.tier, baseline.tier);
|
||||
assert_eq!(recovered.subcarriers.len(), baseline.subcarriers.len());
|
||||
for (a, b) in recovered.subcarriers.iter().zip(baseline.subcarriers.iter()) {
|
||||
assert!((a.amp_mean - b.amp_mean).abs() < 1e-6, "amp_mean mismatch");
|
||||
assert!((a.phase_mean - b.phase_mean).abs() < 1e-6, "phase_mean mismatch");
|
||||
assert!((a.phase_dispersion - b.phase_dispersion).abs() < 1e-6, "dispersion mismatch");
|
||||
}
|
||||
}
|
||||
|
||||
// (d) Tier dispatch: each config constructor produces the correct counts.
|
||||
#[test]
|
||||
fn tier_dispatch_correct_counts() {
|
||||
let ht20 = CalibrationConfig::ht20();
|
||||
assert_eq!(ht20.num_subcarriers, 64);
|
||||
assert_eq!(ht20.num_active, 52);
|
||||
|
||||
let ht40 = CalibrationConfig::ht40();
|
||||
assert_eq!(ht40.num_subcarriers, 128);
|
||||
assert_eq!(ht40.num_active, 114);
|
||||
|
||||
let he20 = CalibrationConfig::he20();
|
||||
assert_eq!(he20.num_subcarriers, 256);
|
||||
assert_eq!(he20.num_active, 242);
|
||||
|
||||
let he40 = CalibrationConfig::he40();
|
||||
assert_eq!(he40.num_subcarriers, 512);
|
||||
assert_eq!(he40.num_active, 484);
|
||||
}
|
||||
|
||||
// Additional: insufficient frames → error.
|
||||
#[test]
|
||||
fn finalize_requires_min_frames() {
|
||||
let cfg = CalibrationConfig::ht20(); // min_frames = 600
|
||||
let mut rec = CalibrationRecorder::new(cfg);
|
||||
let f = constant_frame(52, 1.0, 0.0);
|
||||
rec.record(&f).unwrap();
|
||||
match rec.finalize() {
|
||||
Err(CalibrationError::InsufficientFrames { got: 1, need: 600 }) => {}
|
||||
other => panic!("expected InsufficientFrames, got {:?}", other),
|
||||
}
|
||||
}
|
||||
|
||||
// Binary magic / version check.
|
||||
#[test]
|
||||
fn binary_magic_and_version() {
|
||||
let mut cfg = CalibrationConfig::ht20();
|
||||
cfg.min_frames = 1;
|
||||
let mut rec = CalibrationRecorder::new(cfg);
|
||||
rec.record(&constant_frame(52, 1.0, 0.0)).unwrap();
|
||||
let b = rec.finalize().unwrap().to_bytes();
|
||||
let magic = u32::from_le_bytes(b[0..4].try_into().unwrap());
|
||||
assert_eq!(magic, 0xCA1B_0001u32);
|
||||
assert_eq!(b[4], 1u8); // version = 1
|
||||
}
|
||||
|
||||
// Subcarrier mismatch is rejected.
|
||||
#[test]
|
||||
fn subcarrier_mismatch_error() {
|
||||
let mut cfg = CalibrationConfig::ht20();
|
||||
cfg.min_frames = 1;
|
||||
let mut rec = CalibrationRecorder::new(cfg);
|
||||
let bad = constant_frame(50, 1.0, 0.0); // 50 ≠ 52, 50 ≠ 64
|
||||
assert!(matches!(
|
||||
rec.record(&bad),
|
||||
Err(CalibrationError::SubcarrierMismatch { expected: 52, got: 50 })
|
||||
));
|
||||
}
|
||||
}
|
||||
|
|
@ -58,6 +58,9 @@ pub mod pose_tracker;
|
|||
// ADR-134: CIR estimation (ISTA + NeumannSolver warm-start)
|
||||
pub mod cir;
|
||||
|
||||
// ADR-135: Empty-room baseline calibration (Welford online, circular phase)
|
||||
pub mod calibration;
|
||||
|
||||
// Re-export core types for ergonomic access
|
||||
pub use coherence::CoherenceState;
|
||||
pub use coherence_gate::{GateDecision, GatePolicy};
|
||||
|
|
|
|||
|
|
@ -0,0 +1,243 @@
|
|||
//! Drift-triggered recalibration scenario tests (ADR-135 §2.5 and §2.6).
|
||||
//!
|
||||
//! Validates that the deviation z-score escalates correctly under sustained
|
||||
//! amplitude drift, and stays suppressed for a stable stationary channel.
|
||||
//!
|
||||
//! Tests are seeded with literal `42` and are fully deterministic.
|
||||
|
||||
use std::f32::consts::PI;
|
||||
|
||||
use ndarray::Array2;
|
||||
use num_complex::Complex64;
|
||||
use wifi_densepose_core::types::{AntennaConfig, CsiFrame, CsiMetadata, DeviceId, FrequencyBand};
|
||||
use wifi_densepose_signal::calibration::{
|
||||
BaselineCalibration, CalibrationConfig, CalibrationError, CalibrationRecorder,
|
||||
};
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Deterministic PRNG (xorshift32, seed=42) — duplicated locally.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
struct Rng(u32);
|
||||
|
||||
impl Rng {
|
||||
fn new(seed: u32) -> Self {
|
||||
assert_ne!(seed, 0, "xorshift seed must be non-zero");
|
||||
Self(seed)
|
||||
}
|
||||
fn next_u32(&mut self) -> u32 {
|
||||
let mut x = self.0;
|
||||
x ^= x << 13;
|
||||
x ^= x >> 17;
|
||||
x ^= x << 5;
|
||||
self.0 = x;
|
||||
x
|
||||
}
|
||||
fn next_normal(&mut self) -> f32 {
|
||||
let u1 = (self.next_u32() as f32 + 1.0) / (u32::MAX as f32 + 2.0);
|
||||
let u2 = (self.next_u32() as f32 + 1.0) / (u32::MAX as f32 + 2.0);
|
||||
let r = (-2.0 * u1.ln()).sqrt();
|
||||
let theta = 2.0 * PI * u2;
|
||||
r * theta.cos()
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Constants and helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const N_ACTIVE: usize = 52; // HT20
|
||||
|
||||
fn base_amp() -> Vec<f32> {
|
||||
(0..N_ACTIVE)
|
||||
.map(|k| 0.3 + 0.7 * (k as f32 * PI / N_ACTIVE as f32).sin().abs())
|
||||
.collect()
|
||||
}
|
||||
|
||||
fn base_phase() -> Vec<f32> {
|
||||
(0..N_ACTIVE)
|
||||
.map(|k| (k as f32 * 0.1).rem_euclid(2.0 * PI) - PI)
|
||||
.collect()
|
||||
}
|
||||
|
||||
fn make_frame_with_amp(amp_vals: &[f32], phase: &[f32], rng: &mut Rng) -> CsiFrame {
|
||||
let n = amp_vals.len();
|
||||
let noise_std = 0.005_f32; // very low noise for clean drift detection
|
||||
let mut data = Array2::<Complex64>::zeros((1, n));
|
||||
for k in 0..n {
|
||||
let re = amp_vals[k] * phase[k].cos() + noise_std * rng.next_normal();
|
||||
let im = amp_vals[k] * phase[k].sin() + noise_std * rng.next_normal();
|
||||
data[(0, k)] = Complex64::new(re as f64, im as f64);
|
||||
}
|
||||
let mut meta = CsiMetadata::new(DeviceId::new("drift-test"), FrequencyBand::Band2_4GHz, 6);
|
||||
meta.bandwidth_mhz = 20;
|
||||
meta.antenna_config = AntennaConfig::new(1, 1);
|
||||
CsiFrame::new(meta, data)
|
||||
}
|
||||
|
||||
fn build_baseline() -> BaselineCalibration {
|
||||
let amp = base_amp();
|
||||
let phase = base_phase();
|
||||
let mut rng = Rng::new(42);
|
||||
let mut recorder = CalibrationRecorder::new(CalibrationConfig::ht20());
|
||||
for _ in 0..600 {
|
||||
let frame = make_frame_with_amp(&, &phase, &mut rng);
|
||||
recorder.record(&frame).expect("record");
|
||||
}
|
||||
recorder.finalize().expect("finalize")
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Test 1: slow amplitude drift causes z-score to escalate above 4.0 by frame 900
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// ADR-135 §2.5: drift_score > 4.0 is the recalibration threshold.
|
||||
/// With amplitude growing +0.01/frame, the squared z-score (relative to baseline
|
||||
/// variance) must exceed 4.0 on average over the last 100 of 900 frames.
|
||||
#[test]
|
||||
fn should_exceed_drift_threshold_when_amplitude_drifts_slowly() {
|
||||
let baseline = build_baseline();
|
||||
let base = base_amp();
|
||||
let phase = base_phase();
|
||||
let mut rng = Rng::new(42);
|
||||
let mut last_100_mean_sq_z: Vec<f32> = Vec::new();
|
||||
|
||||
for t in 0..900usize {
|
||||
// Each frame has amplitudes drifted up by +0.01 per frame step
|
||||
let amp: Vec<f32> = base.iter().map(|a| a + 0.01 * t as f32).collect();
|
||||
let frame = make_frame_with_amp(&, &phase, &mut rng);
|
||||
let score = baseline.deviation(&frame).expect("deviation");
|
||||
|
||||
if t >= 800 {
|
||||
// amplitude_z_median is the median absolute z. drift_score in ADR-135 is
|
||||
// mean over k of median squared z over a window. We approximate here
|
||||
// by squaring the amplitude_z_median.
|
||||
let approx_drift_score = score.amplitude_z_median * score.amplitude_z_median;
|
||||
last_100_mean_sq_z.push(approx_drift_score);
|
||||
}
|
||||
}
|
||||
|
||||
let avg_drift_score: f32 =
|
||||
last_100_mean_sq_z.iter().sum::<f32>() / last_100_mean_sq_z.len() as f32;
|
||||
|
||||
assert!(
|
||||
avg_drift_score > 4.0,
|
||||
"drift scenario: approx drift score over last 100 frames = {:.3} must exceed 4.0 \
|
||||
(ADR-135 drift threshold)",
|
||||
avg_drift_score
|
||||
);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Test 2: 900 stationary frames keep z-score below 2.0
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
#[test]
|
||||
fn should_stay_below_drift_threshold_for_stable_channel() {
|
||||
let baseline = build_baseline();
|
||||
let base = base_amp();
|
||||
let phase = base_phase();
|
||||
let mut rng = Rng::new(42);
|
||||
let mut last_100_mean_sq_z: Vec<f32> = Vec::new();
|
||||
|
||||
for t in 0..900usize {
|
||||
let _ = t;
|
||||
let frame = make_frame_with_amp(&base, &phase, &mut rng);
|
||||
let score = baseline.deviation(&frame).expect("deviation");
|
||||
if last_100_mean_sq_z.len() < 100 || t >= 800 {
|
||||
let approx_drift = score.amplitude_z_median * score.amplitude_z_median;
|
||||
if t >= 800 {
|
||||
last_100_mean_sq_z.push(approx_drift);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let avg_drift_score: f32 =
|
||||
last_100_mean_sq_z.iter().sum::<f32>() / last_100_mean_sq_z.len() as f32;
|
||||
|
||||
assert!(
|
||||
avg_drift_score < 2.0,
|
||||
"stable scenario: approx drift score over last 100 frames = {:.3} must be < 2.0",
|
||||
avg_drift_score
|
||||
);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Test 3: is_complete() reflects target_frames boundary
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
#[test]
|
||||
fn should_report_not_complete_before_target_frames() {
|
||||
let base = base_amp();
|
||||
let phase = base_phase();
|
||||
let mut rng = Rng::new(42);
|
||||
// min_frames=600 means recorder needs at least 600 frames before finalize succeeds.
|
||||
// is_complete() is defined as frames_recorded() >= config.min_frames.
|
||||
let config = CalibrationConfig::ht20(); // min_frames = 600
|
||||
let mut recorder = CalibrationRecorder::new(config);
|
||||
for _ in 0..10 {
|
||||
let frame = make_frame_with_amp(&base, &phase, &mut rng);
|
||||
recorder.record(&frame).expect("record");
|
||||
}
|
||||
assert_eq!(recorder.frames_recorded(), 10, "frames_recorded should be 10");
|
||||
// finalize should fail with InsufficientFrames
|
||||
let result = recorder.finalize();
|
||||
assert!(
|
||||
matches!(result, Err(CalibrationError::InsufficientFrames { .. })),
|
||||
"expected InsufficientFrames after 10 frames, got {:?}", result
|
||||
);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Test 4: finalize() returns InsufficientFrames with correct counts
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
#[test]
|
||||
fn should_error_on_finalize_with_insufficient_frames() {
|
||||
let base = base_amp();
|
||||
let phase = base_phase();
|
||||
let mut rng = Rng::new(42);
|
||||
let mut recorder = CalibrationRecorder::new(CalibrationConfig::ht20()); // min=600
|
||||
for _ in 0..50 {
|
||||
let frame = make_frame_with_amp(&base, &phase, &mut rng);
|
||||
recorder.record(&frame).expect("record");
|
||||
}
|
||||
match recorder.finalize() {
|
||||
Err(CalibrationError::InsufficientFrames { got, need }) => {
|
||||
assert_eq!(got, 50, "got should be 50");
|
||||
assert_eq!(need, 600, "need should be 600 (min_frames)");
|
||||
}
|
||||
other => panic!("expected InsufficientFrames, got {:?}", other),
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Test 5: motion_flagged flips when amplitude jumps substantially
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
#[test]
|
||||
fn should_flag_motion_when_amplitude_jumps_by_many_sigma() {
|
||||
let baseline = build_baseline();
|
||||
let phase = base_phase();
|
||||
|
||||
// Compute a meaningful sigma: mean amp_variance across subcarriers
|
||||
let mean_sigma: f32 = baseline
|
||||
.subcarriers
|
||||
.iter()
|
||||
.map(|sc| sc.amp_variance.sqrt())
|
||||
.sum::<f32>()
|
||||
/ N_ACTIVE as f32;
|
||||
|
||||
// Build a frame with all amplitudes shifted up by 5σ
|
||||
let base = base_amp();
|
||||
let shifted_amp: Vec<f32> = base.iter().map(|a| a + 5.0 * mean_sigma).collect();
|
||||
let mut rng = Rng::new(77);
|
||||
let frame = make_frame_with_amp(&shifted_amp, &phase, &mut rng);
|
||||
let score = baseline.deviation(&frame).expect("deviation");
|
||||
assert!(
|
||||
score.motion_flagged,
|
||||
"motion must be flagged when amplitude is shifted by 5σ; \
|
||||
amplitude_z_median={:.3}",
|
||||
score.amplitude_z_median
|
||||
);
|
||||
}
|
||||
|
|
@ -0,0 +1,247 @@
|
|||
//! Bytes round-trip tests for BaselineCalibration serialisation (ADR-135 §2.4).
|
||||
//!
|
||||
//! The implementation uses `to_bytes()` / `from_bytes()` as the binary format.
|
||||
//! Magic word is 0xCA1B_0001, schema version = 1.
|
||||
//!
|
||||
//! Covers:
|
||||
//! - Binary round-trip determinism (to_bytes twice → same output)
|
||||
//! - deserialise→re-serialise produces identical bytes
|
||||
//! - Version mismatch detection
|
||||
//! - Truncated buffer detection
|
||||
//! - Magic word mismatch detection
|
||||
|
||||
use std::f32::consts::PI;
|
||||
|
||||
use ndarray::Array2;
|
||||
use num_complex::Complex64;
|
||||
use wifi_densepose_core::types::{AntennaConfig, CsiFrame, CsiMetadata, DeviceId, FrequencyBand};
|
||||
use wifi_densepose_signal::calibration::{
|
||||
BaselineCalibration, CalibrationConfig, CalibrationError, CalibrationRecorder,
|
||||
};
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Deterministic PRNG (xorshift32, seed=42) — duplicated locally.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
struct Rng(u32);
|
||||
|
||||
impl Rng {
|
||||
fn new(seed: u32) -> Self {
|
||||
assert_ne!(seed, 0, "xorshift seed must be non-zero");
|
||||
Self(seed)
|
||||
}
|
||||
fn next_u32(&mut self) -> u32 {
|
||||
let mut x = self.0;
|
||||
x ^= x << 13;
|
||||
x ^= x >> 17;
|
||||
x ^= x << 5;
|
||||
self.0 = x;
|
||||
x
|
||||
}
|
||||
fn next_normal(&mut self) -> f32 {
|
||||
let u1 = (self.next_u32() as f32 + 1.0) / (u32::MAX as f32 + 2.0);
|
||||
let u2 = (self.next_u32() as f32 + 1.0) / (u32::MAX as f32 + 2.0);
|
||||
let r = (-2.0 * u1.ln()).sqrt();
|
||||
let theta = 2.0 * PI * u2;
|
||||
r * theta.cos()
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Build a deterministic baseline (HT20, 600 frames, seed=42).
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn build_ht20_baseline() -> BaselineCalibration {
|
||||
const N: usize = 52;
|
||||
let amp: Vec<f32> = (0..N)
|
||||
.map(|k| 0.3 + 0.7 * (k as f32 * PI / N as f32).sin().abs())
|
||||
.collect();
|
||||
let phase: Vec<f32> = (0..N)
|
||||
.map(|k| (k as f32 * 0.1).rem_euclid(2.0 * PI) - PI)
|
||||
.collect();
|
||||
|
||||
let mut rng = Rng::new(42);
|
||||
let mut recorder = CalibrationRecorder::new(CalibrationConfig::ht20());
|
||||
for _ in 0..600 {
|
||||
let noise_std = 0.01_f32;
|
||||
let mut data = Array2::<Complex64>::zeros((1, N));
|
||||
for k in 0..N {
|
||||
let re = amp[k] * phase[k].cos() + noise_std * rng.next_normal();
|
||||
let im = amp[k] * phase[k].sin() + noise_std * rng.next_normal();
|
||||
data[(0, k)] = Complex64::new(re as f64, im as f64);
|
||||
}
|
||||
let mut meta =
|
||||
CsiMetadata::new(DeviceId::new("roundtrip-test"), FrequencyBand::Band2_4GHz, 6);
|
||||
meta.bandwidth_mhz = 20;
|
||||
meta.antenna_config = AntennaConfig::new(1, 1);
|
||||
let frame = CsiFrame::new(meta, data);
|
||||
recorder.record(&frame).expect("record");
|
||||
}
|
||||
recorder.finalize().expect("finalize")
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Binary round-trip determinism
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Two calls to `to_bytes()` on the same value must produce identical buffers.
|
||||
#[test]
|
||||
fn should_produce_identical_bytes_on_two_calls_to_same_baseline() {
|
||||
let baseline = build_ht20_baseline();
|
||||
let bytes1 = baseline.to_bytes();
|
||||
let bytes2 = baseline.to_bytes();
|
||||
assert_eq!(
|
||||
bytes1, bytes2,
|
||||
"to_bytes must be deterministic across two calls on the same value"
|
||||
);
|
||||
}
|
||||
|
||||
/// deserialise → re-serialise must produce identical bytes.
|
||||
#[test]
|
||||
fn should_deserialise_and_reserialise_to_identical_bytes() {
|
||||
let baseline = build_ht20_baseline();
|
||||
let bytes = baseline.to_bytes();
|
||||
let recovered = BaselineCalibration::from_bytes(&bytes)
|
||||
.expect("from_bytes should succeed on valid bytes");
|
||||
let bytes_recovered = recovered.to_bytes();
|
||||
assert_eq!(
|
||||
bytes, bytes_recovered,
|
||||
"round-trip: re-serialised bytes must match original"
|
||||
);
|
||||
}
|
||||
|
||||
/// Recovered baseline must have matching field values.
|
||||
#[test]
|
||||
fn should_preserve_frame_count_and_subcarrier_count_after_round_trip() {
|
||||
let baseline = build_ht20_baseline();
|
||||
let bytes = baseline.to_bytes();
|
||||
let recovered = BaselineCalibration::from_bytes(&bytes).expect("from_bytes");
|
||||
assert_eq!(
|
||||
baseline.frame_count, recovered.frame_count,
|
||||
"frame_count must survive round-trip"
|
||||
);
|
||||
assert_eq!(
|
||||
baseline.subcarriers.len(),
|
||||
recovered.subcarriers.len(),
|
||||
"subcarrier count must survive round-trip"
|
||||
);
|
||||
}
|
||||
|
||||
/// Per-subcarrier amp_mean values must survive round-trip within f32 precision.
|
||||
#[test]
|
||||
fn should_preserve_amp_mean_per_subcarrier_after_round_trip() {
|
||||
let baseline = build_ht20_baseline();
|
||||
let bytes = baseline.to_bytes();
|
||||
let recovered = BaselineCalibration::from_bytes(&bytes).expect("from_bytes");
|
||||
for k in 0..baseline.subcarriers.len() {
|
||||
assert!(
|
||||
(baseline.subcarriers[k].amp_mean - recovered.subcarriers[k].amp_mean).abs() < 1e-6,
|
||||
"amp_mean[{}] mismatch: {:.8} vs {:.8}",
|
||||
k,
|
||||
baseline.subcarriers[k].amp_mean,
|
||||
recovered.subcarriers[k].amp_mean
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/// Magic word 0xCA1B_0001 must appear at offset 0 in serialised bytes.
|
||||
#[test]
|
||||
fn should_embed_magic_word_0xca1b0001_at_offset_0() {
|
||||
let baseline = build_ht20_baseline();
|
||||
let bytes = baseline.to_bytes();
|
||||
assert!(bytes.len() >= 4, "serialised bytes must be at least 4 bytes long");
|
||||
let magic = u32::from_le_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]);
|
||||
assert_eq!(
|
||||
magic, 0xCA1B_0001_u32,
|
||||
"magic word at offset 0 must be 0xCA1B0001, got 0x{:08X}",
|
||||
magic
|
||||
);
|
||||
}
|
||||
|
||||
/// Schema version at offset 4 must equal 1.
|
||||
#[test]
|
||||
fn should_embed_schema_version_1_at_offset_4() {
|
||||
let baseline = build_ht20_baseline();
|
||||
let bytes = baseline.to_bytes();
|
||||
assert!(bytes.len() >= 6, "bytes too short");
|
||||
let version = bytes[4];
|
||||
assert_eq!(version, 1, "schema version at offset 4 must be 1, got {}", version);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Error path: version mismatch
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Overwrite version byte with 99 → expect VersionMismatch { got: 99, want: 1 }.
|
||||
#[test]
|
||||
fn should_return_version_mismatch_for_version_99() {
|
||||
let baseline = build_ht20_baseline();
|
||||
let mut bytes = baseline.to_bytes();
|
||||
// Version is at offset 4 (u8)
|
||||
bytes[4] = 99;
|
||||
|
||||
let result = BaselineCalibration::from_bytes(&bytes);
|
||||
match result {
|
||||
Err(CalibrationError::VersionMismatch { got, want }) => {
|
||||
assert_eq!(got, 99, "VersionMismatch.got should be 99");
|
||||
assert_eq!(want, 1, "VersionMismatch.want should be 1");
|
||||
}
|
||||
other => panic!(
|
||||
"expected CalibrationError::VersionMismatch, got {:?}",
|
||||
other
|
||||
),
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Error path: truncated buffer
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Trim the last 4 bytes → expect TruncatedBuffer.
|
||||
#[test]
|
||||
fn should_return_truncated_buffer_error_for_short_input() {
|
||||
let baseline = build_ht20_baseline();
|
||||
let mut bytes = baseline.to_bytes();
|
||||
let new_len = bytes.len().saturating_sub(4);
|
||||
bytes.truncate(new_len);
|
||||
|
||||
let result = BaselineCalibration::from_bytes(&bytes);
|
||||
assert!(
|
||||
matches!(result, Err(CalibrationError::TruncatedBuffer { .. })),
|
||||
"expected TruncatedBuffer, got {:?}",
|
||||
result
|
||||
);
|
||||
}
|
||||
|
||||
/// A completely empty buffer → expect TruncatedBuffer.
|
||||
#[test]
|
||||
fn should_return_truncated_buffer_for_empty_input() {
|
||||
let result = BaselineCalibration::from_bytes(&[]);
|
||||
assert!(
|
||||
matches!(result, Err(CalibrationError::TruncatedBuffer { .. })),
|
||||
"expected TruncatedBuffer for empty buffer, got {:?}",
|
||||
result
|
||||
);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Error path: magic word mismatch
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Zero out the first 4 bytes (magic word) → expect InvalidMagic error.
|
||||
#[test]
|
||||
fn should_return_error_for_zeroed_magic_word() {
|
||||
let baseline = build_ht20_baseline();
|
||||
let mut bytes = baseline.to_bytes();
|
||||
bytes[0] = 0;
|
||||
bytes[1] = 0;
|
||||
bytes[2] = 0;
|
||||
bytes[3] = 0;
|
||||
|
||||
let result = BaselineCalibration::from_bytes(&bytes);
|
||||
assert!(
|
||||
matches!(result, Err(CalibrationError::InvalidMagic { .. })),
|
||||
"expected InvalidMagic when magic word is zeroed, got {:?}",
|
||||
result
|
||||
);
|
||||
}
|
||||
|
|
@ -0,0 +1,484 @@
|
|||
//! Deterministic synthetic channel tests for the empty-room baseline calibration
|
||||
//! module (ADR-135).
|
||||
//!
|
||||
//! Validates Welford online statistics, deviation scoring, and per-PHY-tier
|
||||
//! subcarrier counts. Tests are seeded with literal `42` via xorshift32 and are
|
||||
//! fully deterministic.
|
||||
//!
|
||||
//! Run (compile-only):
|
||||
//! cargo test -p wifi-densepose-signal --no-default-features --tests --no-run
|
||||
|
||||
use std::f32::consts::PI;
|
||||
|
||||
use ndarray::Array2;
|
||||
use num_complex::Complex64;
|
||||
use wifi_densepose_core::types::{AntennaConfig, CsiFrame, CsiMetadata, DeviceId, FrequencyBand};
|
||||
use wifi_densepose_signal::calibration::{
|
||||
BaselineCalibration, CalibrationConfig, CalibrationRecorder,
|
||||
};
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Deterministic PRNG (xorshift32, seed=42) — duplicated locally per ADR-135
|
||||
// constraint: do not refactor existing test helpers.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
struct Rng(u32);
|
||||
|
||||
impl Rng {
|
||||
fn new(seed: u32) -> Self {
|
||||
assert_ne!(seed, 0, "xorshift seed must be non-zero");
|
||||
Self(seed)
|
||||
}
|
||||
|
||||
fn next_u32(&mut self) -> u32 {
|
||||
let mut x = self.0;
|
||||
x ^= x << 13;
|
||||
x ^= x >> 17;
|
||||
x ^= x << 5;
|
||||
self.0 = x;
|
||||
x
|
||||
}
|
||||
|
||||
/// Sample N(0,1) via Box-Muller (always consumes two draws).
|
||||
fn next_normal(&mut self) -> f32 {
|
||||
let u1 = (self.next_u32() as f32 + 1.0) / (u32::MAX as f32 + 2.0);
|
||||
let u2 = (self.next_u32() as f32 + 1.0) / (u32::MAX as f32 + 2.0);
|
||||
let r = (-2.0 * u1.ln()).sqrt();
|
||||
let theta = 2.0 * PI * u2;
|
||||
r * theta.cos()
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Tier parameters
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
struct TierSpec {
|
||||
label: &'static str,
|
||||
n_active: usize, // active (non-pilot) subcarriers passed in frame
|
||||
bandwidth_mhz: u16,
|
||||
config: CalibrationConfig,
|
||||
}
|
||||
|
||||
fn ht20_spec() -> TierSpec {
|
||||
TierSpec { label: "HT20", n_active: 52, bandwidth_mhz: 20, config: CalibrationConfig::ht20() }
|
||||
}
|
||||
fn ht40_spec() -> TierSpec {
|
||||
TierSpec { label: "HT40", n_active: 114, bandwidth_mhz: 40, config: CalibrationConfig::ht40() }
|
||||
}
|
||||
fn he20_spec() -> TierSpec {
|
||||
TierSpec { label: "HE20", n_active: 242, bandwidth_mhz: 20, config: CalibrationConfig::he20() }
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Ground-truth per-subcarrier channel parameters
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn ground_truth_amp(n: usize) -> Vec<f32> {
|
||||
(0..n).map(|k| 0.3 + 0.7 * (k as f32 * PI / n as f32).sin().abs()).collect()
|
||||
}
|
||||
|
||||
fn ground_truth_phase(n: usize) -> Vec<f32> {
|
||||
(0..n).map(|k| (k as f32 * 0.1).rem_euclid(2.0 * PI) - PI).collect()
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// CSI frame builder helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn make_stationary_frame(
|
||||
bandwidth_mhz: u16,
|
||||
n_active: usize,
|
||||
amp: &[f32],
|
||||
phase: &[f32],
|
||||
snr_db: f32,
|
||||
rng: &mut Rng,
|
||||
) -> CsiFrame {
|
||||
assert_eq!(amp.len(), n_active);
|
||||
let signal_power: f32 = amp.iter().map(|a| a * a).sum::<f32>() / n_active as f32;
|
||||
let noise_power = signal_power / 10_f32.powf(snr_db / 10.0);
|
||||
let noise_std = (noise_power / 2.0).sqrt();
|
||||
|
||||
let mut data = Array2::<Complex64>::zeros((1, n_active));
|
||||
for k in 0..n_active {
|
||||
let re = amp[k] * phase[k].cos() + noise_std * rng.next_normal();
|
||||
let im = amp[k] * phase[k].sin() + noise_std * rng.next_normal();
|
||||
data[(0, k)] = Complex64::new(re as f64, im as f64);
|
||||
}
|
||||
let mut meta = CsiMetadata::new(DeviceId::new("test"), FrequencyBand::Band2_4GHz, 6);
|
||||
meta.bandwidth_mhz = bandwidth_mhz;
|
||||
meta.antenna_config = AntennaConfig::new(1, 1);
|
||||
CsiFrame::new(meta, data)
|
||||
}
|
||||
|
||||
/// Build a frame where subcarrier amplitudes are shifted up by `shift_sigma * sigma`.
|
||||
fn make_perturbed_frame(
|
||||
bandwidth_mhz: u16,
|
||||
n_active: usize,
|
||||
amp: &[f32],
|
||||
phase: &[f32],
|
||||
amp_sigma: f32,
|
||||
perturb_indices: &[usize],
|
||||
shift_sigma: f32,
|
||||
rng: &mut Rng,
|
||||
) -> CsiFrame {
|
||||
let noise_std = 0.001_f32;
|
||||
let mut data = Array2::<Complex64>::zeros((1, n_active));
|
||||
for k in 0..n_active {
|
||||
let extra = if perturb_indices.contains(&k) { shift_sigma * amp_sigma } else { 0.0 };
|
||||
let a = amp[k] + extra;
|
||||
let re = a * phase[k].cos() + noise_std * rng.next_normal();
|
||||
let im = a * phase[k].sin() + noise_std * rng.next_normal();
|
||||
data[(0, k)] = Complex64::new(re as f64, im as f64);
|
||||
}
|
||||
let mut meta = CsiMetadata::new(DeviceId::new("test"), FrequencyBand::Band2_4GHz, 6);
|
||||
meta.bandwidth_mhz = bandwidth_mhz;
|
||||
meta.antenna_config = AntennaConfig::new(1, 1);
|
||||
CsiFrame::new(meta, data)
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Helper: build a finalised baseline from 600 stationary frames at SNR=30 dB
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn build_baseline(spec: &TierSpec) -> BaselineCalibration {
|
||||
let amp = ground_truth_amp(spec.n_active);
|
||||
let phase = ground_truth_phase(spec.n_active);
|
||||
let mut rng = Rng::new(42);
|
||||
let mut recorder = CalibrationRecorder::new(spec.config.clone());
|
||||
for _ in 0..600 {
|
||||
let frame = make_stationary_frame(
|
||||
spec.bandwidth_mhz, spec.n_active, &, &phase, 30.0, &mut rng,
|
||||
);
|
||||
recorder.record(&frame).expect("record should succeed");
|
||||
}
|
||||
recorder.finalize().expect("finalize should succeed with 600 frames")
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Tests — HT20
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
mod ht20 {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn should_record_600_frames_when_600_fed() {
|
||||
let spec = ht20_spec();
|
||||
let amp = ground_truth_amp(spec.n_active);
|
||||
let phase = ground_truth_phase(spec.n_active);
|
||||
let mut rng = Rng::new(42);
|
||||
let mut recorder = CalibrationRecorder::new(spec.config.clone());
|
||||
for _ in 0..600 {
|
||||
let frame = make_stationary_frame(
|
||||
spec.bandwidth_mhz, spec.n_active, &, &phase, 30.0, &mut rng,
|
||||
);
|
||||
recorder.record(&frame).expect("record should succeed");
|
||||
}
|
||||
assert_eq!(
|
||||
recorder.frames_recorded(), 600,
|
||||
"HT20: frames_recorded() should equal 600"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn should_finalize_with_amp_mean_within_tolerance_of_ground_truth() {
|
||||
let spec = ht20_spec();
|
||||
let amp = ground_truth_amp(spec.n_active);
|
||||
let baseline = build_baseline(&spec);
|
||||
let tol = 0.05_f32;
|
||||
for k in 0..spec.n_active {
|
||||
let got = baseline.subcarriers[k].amp_mean;
|
||||
let expected = amp[k];
|
||||
assert!(
|
||||
(got - expected).abs() < tol,
|
||||
"HT20 amp_mean[{}]: got={:.4} expected={:.4} tol={:.4}",
|
||||
k, got, expected, tol
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn should_have_positive_amp_variance_after_finalize() {
|
||||
let spec = ht20_spec();
|
||||
let baseline = build_baseline(&spec);
|
||||
for k in 0..spec.n_active {
|
||||
assert!(
|
||||
baseline.subcarriers[k].amp_variance > 0.0,
|
||||
"HT20 amp_variance[{}] must be positive",
|
||||
k
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn should_have_small_amp_variance_for_stationary_channel() {
|
||||
let spec = ht20_spec();
|
||||
let baseline = build_baseline(&spec);
|
||||
for k in 0..spec.n_active {
|
||||
assert!(
|
||||
baseline.subcarriers[k].amp_variance < 0.1,
|
||||
"HT20 amp_variance[{}]={:.6} must be < 0.1",
|
||||
k, baseline.subcarriers[k].amp_variance
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn should_have_tight_phase_dispersion_for_stationary_channel() {
|
||||
let spec = ht20_spec();
|
||||
let baseline = build_baseline(&spec);
|
||||
for k in 0..spec.n_active {
|
||||
assert!(
|
||||
baseline.subcarriers[k].phase_dispersion < 0.05,
|
||||
"HT20 phase_dispersion[{}]={:.6} must be < 0.05",
|
||||
k, baseline.subcarriers[k].phase_dispersion
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn should_not_flag_motion_for_stationary_frame() {
|
||||
let spec = ht20_spec();
|
||||
let amp = ground_truth_amp(spec.n_active);
|
||||
let phase = ground_truth_phase(spec.n_active);
|
||||
let baseline = build_baseline(&spec);
|
||||
let mut rng = Rng::new(999);
|
||||
let frame = make_stationary_frame(
|
||||
spec.bandwidth_mhz, spec.n_active, &, &phase, 30.0, &mut rng,
|
||||
);
|
||||
let score = baseline.deviation(&frame).expect("deviation should succeed");
|
||||
assert!(
|
||||
score.amplitude_z_median < 1.5,
|
||||
"HT20 stationary: amplitude_z_median={:.3} must be < 1.5",
|
||||
score.amplitude_z_median
|
||||
);
|
||||
assert!(
|
||||
!score.motion_flagged,
|
||||
"HT20 stationary: motion_flagged must be false"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn should_flag_motion_for_3sigma_perturbed_frame() {
|
||||
let spec = ht20_spec();
|
||||
let amp = ground_truth_amp(spec.n_active);
|
||||
let phase = ground_truth_phase(spec.n_active);
|
||||
let baseline = build_baseline(&spec);
|
||||
// Use mean amp_variance as the sigma estimate
|
||||
let amp_sigma: f32 = baseline
|
||||
.subcarriers
|
||||
.iter()
|
||||
.map(|sc| sc.amp_variance.sqrt())
|
||||
.sum::<f32>()
|
||||
/ spec.n_active as f32;
|
||||
let perturb_indices: Vec<usize> = (0..spec.n_active).collect();
|
||||
let mut rng = Rng::new(999);
|
||||
let frame = make_perturbed_frame(
|
||||
spec.bandwidth_mhz, spec.n_active, &, &phase, amp_sigma,
|
||||
&perturb_indices, 3.0, &mut rng,
|
||||
);
|
||||
let score = baseline.deviation(&frame).expect("deviation should succeed");
|
||||
assert!(
|
||||
score.amplitude_z_median > 2.5,
|
||||
"HT20 perturbed: amplitude_z_median={:.3} must be > 2.5",
|
||||
score.amplitude_z_median
|
||||
);
|
||||
assert!(
|
||||
score.motion_flagged,
|
||||
"HT20 perturbed: motion_flagged must be true for 3σ perturbation"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Tests — HT40
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
mod ht40 {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn should_record_600_frames_when_600_fed() {
|
||||
let spec = ht40_spec();
|
||||
let amp = ground_truth_amp(spec.n_active);
|
||||
let phase = ground_truth_phase(spec.n_active);
|
||||
let mut rng = Rng::new(42);
|
||||
let mut recorder = CalibrationRecorder::new(spec.config.clone());
|
||||
for _ in 0..600 {
|
||||
let frame = make_stationary_frame(
|
||||
spec.bandwidth_mhz, spec.n_active, &, &phase, 30.0, &mut rng,
|
||||
);
|
||||
recorder.record(&frame).expect("record should succeed");
|
||||
}
|
||||
assert_eq!(recorder.frames_recorded(), 600, "HT40: frames_recorded() should equal 600");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn should_finalize_with_amp_mean_within_tolerance() {
|
||||
let spec = ht40_spec();
|
||||
let amp = ground_truth_amp(spec.n_active);
|
||||
let baseline = build_baseline(&spec);
|
||||
let tol = 0.05_f32;
|
||||
for k in 0..spec.n_active {
|
||||
let got = baseline.subcarriers[k].amp_mean;
|
||||
let expected = amp[k];
|
||||
assert!(
|
||||
(got - expected).abs() < tol,
|
||||
"HT40 amp_mean[{}]: got={:.4} expected={:.4} tol={:.4}",
|
||||
k, got, expected, tol
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn should_have_tight_phase_dispersion_for_stationary_channel() {
|
||||
let spec = ht40_spec();
|
||||
let baseline = build_baseline(&spec);
|
||||
for k in 0..spec.n_active {
|
||||
assert!(
|
||||
baseline.subcarriers[k].phase_dispersion < 0.05,
|
||||
"HT40 phase_dispersion[{}]={:.6} must be < 0.05",
|
||||
k, baseline.subcarriers[k].phase_dispersion
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn should_not_flag_motion_for_stationary_frame() {
|
||||
let spec = ht40_spec();
|
||||
let amp = ground_truth_amp(spec.n_active);
|
||||
let phase = ground_truth_phase(spec.n_active);
|
||||
let baseline = build_baseline(&spec);
|
||||
let mut rng = Rng::new(999);
|
||||
let frame = make_stationary_frame(
|
||||
spec.bandwidth_mhz, spec.n_active, &, &phase, 30.0, &mut rng,
|
||||
);
|
||||
let score = baseline.deviation(&frame).expect("deviation should succeed");
|
||||
assert!(
|
||||
!score.motion_flagged,
|
||||
"HT40 stationary: motion_flagged must be false"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn should_flag_motion_for_3sigma_perturbed_frame() {
|
||||
let spec = ht40_spec();
|
||||
let amp = ground_truth_amp(spec.n_active);
|
||||
let phase = ground_truth_phase(spec.n_active);
|
||||
let baseline = build_baseline(&spec);
|
||||
let amp_sigma: f32 = baseline
|
||||
.subcarriers
|
||||
.iter()
|
||||
.map(|sc| sc.amp_variance.sqrt())
|
||||
.sum::<f32>()
|
||||
/ spec.n_active as f32;
|
||||
let perturb_indices: Vec<usize> = (0..spec.n_active).collect();
|
||||
let mut rng = Rng::new(999);
|
||||
let frame = make_perturbed_frame(
|
||||
spec.bandwidth_mhz, spec.n_active, &, &phase, amp_sigma,
|
||||
&perturb_indices, 3.0, &mut rng,
|
||||
);
|
||||
let score = baseline.deviation(&frame).expect("deviation should succeed");
|
||||
assert!(
|
||||
score.motion_flagged,
|
||||
"HT40 perturbed: motion_flagged must be true for 3σ perturbation"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Tests — HE20
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
mod he20 {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn should_record_600_frames_when_600_fed() {
|
||||
let spec = he20_spec();
|
||||
let amp = ground_truth_amp(spec.n_active);
|
||||
let phase = ground_truth_phase(spec.n_active);
|
||||
let mut rng = Rng::new(42);
|
||||
let mut recorder = CalibrationRecorder::new(spec.config.clone());
|
||||
for _ in 0..600 {
|
||||
let frame = make_stationary_frame(
|
||||
spec.bandwidth_mhz, spec.n_active, &, &phase, 30.0, &mut rng,
|
||||
);
|
||||
recorder.record(&frame).expect("record should succeed");
|
||||
}
|
||||
assert_eq!(recorder.frames_recorded(), 600, "HE20: frames_recorded() should equal 600");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn should_finalize_with_amp_mean_within_tolerance() {
|
||||
let spec = he20_spec();
|
||||
let amp = ground_truth_amp(spec.n_active);
|
||||
let baseline = build_baseline(&spec);
|
||||
let tol = 0.05_f32;
|
||||
for k in 0..spec.n_active {
|
||||
let got = baseline.subcarriers[k].amp_mean;
|
||||
let expected = amp[k];
|
||||
assert!(
|
||||
(got - expected).abs() < tol,
|
||||
"HE20 amp_mean[{}]: got={:.4} expected={:.4} tol={:.4}",
|
||||
k, got, expected, tol
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn should_have_tight_phase_dispersion_for_stationary_channel() {
|
||||
let spec = he20_spec();
|
||||
let baseline = build_baseline(&spec);
|
||||
for k in 0..spec.n_active {
|
||||
assert!(
|
||||
baseline.subcarriers[k].phase_dispersion < 0.05,
|
||||
"HE20 phase_dispersion[{}]={:.6} must be < 0.05",
|
||||
k, baseline.subcarriers[k].phase_dispersion
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn should_not_flag_motion_for_stationary_frame() {
|
||||
let spec = he20_spec();
|
||||
let amp = ground_truth_amp(spec.n_active);
|
||||
let phase = ground_truth_phase(spec.n_active);
|
||||
let baseline = build_baseline(&spec);
|
||||
let mut rng = Rng::new(999);
|
||||
let frame = make_stationary_frame(
|
||||
spec.bandwidth_mhz, spec.n_active, &, &phase, 30.0, &mut rng,
|
||||
);
|
||||
let score = baseline.deviation(&frame).expect("deviation should succeed");
|
||||
assert!(
|
||||
!score.motion_flagged,
|
||||
"HE20 stationary: motion_flagged must be false"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn should_flag_motion_for_3sigma_perturbed_frame() {
|
||||
let spec = he20_spec();
|
||||
let amp = ground_truth_amp(spec.n_active);
|
||||
let phase = ground_truth_phase(spec.n_active);
|
||||
let baseline = build_baseline(&spec);
|
||||
let amp_sigma: f32 = baseline
|
||||
.subcarriers
|
||||
.iter()
|
||||
.map(|sc| sc.amp_variance.sqrt())
|
||||
.sum::<f32>()
|
||||
/ spec.n_active as f32;
|
||||
let perturb_indices: Vec<usize> = (0..spec.n_active).collect();
|
||||
let mut rng = Rng::new(999);
|
||||
let frame = make_perturbed_frame(
|
||||
spec.bandwidth_mhz, spec.n_active, &, &phase, amp_sigma,
|
||||
&perturb_indices, 3.0, &mut rng,
|
||||
);
|
||||
let score = baseline.deviation(&frame).expect("deviation should succeed");
|
||||
assert!(
|
||||
score.motion_flagged,
|
||||
"HE20 perturbed: motion_flagged must be true for 3σ perturbation"
|
||||
);
|
||||
}
|
||||
}
|
||||
Loading…
Reference in New Issue