149 lines
6.3 KiB
Markdown
149 lines
6.3 KiB
Markdown
# ESPectre Gap Analysis (full Pace Part-2 vs. RuView as of 2026-05-17)
|
||
|
||
Companion to [`espectre-techniques.md`](espectre-techniques.md). That
|
||
doc is the technique catalogue; this one is the **what's still
|
||
missing** breakdown, structured exactly along the sections of Pace's
|
||
*How I Turned My Wi-Fi Into a Motion Sensor — Part 2*.
|
||
|
||
## Problem #1: NBVI subcarrier selection
|
||
|
||
| Pace step | Status in RuView |
|
||
|---|---|
|
||
| Formula `α·σ/μ² + (1-α)·σ/μ`, α = 0.5 | ✅ ADR-102 |
|
||
| Step 1: quiet-window finder | ✅ ADR-102 v2 |
|
||
| Step 2: 25 %-percentile dead-zone gate | ✅ ADR-102 |
|
||
| **Step 3: rank + validate (run motion detector on the calibration buffer, pick K with lowest FP rate)** | ❌ raw ranking accepted |
|
||
| Step 4: pick top-K (K=12) | ✅ ADR-102 |
|
||
| Amplitude only (no phase) | ✅ same |
|
||
|
||
Step 3 absence means a noisy WiFi neighbour with energy concentrated
|
||
on our top-12 subcarriers would still get picked. Defence: validate.
|
||
|
||
## Problem #2: Gain Lock (AGC + FFT)
|
||
|
||
✅ **All done** — ADR-100. Median over 300 packets, `MIN_SAFE_AGC=30`
|
||
skip-on-strong-signal safety, ESP32-S3/C3/C6 platform guards.
|
||
|
||
## Problem #3: Universal threshold via baseline-variance normalization
|
||
|
||
✅ **Done** — ADR-103 D3. Pace's `scale = 0.25 / baseline_variance`
|
||
implemented as `norm_cv = cv / baseline_cv` with universal gates
|
||
`3×` (moving) / `6×` (active). Falls back to absolute gates when no
|
||
calibration loaded.
|
||
|
||
## Two-phase boot calibration (~10 s total)
|
||
|
||
Pace runs both phases as a single atomic boot sequence on the device:
|
||
|
||
```
|
||
PHASE 1 (3 s) collect AGC/FFT → median → lock
|
||
PHASE 2 (7 s) rank subcarriers with gain locked → save top-K to NVS
|
||
```
|
||
|
||
| Phase | Status in RuView |
|
||
|---|---|
|
||
| Phase 1 in FW | ✅ ADR-100 (`csi_collector.c::rv_gain_lock_process`) |
|
||
| **Phase 2 in FW after Phase 1** | ❌ NBVI lives in the server as a rolling refresh, not a boot-time freeze |
|
||
| **NVS save of both lock + selection** | ❌ each FW boot re-calibrates gain; NBVI re-ranks every server boot |
|
||
|
||
Doing Phase 2 in FW would mean reboot → ready in 0.5 s instead of
|
||
~10 s. Trade-off: doesn't adapt to room changes without explicit
|
||
re-calibration.
|
||
|
||
## Persisted calibration (NVS on the sensor)
|
||
|
||
Pace stores **everything** the algorithm needs in NVS on first boot,
|
||
so post-reboot the sensor is back in detect mode in well under a
|
||
second:
|
||
|
||
* AGC lock value
|
||
* FFT lock value
|
||
* Selected subcarrier indices
|
||
* Baseline variance
|
||
* User-tuned threshold
|
||
|
||
| Item | Status in RuView |
|
||
|---|---|
|
||
| WiFi creds + collector IP in NVS | ✅ `csi_cfg` namespace |
|
||
| **Gain lock NVS persistence** | ❌ recomputed on every FW boot |
|
||
| **NBVI selection NVS persistence** | ❌ recomputed on every server boot |
|
||
| **Baseline NVS persistence** | partial — server persists to disk (ADR-103), not on the sensor |
|
||
| **Threshold NVS persistence** | ❌ universal threshold loaded from `data/baseline.json` server-side |
|
||
|
||
If we ever ship to operators who don't run the Rust server (pure FW
|
||
+ HA), all of these become required.
|
||
|
||
## The Game (Web Serial calibration UI)
|
||
|
||
❌ **Not done.** Pace ships a browser-based reaction game at
|
||
`espectre.dev/game` that talks to the ESP32 directly over Web Serial
|
||
API (USB-CDC). The game shows a live motion bar, lets the user tune
|
||
threshold while playing, and persists the chosen threshold to NVS.
|
||
|
||
Our closest analogue is the read-only `raw.html` calibration console
|
||
(per-node amplitude bars + RSSI traces + classification badges)
|
||
served by sensing-server on `/static/raw.html`. No interactive
|
||
threshold tuning; no Web Serial path; no game.
|
||
|
||
## Testing
|
||
|
||
| Pace ships | RuView has |
|
||
|---|---|
|
||
| 500+ unit tests | small smoke tests in some crates |
|
||
| 90 % code coverage | not tracked |
|
||
| Fixed 2 000-packet reference capture (1 000 idle + 1 000 motion) | none — we test live on the operator's deployment |
|
||
| PlatformIO + pytest + ESPHome + Codecov on every push | partial — Rust `cargo test` only; 2 parser regression tests added by parallel agent (`csi.rs:751`) |
|
||
|
||
This is the largest reliability gap. A 2 000-packet replay against
|
||
the classifier would protect against silent regressions when we
|
||
re-tune thresholds or refactor NBVI.
|
||
|
||
## Native Home Assistant integration via ESPHome
|
||
|
||
❌ **Not done.** Pace's sensor shows up in HA the moment it's
|
||
flashed — `binary_sensor.motion_<room>` entity with attributes.
|
||
ESPHome handles MQTT / native API / device discovery automatically.
|
||
|
||
RuView publishes via WebSocket and REST only; would need either an
|
||
ESPHome component, an MQTT bridge, or a custom HA integration.
|
||
|
||
## Hardware support
|
||
|
||
* Pace supports ESP32-S3, ESP32-C3, ESP32-C5, ESP32-C6. Gain-lock is
|
||
guarded on these targets only; ESP32 + ESP32-S2 fall back to no
|
||
gain lock.
|
||
* RuView gain-lock code has the same `#if` guard so the same
|
||
hardware list works — but we only have hands-on test data for
|
||
ESP32-S3.
|
||
|
||
## What Pace announces for Part 3 (not yet shipped, not yet on our
|
||
## radar either)
|
||
|
||
* Gesture recognition
|
||
* Fall detection
|
||
* Person vs. pet classification
|
||
|
||
## Priority for RuView, ranked by expected impact
|
||
|
||
| # | Item | Net benefit | Estimate |
|
||
|---|---|---|---|
|
||
| 1 | NVS persistence + boot-time NBVI freeze in FW | reboot → ready in 0.5 s instead of ~10 s; survives server outage | 3-4 h |
|
||
| 2 | FP-rate validation of NBVI Step 3 | defence against noise-source subcarrier overlap | 1 h |
|
||
| 3 | `POST /api/v1/baseline/calibrate` + button in `raw.html` | calibrate from browser instead of CLI script | 30 min |
|
||
| 4 | Auto-recalibrate on long-quiet periods | drops the manual step entirely | 1-2 h |
|
||
| 5 | HA via MQTT (lighter than full ESPHome rewrite) | sensor as HA entity | 1 day |
|
||
| 6 | Fixed-replay test suite (2 000 packets) | regression protection | 1 day |
|
||
| 7 | Per-subcarrier baseline comparison (ADR-104 draft) | off-axis presence detection | 1 h |
|
||
| 8 | Web Serial calibration game | nice-to-have | 1 day |
|
||
| 9 | ESPHome native component (instead of MQTT bridge) | tighter HA integration | 2-3 days |
|
||
|
||
## References
|
||
|
||
* [`espectre-techniques.md`](espectre-techniques.md) — technique catalogue
|
||
* [ADR-100](../adr/ADR-100-gain-lock-baseline-stabilization.md) — gain lock
|
||
* [ADR-101](../adr/ADR-101-raw-amplitude-classifier.md) — classifier
|
||
* [ADR-102](../adr/ADR-102-nbvi-subcarrier-selection.md) — NBVI
|
||
* [ADR-103](../adr/ADR-103-persistent-baseline.md) — baseline persistence
|
||
* Pace, *How I Turned My Wi-Fi Into a Motion Sensor — Part 2*, Dec 2025
|
||
* `francescopace/espectre` on GitHub (GPLv3)
|