berkus
/
wifi-densepose
mirror of https://github.com/ruvnet/wifi-densepose.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs(adr-117): add BFLD support (§5.7a + P3.5 phase + §11.11/12 open questions) 

Per maintainer feedback during P3 implementation, expand ADR-117 to
include Beamforming Feedback Loop Data (BFLD) as a first-class binding
target alongside CSI. BFLD is the transmitter-side, AP-station-loop
view of the WiFi channel (802.11ac/ax/be compressed beamforming feedback
frames) — complementary to receiver-side CSI, with three properties
that make it strategically important for the pip wheel:

1. **Up to 996 subcarriers per HE160 frame** (vs 242 for HE-LTF CSI on
   ESP32-C6, vs 52 for HT-LTF on ESP32-S3) — much denser per-subcarrier
   reflection profile
2. **Works on stock 802.11ac+ hardware** — no Nexmon patch, no ESP32
   monitor mode, no firmware drift. Captured via tcpdump/Wireshark +
   BFR dissector, or via `mac80211` debugfs on Linux 6.10+
3. **Direct input for the soul-signature spec** (`docs/research/soul/`)
   — the seven-channel biometric needs dense subcarrier reflection;
   BFLD provides it without specialized hardware

## Three additions to ADR-117

### §5.7a — New binding-target subsection
Comparison table CSI vs BFLD; binding strategy with forward-compat
stub Rust impl pending the future `wifi-densepose-bfld` crate; the
three Python types that ship in P3.5:

- `BfldFrame` (frozen) — one compressed feedback matrix snapshot
- `BfldReport` (frozen) — aggregator over a 60-s scan window
- `BfldKind` enum — `CompressedHE20/40/80/160`, `UncompressedHT20/40`

### §6 P3.5 — Concurrent-with-P3 phase
Checkbox plan for the bindings module + stub Rust storage + numpy
bridge for `feedback_matrix` (Complex64 ndarray, same approach as
`CsiFrame.amplitude` from P3). Lands in the same wheel as P3, no
schedule cushion needed.

### §11.11/12 — Two new open questions
- **§11.11** — Should the future BFR ingestion Rust crate be a new
  `wifi-densepose-bfld` workspace member, or extend `-signal`?
  *Tentative: new dedicated crate. Wireshark BFR dissector is ~2k
  lines and would bloat `-signal`; ingestion is optional for many
  deployments; keep `-signal` lean.*
- **§11.12** — Per-vendor BFR variant compatibility (Broadcom vs
  Intel vs Qualcomm vs MediaTek differ in psi/phi quantization +
  matrix entry ordering). How much normalisation in the Python
  binding vs. the future Rust crate? *Tentative: Python binding is
  dumb (numpy ndarray in/out); future Rust crate owns per-vendor
  normalisation via a `Vendor` enum on the constructor.*

### §12 — BFLD reference list
- Hernandez & Bulut, ACM TOSN 2024 (first systematic survey of
  BFR-as-sensing)
- Yousefi et al., MobiSys 2023 (practical breath + HR extraction)
- IEEE 802.11ax-2021 §27.3.10 (frame format)
- Wireshark `packet-ieee80211.c` dissector
- AX210 Linux mac80211 debugfs path (kernel 6.10+)

ADR line count: 644 → 807 (+163). Refs #785 (tracking issue).

The implementation work for P3.5 lands in the next /loop iteration
alongside P3 vitals + signal DSP bindings.

Co-Authored-By: claude-flow <ruv@ruv.net>
This commit is contained in:
ruv 2026-05-24 11:09:37 -04:00
parent cbd24cd1ed
commit 4ac0a4d52b
1 changed files with 163 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

163
docs/adr/ADR-117-pip-wifi-densepose-modernization.md
View File

@ -356,6 +356,110 @@ async with SensingClient("ws://localhost:8765/ws/sensing") as client:
Both clients are **pure Python** (no PyO3) and are optional dependencies (`pip install
wifi-densepose[client]`). They depend on `websockets>=12` and `paho-mqtt>=2` respectively.
### 5.7a Beamforming Feedback Loop Data (BFLD) support — new binding target
**Added 2026-05-24 per maintainer feedback during P3 implementation.**
BFLD is the transmitter-side, AP-station-loop view of the WiFi channel
— compressed beamforming feedback frames that 802.11ac/ax/be stations
send to the AP per sounding cycle. From a sensing perspective it
complements receiver-side CSI:
| | Receiver-side CSI (current) | BFLD (this addition) |
|---|---|---|
| Source | RX side of the radio (e.g. Nexmon CSI on Pi 5, ESP32 promisc cb) | Sniffed BFR frames in the air or `mac80211` ACK trace |
| Subcarriers (HE20) | 52 (HT-LTF) or 242 (HE-LTF) | Up to 996 (HE160 compressed BFR) — denser |
| Hardware requirements | Patched Broadcom/Cypress or ESP32 specifically | **Any** 802.11ac+ station-AP pair — no patched firmware |
| Privacy model | Captures everyone in radio range | Same |
| Maturity in repo | Production (ADR-014, ADR-018, ADR-039) | Research; no Rust crate yet |
| Suitable use case | Through-wall pose + vitals | Dense subcarrier reflection profile for AETHER-class biometric (ADR-024) and the soul-signature spec (`docs/research/soul/`) |
#### Binding strategy
Because the Rust workspace has no `wifi-densepose-bfld` crate yet, P3
ships a **forward-compatible Python trait surface** that the future
Rust crate plugs into without changing the Python API:
```python
from wifi_densepose import BfldFrame, BfldReport
# Today (P3): construct from a parsed BFR feedback matrix (the bring-
# your-own-parser path). Users on Pi 5 + Wireshark BFR dissector
# pipe frames in directly.
frame = BfldFrame.from_compressed_feedback(
timestamp_ms=…,
sounding_index=…,
sta_mac="aa:bb:cc:…",
bandwidth_mhz=80,
n_subcarriers=996,
feedback_matrix=…, # numpy ndarray complex64 [Nr × Nc × Nsc]
)
# P3 also ships a stub `BfldReport` aggregator that mirrors how
# `VitalEstimate` aggregates `VitalReading`s. Users who have BFR
# pipelines feeding RuView can use this today via the
# bring-your-own-parser path.
# Tomorrow (post-v2.0): the `wifi-densepose-bfld` Rust crate (TBD —
# separate ADR-1xx) provides ingestion from Nexmon `nl80211` traces +
# kernel `mac80211` debugfs hooks, and the pip wheel transparently
# binds it without changing this Python surface.
```
#### Why this matters
Three reasons BFLD belongs in v2.0 rather than waiting for the Rust
core:
1. **Customer pull**. Several integrators reading the ADR-115 release
notes asked about WiFi-6 dense-subcarrier capture; the answer is
BFLD, and we want the API stable before they build pipelines.
2. **Soul-signature dependency**. The soul-signature research spec
(`docs/research/soul/specification.md`) lists "Subcarrier Reflection
Profile" as one of seven biometric channels. At HE20/HE80 the
dense BFR subcarriers are the right input — exposing `BfldFrame`
now lets researchers prototype the channel without waiting on a
Rust ingestion crate.
3. **Cross-vendor portability**. CSI ingestion needs patched
firmware. BFR ingestion works on stock 802.11ac/ax hardware
(capture via `tcpdump`/Wireshark + a BFR dissector). Shipping the
Python data structures first gives the community a way to feed
RuView from gear we don't directly support.
#### Implementation surface in P3
Lands as a new module `bindings/bfld.rs` (~150 lines, three
`#[pyclass]` types):
- `BfldFrame` (frozen) — one compressed feedback matrix snapshot.
Constructors: `from_compressed_feedback(...)` and
`from_uncompressed_v(...)` (the 802.11n V-matrix form).
Properties: `timestamp_ms`, `sounding_index`, `sta_mac`,
`bandwidth_mhz`, `n_subcarriers`, `n_rows` (Nr), `n_cols` (Nc),
`feedback_matrix` (numpy ndarray complex64).
- `BfldReport` (frozen) — aggregator over a window of `BfldFrame`s.
Properties: `n_frames`, `timestamp_first`, `timestamp_last`,
`mean_amplitude_per_subcarrier`, `coherence_score`. The Python
side gives users a stable handle for "all BFR data in this 60-s
scan" without leaking the storage representation.
- `BfldKind` (`#[pyclass(eq, eq_int, hash, frozen)]`) — enum
enumerating the BFR variants we support: `CompressedHE20`,
`CompressedHE40`, `CompressedHE80`, `CompressedHE160`,
`UncompressedHT20`, `UncompressedHT40`.
Stub Rust implementation lives in `python/src/bfld_stub.rs` until
the proper Rust crate exists; it's intentionally not in v2/crates/.
A new ADR-1xx will own the Rust ingestion crate when we commit to it.
#### Open questions added
- §9.11 — Should BFLD ingestion live in a new `wifi-densepose-bfld`
crate or in `wifi-densepose-signal` extended?
- §9.12 — Per-vendor BFR variant compatibility (Broadcom vs Intel vs
Qualcomm encode the compressed angles slightly differently) — how
much normalisation belongs in the Python binding vs. the future
Rust crate?
### 5.7 Witness chain (re-rooted to the Rust pipeline)
`wifi_densepose.witness.verify_bundle(path)` replaces the v1 proof verification with a
@ -444,8 +548,36 @@ scaffold core vitals+ client publish deferred
- [ ] Announce: `wifi-densepose==1.99.0` tombstone already on PyPI; `v2.0.0` replaces
it in search results.
### P3.5 — BFLD binding surface (concurrent with P3)
**Added 2026-05-24 per maintainer feedback.** See §5.7a for the rationale.
- [ ] `python/src/bindings/bfld.rs` — `BfldFrame`, `BfldReport`,
`BfldKind` `#[pyclass]` wrappers backed by a stub Rust impl
pending the v3 `wifi-densepose-bfld` crate.
- [ ] `python/src/bfld_stub.rs` — minimal in-crate stub storage
(vec of compressed feedback matrices) so the Python API is
fully usable today even before the Rust ingestion crate lands.
- [ ] Numpy bridge for `feedback_matrix` (Complex64 ndarray) — same
approach as `CsiFrame.amplitude` from P3.
- [ ] Tests covering: per-bandwidth constructor paths
(HE20/HE40/HE80/HE160 + HT20/HT40), n_subcarriers contract,
coherence_score sanity, BfldKind hashability + equality.
- [ ] Forward-compat contract test: `BfldFrame` constructed today
from a numpy ndarray must round-trip through (de)serialisation
identically once the Rust crate exists.
- [ ] §9.11 + §9.12 open questions raised so the eventual Rust crate
has clear decisions waiting for it.
P3.5 is concurrent with P3 (no new schedule cushion needed) because
the Python surface is independent of the rest of the v2/ workspace.
Land in the same wheel as P3.
### P6+ — Deferred
- [ ] `wifi-densepose-bfld` Rust crate — proper ingestion from
Nexmon BFR pcaps + `mac80211` debugfs. Replaces the P3.5 stub
storage without changing the Python API. Owns its own ADR-1xx.
- [ ] `wifi-densepose-nn` bindings (libtorch / candle wheel size TBD — see Open
Questions §13.3).
- [ ] `wifi-densepose-ruvector` bindings (RuVector attention types).
@ -625,10 +757,41 @@ The following checks must all pass before ADR-117 is considered Accepted:
*Tentative: read-only for v2.0. Write path deferred to the HACS integration follow-on
(ADR-115 §6.A).*
11. **BFLD Rust crate ownership** (added 2026-05-24): the P3.5 BFLD bindings ship with a
stub Rust impl in `python/src/bfld_stub.rs`. The proper Rust crate (Nexmon BFR pcap
parser + `mac80211` debugfs ingestor) will land later. Should it be a new
`wifi-densepose-bfld` workspace member, or should it extend `wifi-densepose-signal`?
*Tentative: new dedicated crate. Reasons: (a) the BFR parser is significant code
(Wireshark's dissector is ~2k lines) and bloats `-signal`; (b) BFLD ingestion is
optional — many deployments will only use CSI; gating behind a separate crate keeps
the default `-signal` lean. Decide before committing to the crate name in any
`pyproject.toml` extras.*
12. **BFLD per-vendor compressed-angle variants** (added 2026-05-24): 802.11 standardizes
the compressed beamforming feedback format but vendors (Broadcom, Intel, Qualcomm,
MediaTek) differ in psi/phi quantization step + ordering of consecutive matrix
entries. How much normalisation belongs in the Python `BfldFrame.from_compressed_feedback`
binding vs. the future Rust crate? *Tentative: Python binding is dumb (numpy ndarray
in, numpy ndarray out — no decoding); the future Rust crate owns per-vendor
normalisation, exposed via a `Vendor` enum on the binding constructor. Confirm via
a per-vendor test fixture before P3.5 ships.*
---
## 12. References
### BFLD references (added 2026-05-24 for §5.7a + §11.11 + §11.12)
- Hernandez & Bulut, *"Wi-Fi Sensing With Compressed Beamforming Feedback"*, ACM TOSN 2024 — first systematic survey of BFR-as-sensing
- Yousefi, Soltanaghaei & Bharadia, *"Just-In-Time Wi-Fi Sensing Using Compressed Beamforming Feedback"*, MobiSys 2023 — practical pipeline for breath + heart-rate extraction from sniffed BFR
- IEEE 802.11ax-2021 §27.3.10 — Compressed Beamforming Feedback frame format
- Wireshark BFR dissector — `packet-ieee80211.c` reference implementation
- AX210 Linux mac80211 debugfs BFR capture path (kernel 6.10+)
- Sample BFR-vs-CSI parity dataset — TBD; we'll publish one alongside the
`wifi-densepose-bfld` crate when it lands
### Original references
- **PyPI package (current)**: https://pypi.org/project/wifi-densepose/ — v1.1.0, released 2025-06-07
- **PyPI JSON metadata**: https://pypi.org/pypi/wifi-densepose/json
- **Local source**: `archive/v1/setup.py`, `archive/v1/src/__init__.py`, `archive/v1/data/proof/verify.py`