docs: visual RF primer — four animated diagrams for newcomers#182
Merged
Conversation
Add docs/rf-primer.md, a picture-book walk through the low-level RF machinery for readers new to it, built in the DEVOURER live-monitor style (siblings of the per-subcarrier waterfall and NHM histogram): - OFDM channel anatomy (tools/ofdm_anatomy_gif.py) — subcarriers, DC null, pilots, guard, 312.5 kHz spacing, and the 20/40/80 + 5/10 narrowband widths; the coordinate system every per-tone sensor indexes into. - IQ constellation vs SNR (tools/constellation_gif.py) — QPSK -> 256-QAM densifying, clusters smearing as the same-channel noise breaks the higher orders; the textbook AWGN model, EVM = 1/sqrt(SNR). Ties to the MCS-headroom probe. - CW tone vs modulated carrier (tools/spectrum_compare_gif.py) — a spike vs a flat 20 MHz block, at the real levels a B210 measured on ch100; grounds DEVOURER_CW_TONE vs DEVOURER_CONT_TX. - AGC / ADC saturation (tools/agc_gif.py) — gain backing off with signal until the floor, where the ADC clips and the RX goes deaf; the "collapse" the energy sensor sees under a strong co-located interferer. Shared chrome in tools/monitor_style.py. tests/sdr_spectrum.py gains a --dump for the PSD capture the spectrum diagram's levels came from. README points newcomers at the primer. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
josephnef
added a commit
that referenced
this pull request
Jul 5, 2026
…y, hopping (#183) Completes the visual RF primer (#182) with the remaining four animated diagrams, woven into a single logically-ordered course in `docs/rf-primer.md` — a newcomer can read from a single subcarrier all the way to a hopping, diversity-combined link. | # | New diagram | Teaches | |---|---|---| | 3 | **TX pipeline** | bits → scramble → FEC → interleave → QAM → IFFT → cyclic-prefix → RF: how a packet becomes a waveform | | 6 | **Beamforming self-sounding** | NDPA → NDP → measure H(k) → CSI report between two adapters — the source of the waterfall, the localizer, and the motion sensor | | 7 | **Antenna diversity / MRC** | two fading antennas: correlated when still (combining barely helps) vs decorrelated under motion (fills the fades) — why chain count is a fade-state lever | | 8 | **Frequency hopping** | a time–frequency view of the TX spreading across the band and escaping a parked interferer — hopping as a frequency-diversity interleaver | The primer now runs 1–8 in order: channel → modulation → TX pipeline → on-air → receiver → sounding → diversity → hopping. All in the shared DEVOURER live-monitor style (`tools/monitor_style.py`); each regenerates from its own `tools/*_gif.py`. README points at the eight-part primer. Docs/tooling only; GIFs 161 KB–978 KB (all ≤ the existing waterfall). 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A picture-book primer on the low-level RF machinery for readers new to it —
docs/rf-primer.md— with four short animations in the DEVOURER live-monitorstyle (siblings of the per-subcarrier waterfall and NHM histogram). Read top to
bottom and the rest of the docs click.
DEVOURER_CW_TONEvsDEVOURER_CONT_TXEverything is grounded in what devourer measures: the constellation noise is the
textbook AWGN model, the spectrum levels are a real USRP B210 capture on ch100,
and the AGC behaviour is the very effect the sensing docs describe.
Shared chrome lives in
tools/monitor_style.py; each diagram regenerates fromits own
tools/*_gif.py.tests/sdr_spectrum.pygains a--dumpfor the PSDcapture the spectrum levels came from. README points newcomers at the primer.
Docs/tooling only; GIFs 341–738 KB each (all under the existing waterfall).
🤖 Generated with Claude Code