Skip to content

Commit eb03759

Browse files
committed
examples updated. sample and demod
1 parent dad3237 commit eb03759

2 files changed

Lines changed: 253 additions & 18 deletions

File tree

‎hackrfpy/examples/collect_sample_data.py‎

Lines changed: 76 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -63,28 +63,41 @@
6363
BANDS = {
6464
"fm": {
6565
"center": 98_000_000, "sweep": (88_000_000, 108_000_000),
66-
"desc": "FM broadcast band"},
66+
"desc": "FM broadcast band", "signal": "continuous"},
6767
"airband": {
6868
"center": 124_000_000, "sweep": (118_000_000, 137_000_000),
69-
"desc": "VHF airband (AM voice)"},
69+
"desc": "VHF airband (AM voice)", "signal": "bursty"},
7070
"ism433": {
7171
"center": 433_920_000, "sweep": (433_000_000, 435_000_000),
72-
"desc": "433 MHz ISM"},
72+
"desc": "433 MHz ISM", "signal": "bursty"},
7373
"ism915": {
7474
"center": 915_000_000, "sweep": (902_000_000, 928_000_000),
75-
"desc": "915 MHz ISM (US)"},
75+
"desc": "915 MHz ISM (US)", "signal": "bursty"},
7676
"noaa": {
7777
"center": 137_500_000, "sweep": (137_000_000, 138_000_000),
78-
"desc": "NOAA weather satellite downlink"},
78+
"desc": "NOAA weather satellite downlink", "signal": "scheduled"},
7979
}
8080

8181

82-
def _validate_capture(iq, expected_n):
82+
def _burst_ratio_db(iq):
83+
# Peak-to-median magnitude: >~10 dB means something transmitted during
84+
# the window; near 0 dB means the window is pure noise floor.
85+
if not len(iq):
86+
return 0.0
87+
mag = np.abs(iq)
88+
med = float(np.median(mag)) + 1e-9
89+
return 10 * np.log10((float(mag.max()) / med) ** 2)
90+
91+
92+
def _validate_capture(iq, expected_n, signal="continuous"):
8393
# Catch the failure modes of a bad collection run BEFORE the data goes
8494
# into the sample library: short reads, a dead/disconnected front end
8595
# (pure noise-floor silence), a stuck DC rail, and gain-induced clipping.
86-
# Returns (ok, [reasons]).
87-
reasons = []
96+
# Band-aware: a CONTINUOUS band (FM broadcast) with a tiny peak is a bad
97+
# capture, but a BURSTY band (ISM) with a tiny peak usually means nothing
98+
# transmitted during the window -- correct data, noted, not SUSPECT.
99+
# Returns (ok, [reasons], [notes]).
100+
reasons, notes = [], []
88101
if len(iq) < 0.9 * expected_n:
89102
reasons.append(f"short read ({len(iq)}/{expected_n} samples)")
90103
if len(iq):
@@ -95,9 +108,20 @@ def _validate_capture(iq, expected_n):
95108
"dead antenna / wrong gain?)")
96109
peak = float(mag.max())
97110
if peak < 0.1:
98-
reasons.append(f"low ADC utilization (peak {peak:.3f} < 0.1, "
99-
f"~{int(peak*128)} of 127 int8 codes -- raise "
100-
"LNA/VGA; see examples/calibrate.py)")
111+
msg = (f"low ADC utilization (peak {peak:.3f} < 0.1, "
112+
f"~{int(peak*128)} of 127 int8 codes)")
113+
if signal == "continuous":
114+
reasons.append(msg + " -- raise LNA/VGA; see "
115+
"examples/calibrate.py")
116+
else:
117+
notes.append(msg + f" -- normal for a {signal} band with no "
118+
"transmission in the window; data is a "
119+
"noise-floor reference (try --hunt to catch a "
120+
"burst)")
121+
if signal != "continuous":
122+
br = _burst_ratio_db(iq)
123+
if br >= 10.0:
124+
notes.append(f"activity detected (burst ratio {br:.0f} dB)")
101125
clip = float(np.mean(mag > 0.99))
102126
if clip > 0.01:
103127
reasons.append(f"clipping ({clip*100:.1f}% of samples -- "
@@ -107,7 +131,7 @@ def _validate_capture(iq, expected_n):
107131
reasons.append(f"large DC offset ({dc:.3f})")
108132
else:
109133
reasons.append("empty capture")
110-
return (not reasons), reasons
134+
return (not reasons), reasons, notes
111135

112136

113137
def _signal_summary(iq):
@@ -121,7 +145,7 @@ def _signal_summary(iq):
121145
return f"mean {db:.1f} dBFS, peak |amp| {peak:.3f}"
122146

123147

124-
def collect_band(h, name, args, suspects):
148+
def collect_band(h, name, args, suspects, file_notes):
125149
band = BANDS[name]
126150
os.makedirs(OUT_DIR, exist_ok=True)
127151
n = int(args.sample_rate * args.seconds)
@@ -132,14 +156,39 @@ def collect_band(h, name, args, suspects):
132156
print(f"\n== {name}: IQ capture @ {band['center']/1e6:g} MHz "
133157
f"({args.seconds}s, {args.sample_rate/1e6:g} Msps) ==")
134158
try:
159+
if args.hunt and band.get("signal") in ("bursty", "scheduled"):
160+
# Probe in short slices until something transmits, THEN take the
161+
# real capture -- so a bursty band's sample actually contains a
162+
# burst. Press a key fob / doorbell during the hunt to help.
163+
print(f" hunting for a burst (up to {args.hunt_secs:g}s; "
164+
"trigger: peak > 3x median)...")
165+
import time as _time
166+
t0 = _time.time()
167+
while _time.time() - t0 < args.hunt_secs:
168+
probe = h.capture_array(band["center"], args.sample_rate,
169+
int(args.sample_rate * 0.1),
170+
lna=args.lna, vga=args.vga)
171+
if len(probe) and _burst_ratio_db(probe) >= 10.0:
172+
print(f" burst seen after {_time.time()-t0:.1f}s -- "
173+
"capturing now")
174+
break
175+
else:
176+
print(" no burst within the hunt window; capturing "
177+
"noise floor anyway")
135178
h.capture(band["center"], args.sample_rate, num_samples=n,
136179
out=iq_path, sigmf=True, lna=args.lna, vga=args.vga)
137180
iq = load_iq(iq_path)
138181
size_mb = os.path.getsize(iq_path) / 1e6
139182
print(f" wrote {os.path.basename(iq_path)} "
140183
f"({size_mb:.1f} MB, {len(iq)} samples) -- {_signal_summary(iq)}")
141184
print(f" + {os.path.basename(iq_path).rsplit('.',1)[0]}.sigmf-meta")
142-
ok, reasons = _validate_capture(iq, n)
185+
ok, reasons, notes = _validate_capture(
186+
iq, n, band.get("signal", "continuous"))
187+
for note in notes:
188+
print(f" [i] {note}")
189+
if notes:
190+
file_notes[iq_path] = ("burst captured" if any(
191+
"activity" in x for x in notes) else "noise-floor reference")
143192
if not ok:
144193
print(" [!] SUSPECT capture -- " + "; ".join(reasons),
145194
file=sys.stderr)
@@ -174,7 +223,8 @@ def collect_band(h, name, args, suspects):
174223
return results
175224

176225

177-
def write_readme(collected, args, det, suspects=()):
226+
def write_readme(collected, args, det, suspects=(), file_notes=None):
227+
file_notes = file_notes or {}
178228
# A README for the sample library so the data is self-documenting.
179229
path = os.path.join(OUT_DIR, "README.md")
180230
with open(path, "w", newline="\n") as f:
@@ -197,7 +247,8 @@ def write_readme(collected, args, det, suspects=()):
197247
for p in collected:
198248
flag = " **(SUSPECT -- failed validation; re-collect)**" \
199249
if p in suspects else ""
200-
f.write(f"- `{os.path.basename(p)}`{flag}\n")
250+
note = f" *({file_notes[p]})*" if p in file_notes else ""
251+
f.write(f"- `{os.path.basename(p)}`{flag}{note}\n")
201252
print(f"\n wrote {os.path.relpath(path, _HERE)}")
202253

203254

@@ -219,6 +270,12 @@ def main():
219270
"16 produced ~3-bit captures on 2026-09-17)")
220271
p.add_argument("--vga", type=int, default=28,
221272
help="VGA gain dB (default 28)")
273+
p.add_argument("--hunt", action="store_true",
274+
help="for bursty bands (ISM, airband): probe until a "
275+
"transmission appears before capturing, so the "
276+
"sample contains an actual burst")
277+
p.add_argument("--hunt-secs", type=float, default=30.0,
278+
help="max seconds to hunt per band (default 30)")
222279
p.add_argument("--no-sweep", action="store_true",
223280
help="IQ captures only, skip sweep datasets")
224281
args = p.parse_args()
@@ -236,13 +293,14 @@ def main():
236293

237294
collected = []
238295
suspects = []
296+
file_notes = {}
239297
try:
240298
for name in bands:
241-
collected += collect_band(h, name, args, suspects)
299+
collected += collect_band(h, name, args, suspects, file_notes)
242300
except KeyboardInterrupt:
243301
print("\ninterrupted", file=sys.stderr)
244302
if collected:
245-
write_readme(collected, args, det, suspects)
303+
write_readme(collected, args, det, suspects, file_notes)
246304
total = sum(os.path.getsize(p) for p in collected
247305
if p.endswith(".iq")) / 1e6
248306
print(f"\n== done: {len(collected)} files, ~{total:.1f} MB of IQ "
Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
#! /usr/bin/python3
2+
##--------------------------------------------------------------------\
3+
# hackrfpy 'examples/fm_demod_to_wav.py'
4+
# The missing last mile: turn a captured IQ file into AUDIBLE audio.
5+
# Broadcast-FM demodulation -- channelize, discriminate, de-emphasize,
6+
# write a mono 16-bit WAV -- using only numpy and the stdlib.
7+
#
8+
# Chain (rates for the default 8 Msps reference capture):
9+
# 1. load IQ + SigMF sidecar (rate and center come from the sidecar)
10+
# 2. mix the station to DC (--offset, for captures where the station
11+
# is parked off-center, e.g. +300 kHz from collect_fm_testdata.py)
12+
# 3. FIR lowpass + decimate to a ~200 kHz channel (windowed sinc,
13+
# staged x8 then x5)
14+
# 4. FM discriminator: phase difference of successive samples
15+
# 5. 75 us de-emphasis (single-pole IIR; use --deemph 50 outside
16+
# the Americas/South Korea)
17+
# 6. 15 kHz audio lowpass, decimate to 50 kHz, normalize, WAV
18+
#
19+
# This intentionally decodes MONO (the L+R sum). The 19 kHz pilot,
20+
# 38 kHz stereo subcarrier, and 57 kHz RDS are all present in the
21+
# discriminator output this script produces -- extracting them is the
22+
# natural next exercise, and the printed multiplex power readout shows
23+
# they are there.
24+
#
25+
# Works on: tests/fm_reference/ captures (station at center),
26+
# tests/fm_testdata/ captures (--offset 300e3), or any FM capture with
27+
# a sidecar. SAFETY: file processing only; never touches the device.
28+
#
29+
# Usage:
30+
# uv run python examples/fm_demod_to_wav.py tests/fm_reference/fm_98.1MHz_8Msps.iq
31+
# uv run python examples/fm_demod_to_wav.py tests/fm_testdata/fm_hw_103.7MHz_2Msps.iq --offset 300e3
32+
#
33+
#
34+
# Author(s): Lauren Linkous
35+
##--------------------------------------------------------------------\
36+
import argparse
37+
import os
38+
import sys
39+
import time
40+
import wave
41+
42+
import numpy as np
43+
44+
from hackrfpy import load_iq, parse_freq, read_sigmf_meta
45+
46+
AUDIO_FS_TARGET = 50_000.0 # output WAV rate (channel_fs / 4)
47+
CHANNEL_FS_TARGET = 200_000.0 # wide enough for +/-75 kHz deviation
48+
49+
50+
def lpf_decimate(x, factor, cutoff_frac=0.45):
51+
# Windowed-sinc FIR lowpass then downsample. cutoff_frac is relative to
52+
# the OUTPUT Nyquist; 0.45 leaves transition headroom.
53+
if factor == 1:
54+
return x
55+
ntaps = 16 * factor + 1
56+
m = np.arange(ntaps) - (ntaps - 1) / 2
57+
taps = np.sinc(2 * (cutoff_frac / factor) * m) * np.hanning(ntaps)
58+
taps /= taps.sum()
59+
return np.convolve(x, taps, mode="same")[::factor]
60+
61+
62+
def staged_factors(total):
63+
# split a big decimation into stages (cheaper: taps scale per stage)
64+
stages = []
65+
for f in (8, 5, 4, 3, 2):
66+
while total % f == 0 and total > 1:
67+
stages.append(f)
68+
total //= f
69+
if total > 1:
70+
stages.append(total)
71+
return stages
72+
73+
74+
def main():
75+
p = argparse.ArgumentParser(
76+
description="Demodulate a broadcast-FM IQ capture to a mono WAV.")
77+
p.add_argument("iq_file", help="int8 interleaved IQ file with sidecar")
78+
p.add_argument("--offset", type=parse_freq, default=0.0,
79+
help="station offset from capture center in Hz "
80+
"(default 0; collect_fm_testdata.py files use 300e3)")
81+
p.add_argument("--out", default=None,
82+
help="output WAV path (default: alongside the IQ file)")
83+
p.add_argument("--deemph", type=float, default=75.0,
84+
help="de-emphasis time constant in us (75 Americas/KR, "
85+
"50 most elsewhere; default 75)")
86+
args = p.parse_args()
87+
88+
meta = read_sigmf_meta(args.iq_file)
89+
fs = float(meta["global"]["core:sample_rate"])
90+
center = float(meta["captures"][0]["core:frequency"])
91+
station = center + args.offset
92+
print(f"[*] {os.path.basename(args.iq_file)}: {fs/1e6:g} Msps, "
93+
f"center {center/1e6:g} MHz, station {station/1e6:g} MHz")
94+
95+
t0 = time.perf_counter()
96+
iq = load_iq(args.iq_file)
97+
98+
# 2. mix the station to DC
99+
if args.offset:
100+
t = np.arange(len(iq)) / fs
101+
iq = iq * np.exp(-2j * np.pi * args.offset * t)
102+
103+
# 3. channelize to ~200 kHz
104+
chan_factor = max(1, int(round(fs / CHANNEL_FS_TARGET)))
105+
x = iq
106+
for f in staged_factors(chan_factor):
107+
x = lpf_decimate(x, f)
108+
chan_fs = fs / chan_factor
109+
print(f"[*] channelized: x{chan_factor} -> {chan_fs/1e3:g} kHz "
110+
f"({time.perf_counter()-t0:.1f}s)")
111+
112+
# 4. FM discriminator, scaled to Hz of instantaneous deviation
113+
demod = np.angle(x[1:] * np.conj(x[:-1])) * chan_fs / (2 * np.pi)
114+
115+
# multiplex readout: prove the pilot/stereo/RDS are in there
116+
spec = np.abs(np.fft.rfft(demod * np.hanning(len(demod)))) ** 2
117+
fr = np.fft.rfftfreq(len(demod), 1.0 / chan_fs)
118+
119+
def band_db(lo, hi):
120+
m = (fr >= lo) & (fr < hi)
121+
return 10 * np.log10(float(spec[m].max()) + 1e-20) if m.any() else -200
122+
123+
ref = band_db(300, 15_000)
124+
print(f"[*] multiplex (dB rel. audio peak): "
125+
f"pilot 19k {band_db(18_700, 19_300)-ref:+.1f}, "
126+
f"stereo 38k {band_db(37_000, 39_000)-ref:+.1f}, "
127+
f"RDS 57k {band_db(56_500, 57_500)-ref:+.1f}")
128+
129+
# 5. de-emphasis: single-pole IIR y[n] = a*x[n] + b*y[n-1], with
130+
# a = 1 - exp(-1/(fs*tau)), b = 1 - a. A pure-python sample loop is too
131+
# slow, so evaluate the same recurrence blockwise: within each block,
132+
# y[n] = a * sum_{k<=n} b^(n-k) x[k] + y_prev * b^(n+1)
133+
# via one convolution against the geometric kernel, carrying y_prev
134+
# across block boundaries. Numerically safe because b < 1 and blocks
135+
# are short enough that b^n underflows to 0 harmlessly.
136+
tau = args.deemph * 1e-6
137+
a = 1.0 - np.exp(-1.0 / (chan_fs * tau))
138+
b = 1.0 - a
139+
# The geometric kernel decays fast (b < 1), so truncate it where its
140+
# weight drops below 1e-9 -- a few hundred taps at 200 kHz -- instead
141+
# of convolving against a full-block kernel, which is quadratic.
142+
klen = int(np.ceil(np.log(1e-9) / np.log(b))) + 1
143+
kernel = a * b ** np.arange(klen)
144+
audio = np.empty_like(demod)
145+
y_prev = 0.0
146+
block = 262144
147+
for start in range(0, len(demod), block):
148+
seg = demod[start:start + block]
149+
n = len(seg)
150+
y = np.convolve(seg, kernel)[:n]
151+
decay = b ** np.arange(1, min(n, klen) + 1)
152+
y[:len(decay)] += y_prev * decay
153+
audio[start:start + n] = y
154+
y_prev = y[-1]
155+
156+
# 6. audio lowpass + decimate to WAV rate
157+
audio_factor = max(1, int(round(chan_fs / AUDIO_FS_TARGET)))
158+
for f in staged_factors(audio_factor):
159+
audio = lpf_decimate(audio, f, cutoff_frac=0.30) # 15 kHz at x4 from 200k
160+
audio_fs = chan_fs / audio_factor
161+
audio -= np.mean(audio) # remove residual tuning DC
162+
peak = float(np.max(np.abs(audio))) + 1e-12
163+
pcm = np.clip(audio / peak * 0.9 * 32767, -32768, 32767).astype("<i2")
164+
165+
out = args.out or os.path.splitext(args.iq_file)[0] + ".wav"
166+
with wave.open(out, "wb") as w:
167+
w.setnchannels(1)
168+
w.setsampwidth(2)
169+
w.setframerate(int(audio_fs))
170+
w.writeframes(pcm.tobytes())
171+
print(f"[*] wrote {out} ({len(pcm)/audio_fs:.2f}s mono @ "
172+
f"{audio_fs/1e3:g} kHz; {time.perf_counter()-t0:.1f}s total)")
173+
return 0
174+
175+
176+
if __name__ == "__main__":
177+
sys.exit(main())

0 commit comments

Comments
 (0)