#!/usr/bin/env python3 """Meter-anchored TX verification. The only trustworthy way we have found to verify DUT transmissions in IQ: 1. Fit the serial<->IQ clock offset using STRONG METER RECEPTIONS as anchors (independent events, visible to both DUT and SDR, abundant). 2. Judge each firmware TX event by the envelope inside its EXACT window. 3. Report ambient meter levels alongside -- they are the in-band health control for the observer (deaf dongle => meters compressed => run void). Why not fit the clock on TX events (the removed verify_repeats_iq.py did): repeats fire RX + delay by construction, so an offset shifted by -delay "matches" every repeat to its own original's burst. That artifact produced fake "7/7 at +37 dB" confirmations. See docs/FINDINGS.md. Usage: meter_anchored.py --iq FILE --serial FILE [--json] """ import argparse, json, sys import numpy as np FS = 1600000 WIN = FS // 1000 # 1 ms envelope bins def envelope(path): raw = np.fromfile(path, dtype=np.uint8).astype(np.float32) - 127.5 iq = raw[0::2] + 1j * raw[1::2] p = np.abs(iq) ** 2 env = p[:(len(p) // WIN) * WIN].reshape(-1, WIN).mean(axis=1) db = 10 * np.log10(env + 1e-9) return db, float(np.median(db)) def bursts_of(db, floor, thresh=5): idx = np.where(db > floor + thresh)[0] if not len(idx): return [] out, s, p0 = [], idx[0], idx[0] for i in idx[1:]: if i > p0 + 3: out.append((s, p0)) s = i p0 = i out.append((s, p0)) return [(a, b - a + 1, float(db[a:b + 1].max() - floor)) for a, b in out if (b - a + 1) >= 3] def parse_serial(path): rx, tx = [], [] for line in open(path, errors="replace"): for tag, dst in (("wmbus_rx", rx), ("wmbus_tx", tx), ("beacon", tx)): if f'"event":"{tag}"' in line: try: dst.append(json.loads(line[line.index("{"):])) except (ValueError, KeyError): pass break return rx, tx def fit_clock(bursts, anchors_ms, span_ms): bst = np.array([b[0] for b in bursts], dtype=float) best = (None, -1, 1e9) for off in np.arange(anchors_ms[0] - span_ms - 3000, anchors_ms[0] + 3000, 2): d = [np.min(np.abs(bst - (t - off))) for t in anchors_ms] m = sum(1 for x in d if x < 15) e = float(np.median(d)) if m > best[1] or (m == best[1] and e < best[2]): best = (off, m, e) return best # offset, matched, median_err def fsk_spectral_excess(path, db, floor, event_times_ms): """Return event-correlated 45 kHz FSK excess over nearby control windows.""" nfft = 2048 fft_window = np.hanning(nfft) raw = np.memmap(path, dtype=np.uint8, mode="r") sample_count = raw.size // 2 event_times = np.asarray(event_times_ms, dtype=float) event_psd, control_psd = [], [] def spectrum(center): lo = center - nfft // 2 hi = lo + nfft if lo < 0 or hi > sample_count: return None values = raw[2 * lo:2 * hi].astype(np.float32) - 127.5 iq = values[0::2] + 1j * values[1::2] return np.abs(np.fft.fftshift(np.fft.fft(iq * fft_window))) ** 2 for ts_ms in event_times: a0, a1 = int(ts_ms) - 2, int(ts_ms) + 12 if not (0 <= a0 < a1 < len(db)): continue peak_bin = a0 + int(np.argmax(db[a0:a1] - floor)) event = spectrum(peak_bin * WIN + WIN // 2) if event is None: continue control = None for delta_ms in (100, 200, -100, -200): control_bin = peak_bin + delta_ms if not (0 <= control_bin < len(db)): continue if np.any(np.abs(event_times - control_bin) < 25): continue control = spectrum(control_bin * WIN + WIN // 2) if control is not None: break if control is None: continue event_psd.append(event) control_psd.append(control) if len(event_psd) < 5: return None, len(event_psd) event_med = np.median(np.stack(event_psd), axis=0) control_med = np.median(np.stack(control_psd), axis=0) freq = np.fft.fftshift(np.fft.fftfreq(nfft, 1 / FS)) signal = (np.abs(freq) >= 20000) & (np.abs(freq) < 80000) wide = (np.abs(freq) >= 250000) & (np.abs(freq) < 700000) signal_db = 10 * np.log10(event_med[signal].sum() / control_med[signal].sum()) wide_db = 10 * np.log10(event_med[wide].sum() / control_med[wide].sum()) return float(signal_db - wide_db), len(event_psd) def main(): ap = argparse.ArgumentParser() ap.add_argument("--iq", required=True) ap.add_argument("--serial", required=True) ap.add_argument("--rssi-min", type=float, default=-65, help="anchor threshold: DUT-side RSSI of meter frames") ap.add_argument("--json", action="store_true") args = ap.parse_args() try: db, floor = envelope(args.iq) except (FileNotFoundError, ValueError): print("IQ file missing or unreadable -- capture never started", file=sys.stderr) sys.exit(3) bursts = bursts_of(db, floor) rx, tx = parse_serial(args.serial) strong = [r for r in rx if r.get("rssi_dbm", -99) > args.rssi_min and r.get("timestamp_us")] if len(bursts) < 5: print(f"only {len(bursts)} bursts in IQ ({len(db)/1000.0:.0f}s) -- " "capture empty or observer dead", file=sys.stderr) sys.exit(3) if len(strong) < 5: print(f"only {len(strong)} strong meter anchors -- cannot fit clock", file=sys.stderr) sys.exit(2) anchors = np.array([r["timestamp_us"] / 1000.0 for r in strong]) span = len(db) off, matched, err = fit_clock(bursts, anchors, span) # A broken clock (sample drops, dongle stalls) makes every TX window # meaningless. Reject rather than emit garbage. if matched < max(5, len(strong) * 0.6) or err > 5.0: print(f"clock fit unusable: {matched}/{len(strong)} anchors, " f"median err {err:.1f} ms -- IQ stream integrity suspect", file=sys.stderr) sys.exit(3) bst = np.array([b[0] for b in bursts], dtype=float) meter_lv = [] for t in anchors: k = int(np.argmin(np.abs(bst - (t - off)))) if abs(bst[k] - (t - off)) < 15: meter_lv.append(bursts[k][2]) def winmax(ts_ms): a0, a1 = int(ts_ms) - 2, int(ts_ms) + 12 if not (0 <= a0 < a1 < len(db)): return None return float((db[a0:a1] - floor).max()) events, mapped_tx = [], [] for t in tx: mapped = t["timestamp_us"] / 1000.0 - off w = winmax(mapped) if w is None: continue mapped_tx.append(mapped) events.append({"event": t.get("event", "wmbus_tx"), "result": t.get("result"), "window_db": round(w, 1), "above_6db": bool(w >= 6)}) meter_med = float(np.median(meter_lv)) if meter_lv else 0.0 observer = "ok" if meter_med >= 15 else ("degraded" if meter_med >= 8 else "deaf") n_above = sum(1 for e in events if e["above_6db"]) levels = [e["window_db"] for e in events] tx_med = float(np.median(levels)) if levels else None controls = [winmax(t + 100) for t in mapped_tx] controls = [v for v in controls if v is not None] control_med = float(np.median(controls)) if controls else None fsk_db, fsk_windows = fsk_spectral_excess( args.iq, db, floor, mapped_tx) if not events: rf_state = "no_events" elif fsk_db is not None and fsk_db >= 3.0: rf_state = "strong" if tx_med >= 6.0 else "weak" else: rf_state = "not_observed" report = { "clock_matched": f"{matched}/{len(strong)}", "clock_err_ms": round(err, 1), "floor_db": round(floor, 1), "meter_median_db": round(meter_med, 1), "observer": observer, "tx_events": len(events), "tx_above_6db": n_above, "tx_median_db": round(tx_med, 1) if tx_med is not None else None, "control_median_db": (round(control_med, 1) if control_med is not None else None), "fsk_excess_db": round(fsk_db, 1) if fsk_db is not None else None, "fsk_windows": fsk_windows, "rf_state": rf_state, "tx_levels_db": levels, } if args.json: print(json.dumps(report)) else: print(f"clock: {report['clock_matched']} anchors, err {report['clock_err_ms']} ms") print(f"observer: {observer} (meter median +{report['meter_median_db']} dB, " f"floor {report['floor_db']})") print(f"TX state: {rf_state}; median +{report['tx_median_db']} dB, " f"FSK excess {report['fsk_excess_db']} dB") for e in events: print(f" {e['event']:>9} {e['result'] or '':>10} " f"+{e['window_db']:>5.1f} dB " f"{'>=6dB' if e['above_6db'] else 'weak'}") # exit 3 = observer unusable, 1 = no event-correlated FSK while observer ok if observer == "deaf": sys.exit(3) sys.exit(0 if rf_state in ("strong", "weak", "no_events") else 1) if __name__ == "__main__": main()