You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 

204 lines
9.2 KiB

#!/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()