6363BANDS = {
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
113137def _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 ("\n interrupted" , 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 "
0 commit comments