@@ -28,6 +28,63 @@ release.
2828 (` cli.py ` from 12% to ~ 98%).
2929- Community health files: ` CONTRIBUTING.md ` , ` CODE_OF_CONDUCT.md ` ,
3030 ` SECURITY.md ` , issue templates, and a pull request template.
31+ - ` examples/channel_monitor.py ` : live multi-channel power meter driven by
32+ ` monitor_frequencies ` (one continuous sweep, ASCII bar output, no plotting
33+ extra) -- the library's sweep-backed monitoring style previously had no
34+ example.
35+ - ` examples/tx_test_tone.py ` : the first and only transmitting example. A
36+ constant-wave test tone behind the deliberate RX->TX mode switch, with a
37+ required and capped duration (10 s), a deliberately low default TX gain, the
38+ RF amp never enabled, and ` --print-cmd ` dry-run support.
39+ - ` tests/collect_real_FM_data.py ` : records one named FM broadcast station as a
40+ reference dataset for comparison against a hardware receiver implementation.
41+ Writes the IQ + SigMF sidecar plus a machine-readable ` .report.json ` pinning
42+ down exact settings, firmware/tools versions, raw-IQ health (power, clipping,
43+ DC), and an FM-discriminator check for the 19 kHz stereo pilot with its SNR
44+ -- the definitive "this really is the station" test. Deliberately split from
45+ ` tests/collect_real_data.py ` , which freezes tiny verbatim parser fixtures.
46+ - ` tests/collect_fm_testdata.py ` : repeatable FM test-data generator with a
47+ five-stage hardware pipeline -- discover (top-N sweep candidates), calibrate
48+ (walks LNA/VGA until peak amplitude lands in [ 0.25, 0.70] ), verify (short
49+ probe per candidate; the 19 kHz pilot must show at the tuning offset before
50+ any full recording, making the script robust to time-of-day and weather
51+ propagation changes), record (station parked at +300 kHz, clear of the DC
52+ spike), validate. Falls back (` --fallback auto|always|never ` ) to a
53+ deterministic synthetic FM recording (fixed-seed; byte-identical every run)
54+ in the identical int8 + SigMF format, so downstream pipelines are never
55+ blocked by RF conditions or a missing board. Reports log every candidate
56+ tried with its pilot SNR, keeping runs at different times comparable.
57+ - Per-capture validation in ` examples/collect_sample_data.py ` : short reads,
58+ dead/quiet front end, gain-induced clipping, stuck DC, and ADC utilization
59+ (peak amplitude < 0.1, i.e. fewer than ~ 13 of 127 int8 codes) are flagged.
60+ Validation is band-aware: bands are tagged ` continuous ` (fm), ` bursty `
61+ (airband, ism433, ism915), or ` scheduled ` (noaa), and low utilization is a
62+ hard SUSPECT only for continuous bands -- on bursty bands a quiet window is
63+ correct data and is annotated as a noise-floor reference instead. A
64+ peak-to-median burst-ratio metric reports detected activity. Suspect
65+ captures are kept on disk but flagged on stderr, marked in the generated
66+ sample-data README, and the script exits 2 so a bad collection run cannot
67+ silently ship. (Motivated by a real 2026-09-17 run whose captures spanned
68+ only +/-4 of 127 int8 codes -- effectively 3-bit recordings -- while passing
69+ every earlier check.)
70+ - ` --hunt ` / ` --hunt-secs ` in ` examples/collect_sample_data.py ` : for bursty
71+ bands, probe in 100 ms slices until a transmission appears (burst ratio
72+ > = 10 dB), then take the real capture -- so an ISM sample can be made to
73+ actually contain a burst (e.g. by pressing a key fob during the hunt window).
74+ - The generated sample-data README now annotates each IQ file as a
75+ * (noise-floor reference)* or * (burst captured)* .
76+ - ` .gitignore ` : ` tests/fm_testdata/ ` (deterministic, regenerable output).
77+ - ` examples/fm_demod_to_wav.py ` : the missing last mile -- demodulate a
78+ captured broadcast-FM IQ file to an audible mono 16-bit WAV using only
79+ numpy and the stdlib. Channelize (staged windowed-sinc decimation to
80+ 200 kHz), FM-discriminate, 75 us de-emphasis (` --deemph 50 ` for regions
81+ using 50 us), 15 kHz audio lowpass to a 50 kHz WAV. Handles off-center
82+ stations via ` --offset ` (e.g. 300e3 for ` collect_fm_testdata.py ` output)
83+ and prints a multiplex readout proving the 19 kHz pilot, 38 kHz stereo
84+ subcarrier, and 57 kHz RDS are present in the discriminator output.
85+ Developed and verified against the 2026-09-17 98.1 MHz reference capture:
86+ the output audio shows music-shaped spectra, syllabic-band envelope
87+ modulation, and spectral flatness 0.09 (structured content, not noise).
3188
3289### Changed
3390- Library diagnostics now go through the standard ` logging ` module instead of
@@ -49,6 +106,35 @@ release.
49106 ` 5 - Production/Stable ` to match the 1.0.0 release.
50107- Ruff configuration added (` line-length = 100 ` , ` select = ["E", "F", "W"] ` ), and
51108 the codebase made lint-clean so the CI lint job is meaningful.
109+ - ` examples/persistent_capture.py ` rewritten to match its name and the README's
110+ description: a gapless segment collector draining ONE long-lived
111+ ` open_receiver() ` stream into back-to-back ` seg_NNN.iq ` files with SigMF
112+ sidecars (contrast with ` capture(segment_secs=...) ` , whose per-file process
113+ re-open leaves a short gap between files). The file had been a near-duplicate
114+ of ` waterfall_persistent.py ` whose own header pointed at the wrong filename.
115+ - ` examples/waterfall_persistent.py ` absorbed the improvements stranded in that
116+ duplicate: frame-averaged spectra, DC/LO-leakage spike suppression, and
117+ large-block reads so the pipe drains fast enough to keep ` hackrf_transfer `
118+ streaming at 10 Msps.
119+ - ` hackrfpy/README.md ` examples list corrected (` persistent_capture.py ` entry
120+ now matches the code) and extended with the new examples, including a new
121+ Transmit section.
122+ - ` examples/collect_sample_data.py ` defaults: collects three bands (fm,
123+ ism433, ism915) instead of one, and exposes ` --lna ` / ` --vga ` with defaults
124+ raised to 32 / 28 (the old library defaults of 16 / 20 produced the 3-bit
125+ captures described above).
126+ - ` tests/collect_real_FM_data.py ` defaults: gains raised to LNA 32 / VGA 28,
127+ and default sample rate raised from 2 Msps to 8 Msps -- the HackRF's
128+ baseband filter bottoms out at 1.75 MHz, so rates under 8 Msps admit
129+ aliases; a reference recording deserves the alias-free version at the price
130+ of larger files.
131+ - ` tests/collect_fm_testdata.py ` captures at an integer multiple of the
132+ requested output rate that clears 8 Msps and decimates in software
133+ (windowed-sinc FIR) back down, so output files are unchanged (2 Msps int8 +
134+ SigMF by default) while discovery and demodulation run alias-free. Offline
135+ verification: an interferer 1.7 MHz off-channel, which a direct 2 Msps
136+ capture folds onto the demod region, is suppressed ~ 45 dB while the pilot
137+ survives at ~ 72 dB SNR.
52138
53139### Fixed
54140- The ` atexit ` backstop never reaped an orphaned ` PersistentReceiver ` .
@@ -79,6 +165,15 @@ release.
79165 directory on every run.
80166- ` CITATION.cff ` version and release date corrected to ` 1.0.0 ` / ` 2026-06-16 ` ,
81167 aligning the citation metadata with ` pyproject.toml ` and the tagged release.
168+ - Removed a stray ` hackrfpy/capture.sigmf-meta ` at the package root, left over
169+ from a July test run at 433.92 MHz.
170+ - ` examples/fm_demod_to_wav.py ` de-emphasis was accidentally quadratic: each
171+ 64 K block was convolved against a full-block-length geometric kernel
172+ (~ 5e10 multiply-adds for a 2 s / 8 Msps capture), stalling the script after
173+ the multiplex readout. The kernel is now truncated where its weight falls
174+ below 1e-9 (a few hundred taps at 200 kHz); a 2 s reference file demodulates
175+ in ~ 3 s end to end, with output identical to within 1 LSB. Stage timings are
176+ now printed so a future stall is self-locating.
82177
83178<!--
84179Roadmap for this branch (append entries above as each lands):
0 commit comments