docs(firmware): truth-up Tier 2 wording — slot-capacity heuristic, not learned person counter (#573)

@xiaofuchen's code audit in #568 was correct: the firmware's
`pkt.n_persons` is `s_top_k_count / 2` (clamped) — a subcarrier-slot
partition, not a learned classifier. The README's old wording
('Multi-person estimation', 'Presence sensing') reads stronger than
`edge_processing.c:481-548` actually supports. Same-direction fix as
commit bd4f81749 (which retracted the 92.9% PCK@20 claim because
ADR-079's eval phases are still Pending) and ADR-099 §D8 (which
honestly amended the 10× latency target because it's unreachable on
1-D scalar features).

Three things this commit changes:

1. **Headline-table 'Presence sensing' -> 'Presence indicator (heuristic)'.**
   Adds an explicit caveat that strong RF interference can false-positive
   without re-calibration, with a link to the detailed Tier-2 section.
   The marketing word 'sensing' implied a classifier; the code is a
   variance threshold.

2. **Tier-2 bullet 'Multi-person estimation' -> 'Multi-person slot count'.**
   Now reads:

     'partitions the top-K subcarriers into top_k / 2 groups (clamped to
     [1, EDGE_MAX_PERSONS]), computes per-group filtered breathing/heart-
     rate estimates, and reports the slot count as pkt.n_persons. This
     is a slot-capacity heuristic, not a learned counter — the reported
     count tracks subcarrier diversity, not actual occupancy.'

   Links directly to `main/edge_processing.c:481-548` so the user can
   verify the claim against the code.

3. **New 'What this firmware does NOT do (Tier 2 caveats)' subsection.**
   Three explicit non-claims:

   - No trained neural model on the ESP32 — the person count is
     arithmetic, not inference.
   - No pose estimation on the ESP32; pose comes from the host's Rust
     server, and only runs learned inference when --model <rvf-file> is
     passed. Without a trained model, the host runs signal-based
     heuristics, not keypoint inference. Same point as #509 / #506.
   - Presence indicator false-positives under fans/microwaves/AP TX
     swings without re-running the 60 s ambient calibration. Notes the
     concrete remedy (power-cycle in an empty room).

Closes #568.
This commit is contained in:
rUv 2026-05-17 17:31:51 -04:00 committed by GitHub
parent 3685d16a49
commit ea62ec4667
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 24 additions and 3 deletions

View File

@ -15,7 +15,7 @@ This firmware captures WiFi Channel State Information (CSI) from an ESP32-S3 and
> | **CSI streaming** | Per-subcarrier I/Q capture over UDP | ~20 Hz, ADR-018 binary format |
> | **Breathing detection** | Bandpass 0.1-0.5 Hz, zero-crossing BPM | 6-30 BPM |
> | **Heart rate** | Bandpass 0.8-2.0 Hz, zero-crossing BPM | 40-120 BPM |
> | **Presence sensing** | Phase variance + adaptive calibration | < 1 ms latency |
> | **Presence indicator** (heuristic) | Phase variance + adaptive threshold (60 s ambient learning) | < 1 ms latency, false-positives under strong RF interference see [Tier 2 caveats](#what-this-firmware-does-not-do-tier-2-caveats) |
> | **Fall detection** | Phase acceleration threshold | Configurable sensitivity |
> | **Programmable sensing** | WASM modules loaded over HTTP | Hot-swap, no reflash |
@ -133,11 +133,32 @@ Adds real-time health and safety monitoring.
- **Breathing rate** -- biquad IIR bandpass 0.1-0.5 Hz, zero-crossing BPM (6-30 BPM)
- **Heart rate** -- biquad IIR bandpass 0.8-2.0 Hz, zero-crossing BPM (40-120 BPM)
- **Presence detection** -- adaptive threshold calibration (60 s ambient learning)
- **Presence indicator** -- phase variance vs an adaptively-calibrated threshold (60 s ambient learning at boot). Heuristic, not a learned classifier — strong RF interferers (fans, microwaves, transmit-power swings) can push variance above threshold without anyone in the room. See "What this firmware does NOT do" below.
- **Fall detection** -- phase acceleration exceeds configurable threshold
- **Multi-person estimation** -- subcarrier group clustering (up to 4 persons)
- **Multi-person slot count** -- partitions the top-K subcarriers into `top_k / 2` groups (clamped to `[1, EDGE_MAX_PERSONS]`), computes per-group filtered breathing/heart-rate estimates, and reports the slot count as `pkt.n_persons`. This is a **slot-capacity heuristic**, not a learned counter — the reported count tracks subcarrier diversity, not actual occupancy. See [`edge_processing.c:481-548`](main/edge_processing.c#L481-L548).
- **Vitals packet** -- 32-byte UDP packet at 1 Hz (magic `0xC5110002`)
### What this firmware does NOT do (Tier 2 caveats)
- It does **not** run a trained neural model. The "person count" is an
arithmetic slot-capacity heuristic over the top-K subcarrier groups
(`firmware/esp32-csi-node/main/edge_processing.c:481`). It tracks
subcarrier diversity, not actual occupancy.
- It does **not** run pose estimation. Pose-related features in the host
UI come from the Rust `wifi-densepose-sensing-server` running a separate
pipeline. When no `.rvf` model file is loaded via `--model`, the server
drives the on-screen skeleton from signal-based heuristics (amplitude
variance, motion-band power), not from learned keypoint inference. The
repository does not ship pre-trained weights — see issues
[#509](../../issues/509) and [#506](../../issues/506) for context, and
[ADR-079](../../docs/adr/ADR-079-camera-supervised-pose-finetune.md) for
the planned training path (phases P7-P9 are `Pending`).
- The presence indicator is a calibrated variance threshold and **will
false-positive** under strong RF interference from non-human sources
(fans near the antenna, microwave duty cycles, neighbouring AP power
swings) without re-running the 60-second ambient calibration. If you
see ghost detections, re-calibrate by power-cycling in an empty room.
### Tier 3 -- WASM Programmable Sensing (Alpha)
Turns the ESP32 from a fixed-function sensor into a programmable sensing computer. Instead of reflashing firmware to change algorithms, you upload new sensing logic as small WASM modules -- compiled from Rust, packaged in signed RVF containers.