Add WiFiSenseDemo: Wi-Fi motion sensing from beamforming reports

[josephnef]

What

A runnable example — examples/sense/ (WiFiSenseDemo) — that turns two
supported Realtek adapters into a motion / presence sensor, with no SDR and
no cooperating AP. One binary drives a sounder and a beamformee on the
same host: the sounder injects an NDPA (the MAC hardware-generates the sounding
NDP), the beamformee returns a VHT compressed beamforming report, and the sounder
self-captures it on a concurrent RX loop (the existing beamforming self-sounding
path). The per-tone Givens angles are a beamformee-side measurement of the channel
between the two adapters, so a person moving makes them jitter frame-to-frame —
the mechanism behind published work like Wi-BFI / BeamSense.

Contents

• src/BfReportDecode.h — header-only decoder for VHT/HT compressed
  beamforming reports (LSB-first Givens-angle unpack + dequant) and a
  MotionMeter that measures the per-tone cross-frame circular variance of the
  phase angle. pick_split() enforces the 802.11 codebook relationship
  b_phi = b_psi + 2 — uniquely (6,4) for a 10-bit 2×1 report. (A naive
  min-cross-frame-variance search is fooled by a trivially-constant coarse psi
  into a bit-misaligned split whose phi decodes to noise and reads as constant
  motion — a real bug found on hardware and now pinned by the self-test.)
• examples/sense/main.cpp — the WiFiSenseDemo binary: two-adapter bring-up
  (separate libusb contexts), the sounding loop, an AdaptiveDetector
  (self-calibrating CFAR floor + rising-edge dwell + hold, so no fixed per-rig
  threshold), a live σ readout, a report-stream stall watchdog, and a
  deadlock-proof shutdown.
• examples/sense/bf_report_decode_selftest.cpp — headless ctest
  (bf_report_decode) guarding the decoder against a real captured report;
  asserts the (6,4) split.
• examples/sense/README.md — comprehensive hands-on guide: hardware,
  placement, every knob, the decoding/detector maths, and a capture→analyse loop
  for experimenting with your own formulas.
• src/logger.h — add a verbosity Level to Logger (default Debug,
  unchanged behaviour) so a demo can quiet the library and own the console.
• src/jaguar1/RadioManagementModule.cpp — a channel-set trace was logged at
  error level; demoted to info.
• docs/beamforming-victim-sensing.md — trim the "Try it" section to a
  quickstart that points at the full guide.

Validation

• Active two-adapter mode: validated on hardware. Still → CLEAR (0 false
  alarms over a deliberate hands-away capture), hand wave → MOTION (verified by
  replaying a labelled still/wave capture through the exact detector logic). Clean
  SIGINT exit; stall watchdog exits cleanly when the beamformee stops responding.
• Decoder: ctest self-test (green) decodes a real captured report and pins
  the Givens split.
• Builds on macOS/Linux; the demo touches no chip-specific code.

Scope (deliberately honest)

• A passive AP-sniffing mode (Wi-BFI style) and a single-radio --mode self
  variant are documented as unimplemented follow-ups rather than shipped untested —
  passive needs a real AP actively sounding VHT beamforming, which couldn't be
  validated against here.

🤖 Generated with Claude Code