diff --git a/docs/TESTING.md b/docs/TESTING.md index dc86a87..7aaeca7 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -148,3 +148,24 @@ Differences are behavioural, not cosmetic: timing is never perturbed by debug serial traffic. Build directories are separate (`build-test`, `build-debug`) so profiles cannot silently reuse a stale sdkconfig. + +## Verifying a standalone repeater (no serial connection) + +When the DUT runs on external power with no USB host, firmware telemetry is +unavailable and RF is the only evidence. Record IQ once, then derive both +decodes and RF-level repeat pairs from the same samples: + +``` +timeout 80 rtl_sdr -f 868950000 -s 1600000 -g 42.1 -n 96000000 iq.raw +cat iq.raw | rtl_wmbus -f > decodes.log +./result-py/bin/python3 hil/verify_standalone.py --iq iq.raw --decodes decodes.log +``` + +Reports decoded repeats (same payload twice) and RF-level repeat pairs +(burst pairs of matching duration inside the delay window). The latter +matters because our transmission usually overloads the dongle and fails CRC +even though the RF is correct. + +Note: only one process can hold the RTL-SDR. If another tool (e.g. an +oms-tui / wmbusmeters pipeline) is running, `rtl_sdr` fails with +`usb_claim_interface error -6` and it must be stopped first. diff --git a/hil/verify_standalone.py b/hil/verify_standalone.py new file mode 100755 index 0000000..88a85c0 --- /dev/null +++ b/hil/verify_standalone.py @@ -0,0 +1,163 @@ +#!/usr/bin/env python3 +"""Verify a standalone repeater from RF alone -- no serial connection. + +Use case: the DUT is running on external power (charger/battery) with no USB +host, so firmware telemetry is unavailable. The only evidence is what the +SDR observes. This is also the honest test of "power it up and leave it be". + +Two independent lines of evidence, both derived from ONE recorded IQ file so +they cannot disagree about gain or time: + + 1. Decoded repeats - rtl_wmbus run over the recording; a repeat is the + same cooked payload decoded twice within the delay window. + 2. RF-level repeats - burst-envelope pairs separated by the delay window + where the second burst is at least as strong as the first. This catches + repeats that fail CRC because our transmission overloads the dongle + (docs/RF_FRONTEND_TESTS.md), which is the common case on this bench. + +Usage: + verify_standalone.py --iq iq.raw --decodes decodes.log + [--min-ms 20] [--max-ms 400] [--rate 1600000] [--json] + +Exit 0 if at least one repeat was observed by either method. +""" +import argparse +import json +import sys +from collections import Counter +from datetime import datetime + +import numpy as np + +sys.path.insert(0, __file__.rsplit("/", 1)[0]) +from correlate import SDR_RE # noqa: E402 + +ap = argparse.ArgumentParser() +ap.add_argument("--iq", required=True) +ap.add_argument("--decodes", required=True) +ap.add_argument("--min-ms", type=float, default=20.0) +ap.add_argument("--max-ms", type=float, default=400.0) +ap.add_argument("--rate", type=int, default=1_600_000) +ap.add_argument("--json", action="store_true") +args = ap.parse_args() + +WIN = args.rate // 1000 + +# ---------------------------------------------------------------- decodes +rows = [] +for line in open(args.decodes, errors="replace"): + m = SDR_RE.match(line.strip()) + if not m: + continue + rows.append({ + "mode": m["mode"], + "crc_ok": m["crc"] == "1", + "t": datetime.strptime(m["ts"].strip(), "%Y-%m-%d %H:%M:%S.%f").timestamp(), + "serial": m["serial"].lower(), + "hex": m["hex"].lower(), + }) +rows.sort(key=lambda r: r["t"]) + +c1 = [r for r in rows if r["mode"] == "C1" and r["crc_ok"]] +# rtl_wmbus runs two demodulators; collapse identical bytes <5 ms apart +dedup = [] +for r in c1: + if dedup and dedup[-1]["hex"] == r["hex"] and r["t"] - dedup[-1]["t"] < 0.005: + continue + dedup.append(r) + +# A decoded repeat: identical payload seen twice. rtl_sdr delivers ~82 ms +# buffers so decode timestamps are quantised; count occurrences rather than +# trusting sub-100 ms timing (docs/FINDINGS.md). +occ = Counter(r["hex"] for r in dedup) +decoded_repeats = sum(v - 1 for v in occ.values() if v > 1) +meters = Counter(r["serial"] for r in dedup) + +# ---------------------------------------------------------------- IQ bursts +env = [] +with open(args.iq, "rb") as f: + while True: + raw = f.read(args.rate * 2) + if len(raw) < WIN * 2: + break + b = np.frombuffer(raw, dtype=np.uint8).astype(np.float32) - 127.5 + iq = b[0::2] + 1j * b[1::2] + p = np.abs(iq) ** 2 + p = p[: (len(p) // WIN) * WIN].reshape(-1, WIN).mean(axis=1) + env.append(p) + +if not env: + print(json.dumps({"error": "iq too short"}) if args.json else "ERROR: iq too short") + sys.exit(3) + +db = 10 * np.log10(np.concatenate(env) + 1e-9) +floor = float(np.median(db)) + +idx = np.where(db > floor + 6.0)[0] +bursts = [] +if len(idx): + start = prev = idx[0] + for i in idx[1:]: + if i > prev + 3: + bursts.append((start, prev)) + start = i + prev = i + bursts.append((start, prev)) + +binfo = [{"t_ms": int(s), "dur_ms": int(e - s + 1), + "peak_db": float(db[s:e + 1].max() - floor)} for s, e in bursts] + +# RF-level repeat: a burst followed by a comparable-or-stronger burst of +# similar duration inside the delay window. Duration similarity matters -- +# a repeat carries the same frame, so its airtime should match. +pairs = [] +for i, a in enumerate(binfo): + a_end = a["t_ms"] + a["dur_ms"] + for b in binfo[i + 1:]: + gap = b["t_ms"] - a_end + if gap > args.max_ms: + break + if (args.min_ms <= gap <= args.max_ms + and abs(b["dur_ms"] - a["dur_ms"]) <= max(3, a["dur_ms"] * 0.35) + and b["peak_db"] >= a["peak_db"] - 3.0): + pairs.append({"orig_t_ms": a["t_ms"], "gap_ms": int(gap), + "orig_dur_ms": a["dur_ms"], "repeat_dur_ms": b["dur_ms"], + "orig_db": round(a["peak_db"], 1), + "repeat_db": round(b["peak_db"], 1)}) + break + +gaps = sorted(p["gap_ms"] for p in pairs) +result = { + "iq_seconds": round(len(db) / 1000.0, 1), + "noise_floor_db": round(floor, 1), + "bursts_total": len(binfo), + "c1_decodes": len(dedup), + "unique_meters": len(meters), + "decoded_repeats": decoded_repeats, + "rf_repeat_pairs": len(pairs), + "gap_ms": {"min": gaps[0] if gaps else None, + "median": gaps[len(gaps) // 2] if gaps else None, + "max": gaps[-1] if gaps else None}, + "repeater_online": bool(decoded_repeats or pairs), + "pairs": pairs[:20], + "top_meters": meters.most_common(10), +} + +if args.json: + print(json.dumps(result, indent=2)) +else: + print(f"STANDALONE CHECK iq={result['iq_seconds']}s floor={floor:.1f}dB") + print(f" C1 telegrams decoded: {len(dedup)} from {len(meters)} meters") + print(f" RF bursts in window: {len(binfo)}") + print(f" decoded repeats: {decoded_repeats}") + print(f" RF-level repeat pairs: {len(pairs)}") + if gaps: + print(f" repeat gap min/med/max: " + f"{gaps[0]}/{gaps[len(gaps)//2]}/{gaps[-1]} ms") + for p in pairs[:10]: + print(f" t={p['orig_t_ms']/1000:7.3f}s +{p['gap_ms']:3d} ms " + f"{p['orig_dur_ms']}ms/{p['repeat_dur_ms']}ms " + f"{p['orig_db']:+.1f}/{p['repeat_db']:+.1f} dB") + print(f"\n REPEATER {'ONLINE' if result['repeater_online'] else 'NOT OBSERVED'}") + +sys.exit(0 if result["repeater_online"] else 1)