ruvnet--RuView/docs/adr/ADR-153-ieee-802-11bf-sensing-protocol-layer.md

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:

     pub enum SpecProfile {
         DraftCompatible,
         Ieee80211Bf2025,
         VendorExtension(String),
     }
     

   • Capability negotiation — no hardcoded ESP32 assumptions in the future-silicon path:

     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:

     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/