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
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()
|
|
|