169 lines
7.7 KiB
Markdown
169 lines
7.7 KiB
Markdown
# ADR-153: IEEE 802.11bf-2025 Forward-Compatibility Protocol Model for wifi-densepose-hardware
|
||
|
||
- **Status**: accepted
|
||
- **Date**: 2026-06-10
|
||
- **Deciders**: ruv
|
||
- **Tags**: hardware, protocol, sensing, 802.11bf, forward-compatibility
|
||
|
||
## Context
|
||
|
||
IEEE 802.11bf-2025 (WLAN Sensing) is an **Active Standard**: board approval
|
||
2025-05-28, published 2025-09-26 (verified against the IEEE SA record,
|
||
<https://standards.ieee.org/ieee/802.11bf/11574/>). Its scope modifies the
|
||
MAC, HE and EHT PHY service interfaces, plus DMG and EDMG PHYs, for WLAN
|
||
sensing in **1–7.125 GHz** and **above 45 GHz** bands, with formal sensing
|
||
measurement setup, measurement instance, feedback/reporting, and
|
||
sensing-by-proxy (SBP) procedures (ADR-152 F4, evidence grade MEASURED).
|
||
|
||
No commodity silicon implements the standard yet — ESP32 parts included.
|
||
ADR-152 §2.4 therefore decided "track silicon; no code now", with RuView's
|
||
opportunistic CSI extraction remaining the mechanism. That left a gap: when
|
||
silicon does land, RuView would have no typed model of the standard's
|
||
procedures to bind to, and the integration would start from zero.
|
||
|
||
ADR-152 §2.4 originally classified 802.11bf as a hardware watch item with no
|
||
implementation work until commodity silicon exposes standardized sensing
|
||
measurements. This ADR amends that clause: OTA binding remains deferred, but
|
||
a pure Rust protocol model, session FSM, transport seam, and opportunistic
|
||
CSI bridge will be implemented now so RuView consumers can target a stable
|
||
standardized sensing interface before silicon arrives.
|
||
|
||
The user directed (2026-06-10) that this **forward-compatibility protocol
|
||
model** — a protocol surface, not a conformance implementation — be built
|
||
now.
|
||
|
||
## Decision
|
||
|
||
Implement an `ieee80211bf` **forward-compatibility protocol model** in
|
||
`wifi-densepose-hardware` (pure Rust, no internal deps, simulation-testable,
|
||
no OTA path):
|
||
|
||
> This module is not a certified 802.11bf implementation. It models the
|
||
> public procedure shape needed by RuView and RuvSense, while intentionally
|
||
> avoiding OTA frame binding until chipset support and vendor APIs exist.
|
||
|
||
1. **`types.rs`** — typed structures for the standard's sensing procedures
|
||
(sub-7 GHz focus; DMG stubbed): Sensing Measurement Setup (setup ID,
|
||
initiator/responder and transmitter/receiver roles, bandwidth,
|
||
periodicity, threshold-based reporting parameters), Sensing Measurement
|
||
Instance, Sensing Measurement Report (CSI-variant payload), SBP
|
||
request/response, termination. Two future-proofing requirements:
|
||
|
||
- **Version gates** — every negotiated surface is tagged with a spec
|
||
profile, because vendors will expose partial or renamed capabilities
|
||
first:
|
||
|
||
```rust
|
||
pub enum SpecProfile {
|
||
DraftCompatible,
|
||
Ieee80211Bf2025,
|
||
VendorExtension(String),
|
||
}
|
||
```
|
||
|
||
- **Capability negotiation** — no hardcoded ESP32 assumptions in the
|
||
future-silicon path:
|
||
|
||
```rust
|
||
pub struct SensingCapabilities {
|
||
pub sub_7_ghz: bool,
|
||
pub dmg: bool,
|
||
pub edmg: bool,
|
||
pub csi_report: bool,
|
||
pub threshold_reporting: bool,
|
||
pub sensing_by_proxy: bool,
|
||
pub max_bandwidth_mhz: u16,
|
||
pub max_period_ms: u32,
|
||
pub max_active_setups: u16,
|
||
}
|
||
```
|
||
|
||
- **Privacy and governance fields** — sensing is presence inference, not
|
||
just radio telemetry. Every `SensingMeasurementSetup` carries policy
|
||
metadata (required, not optional), for enterprise, elderly-care,
|
||
retail, workplace, and municipal deployments:
|
||
|
||
```rust
|
||
pub enum ConsentMode {
|
||
LabOnly,
|
||
ExplicitConsent,
|
||
ManagedEnterprisePolicy,
|
||
Disabled,
|
||
}
|
||
```
|
||
|
||
2. **`session.rs`** — deterministic event-driven session state machine:
|
||
`Idle → SetupNegotiating → Active → Terminating → Idle`, with explicit
|
||
rejection paths (unsupported parameters, setup-ID collision) and timeout
|
||
handling.
|
||
3. **`transport.rs`** — a `SensingTransport` trait abstracting frame
|
||
exchange; a `SimTransport` test double; and an `OpportunisticCsiBridge`
|
||
adapter mapping today's ESP32 CSI extraction onto the report path
|
||
(measurement instances ≈ CSI frame batches), so current hardware sits
|
||
behind the standardized interface. **Replaceability benchmark
|
||
(acceptance test):** RuvSense must consume either ESP32 opportunistic CSI
|
||
or future 802.11bf chipset reports through the same `SensingTransport`
|
||
and `SensingMeasurementReport` path, with no consumer-side rewrite — a
|
||
future chipset adapter replaces `OpportunisticCsiBridge` without changing
|
||
consumers.
|
||
|
||
Constraints: input validation at boundaries (typed errors, no panics on
|
||
adversarial input), files under 500 lines, all protocol tests runnable
|
||
without hardware.
|
||
|
||
### Acceptance checklist
|
||
|
||
| Area | Acceptance test |
|
||
| --------------- | -------------------------------------------------------------------- |
|
||
| Types | Serde round trip for setup, instance, report, SBP, termination |
|
||
| FSM | Idle → setup → active → terminating → idle |
|
||
| Rejection | Unsupported bandwidth, invalid period, duplicate setup ID |
|
||
| Timeout | Negotiation timeout returns typed error and resets to Idle |
|
||
| Threshold | Report emitted only when threshold condition is crossed |
|
||
| SBP | Proxy request maps to responder path without direct sensor coupling |
|
||
| Bridge | ESP32 CSI batch becomes standardized measurement report |
|
||
| Safety | No panics on malformed inputs |
|
||
| CI | All protocol tests run without hardware |
|
||
| Maintainability | Each file under 500 lines |
|
||
|
||
### Non-Goals
|
||
|
||
This ADR does not claim IEEE 802.11bf conformance, certification, or OTA
|
||
interoperability. It creates a typed protocol compatibility layer so RuView
|
||
can consume standardized sensing reports when commodity silicon exposes
|
||
them. Vendor-specific frame exchange, firmware hooks, trigger-frame
|
||
sounding, and certification test vectors remain future ADRs.
|
||
|
||
## Consequences
|
||
|
||
### Positive
|
||
- RuView can adopt standardized WLAN sensing the day any chipset exposes
|
||
802.11bf measurements — the data model, session FSM, and transport seam
|
||
already exist and are tested.
|
||
- The `OpportunisticCsiBridge` gives current ESP32 nodes a standardized-shape
|
||
interface now, decoupling RuvSense consumers from the extraction mechanism.
|
||
- Simulation transport enables protocol-level tests in CI without hardware.
|
||
- `SpecProfile` + `SensingCapabilities` give a clean escape hatch for the
|
||
partial/renamed vendor capabilities that will certainly arrive first.
|
||
- Consent/policy metadata is structural from day one, not retrofitted.
|
||
|
||
### Negative
|
||
- Code written against a standard with zero silicon risks drift: vendor
|
||
implementations may interpret parameters differently; the layer may need
|
||
rework at first real binding (drift risk scored 7/10 at acceptance).
|
||
- Adds maintenance surface to wifi-densepose-hardware before any
|
||
user-visible benefit (maintenance cost scored 3/10 — small without OTA).
|
||
|
||
### Neutral
|
||
- ADR-152 §2.4's "watch item" remains: revisit when silicon/certification
|
||
appears (re-check by 2026-12). This ADR changes only the "no code now"
|
||
clause.
|
||
|
||
## Links
|
||
|
||
- ADR-152 — WiFi-Pose SOTA 2026 Intake (F4, §2.4 — amended by this ADR)
|
||
- ADR-028 — ESP32 capability audit (opportunistic CSI extraction baseline)
|
||
- ADR-029 — RuvSense multistatic sensing mode (consumer of sensing reports)
|
||
- IEEE 802.11bf-2025 — Active Standard, board approval 2025-05-28, published
|
||
2025-09-26: <https://standards.ieee.org/ieee/802.11bf/11574/>
|