From 677b3ac31bc123155063d0c9dce861fff3e4a119 Mon Sep 17 00:00:00 2001 From: ruv Date: Fri, 15 May 2026 07:41:57 -0400 Subject: [PATCH] =?UTF-8?q?docs(firmware):=20truth-up=20Tier=202=20wording?= =?UTF-8?q?=20=E2=80=94=20slot-capacity=20heuristic,=20not=20learned=20per?= =?UTF-8?q?son=20counter=20(closes=20#568)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit @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 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. Co-Authored-By: claude-flow --- firmware/esp32-csi-node/README.md | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/firmware/esp32-csi-node/README.md b/firmware/esp32-csi-node/README.md index a3cfe28d..e31c527c 100644 --- a/firmware/esp32-csi-node/README.md +++ b/firmware/esp32-csi-node/README.md @@ -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 | @@ -129,11 +129,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.