Real-time Wi-Fi monitoring and raw 802.11 frame injection library for the Realtek RTL8721Dx (AmebaDplus, KM4 / Cortex-M33, ARMv8-M @ 334 MHz).
Some documentation text and the architecture diagram were drafted with the assistance of generative AI and then reviewed for accuracy.
| Capability | Details |
|---|---|
| Capture | Lock-free promiscuous pipeline → pcapng/radiotap output (Wireshark-ready) |
| Injection | ATCS-EDF scheduler, up to 32 named injectors with per-frame mutation callbacks |
| Rates | Legacy CCK/OFDM, HT MCS0–7 (+MCS32), VHT 1SS MCS0–9, HE 1SS MCS0–11 |
| Lossless TX | Opt-in reliable mode retries on back-pressure instead of dropping (zero TX drops) |
| Timing | SysTick cycle-accumulator (3 ns resolution, immune to Wi-Fi IRQ tick-lag) disciplined against a 1 MHz coarse timer by a Kalman phase + frequency servo |
| Telemetry | Per-operation ns cost stats (channel/power switch, inject), PHY read-back (RSSI/SNR, CCA/EDCCA), radio TSF |
| Absolute time (opt-in) | Crystal-only disciplined-holdover clock: one-time ppb calibration + optional thermal feed-forward, with an honest growing uncertainty bound (not an atomic clock) |
| Console | Example app drops into an interactive research CLI after self-test, registered into the SDK monitor command table (capture/injector/clock control + telemetry) |
| Facade | Verified lifecycle state machine, capability-grant channel ownership, DUAL mode (capture + inject) |
| Admission | Liu & Layland 85% utilization bound prevents scheduler overload |
| Hopping | UCB1 multi-armed bandit for intelligent channel selection |
| CSI (opt-in) | Channel-State-Information capture via the SDK sounding path (requires an associated peer) |
| Parameter | Value | Version |
|---|---|---|
| Software | Ameba-rtos SDK | master |
| Hardware | Ai-Thinker BW20-12F Dev Kit | 1.0.0 |
The BW20-12F datasheet labels the KM4 core "Cortex-M4F compatible," but the silicon's CPUID reports Cortex-M33 r1p10 (ARMv8-M Mainline) and Realtek's SDK debugs it as such — it is Realtek's "Real-M300" core. The part boots in TrustZone secure state, which is why the DWT cycle counter is unavailable and the timer uses its SysTick path.
| Document | Description |
|---|---|
| Wiki | Full technical reference with all design math |
| Timer | Composite clock, Kalman servo, Allan deviation, 1PPS |
| Injector | ATCS-EDF scheduler, admission control, cost telemetry |
| Monitor | Lock-free capture pipeline, UCB1 hopping, CSI |
| Wifi Radio | Facade lifecycle and grant protocol |
RTL-base is released under the GNU Lesser General Public License v2.1