ruvnet--RuView/api-docs/calibration-guide.md

# Calibration & Room Training Guide

This guide explains what actually happens — and what is actually *enforced* —
when you run `wifi-densepose calibrate`, `enroll`, and `train-room`. It is
written for the person setting up a room, not for developers.

Everything below was checked against the real Rust implementation in
`v2/crates/wifi-densepose-calibration/`, `v2/crates/wifi-densepose-signal/src/ruvsense/calibration.rs`,
and `v2/crates/wifi-densepose-cli/`, not just the design ADRs. Where the design
documents (ADR-135, ADR-151) describe something that isn't actually built yet,
this guide says so explicitly.

## The three-step pipeline

```
wifi-densepose calibrate --port <PORT>      # Stage 1: empty-room baseline (no people)
wifi-densepose enroll --room <NAME>         # Stage 2+3: 8 guided anchors (~4 minutes)
wifi-densepose train-room --room <NAME>     # Stage 4: fit the specialist bank
wifi-densepose room-status --room <NAME>    # check what trained / what's stale
wifi-densepose room-watch --room <NAME>     # live inference
```

`calibrate` must run first — `enroll` refuses to start without a baseline file
(`--baseline ./baseline.bin` by default), and `train-room` refuses to start
without an enrollment file. Each step writes a file the next step reads; there
is no way to skip a step.

---

## 1. Is there a minimum amount of data required?

**Yes, and for the empty-room baseline it is a hard, enforced minimum — not a
recommendation.**

`wifi-densepose calibrate` will not produce a baseline file with fewer than
**600 recorded frames** (the default for every PHY tier: HT20, HT40, HE20,
HE40). This is `DEFAULT_MIN_FRAMES = 600` in
`v2/crates/wifi-densepose-signal/src/ruvsense/calibration.rs:48`, and it is
checked in `CalibrationRecorder::finalize()`
(`ruvsense/calibration.rs:532-538`): if fewer than `config.min_frames` frames
were recorded, `finalize()` returns
`CalibrationError::InsufficientFrames { got, need }` and calibration fails
outright — there is no partial/degraded baseline. This is pinned by a unit
test (`finalize_requires_min_frames`, same file) so it isn't accidental
behavior.

**Important subtlety:** the CLI's `--duration-s` flag (default 30 seconds)
and the 600-frame minimum are checked *independently*. The capture loop in
`v2/crates/wifi-densepose-cli/src/calibrate.rs:135-183` stops as soon as
**either** the duration timer expires **or** 600 frames have been recorded,
whichever comes first. If your node streams CSI slower than the assumed 20 Hz
(e.g. congested WiFi, a busier ESP32), 30 seconds may not be enough to reach
600 frames, and `calibrate` will fail with an explicit
`"insufficient frames: have X, need 600"` error rather than silently
producing a short baseline. If you hit this, raise `--duration-s` rather than
overriding `--min-frames`.

You *can* override the 600-frame floor with `--min-frames <N>` (0 = use the
tier default). The code prints an explicit warning when you do:

> `[calibrate] WARN: --min-frames=N overrides ADR-135 tier default (600 for
> ht20). This relaxes the phase-concentration guarantee; do not use in
> production.`

(`v2/crates/wifi-densepose-cli/src/calibrate.rs:112-119`). Treat this as a
debugging escape hatch, not a supported way to shorten setup.

The CLI also independently rejects `--duration-s` below 10 seconds
(`"Fewer frames produce unreliable phase-concentration estimates"`,
`calibrate.rs:341-348`) and prints (but does not block on) a warning above 300
seconds.

**Guided enrollment (`enroll`) has a much lower, per-anchor floor.** Each of
the 8 guided anchors (`empty`, `stand_still`, `sit`, `lie_down`,
`breathe_slow`, `breathe_normal`, `small_move`, `sleep_posture`) is captured
for a fixed duration baked into the code — 20 seconds for the static/motion
anchors, 30 seconds for the two breathing anchors and `sleep_posture`
(`AnchorLabel::duration_s()`, `v2/crates/wifi-densepose-calibration/src/anchor.rs:98-104`).
This is **not** a CLI flag — you cannot currently shorten or lengthen an
individual anchor capture from the command line.

Underneath that fixed duration, the anchor is only *accepted* if it clears a
quality gate (`AnchorQualityGate`, `v2/crates/wifi-densepose-calibration/src/enrollment.rs:43-53`):

| Threshold | Default | What it checks |
|---|---|---|
| `min_frames` | **60 frames** | Anchor is rejected if fewer than 60 frames were captured — mainly catches "the ESP32 stopped streaming" mid-capture, not a real duration requirement (60 frames is a fraction of a second of streaming at typical rates) |
| `min_presence_z` | 1.5 | For anchors that expect a person, the mean amplitude z-score must exceed this or the anchor is rejected as "no person detected" |
| `empty_max_z` | 1.0 | For the `empty` anchor, the z-score must stay under this or it's rejected as "room not empty" |
| `max_still_motion` | 0.6 (60%) | For still anchors, motion-flagged frame fraction above this is rejected as "too much motion" |
| `min_move_motion` | 0.3 (30%) | For `small_move`, motion-flagged fraction below this is rejected as "not enough motion" |

A rejected anchor is re-prompted, up to `--attempts` times (default **2**).
If an anchor is still rejected after all attempts, `enroll` moves on without
it and logs `"moving on without '<label>'"` — enrollment does **not** abort;
you end up with a partial anchor set.

**`train-room` itself enforces almost nothing.** It only bails if the
enrollment file has *zero* accepted anchors at all
(`v2/crates/wifi-densepose-cli/src/room.rs:246-248`, `"no accepted anchors …
re-run enroll"`). There is no minimum anchor count beyond that. What actually
happens with a partial anchor set is that individual specialists silently
fail to train and are simply absent from the resulting bank — for example
(from `v2/crates/wifi-densepose-calibration/src/specialist.rs`):

- **presence** needs the `empty` anchor plus at least one anchor where a
  person was expected present — missing either, `PresenceSpecialist::train()`
  returns `None` and presence detection is unavailable in that bank.
- **anomaly** needs at least 2 anchors total, of any kind.
- **restlessness** needs `sleep_posture` (or `lie_down` as a fallback) *and*
  `small_move`.
- **posture** needs at least one anchor that establishes a posture
  (`stand_still`, `sit`, `lie_down`, or `sleep_posture`).

So a "successful" `train-room` run can still produce a bank missing one or
more specialists if enrollment didn't collect the anchors those specialists
need. `room-status` (`v2/crates/wifi-densepose-cli/src/room.rs`) is the way
to check what actually trained.

### What we could not verify

The ADR-151 design document (§2.2) claims total guided enrollment is
"~4 minutes of wall-clock" — that arithmetic checks out against the coded
per-anchor durations (5 × 20s + 3 × 30s = 190s ≈ 3.2 min, plus a 3-second
countdown before each anchor ≈ +24s, so ~3.5–4 minutes is consistent with the
code). But we found **no integration test or measurement showing that this
duration is sufficient for reliable specialist accuracy** — the ADR's own
status section says the full `baseline → enroll → train-room → infer` loop is
proven only against **deterministic synthetic CSI** (`tests/full_loop.rs`),
not yet run start-to-finish on real hardware in an empty room. Treat the
default durations as reasonable code defaults, not as a validated minimum for
real-world accuracy.

---

## 2. Recommended duration if there's no hard minimum

Where a hard minimum *does* exist (the 600-frame baseline, the 60-frame
per-anchor floor), it's documented above. Beyond that:

- **Baseline capture**: the CLI default (`--duration-s 30`) is the number to
  use; it's what the 600-frame minimum is designed around at the assumed
  20 Hz sensing rate. ADR-135 §2.3 argues 30 s is the shortest duration that
  keeps the phase-concentration estimate's standard deviation under
  0.02 rad², citing published circular-statistics error bounds — but this is
  a paper-derived justification for the *default value*, not a code-enforced
  floor beyond the 600-frame check itself.
- **Enrollment anchors**: use the built-in per-anchor durations (20s/30s) —
  there's currently no way to change them from the CLI anyway.

---

## 3. Will a pet get classified as "occupied"?

**Honest answer: the code has no way to distinguish a pet (or any small/animal-scale
motion) from a person.** This is a real limitation, not a solved problem —
flagging it here rather than guessing.

Presence detection (`PresenceSpecialist`,
`v2/crates/wifi-densepose-calibration/src/specialist.rs:100-198`) is trained
purely from two scalar channels measured during enrollment:

- **variance** of the CSI amplitude series, thresholded at the midpoint
  between the `empty` anchor's variance and the mean variance of the
  person-present anchors;
- **mean shift** — `|mean − empty_mean|`, thresholded at half the
  empty→occupied mean distance.

Presence fires if **either** channel crosses its threshold. Both thresholds
are learned entirely from the amplitude statistics of your enrollment
anchors — there is no body-size, RCS (radar cross-section), Doppler-signature,
or any other physical feature in this code that separates "a full-grown
adult moved" from "a cat walked past" or "a dog jumped on the couch." If a
pet's motion perturbs the CSI amplitude by roughly the same amount as the
`small_move` anchor did during your enrollment, `PresenceSpecialist` will read
it as occupied, because that's mechanically what the threshold measures.

The closest thing to a safeguard is `AnomalySpecialist`
(`specialist.rs:386-448`), a generic novelty detector that flags a live
window as "anomalous" when it's far (in embedding distance) from every
enrolled anchor prototype. It is **not** a validated pet filter — it will
flag *any* statistically unusual signal as anomalous or normal depending on
how close it happens to land to your anchors, with no guarantee it
distinguishes species or motion source. A pet whose motion pattern happens
to resemble the `small_move` anchor would not be flagged as anomalous at all.

**Practical takeaway for a homeowner with pets:** expect presence/posture
readings to occasionally trigger on pet motion, especially larger animals or
motion near the sensor. There is currently no configuration option or code
path to suppress this.

---

## 4. Does the empty-room baseline need "typical" conditions (HVAC running) or true silence?

The short answer, grounded in how the baseline is actually computed: **a
stationary, continuously-running interferer (a fan, HVAC blower, humidifier)
that is present for the *entire* capture window becomes part of what "empty"
means, and gets subtracted out naturally** — that's a direct consequence of
how the statistics are computed, not a documented feature you have to
configure.

`CalibrationRecorder` uses Welford's online algorithm to accumulate a running
mean and variance per subcarrier over however many frames you feed it
(`ruvsense/calibration.rs`). If a fan is running steadily the whole time you
capture the baseline, its contribution is baked into `amp_mean`/`amp_variance`
for every frame equally, so the resulting baseline already represents "empty
room with the fan on" — and at runtime, `BaselineCalibration::subtract()`
removes exactly that reference, so a room in the same steady state reads as
quiet. The design intent documented in ADR-135 §1.1 is explicit about this:
the whole point of baseline subtraction is to remove "hardware-induced gain
bias and environment-fixed multipath" so downstream motion detectors aren't
tripped by things that are always there.

**What actually matters is consistency, not silence**: capture the baseline
under whatever background conditions the room will normally be in during
real use (HVAC/fans running as usual), and try to keep the room in that same
steady state for the entire capture window. What the code cannot correct
for is a background condition that **changes partway through** the capture
(e.g. HVAC cycles on 15 seconds into a 30-second capture) — that would bias
the Welford mean/variance toward an in-between state that matches neither
"HVAC off" nor "HVAC on" well.

There is a **real-time guard during capture** that can catch gross problems:
`--abort-z-threshold` (default `2.0`) aborts the capture if the per-frame
amplitude z-score median stays above that threshold for 20 consecutive
banner intervals (`v2/crates/wifi-densepose-cli/src/calibrate.rs:82-83,
163-178`). This is designed to catch someone walking through mid-capture, not
necessarily short-duration mechanical noise — we found no test exercising it
against an HVAC-cycling scenario specifically, so how it behaves for
"appliance turns on mid-capture" is unverified.

### What we could not verify — and a design gap worth knowing about

ADR-135 §2.5 describes a much more sophisticated staleness-detection system:
a `drift_score` computed from ongoing z-scores, a `BaselineDrift` event fired
after sustained drift, and a `baseline_stale` flag published over the
sensing WebSocket. **We searched the actual `calibration.rs` implementation
and none of that exists in code** — there is no `drift_score` field, no
`BaselineDrift` event, and no `baseline_stale` flag anywhere in
`v2/crates/wifi-densepose-signal/src/ruvsense/calibration.rs`. That part of
ADR-135 is aspirational design, not shipped behavior.

What *is* implemented, at a different layer, is a much simpler check on the
**trained specialist bank** (not the raw baseline): `SpecialistBank` stores
the `baseline_id` it was trained against, and `SpecialistBank::is_stale()`
(`v2/crates/wifi-densepose-calibration/src/bank.rs:102-104`) returns `true`
whenever the *current* baseline's id doesn't match the id the bank was
trained on. Re-running `calibrate` always produces a new baseline id, so
**any** recalibration — whether because of furniture moving, a genuinely
stale reference, or just re-running the command — immediately marks every
previously trained specialist bank stale, and you'll need to re-run `enroll`
and `train-room` afterward. There is no partial/graded staleness signal
(no "how stale"), only this all-or-nothing id comparison.

**Practical guidance:**

1. Calibrate with the room in its normal, steady background state (HVAC,
   fans, fridge compressor, etc. running as they normally would) and keep
   that state constant for the whole `--duration-s` window.
2. If you significantly change background conditions later (move furniture,
   add a permanent appliance, change HVAC routine) or notice the sensing
   quality degrade, re-run `calibrate` — this is an explicit, operator-driven
   step; there is no code path that recalibrates for you.
3. Re-running `calibrate` invalidates every specialist bank trained against
   the old baseline (via the `baseline_id` mismatch above) — plan to re-run
   `enroll` and `train-room` right after.

---

## Quick reference: commands and defaults actually in the code

```bash
# Stage 1 — empty-room baseline. Room must be empty for the whole window.
wifi-densepose calibrate \
  --udp-port 5005 --duration-s 30 --tier ht20 --output ./baseline.bin
# Hard requirement: >= 600 recorded frames, or calibration fails.

# Stage 2+3 — guided enrollment (8 fixed anchors, ~4 minutes total)
wifi-densepose enroll --baseline ./baseline.bin --room living-room \
  --output ./enrollment.json --attempts 2

# Stage 4 — train the specialist bank from whatever anchors were accepted
wifi-densepose train-room --enrollment ./enrollment.json \
  --output ./room-bank.json

# Check what actually trained (and whether the bank is stale)
wifi-densepose room-status --room living-room
```

Source references for everything above:
- `v2/crates/wifi-densepose-cli/src/calibrate.rs`
- `v2/crates/wifi-densepose-cli/src/room.rs`
- `v2/crates/wifi-densepose-signal/src/ruvsense/calibration.rs`
- `v2/crates/wifi-densepose-calibration/src/enrollment.rs`
- `v2/crates/wifi-densepose-calibration/src/anchor.rs`
- `v2/crates/wifi-densepose-calibration/src/specialist.rs`
- `v2/crates/wifi-densepose-calibration/src/bank.rs`
- `docs/adr/ADR-135-empty-room-baseline-calibration.md`
- `docs/adr/ADR-151-room-calibration-specialist-training.md`