#!/usr/bin/env python3 """Decode chirpmodem frames from an IQ capture. Reads a SigMF recording, or a raw file (rtl_sdr's .cu8, a Pluto .ci16, a GNU Radio .cf32) with --format/--fs/--lo, converts it to the modem's rate, then walks it frame by frame. ./rx_file.py cap # cap.sigmf-meta ./rx_file.py cap.cu8 --format cu8 --fs 2.4e6 --lo 223.33e6 --sf 9 # 223.58 MHz, 62.5 kHz --freq is the signal's center frequency; the capture's LO (--lo, or the SigMF core:frequency) can be anywhere that keeps the signal inside the capture. Offset tuning (signal a few hundred kHz from the LO) keeps it clear of the receiver's DC spike. """ import argparse, sys, time import numpy as np from phy import PhyParams from frame import receive_frame, frame_chips, PROFILES import iq_io import rx # Symbols of slack in 'candidate inside the last decoded frame': a frame can # start exactly where the previous one ended, whose last pilot is an up-chirp # too and can pull the detector's peak a window early. BUSY_SLACK = 8 def describe_body(b): try: t = b.decode("utf-8") if all(c.isprintable() or c in "\n\t" for c in t): return repr(t) except UnicodeDecodeError: pass return b.hex() def frame_report(res, t, freq): """A decoded frame (RxResult, stage ok) -> (dict, report lines).""" s, mac, hdr, info = res.sync, res.mac, res.header, res.info flags = [] if info.get("coherent", True) else ["non-coherent"] if not info.get("policy_ok", True): flags.append("POLICY VIOLATION for " + PROFILES[hdr.profile]["name"]) if hdr.encrypted: flags.append("encrypted") if info.get("ramp_retry"): flags.append(f"carrier drift removed ({info.get('freq_ramp_hz_per_s', 0):+.2f} Hz/s)") if info.get("drift_retry"): flags.append(f"clock corrected to {s.eps * 1e6:+.2f} ppm") if info.get("dd_passes"): flags.append(f"decision-directed x{info['dd_passes']}") f = dict(t=t, src=mac.src, dst=mac.dst, body=mac.body, snr_db=info["snr_db"], offset_hz=s.f_hz, ppm=s.f_hz / freq * 1e6, profile=PROFILES[hdr.profile]["name"], flags=flags) route = f"{mac.src or '?'}" + (f" -> {mac.dst}" if mac.dst else "") lines = [f"[{t:9.3f} s] {route}: {describe_body(mac.body)}", f" SNR {f['snr_db']:+.1f} dB, offset {f['offset_hz']:+.1f} Hz " f"({f['ppm']:+.2f} ppm), {f['profile']}, " f"{len(mac.body)} B" + ("; " + "; ".join(flags) if flags else "")] return f, lines def level_check(raw, fmt): """ADC level, clipping, and how much quantization adds to the noise floor. Uniform quantization adds 1/12 LSB^2 per I/Q component; the rest of the measured power is the front end's own noise (the signal is assumed to be weak). Below ~1 LSB rms quantization is a sizeable, non-Gaussian share of the noise and the receiver gain should go up. """ _, off, scale = iq_io._check(fmt) v = np.asarray(raw, np.float64) - off lsb_scale = 16.0 if fmt == "ci16_le" else 1.0 # Pluto/AD936x: 12 bits in 16 v = v / lsb_scale rms = float(np.sqrt(np.mean(v * v))) lim = ((255 - 127.5) if fmt == "cu8" else (127 if fmt == "ci8" else 2047)) - 0.5 clip = float(np.mean(np.abs(v) >= lim)) q = 1 / 12 penalty = 10 * np.log10(rms * rms / max(rms * rms - q, 1e-9)) if rms * rms > q else np.inf msg = (f"ADC level: {rms:.2f} LSB rms, {clip * 100:.3f}% clipped, " f"quantization adds {penalty:.2f} dB to the noise floor") if rms < 1.0: msg += " <-- raise the receiver gain" elif clip > 1e-3: msg += " <-- CLIPPING: lower the receiver gain" return rms, clip, msg def decode_capture(path, fmt, fs, lo, freq, sf=9, bw=62.5e3, max_bytes=255, excise=True, verbose=False, out=None): """Decode every frame in a capture file. Returns dict(frames=[...], n_fail, rms_lsb, clipped, seconds). Each frame is a dict: t, src, dst, body, snr_db, offset_hz, ppm, profile, flags. ``out`` (e.g. print) receives the same report rx_file.py prints. """ say = out or (lambda *a, **k: None) t0 = time.time() p = PhyParams(sf=sf, bw=bw, osr=2, fc=freq) if_off = freq - lo if abs(if_off) + bw / 2 > fs / 2: raise ValueError(f"signal at {if_off / 1e3:+.1f} kHz from the LO is outside a " f"{fs / 1e6:g} MS/s capture") # ---- capture -> modem rate, in chunks raw = iq_io.open_raw(path, fmt) n_cap = len(raw) // 2 rms = clip = None if fmt in ("cu8", "ci8", "ci16_le"): rms, clip, msg = level_check(raw[:min(len(raw), 4_000_000)], fmt) say(msg) rc = iq_io.RateConverter(fs, p.fs, f_shift=if_off, passband=bw / 2 + 20e3) step = 1 << 21 for s in range(0, n_cap, step): rc.process(iq_io.to_complex(raw[2 * s:2 * min(n_cap, s + step)], fmt)) x = rc.finish() delay_s = ((len(rc.h) - 1) / 2 / fs) if rc.D > 1 else 0.0 say(f"{path}: {n_cap / fs:.2f} s at {fs / 1e6:g} MS/s ({fmt}), LO {lo / 1e6:.6f} MHz; " f"signal {freq / 1e6:.6f} MHz ({if_off / 1e3:+.1f} kHz), SF{sf}, {bw / 1e3:g} kHz") # ---- find every preamble, then decode them in time order osr, M = p.osr, p.M max_chips = frame_chips(p, max_bytes, coherent=False) # the longer of the two modes if excise: x, q = rx.excise(x, p) # once, over the whole capture if q > 0: say(f"excised narrowband interference: {q * 100:.1f}% of the signal band") cands, _ = rx.detect_all(rx.decimate(x, p), p) frames, n_fail, n_cut, busy_until = [], 0, 0, 0 # chip index the last frame ended at for k in cands: c0 = max(0, (k - 3) * M) # metric peaks within a few windows of the start if c0 + BUSY_SLACK * M < busy_until: continue # inside a frame already decoded win = x[c0 * osr:(c0 + 6 * M + max_chips + 4 * M) * osr] res = receive_frame(win, p, excise=False, search_chips=6 * M) if res.sync is None: continue start = c0 + res.sync.tau0 # chips from the start of the capture if start + M / 2 < busy_until: continue # synced onto the last frame's tail (BUSY_SLACK) t = start / p.bw + delay_s if res.stage == "ok": f, lines = frame_report(res, t, freq) frames.append(f) for ln in lines: say(ln) busy_until = start + res.info["frame_chips"] elif (res.info or {}).get("reason") == "truncated": n_cut += 1 # runs past the end of the capture if verbose: say(f"[{t:9.3f} s] preamble found, frame cut off by the end of the capture") else: n_fail += 1 if verbose: say(f"[{t:9.3f} s] preamble found, {res.stage.replace('_', ' ')} " f"(offset {res.sync.f_hz:+.1f} Hz)") say(f"{len(frames)} frame(s) decoded, {n_fail} failed after sync" + (f", {n_cut} cut off at the end" if n_cut else "") + f", {time.time() - t0:.1f} s") return dict(frames=frames, n_fail=n_fail, rms_lsb=rms, clipped=clip, seconds=n_cap / fs) def main(): ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) ap.add_argument("capture", help="SigMF base/meta/data name, or a raw file") ap.add_argument("--format", help="raw datatype: cu8, ci8, ci16_le, cf32_le") ap.add_argument("--fs", type=float, help="raw: sample rate, Hz") ap.add_argument("--lo", type=float, help="raw: capture center (LO) frequency, Hz") ap.add_argument("--freq", type=float, help="signal center frequency, Hz (default 223.58e6)") ap.add_argument("--sf", type=int, help="spreading factor (default from metadata, else 9)") ap.add_argument("--bw", type=float, help="bandwidth, Hz (default from metadata, else 62.5e3)") ap.add_argument("--max-bytes", type=int, default=255, help="largest MAC frame to expect (sets the decode window)") ap.add_argument("--no-excise", action="store_true") ap.add_argument("-v", "--verbose", action="store_true", help="also report failed frames") a = ap.parse_args() if a.format: if a.fs is None or a.lo is None: sys.exit("raw input needs --fs and --lo") fmt, fs, lo, ext, path = a.format, a.fs, a.lo, {}, a.capture else: m = iq_io.read_sigmf_meta(a.capture) fmt, fs, lo, ext, path = m["fmt"], m["fs"], m["fc"], m["ext"], m["data_path"] if a.fs: fs = a.fs if a.lo: lo = a.lo freq = a.freq or ext.get("signal_freq") or 223.58e6 sf = a.sf or ext.get("sf") or 9 bw = a.bw or ext.get("bw") or 62.5e3 try: r = decode_capture(path, fmt, fs, lo, freq, sf, bw, a.max_bytes, excise=not a.no_excise, verbose=a.verbose, out=print) except ValueError as e: sys.exit(str(e)) if "sim_expected_offset_hz" in ext: print(f"(simulation: expected offset {ext['sim_expected_offset_hz']:+.1f} Hz, " f"SNR {ext['sim_snr_db']:+.1f} dB)") if __name__ == "__main__": main()