OpenIPC · josephnef · Jul 12, 2026 · Jul 12, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -78,8 +78,8 @@ on rxdemo and txdemo (TX = the data/MGMT BD rings behind the unchanged
 bottom-up.
 Bind/restore: `tests/pcie_vfio_bind.sh` (driver_override, not new_id — the
 in-tree rtw88 auto-probe race). Validation: `sudo python3
-tests/pcie_rx_smoke.py` on the radxa-x4 (`ssh radxa-x4`, 8821CE at
-0000:01:00.0, IOMMU group 12) — ambient beacons CRC-clean on ch 6 + 36.
+tests/pcie_rx_smoke.py` against a vfio-bound 8821CE (rig specifics: local
+`INVENTORY.md`) — ambient beacons CRC-clean on ch 6 + 36.
 
 ## Build
 
@@ -153,7 +153,8 @@ traps it encodes: the in-tree rtw88 modules auto-probe (and fw-download
 into) every Realtek dongle at each enumeration — `modprobe -r` does NOT
 survive re-enumeration, temp-blacklist instead; and `authorized`-toggle
 "cold" leaves chip state (real VBUS cold via `REGRESS_VBUS_MAP` /
-uhubctl — never on xhci root ports on this rig).
+uhubctl — hub ports with per-port power switching only, not xhci root
+ports).
 
 ## Logging
 
@@ -334,6 +335,42 @@ per-bin energy + frame stats; `tests/sounding_sweep.sh` + `tests/sounding_map.py
 recover a coarse per-bin H(f) — down to 5 MHz bins on Jaguar3
 (`docs/rx-spectrum-sensing.md`).
 
+## Hardware time, beacons, AP mode
+
+`ReadTsf()` reads the 64-bit MAC TSF and every received frame carries the
+MAC-latched `tsfl` RX timestamp — on all generations, µs-grade
+(`docs/time-distribution.md`, measured vs NTP/PTP: `docs/timing-accuracy.md`).
+`StartBeacon` loads a beacon into the MAC's reserved page and the chip
+auto-transmits at each TBTT with the live TSF stamped at the TX instant — the
+sub-µs downlink. The chip beacons **autonomously**: a session that ends
+without a power-cycle must call `StopBeacon()` or the beacon keeps airing.
+`UpdateBeaconPayload` swaps the airing content in place (frame-atomic on air,
+TBTT-quantized latency); `PinBeaconTbtt` steers the TBTT to an absolute TSF
+instant without corrupting the clock (Jaguar1: offset 0 only — its TBTT is
+hardware-locked to the TSF grid); `AdjustBeaconTimingFine` is the µs-fine
+manual lever. Demos: `timesync` (`DEVOURER_TSYNC_ROLE=master|slave|ue` +
+`DEVOURER_TSYNC_*` knobs, incl. the PCIe master + I226-PTP discipline loop)
+and `tdma` (TSF-slotted narrowband↔wide bursts on one channel). The beacon is
+also the seed of AP mode — a real Linux station associates, open or WPA2-PSK
+(`docs/ap-mode.md`); the multi-cell architecture it enables is
+`docs/multi-ap-cellular.md`, and the measured scheduler contracts (submit→air
+guard time, dynamic beacon grants, ACK/TxReport, per-UE RX attribution) are
+`docs/scheduled-mac.md`.
+
+## Aggregation, hardware ACK, TX reports
+
+`SetAmpduMode` enables 802.11 A-MPDU on injected frames: ~+30% *goodput* at
+the PHY ceiling by amortizing per-frame overhead — an occupancy metric can't
+show it, count delivered payload. `SetAckResponder(mac)` arms the hardware
+ACK/BlockAck responder; with a unicast TA on the soliciting frame this closes
+a hardware-ARQ loop (autonomous MAC retransmission until ACK). Per-frame TX
+outcomes surface as `tx.report` events (CCX via C2H) — the TX-side link
+sensor; C2H rides the RX path, so J1/J2 TX-only sessions see none (run
+`DEVOURER_TX_WITH_RX=thread`; J3's coex thread drains C2H regardless).
+`GetRxQuality()` is the device-wide windowed RX sensor;
+`cell::UeRxAttribution` is its per-transmitter (per-UE) counterpart. Docs:
+`docs/aggregation.md`, measured per-generation matrix `docs/scheduled-mac.md`.
+
 ## Architecture
 
 **The caller owns libusb.** `WiFiDriver::CreateRtlDevice` is intentionally
@@ -367,6 +404,9 @@ Generation-agnostic core in `src/` (always compiled; depends on no HAL):
 - `PhyTableLoader` — runtime walker for Realtek's phydm-format register tables
   (`check_positive` + opcode state machine, without pulling in phydm itself).
   Shared by Jaguar1 + Jaguar2; Jaguar3 has its own `PhyTableLoaderJaguar3`.
+- `cell/` — caller-side per-cell helpers built on the device API
+  (`UeRxAttribution`: per-transmitter windowed RX statistics keyed by 802.11
+  TA); the device RX loops are untouched.
 
 Per-generation HALs (each self-contained):
 

diff --git a/README.md b/README.md
@@ -70,9 +70,9 @@ Bandwidth cells are devourer's measured on-air TX throughput (Mbps, HT MCS7,
 | **RTL8812AU**                 | 2T2R              | 56            | 52            | 52               | [CHANEVE CHW50L](https://www.aliexpress.com/item/4000762461362.html) (`0bda:8812`). 5/10 MHz capable |
 | **RTL8811AU**                 | 1T1R              | —             | —             | —                | 1T1R cut of 8812 silicon; rides the 8812 code path. Not benchmarked. 5/10 MHz capable |
 | **RTL8814AU**                 | 4T4R, 3-SS max    | 65            | †(32)         | †(32)            | `0bda:8813`; tested on COMFAST CF-938AC and CF-960AC — antenna builds differ in realised [RX diversity](docs/measuring-spatial-diversity.md). 5/10 MHz capable |
-| **RTL8821AU**                 | 1T1R AC + BT      | 54            | 32            | 28               | TP-Link Archer T2U Plus (`2357:0120`) |
+| **RTL8821AU**                 | 1T1R + BT         | 54            | 32            | 28               | TP-Link Archer T2U Plus (`2357:0120`) |
 | **RTL8822BU**                 | 2T2R + BT         | 52            | 50            | 49               | TP-Link Archer T3U (`2357:012d`). 5/10 MHz capable |
-| **RTL8812BU**                 | 1T1R + BT         | —             | —             | —                | 1T1R cut of 8822B silicon; rides the 8822BU code path. Not benchmarked |
+| **RTL8812BU**                 | 1T1R + BT         | —             | —             | —                | 1T1R cut of 8822B silicon; rides the 8822BU code path. Not benchmarked. 5/10 MHz capable |
 | **RTL8811CU**                 | 1T1R + BT         | 36            | 29            | 28               | COMFAST CF-811AC (`0bda:c811`). 5/10 MHz capable |
 | **RTL8821CU**                 | 1T1R + BT         | —             | —             | —                | rides the 8811CU (8821C) code path. 5/10 MHz capable |
 | **RTL8812CU**                 | 2T2R              | 65            | 60            | 60               | LB-LINK WDN1300H (`0bda:c812`). 5/10 MHz capable |
@@ -137,7 +137,11 @@ the `env:` tags in [`src/DeviceConfig.h`](src/DeviceConfig.h).
 | `streamtx` / `duplex` | stdin-driven TX / full-duplex packet link |
 | `svctx` | per-video-layer rate ladders (unequal error protection) |
 | `txpower` | runtime TX-power API walkthrough |
+| `tdma` | TSF-slotted burst TDMA (narrowband ↔ wide on one channel) |
+| `timesync` | over-the-air clock distribution (master / slave / UE roles) |
 | `sense` | Wi-Fi motion sensing from beamforming reports |
+| `doctor` | adapter-health triage → HEALTHY / SUSPECT / FAILING |
+| `pcieprobe` | PCIe transport bring-up validation, layer by layer |
 | `precoder` | OFDM subcarrier shaping proof-of-concept |
 
 All chips compile in by default; per-chip CMake options (`DEVOURER_JAGUAR1`,
@@ -183,30 +187,46 @@ one `IRtlDevice` interface covers all three generations.
 
 ## Going deeper
 
+**Primers** — start here:
+
 - [Visual RF primer](docs/rf-primer.md) — animated intro to the concepts
   behind everything below.
 - [Visual driver primer](docs/driver-primer.md) — animated intro to the chip
   and vendor-driver machinery: registers, efuse, firmware, MAC, PHY tables,
   calibration, coexistence.
+
+**Link engineering:**
+
 - [Adaptive link](docs/adaptive-link.md) — the energy-minimizing video-link
-  controller design, and [its validation](docs/adaptive-link-validation.md).
+  controller design, [its validation](docs/adaptive-link-validation.md), and
+  the [building blocks](docs/adaptive-link-building-blocks.md): what each knob
+  (power, rate, bandwidth, hopping) measurably buys.
 - [Fused FEC](docs/fused-fec.md) — the cross-layer error-protection stack:
   per-layer PHY rates, corrupt-frame salvage, outer erasure code.
+- [Aggregation & hardware ACK](docs/aggregation.md) — USB TX aggregation,
+  per-frame CCX TX-status reports, 802.11 A-MPDU (`SetAmpduMode`, +30% on-air
+  goodput), and the hardware ACK/BlockAck responder for reliable-unicast links.
+- [wfb-ng tuning](docs/wfb-ng-tuning.md) — the most efficient wfb-ng
+  configuration, and the SDR-measured devourer-vs-wfb-ng TX comparison.
+
+**Spectrum agility:**
+
 - [Frequency hopping](docs/frequency-hopping.md) — how per-packet hopping
   works and what it costs on each chip.
+- [FHSS](docs/fhss.md) — the anti-jam design article: keyed SipHash hop
+  schedules, slot-locked lockstep RX, and
+  [jammer resilience](docs/jammer-resilience.md) — measured delivery against
+  parked and following jammers, and where a follower breaks.
 - [Narrowband](docs/narrowband.md) — 5/10 MHz channels across all three
   generations: the baseband re-clock, the per-chip register machinery, and the
   walls (RF re-latch edges, per-die clock coupling, the 5 MHz/5 GHz CFO limit).
-- [Performance](docs/performance-tuning.md) — devourer vs. kernel driver on
-  startup time, on-air throughput, and host CPU (3–4× lower); the TX
-  submission modes and the tuning levers, with the methodology.
-- [Adapter doctor](docs/adapter-doctor.md) — dying-dongle triage: EFUSE
-  read-stability, firmware-boot and RX-smoke probes with a
-  HEALTHY / SUSPECT / FAILING verdict.
-- [Spectrum sensing](docs/rx-spectrum-sensing.md),
-  [spatial diversity](docs/measuring-spatial-diversity.md),
-  [bench testing near-field](docs/bench-testing-near-field.md) — measurement
-  guides for the built-in radio instrumentation.
+- [Spectrum sensing](docs/rx-spectrum-sensing.md) — RX energy sweeps down to
+  5 MHz bins: a coarse per-bin H(f) from the dongle itself.
+- [Pseudo preamble puncturing](docs/pseudo-preamble-puncturing.md) — how close
+  per-tone RX masks/notches get to using a wide channel with a dirty slice.
+
+**Timing & coordination:**
+
 - [Time distribution](docs/time-distribution.md) — LTE-eNB-style over-the-air
   clock distribution off the hardware beacon TSF: sub-µs downlink, TSF adoption,
   µs-fine TBTT steering and a converging closed-loop uplink timing advance.
@@ -216,9 +236,36 @@ one `IRtlDevice` interface covers all three generations.
 - [AP mode](docs/ap-mode.md) — devourer as an infrastructure access point a real
   Linux station associates with: beacon → probe/auth/assoc → DHCP/ARP/ICMP → ping,
   open or WPA2-PSK (4-way handshake + software CCMP), validated against rtw88.
-- [Aggregation & hardware ACK](docs/aggregation.md) — USB TX aggregation,
-  per-frame CCX TX-status reports, 802.11 A-MPDU (`SetAmpduMode`, +30% on-air
-  goodput), and the hardware ACK/BlockAck responder for reliable-unicast links.
+- [Scheduled MAC](docs/scheduled-mac.md) — four measured contracts under a slot
+  scheduler: submit→air guard time, dynamic beacon grants, hardware ACK/TxReport,
+  per-UE RX attribution.
+- [Multi-AP cellular](docs/multi-ap-cellular.md) — what the shared clock
+  enables: coordinated cells, make-before-break handover, roaming robot UEs.
+
+**Measurement & instrumentation:**
+
+- [LA-mode IQ capture](docs/la-capture.md) — raw complex baseband into the TX
+  packet buffer; per-tone H(k)/CSI offline, from the dongle alone.
+- [Spatial diversity](docs/measuring-spatial-diversity.md),
+  [bench testing near-field](docs/bench-testing-near-field.md) — measurement
+  guides for the built-in radio instrumentation.
+- [Beamforming self-sounding](docs/beamforming-self-sounding.md) — per-subcarrier
+  CSI from two adapters via the VHT sounding exchange; and its sibling
+  [victim sensing](docs/beamforming-victim-sensing.md) — motion sensing from
+  captured beamforming reports.
+- [Adapter doctor](docs/adapter-doctor.md) — dying-dongle triage: EFUSE
+  read-stability, firmware-boot and RX-smoke probes with a
+  HEALTHY / SUSPECT / FAILING verdict.
+- [Performance](docs/performance-tuning.md) — devourer vs. kernel driver on
+  startup time, on-air throughput, and host CPU (3–4× lower); the TX
+  submission modes and the tuning levers, with the methodology.
+
+**Chip specifics & internals:**
+
+- [8822E quirks](docs/8822e-quirks.md) — the RTL8812EU/8822EU definitive
+  quirks list: what the chip needs, what devourer does, the reproducers.
+- [Logging](docs/logging.md) — the two-plane output schema: JSONL machine
+  events on stdout, human diagnostics on stderr.
 
 ## Testing
 

diff --git a/docs/8822e-quirks.md b/docs/8822e-quirks.md
@@ -7,8 +7,8 @@ The rtl8822e family (WiFi-only **RTL8812EU** `0bda:a81a`, BT-combo **RTL8822EU**
 `0bda:e822`, chip-id `0x17`, Jaguar3) as devourer drives it today. Every entry
 states what the chip needs, what devourer does about it, the residual cost if
 any, and the reproducer that proves it. Reference hardware: LB-LINK
-BL-M8812EU2 (`0bda:a81a`, rfe-type 21); the BT-combo part and a second board
-for variance remain untested (see **Untested**).
+BL-M8812EU2 (`0bda:a81a`, rfe-type 21); the BT-combo part and other board
+variants are outside the characterized set (see **Coverage**).
 
 The methodology that closed most of these: vendor-kernel ground truth on the
 same unit (`tests/eu_kernel_mcs_probe.sh`), full MAC+BB end-state diff
@@ -35,8 +35,9 @@ family programs. Three of these must hold, or TX breaks in distinctive ways:
   ONE chain (2SS gets both). The old 1ss-on-both mapping (`0x33`) interacts
   with the DPDT fix — MCS0 TX stalls (bulk NAK wedge) and MCS7 delivery
   collapses. Path B is selected at 5 GHz on measured merit (MCS7 ~2.5× the
-  delivery of 1ss-A at ~3 dB better EVM on this module); the 2.4 GHz choice is
-  the kernel default, unvalidated (see **2.4 GHz TX**).
+  delivery of 1ss-A at ~3 dB better EVM on this module); the 2.4 GHz choice
+  follows the kernel default — on-air comparison is blocked by the 2.4 GHz TX
+  quirk (see **2.4 GHz TX**).
 - **`PAD_CTRL1 0x64[29:28]`**: halmac pre-init sets both; the bring-up's
   FW/coex steps clear bit 29 — re-asserted post-coex.
 
@@ -160,10 +161,12 @@ duty×rate — energy, not decodable throughput.)
   `GetTxPowerCaps().step_measured` stays false; controllers should calibrate
   their own dB-per-step or use ground RSSI.
 
-## Untested
+## Coverage
 
-- **RTL8822EU (`0bda:e822`, BT combo)**: entirely untested — including whether
+Everything above is characterized on one board: the LB-LINK BL-M8812EU2
+(WiFi-only RTL8812EU, rfe 21). Outside that set:
+
+- **RTL8822EU (`0bda:e822`, BT combo)**: uncharacterized — including whether
   it needs more than the WiFi-only coex handling the CU-style combo parts get.
-- **Board variance**: all of the above is one LB-LINK BL-M8812EU2 (rfe 21).
-  rfe 22–24 boards differ in RFE pin mapping and DPK policy; the 2.4 GHz TX
-  verdict especially needs a second board.
+- **Other rfe types**: rfe 22–24 boards differ in RFE pin mapping and DPK
+  policy; the 2.4 GHz TX verdict in particular is single-board evidence.
diff --git a/docs/ack-txreport.md b/docs/ack-txreport.md