Skip to content

Commit fe28540

Browse files
committed
gitignore and changelog
1 parent 2e87c75 commit fe28540

2 files changed

Lines changed: 96 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -216,3 +216,4 @@ __marimo__/
216216

217217
# Streamlit
218218
.streamlit/secrets.toml
219+
tests/fm_testdata/

‎CHANGELOG.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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
<!--
84179
Roadmap for this branch (append entries above as each lands):

0 commit comments

Comments
 (0)