Skip to content

Commit afbf09c

Browse files
committed
splitting data capture examples, sample data better
1 parent dbcb64c commit afbf09c

3 files changed

Lines changed: 136 additions & 143 deletions

File tree

‎hackrfpy/examples/collect_sample_data.py‎

Lines changed: 49 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,32 @@
7979
}
8080

8181

82+
def _validate_capture(iq, expected_n):
83+
# Catch the failure modes of a bad collection run BEFORE the data goes
84+
# into the sample library: short reads, a dead/disconnected front end
85+
# (pure noise-floor silence), a stuck DC rail, and gain-induced clipping.
86+
# Returns (ok, [reasons]).
87+
reasons = []
88+
if len(iq) < 0.9 * expected_n:
89+
reasons.append(f"short read ({len(iq)}/{expected_n} samples)")
90+
if len(iq):
91+
mag = np.abs(iq)
92+
power_db = 10 * np.log10(float(np.mean(mag ** 2)) + 1e-20)
93+
if power_db < -70:
94+
reasons.append(f"suspiciously quiet ({power_db:.1f} dBFS -- "
95+
"dead antenna / wrong gain?)")
96+
clip = float(np.mean(mag > 0.99))
97+
if clip > 0.01:
98+
reasons.append(f"clipping ({clip*100:.1f}% of samples -- "
99+
"reduce gain)")
100+
dc = float(abs(np.mean(iq)))
101+
if dc > 0.1:
102+
reasons.append(f"large DC offset ({dc:.3f})")
103+
else:
104+
reasons.append("empty capture")
105+
return (not reasons), reasons
106+
107+
82108
def _signal_summary(iq):
83109
# A quick, honest description of what was captured: mean power and whether
84110
# there's evident signal vs noise floor. Not DSP -- just a sanity readout.
@@ -90,7 +116,7 @@ def _signal_summary(iq):
90116
return f"mean {db:.1f} dBFS, peak |amp| {peak:.3f}"
91117

92118

93-
def collect_band(h, name, args):
119+
def collect_band(h, name, args, suspects):
94120
band = BANDS[name]
95121
os.makedirs(OUT_DIR, exist_ok=True)
96122
n = int(args.sample_rate * args.seconds)
@@ -108,7 +134,15 @@ def collect_band(h, name, args):
108134
print(f" wrote {os.path.basename(iq_path)} "
109135
f"({size_mb:.1f} MB, {len(iq)} samples) -- {_signal_summary(iq)}")
110136
print(f" + {os.path.basename(iq_path).rsplit('.',1)[0]}.sigmf-meta")
137+
ok, reasons = _validate_capture(iq, n)
138+
if not ok:
139+
print(" [!] SUSPECT capture -- " + "; ".join(reasons),
140+
file=sys.stderr)
141+
print(" [!] kept on disk, but re-run this band before shipping "
142+
"it in the sample library", file=sys.stderr)
111143
results.append(iq_path)
144+
if not ok:
145+
suspects.append(iq_path)
112146
except HackRFError as e:
113147
print(f" IQ capture failed: {e}", file=sys.stderr)
114148

@@ -135,7 +169,7 @@ def collect_band(h, name, args):
135169
return results
136170

137171

138-
def write_readme(collected, args, det):
172+
def write_readme(collected, args, det, suspects=()):
139173
# A README for the sample library so the data is self-documenting.
140174
path = os.path.join(OUT_DIR, "README.md")
141175
with open(path, "w", newline="\n") as f:
@@ -156,7 +190,9 @@ def write_readme(collected, args, det):
156190
"meta = read_sigmf_meta('fm_2Msps.iq')\n```\n\n")
157191
f.write("## Files\n\n")
158192
for p in collected:
159-
f.write(f"- `{os.path.basename(p)}`\n")
193+
flag = " **(SUSPECT -- failed validation; re-collect)**" \
194+
if p in suspects else ""
195+
f.write(f"- `{os.path.basename(p)}`{flag}\n")
160196
print(f"\n wrote {os.path.relpath(path, _HERE)}")
161197

162198

@@ -165,7 +201,8 @@ def main():
165201
description="Collect real sample datasets from a HackRF (READ-ONLY).")
166202
p.add_argument("--tools-dir", default=None)
167203
p.add_argument("--band", action="append", choices=list(BANDS),
168-
help="band(s) to collect; repeatable. Default: fm")
204+
help="band(s) to collect; repeatable. "
205+
"Default: fm, ism433, ism915")
169206
p.add_argument("--seconds", type=float, default=0.5,
170207
help="capture duration per band (default 0.5s)")
171208
p.add_argument("--sample-rate", type=float, default=2e6,
@@ -175,7 +212,7 @@ def main():
175212
p.add_argument("--no-sweep", action="store_true",
176213
help="IQ captures only, skip sweep datasets")
177214
args = p.parse_args()
178-
bands = args.band or ["fm"]
215+
bands = args.band or ["fm", "ism433", "ism915"]
179216

180217
h = HackRF(tools_dir=args.tools_dir, verbose=False)
181218
print("== confirming a real board before collecting ==")
@@ -188,17 +225,22 @@ def main():
188225
print(f" ! {w}")
189226

190227
collected = []
228+
suspects = []
191229
try:
192230
for name in bands:
193-
collected += collect_band(h, name, args)
231+
collected += collect_band(h, name, args, suspects)
194232
except KeyboardInterrupt:
195233
print("\ninterrupted", file=sys.stderr)
196234
if collected:
197-
write_readme(collected, args, det)
235+
write_readme(collected, args, det, suspects)
198236
total = sum(os.path.getsize(p) for p in collected
199237
if p.endswith(".iq")) / 1e6
200238
print(f"\n== done: {len(collected)} files, ~{total:.1f} MB of IQ "
201239
f"in {os.path.relpath(OUT_DIR, _HERE)} ==")
240+
if suspects:
241+
print(f"== {len(suspects)} capture(s) FAILED validation -- see "
242+
"warnings above; re-run those bands ==", file=sys.stderr)
243+
return 2
202244
return 0
203245

204246

‎hackrfpy/examples/persistent_capture.py‎

Lines changed: 63 additions & 127 deletions
Original file line numberDiff line numberDiff line change
@@ -1,155 +1,91 @@
11
#! /usr/bin/python3
22
##--------------------------------------------------------------------\
3-
# hackrfpy 'examples/waterfall_persistent.py'
4-
# Single-frequency spectrum waterfall over time, driven by a PERSISTENT
5-
# receiver. Needs the [plotting] extra.
3+
# hackrfpy 'examples/persistent_capture.py'
4+
# Collect many CONTIGUOUS segments at one frequency from a single
5+
# long-lived receive process, using open_receiver(). No plotting.
66
#
7-
# This is the COMPLEMENT to waterfall_realtime.py, not a replacement:
8-
# - waterfall_realtime.py : SWEEP-based. x-axis = frequency across a wide
9-
# band; shows WHERE activity is across the spectrum.
10-
# - waterfall_persistent.py (this) : RECEIVER-based. Locks ONE center
11-
# frequency, FFTs each block; x-axis = frequency WITHIN the capture
12-
# bandwidth; shows how one channel evolves over time at full rate.
7+
# This is DIFFERENT from capture(segment_secs=...):
8+
# - capture(segment_secs=...) spawns a fresh hackrf_transfer per file,
9+
# so each file is whole but there is a short re-open GAP (~hundreds
10+
# of ms) of missing samples between files.
11+
# - this script drains ONE continuous stream and cuts it into files,
12+
# so consecutive segments are GAPLESS (back-to-back samples), at the
13+
# cost of re-quantizing complex64 -> int8 on write (exact for
14+
# samples produced by the library's own decode).
1315
#
14-
# It uses open_receiver() so the hackrf_transfer process spins up once and
15-
# streams continuously -- the natural fit for a live single-frequency view.
16-
# Read-only / receive-only; the receiver is reaped on exit.
16+
# Use this when downstream processing cares about continuity across
17+
# file boundaries (long observations, TDOA-ish work, demod that spans
18+
# segments). Each file gets a SigMF sidecar.
19+
#
20+
# SAFETY: read-only / receive-only.
1721
#
1822
# Usage:
19-
# uv run python examples/waterfall_persistent.py --freq 100e6 --rate 8e6
20-
# uv run python examples/waterfall_persistent.py --freq 2437e6 --rate 10e6
23+
# uv run python examples/persistent_capture.py --freq 100e6 --rate 2e6
24+
# uv run python examples/persistent_capture.py --freq 433.92e6 \
25+
# --rate 2e6 --segment-secs 1.0 --count 10 --out-dir segments
2126
#
2227
#
2328
# Author(s): Lauren Linkous
24-
# Last Update: July 11, 2026
2529
##--------------------------------------------------------------------\
2630
import argparse
31+
import os
2732
import sys
33+
2834
import numpy as np
29-
import matplotlib.pyplot as plt
30-
from matplotlib import colors
31-
from hackrfpy import HackRF
3235

33-
# ---- aesthetic: same signals-monitor identity as the sweep waterfall ------
34-
BG = "#0a0e14"
35-
PANEL = "#0d1320"
36-
GRID = "#1c2738"
37-
ACCENT = "#36e0c8"
38-
TEXT = "#9fb3c8"
39-
TEXTDIM = "#52617a"
40-
CMAP = "turbo"
36+
from hackrfpy import HackRF, write_sigmf_meta
37+
4138

42-
plt.rcParams.update({
43-
"figure.facecolor": BG, "axes.facecolor": PANEL, "savefig.facecolor": BG,
44-
"font.family": "monospace", "text.color": TEXT, "axes.edgecolor": GRID,
45-
"axes.labelcolor": TEXT, "xtick.color": TEXTDIM, "ytick.color": TEXTDIM,
46-
"axes.linewidth": 0.8,
47-
})
39+
def encode_iq(iq: np.ndarray) -> bytes:
40+
# complex64 in ~[-1, 1) -> interleaved int8 (HackRF native). Exact
41+
# round-trip for data that came out of decode_iq (values are k/128).
42+
out = np.empty(len(iq) * 2, dtype=np.int8)
43+
out[0::2] = np.clip(np.round(iq.real * 128.0), -128, 127)
44+
out[1::2] = np.clip(np.round(iq.imag * 128.0), -128, 127)
45+
return out.tobytes()
4846

4947

5048
def main():
51-
p = argparse.ArgumentParser(description="Single-freq waterfall (persistent RX).")
49+
p = argparse.ArgumentParser(
50+
description="Gapless segmented capture from one persistent receiver.")
5251
p.add_argument("--freq", default="100e6", help="center frequency Hz")
53-
p.add_argument("--rate", default="8e6", help="sample rate sps")
54-
p.add_argument("--fft", type=int, default=1024, help="FFT size (bins)")
55-
p.add_argument("--rows", type=int, default=400, help="time history depth")
52+
p.add_argument("--rate", default="2e6", help="sample rate sps")
53+
p.add_argument("--segment-secs", type=float, default=1.0,
54+
help="seconds of samples per file (default 1.0)")
55+
p.add_argument("--count", type=int, default=5,
56+
help="number of segments to collect (default 5)")
57+
p.add_argument("--out-dir", default="segments",
58+
help="output directory (default ./segments)")
59+
p.add_argument("--lna", type=int, default=16)
60+
p.add_argument("--vga", type=int, default=20)
5661
p.add_argument("--tools-dir", default=None)
5762
args = p.parse_args()
58-
freq, rate, nfft, rows = float(args.freq), float(args.rate), args.fft, args.rows
63+
freq, rate = float(args.freq), float(args.rate)
64+
n_per = int(rate * args.segment_secs)
5965

6066
h = HackRF(tools_dir=args.tools_dir)
61-
det = h.detect()
62-
if not det["ready"]:
63-
print(f"no usable HackRF: {det['problem']}", file=sys.stderr)
64-
return 1
65-
66-
# color scale in dBFS-ish FFT magnitude; fixed so colors are stable
67-
DB_FLOOR, DB_CEIL = -90, -20
68-
win = np.hanning(nfft).astype(np.float32)
69-
70-
def spectrum(iq):
71-
# Average several FFT frames across the big block for a smoother line,
72-
# then suppress the center DC / LO-leakage spike that every direct-
73-
# conversion SDR shows at 0 Hz (the bright line dead-center). We
74-
# replace the few central bins with their neighbors so a real signal
75-
# isn't hidden under the artifact.
76-
nframes = max(1, len(iq) // nfft)
77-
acc = np.zeros(nfft, dtype=np.float64)
78-
for k in range(nframes):
79-
seg = iq[k * nfft:(k + 1) * nfft]
80-
if len(seg) < nfft:
81-
break
82-
sp = np.fft.fftshift(np.fft.fft(seg * win))
83-
acc += (np.abs(sp) / nfft) ** 2
84-
acc /= nframes
85-
db = 10 * np.log10(acc + 1e-12)
86-
# flatten the DC spike: overwrite the center +/-2 bins with a neighbor
87-
c = nfft // 2
88-
db[c - 2:c + 3] = db[c + 3]
89-
return db
90-
91-
fig, ax = plt.subplots(figsize=(11, 6))
92-
try:
93-
fig.canvas.manager.set_window_title(
94-
"hackrfpy :: persistent-RX waterfall")
95-
except Exception:
96-
pass
97-
98-
history = []
99-
img = None
100-
cbar = None
101-
# frequency axis: center +/- rate/2, in MHz
102-
f_lo = (freq - rate / 2) / 1e6
103-
f_hi = (freq + rate / 2) / 1e6
104-
105-
print(f"[*] persistent waterfall @ {freq/1e6:g} MHz, {rate/1e6:g} Msps, "
106-
f"{nfft}-pt FFT (close window or Ctrl-C to stop)")
107-
108-
try:
109-
with h.open_receiver(freq, rate) as rx:
110-
# Read a LARGE block per iteration so the pipe drains fast enough
111-
# to keep hackrf_transfer streaming (reading only nfft=1024 samples
112-
# per loop, with a redraw each time, stalls the device at 10 Msps).
113-
# Each big block becomes one averaged waterfall row.
114-
block_samples = 262144
115-
while True:
116-
iq = rx.read(block_samples)
117-
if len(iq) < nfft:
118-
break
119-
history.append(spectrum(iq))
120-
history = history[-rows:]
121-
arr = np.array(history)[::-1] # newest on top
67+
os.makedirs(args.out_dir, exist_ok=True)
12268

123-
if img is None:
124-
img = ax.imshow(
125-
arr, aspect="auto", cmap=CMAP,
126-
norm=colors.Normalize(vmin=DB_FLOOR, vmax=DB_CEIL),
127-
interpolation="nearest", origin="upper",
128-
extent=[f_lo, f_hi, 0, len(arr)])
129-
cbar = fig.colorbar(img, ax=ax, pad=0.01, fraction=0.046)
130-
cbar.set_label("magnitude (dB)", color=TEXT, fontsize=9)
131-
cbar.outline.set_edgecolor(GRID)
132-
plt.setp(plt.getp(cbar.ax, "yticklabels"), color=TEXTDIM)
133-
ax.set_title(
134-
f"SINGLE-FREQ WATERFALL \u2014 {freq/1e6:g} MHz "
135-
f"\u00b1 {rate/2e6:g} MHz",
136-
color=ACCENT, fontsize=13, fontweight="bold",
137-
loc="left", pad=12, family="monospace")
138-
ax.set_xlabel("frequency (MHz)", fontsize=9)
139-
ax.set_ylabel("time (newest at top)", fontsize=9)
140-
ax.set_yticks([])
141-
for s in ax.spines.values():
142-
s.set_color(GRID)
143-
fig.tight_layout()
144-
else:
145-
img.set_data(arr)
146-
img.set_extent([f_lo, f_hi, 0, len(arr)])
147-
plt.pause(0.001)
148-
if not plt.fignum_exists(fig.number):
69+
print(f"[*] {args.count} x {args.segment_secs}s gapless segments "
70+
f"@ {freq/1e6:g} MHz, {rate/1e6:g} Msps -> {args.out_dir}/")
71+
written = []
72+
with h.open_receiver(freq, rate, lna=args.lna, vga=args.vga) as rx:
73+
for i in range(args.count):
74+
iq = rx.read(n_per)
75+
if len(iq) < n_per:
76+
print(f"[!] stream ended early on segment {i}", file=sys.stderr)
77+
if not len(iq):
14978
break
150-
except KeyboardInterrupt:
151-
pass
152-
print("[*] stopped")
79+
path = os.path.join(args.out_dir, f"seg_{i:03d}.iq")
80+
with open(path, "wb") as f:
81+
f.write(encode_iq(iq))
82+
write_sigmf_meta(path, freq, rate, lna=rx.lna, vga=rx.vga,
83+
amp=rx.amp, datatype="ci8")
84+
db = h.power_dbfs(iq)
85+
print(f" seg_{i:03d}.iq {len(iq)} samples {db:6.1f} dBFS")
86+
written.append(path)
87+
print(f"[*] done: {len(written)} files, "
88+
f"{rx.total_samples} contiguous samples total")
15389
return 0
15490

15591

‎hackrfpy/examples/waterfall_persistent.py‎

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -67,13 +67,24 @@ def main():
6767
win = np.hanning(nfft).astype(np.float32)
6868

6969
def spectrum(iq):
70-
# one FFT frame: window, transform, fftshift to put DC center, log-mag
71-
seg = iq[:nfft]
72-
if len(seg) < nfft:
73-
seg = np.pad(seg, (0, nfft - len(seg)))
74-
sp = np.fft.fftshift(np.fft.fft(seg * win))
75-
mag = np.abs(sp) / nfft
76-
return 20 * np.log10(mag + 1e-9)
70+
# Average several FFT frames across the block for a smoother line,
71+
# then suppress the center DC / LO-leakage spike that every direct-
72+
# conversion SDR shows at 0 Hz (the bright line dead-center). We
73+
# replace the few central bins with a neighbor so a real signal
74+
# isn't hidden under the artifact.
75+
nframes = max(1, len(iq) // nfft)
76+
acc = np.zeros(nfft, dtype=np.float64)
77+
for k in range(nframes):
78+
seg = iq[k * nfft:(k + 1) * nfft]
79+
if len(seg) < nfft:
80+
seg = np.pad(seg, (0, nfft - len(seg)))
81+
sp = np.fft.fftshift(np.fft.fft(seg * win))
82+
acc += (np.abs(sp) / nfft) ** 2
83+
acc /= nframes
84+
db = 10 * np.log10(acc + 1e-12)
85+
c = nfft // 2
86+
db[c - 2:c + 3] = db[c + 3] # flatten the DC spike
87+
return db
7788

7889
fig, ax = plt.subplots(figsize=(11, 6))
7990
try:
@@ -94,9 +105,13 @@ def spectrum(iq):
94105

95106
try:
96107
with h.open_receiver(freq, rate) as rx:
97-
# one block per FFT frame; read exactly nfft samples each time
108+
# Read a LARGE block per iteration so the pipe drains fast enough
109+
# to keep hackrf_transfer streaming (reading only nfft=1024
110+
# samples per loop, with a redraw each time, stalls the device at
111+
# 10 Msps). Each big block becomes one averaged waterfall row.
112+
block_samples = 262144
98113
for _ in range(10_000_000): # effectively "until stopped"
99-
iq = rx.read(nfft)
114+
iq = rx.read(block_samples)
100115
if len(iq) < nfft:
101116
break
102117
history.append(spectrum(iq))

0 commit comments

Comments
 (0)