quality check and example updates

Author: LC-Linkous

.github/workflows/tests.yml

@@ -59,9 +59,10 @@ jobs:
         run: uv sync
 
       - name: Run test suite (hardware tests deselected)
-        # 85% floor, same as hackrfpy. The tree is at ~93%; the gate is there
-        # so a large untested module cannot land unnoticed.
-        run: uv run pytest -m "not hardware" --cov=sdr_dsp --cov-report=xml --cov-report=term-missing --cov-fail-under=85
+        # 95% floor. The tree is at ~99.6% line coverage; a floor far below
+        # that lets a whole untested module land unnoticed, which is exactly
+        # what the gate exists to catch. Raise it again if coverage climbs.
+        run: uv run pytest -m "not hardware" --cov=sdr_dsp --cov-report=xml --cov-report=term-missing --cov-fail-under=95
 
   oldest-deps:
     name: pytest (ubuntu, py3.11, oldest declared numpy/scipy)
@@ -141,7 +142,10 @@ jobs:
         run: uv sync
 
       - name: Ruff lint
-        run: uv run ruff check .
+        # The two maintenance scripts in docs/dev_handbook/ live outside the
+        # package directory ruff is run from, so they are named explicitly;
+        # left to the default they were never checked and drifted.
+        run: uv run ruff check . ../docs/dev_handbook
 
       - name: Mypy
         # Blocking. Not the strict gate hackrfpy runs: sdr_dsp DOES ship a

CHANGELOG.md

@@ -17,10 +17,28 @@ was measured, why a design went the way it did) lives in `docs/LOG.md`.
 
 ### Changed
 - Package description and README links prepared for PyPI (absolute links to
-  the docs; "personal" dropped from the one-line description).
+  the docs; "personal" dropped from the one-line description). The README's
+  "hooks that aren't implemented" line is gone (nothing exported is a stub)
+  and its quick-start now calls the `tune_to_baseband` it imports.
 - Python 3.14 added to the CI matrix and the trove classifiers.
+- `zip()` calls carry an explicit `strict=` throughout (bugbear B905):
+  `strict=True` wherever the sequences must match, which turns a silent
+  truncation into an error.
+- `ssb_receiver.py` builds its test signal with `ssb_modulate`;
+  `spectrum_analyzer.py` draws on axes from `plot_spectrum`; `cfo_demo.py`
+  gains `--fm` for `estimate_fm_cfo` / `correct_fm_cfo`.
+
+### Quality gates
+- ruff: bugbear (`B`) enabled; `docs/dev_handbook/*.py` now linted in CI.
+- Coverage floor raised from 85% to 95%.
+- `test_public_surface.py` also requires a docstring on every module.
 
 ### Added
+- `examples/gain_search_demo.py`: the device-agnostic `GainModel` /
+  `search_gain_model` engine run on three simulated radios (HackRF, RTL-SDR
+  and a hand-built two-stage model). `docs/EXAMPLES.md` also catalogs the four
+  scripts it was missing (`transmit_examples`, `fm_band_explorer`,
+  `collect_sample_data`, `sdr_adapter_template`).
 - 89 edge-case tests (`tests/test_core_edges.py`, `test_io_link_edges.py`,
   `test_stream_sources_edges.py`) covering empty-input guards, argument
   validation, every streaming stage's `reset()`, and alternative branches

docs/EXAMPLES.md

@@ -91,6 +91,7 @@ The TX arc, in build order — each script is one phase of "the library can now
 | `packet_loopback.py` | Phase B: send a verifiable *packet* — `[preamble][sync][length][payload][CRC]` — through frame → modulate → channel → demod → `find_frames`, with the CRC deciding whether it survived. | |
 | `channel_sweep.py` | Phase C: send a framed packet through worsening simulated channels (SNR sweep, optional CFO) and report where the link breaks. | |
 | `two_station_link.py` | Phase D, the capstone: two stations exchanging acked messages over the ARQ link protocol, with a forced frame drop showing a retransmit — all in software. The template to copy for bench work. | |
+| `transmit_examples.py` | Across the sink seam: for each of OOK / FSK / BPSK / QPSK, build a real frame, modulate it, key it out through a `TXSink` (the loopback sink by default), read it back and decode it. Proves `demod(modulate(x)) == x` through the same protocol boundary a real radio sits behind. | |
 
 ## Measurement & detection
 
@@ -100,6 +101,7 @@ The TX arc, in build order — each script is one phase of "the library can now
 | `annotate_bursts.py` | The detect → label → save → reload workflow: detected bursts become SigMF annotations in the recording's sidecar, readable by any SigMF-aware tool. | |
 | `cfo_demo.py` | Measure a carrier frequency offset — and only correct it if you ask. Embodies the measure-don't-auto-apply principle. | |
 | `power_calibration.py` | Turn dBFS into absolute dBm via a one-time calibration against a known reference (opt-in, advanced; only valid for the gain/frequency measured). | |
+| `gain_search_demo.py` | Auto-gain a radio the library has never seen by describing its knobs as a `GainModel`: the same `search_gain_model` engine runs on a simulated HackRF (LNA + amp + VGA), an RTL-SDR (one knob) and a hand-built two-stage radio, choosing the front end by measured pilot quality and the level stage by ADC fill. `--antenna` sets signal strength; `--trace` shows every probe. | |
 
 ## Impairment modeling & extraction
 
@@ -128,6 +130,9 @@ library; see §13 of [`sdr_dsp_REFERENCE.md`](sdr_dsp_REFERENCE.md).)
 | `live_433_capture.py` | Capture a 433 MHz burst (e.g. a key fob) and save it for the OOK/FSK decoders to run on offline. | HW |
 | `live_fm_listen.py` | Tune an FM station and play it through your speakers in real time. | HW, audio |
 | `live_spectrum.py` | Live spectrum display from the HackRF — "what's on this frequency right now?" | HW, plot |
+| `fm_band_explorer.py` | Interactive: sweep the FM band, click a station, tune it live and listen. Built for answering "why am I not hearing anything?" — the sweep, the detected peaks and the tuned channel's pilot check are on screen at once. | HW, plot, audio |
+| `collect_sample_data.py` | The read-only collection tool behind `sample_data/`: records real captures with SigMF sidecars and provenance so the file-based examples have genuine signals to run against. Receive and sweep only; never transmits. | HW |
+| `sdr_adapter_template.py` | A fill-in-the-blanks adapter for a *new* SDR: copy it, complete the four marked spots, and you have an `IQSource` (and optionally a `TXSink`) the core drives with no change to `src/`. Not run directly; the modularity claim made concrete. | |
 
 ---
 

docs/dev_handbook/generate_api_handbook.py

@@ -10,15 +10,14 @@
 """
 import importlib
 import inspect
-import sys
-import textwrap
 
 # the public surface, in the order we want it documented
 MODULES = [
     ("sdr_dsp", "Top-level package", "Lazily-loaded submodules and the flattened DSP API."),
     ("sdr_dsp.core", "core — pure DSP", "Every signal-processing primitive. numpy + scipy only."),
     ("sdr_dsp.core.demod", "core.demod — demodulators", "Recover bits/audio/symbols from IQ."),
-    ("sdr_dsp.core.modulate", "core.modulate — modulators", "Inverse of demod: bits/symbols -> IQ."),
+    ("sdr_dsp.core.modulate", "core.modulate — modulators",
+     "Inverse of demod: bits/symbols -> IQ."),
     ("sdr_dsp.sources", "sources — receive seam", "IQSource protocol and concrete sources."),
     ("sdr_dsp.sinks", "sinks — output & transmit seam", "TXSink protocol, file and plot sinks."),
     ("sdr_dsp.io", "io — file formats", "SigMF load/save, annotations, metadata."),
@@ -162,7 +161,7 @@ def main():
 
     # table of contents
     print("## Modules\n")
-    for modname, title, _ in MODULES:
+    for _modname, title, _ in MODULES:
         anchor = title.lower().replace(" — ", "--").replace(" ", "-").replace("—", "")
         print(f"- [{title}](#{anchor})")
     print("\n---\n")
@@ -207,4 +206,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    main()

docs/dev_handbook/tree_map.py

@@ -1,7 +1,6 @@
 #!/usr/bin/env python3
 """Generate an ASCII file tree of the dcdash project."""
 
-import os
 import sys
 from pathlib import Path
 
@@ -65,4 +64,4 @@ def main():
 
 
 if __name__ == '__main__':
-    main()
+    main()

sdr_dsp/README.md

@@ -13,8 +13,9 @@ can't do, and why it's a good development platform.
 
 ## Status
 
-Pre-release; there is no Version 1 yet, and it is heavily under development.
-Some features have hooks that aren't implemented. What is proven where:
+Pre-release; there is no Version 1 yet, and the API may still move between
+minor versions. Everything exported is implemented and tested; what differs
+is how much of it has met a real radio. What is proven where:
 
 - **FM receive** — validated on real, ear-verified over-the-air captures.
 - **Other demodulators (AM/SSB/CW, OOK/ASK, FSK, the PSK family, QAM-16)** —
@@ -42,7 +43,11 @@ from sdr_dsp.io import load_iq
 
 iq, meta = load_iq("sample_data/fm_2Msps.iq")
 fs = meta["global"]["core:sample_rate"]
-# (already at baseband here; tune_to_baseband handles off-center captures)
+# A direct-conversion SDR puts a DC spike at its tuned frequency, so real
+# captures are often made with the radio tuned a little to one side and the
+# station brought back to 0 Hz in software. This capture is centered, so the
+# offset is 0; see docs/DC_SPIKE.md for the recipe.
+iq = tune_to_baseband(iq, offset_hz=0.0, sample_rate=fs)
 audio = fm_demod(fir_apply(iq, design_lowpass(100e3, fs)),
                  deviation_hz=75e3, sample_rate=fs)
 ```

sdr_dsp/examples/cfo_demo.py

@@ -16,13 +16,15 @@
 Usage:
     python examples/cfo_demo.py
     python examples/cfo_demo.py --offset 35000 --correct
+    python examples/cfo_demo.py capture.iq --fm --correct
 """
 import argparse
 import sys
 
 import numpy as np
 
-from sdr_dsp.core import estimate_cfo, frequency_shift
+from sdr_dsp.core import (estimate_cfo, estimate_fm_cfo, correct_fm_cfo,
+                          frequency_shift)
 
 def main():
     p = argparse.ArgumentParser(description="Measure/correct carrier offset.")
@@ -32,6 +34,11 @@ def main():
                    help="synth: put the signal this far off center (Hz)")
     p.add_argument("--correct", action="store_true",
                    help="actually apply the correction (default: measure only)")
+    p.add_argument("--fm", action="store_true",
+                   help="treat the input as broadcast FM: channelize to the FM "
+                        "channel before measuring (estimate_fm_cfo / "
+                        "correct_fm_cfo), so out-of-channel energy cannot "
+                        "pull the estimate")
     args = p.parse_args()
 
     if args.iq_file:
@@ -48,8 +55,18 @@ def main():
         print(f"[*] synthetic signal placed {args.offset/1e3:g} kHz off center")
 
     # MEASURE -- this does not change the data
-    cfo = estimate_cfo(iq, fs)
-    print(f"[*] measured carrier offset: {cfo/1e3:+.2f} kHz")
+    if args.fm:
+        cfo = estimate_fm_cfo(iq, fs)
+        if cfo is None:
+            print("[!] estimate_fm_cfo declined: the capture is too short or "
+                  "the rate too low to channelize to the FM channel",
+                  file=sys.stderr)
+            return 1
+        print(f"[*] measured FM carrier offset: {cfo/1e3:+.2f} kHz "
+              "(mean instantaneous frequency inside the channel)")
+    else:
+        cfo = estimate_cfo(iq, fs)
+        print(f"[*] measured carrier offset: {cfo/1e3:+.2f} kHz")
 
     if not args.correct:
         before = iq.copy()
@@ -61,8 +78,15 @@ def main():
         return 0
 
     # CORRECT -- your explicit choice
-    corrected = frequency_shift(iq, -cfo, fs)
-    residual = estimate_cfo(corrected, fs)
+    if args.fm:
+        # correct_fm_cfo measures and shifts in one call, and returns the
+        # offset it applied so the correction is never hidden from you
+        corrected, applied = correct_fm_cfo(iq, fs)
+        assert applied == cfo
+        residual = estimate_fm_cfo(corrected, fs) or 0.0
+    else:
+        corrected = frequency_shift(iq, -cfo, fs)
+        residual = estimate_cfo(corrected, fs)
     print(f"[*] corrected by {-cfo/1e3:+.2f} kHz; residual offset now "
           f"{residual/1e3:+.2f} kHz")
     print("[*] signal is now centered (residual ~ one FFT bin)")

sdr_dsp/examples/channelizer.py

@@ -66,7 +66,7 @@ def main():
               f"({'oversampled' if args.oversample else 'critically sampled'})")
         print(f"\n    {'ch':>3} {'center (kHz)':>14} {'power':>10}")
         print("    " + "-" * 32)
-        for i, (f, c) in enumerate(zip(freqs, chans)):
+        for i, (f, c) in enumerate(zip(freqs, chans, strict=True)):
             pw = power_dbfs(c)
             mark = "  <-- signal" if pw > -20 else ""
             print(f"    {i:>3} {f/1e3:>14.1f} {pw:>7.1f} dB{mark}")

sdr_dsp/examples/cw_decoder.py

@@ -35,7 +35,7 @@
 def synth_cw(text, fs, dit_samples, tone_hz=800, noise=0.03):
     """Build a complex tone keyed with the Morse for `text`."""
     on = []   # list of (is_on, units)
-    for ci, ch in enumerate(text.upper()):
+    for ch in text.upper():
         if ch == " ":
             on.append((False, 7))
             continue

sdr_dsp/examples/fsk_decoder.py

@@ -106,7 +106,7 @@ def main():
     if truth is not None:
         n = min(len(syms), len(truth))
         # align (recovery may offset by a symbol) and report agreement
-        errs = sum(int(a) != int(b) for a, b in zip(syms[:n], truth[:n]))
+        errs = sum(int(a) != int(b) for a, b in zip(syms[:n], truth[:n], strict=True))
         print(f"[*] vs known truth: {n-errs}/{n} symbols match")
     return 0