tdma example: burst-level bandwidth TDMA (narrowband <-> wide)

[josephnef]

What

A worked, runnable example of the burst-level bandwidth TDMA idea that FastSetBandwidth (#223) unlocks: a transmitter alternates bursts between a robust narrowband width (5/10 MHz — the ~6 dB link-budget win, for critical frames) and a wide width (20/40 MHz — throughput, for bulk frames), flipping bandwidth per-burst in well under a millisecond to a few ms.

It is burst-level, not per-frame, for two reasons that are physics, not laziness: narrowband is an ADC-clock-domain state (not a radiotap field), and a receiver decodes exactly one width at a time. So frames of one protection class are grouped into a burst, both ends switch, then the next burst. Per-frame rate-UEP is layered on top (critical also rides a robust rate, bulk a fast MCS — reusing the svctx radiotap mechanism).

The interesting hard part: sync

devourer exposes no hardware time primitive (no host TSF read, no PPS/GPS hook — only a per-frame read-only tsfl). The example ships both receiver sync strategies so experimenters can compare:

• wallclock — both ends compute the phase from system_clock (shared Unix-epoch anchor). Trivially aligned same-machine; cross-machine needs GPS/PPS/NTP-disciplined clocks (the caller's to provide).
• marker — self-clocking: the TX emits a marker frame at each narrowband-burst start; the RX camps narrowband until it decodes one, anchors its schedule to it, coasts on steady_clock, and re-anchors on each subsequent marker. No external clock at all.

A lockstep receiver switches guard_ms early to absorb the switch-latency dead-window (the guard must exceed the chip's switch latency; bursts ≫ it).

Roles (one binary, one adapter, one role)

• DEVOURER_TDMA_ROLE=tx — run the schedule, inject class-tagged frames + markers.
• =rx-sync (DEVOURER_TDMA_SYNC=wallclock|marker) — switch in lockstep (the user's 1 TX + 1 RX mode).
• =rx-camp (DEVOURER_TDMA_CAMP=5|10|20) — camp on one width. A tx + two rx-camp (narrowband + wide) is the user's 1 TX + 2 RX mode: an independent, always-listening robust narrowband link + a wide bulk link.

Schedule knobs: DEVOURER_TDMA_NB / _WIDE, _NB_MS / _WIDE_MS, _EPOCH_MS, _GUARD_MS, _CRIT_RATE / _BULK_RATE, _GAP_US. Metrics are JSONL on stdout ({"ev":"tdma.*"}); each RX prints a per-band × per-class decode table.

Bench validation (tests/tdma_demo.sh)

TX 8812AU, RX 8822CU/8822BU, ch 36, 10 MHz narrowband. A correct run shows critical+marker under the narrowband band and bulk under the wide band, near-zero off-diagonal (only frames caught mid-switch):

Mode 1 wall-clock lockstep:   narrowband  43 marker / 7700 crit /    4 bulk
                              wide         0        /    3      / 7432
Mode 1 marker lockstep:       narrowband  42       / 8572      /    1
                              wide         0        /    5      / 7341
Mode 2 dual-RX (camp NB):     narrowband  52       /11678      /    2   (wide row 0)
           dual-RX (camp wide): wide       0        /    0      / 7509   (narrowband row 0)

Both sync modes lock and track; the dual-RX split is clean (each receiver hears only its band's bursts). ctest green; no library changes — additive examples/tdma/ + tests/tdma_demo.sh + one docs/narrowband.md section, so it can't regress the driver.

🤖 Generated with Claude Code