Files
heltec-repeater/hil/verify_standalone.py

217 lines
8.9 KiB
Python
Executable File

#!/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 - a supported H=0 original followed by an H=1 frame
with every other cooked byte unchanged.
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 [--delay-ms 500]
[--delay-tol-ms 25] [--rate 1600000] [--json]
Exit 0 only if a decoded hop transition confirms repeater activity.
"""
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, expected_repeat # noqa: E402
ap = argparse.ArgumentParser()
ap.add_argument("--iq", required=True)
ap.add_argument("--decodes", required=True)
ap.add_argument("--delay-ms", type=float, default=50.0,
help="configured repeat delay; pairs must match this")
ap.add_argument("--delay-tol-ms", type=float, default=25.0)
ap.add_argument("--max-frame-ms", type=float, default=20.0,
help="longest plausible C1 frame airtime (100 kbps)")
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(),
"cooked": bytes.fromhex(m["hex"]),
})
rows.sort(key=lambda r: r["t"])
decoded = [r for r in rows if r["mode"] in ("C1", "T1") and r["crc_ok"]]
# rtl_wmbus runs two demodulators; collapse identical bytes <5 ms apart
dedup = []
for r in decoded:
if (dedup and dedup[-1]["mode"] == r["mode"]
and dedup[-1]["cooked"] == r["cooked"]
and r["t"] - dedup[-1]["t"] < 0.005):
continue
dedup.append(r)
# rtl_sdr delivers ~82 ms buffers, so decode timestamps are quantised.
# Preserve order rather than trusting sub-100 ms timing (docs/FINDINGS.md).
# Each supported H=0 original permits one later H=1 counterpart; never
# normalize H on both sides or count identical originals as repeats.
pending = Counter()
decoded_repeats = 0
for r in dedup:
key = (r["mode"], r["cooked"])
if pending[key]:
pending[key] -= 1
decoded_repeats += 1
else:
marked = expected_repeat(r["cooked"])
if marked is not None:
pending[(r["mode"], marked)] += 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_all = [{"t_ms": int(s), "dur_ms": int(e - s + 1),
"peak_db": float(db[s:e + 1].max() - floor)} for s, e in bursts]
# Only frame-like bursts may be considered transmissions. A C1 frame at
# 100 kbps is >= ~5 ms even when short, and a real transmission stands well
# clear of the floor. Without this filter, 1 ms noise-floor flutter at the
# +6 dB detection threshold pairs with itself and manufactures hundreds of
# bogus "repeats" -- an earlier revision of this script did exactly that and
# reported a repeater ONLINE when the device was not transmitting at all.
MIN_FRAME_MS = 5
MIN_FRAME_DB = 10.0
binfo = [b for b in binfo_all
if b["dur_ms"] >= MIN_FRAME_MS and b["peak_db"] >= MIN_FRAME_DB]
# RF-level repeat: a burst followed by a comparable-or-stronger burst of
# similar duration inside the delay window. Duration similarity matters --
# setting H leaves the frame length unchanged, 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.delay_ms + args.delay_tol_ms:
break
# A hop-marked repeat retains the frame length, so it must (a) sit at the
# configured delay, (b) have an airtime consistent with a C1 frame,
# and (c) match the original's duration closely. Pairs that merely
# fall in a wide window are usually unrelated 868 MHz traffic --
# burst trains of 23 ms at 32 ms spacing were seen at this site.
if (abs(gap - args.delay_ms) <= args.delay_tol_ms
and a["dur_ms"] <= args.max_frame_ms
and b["dur_ms"] <= args.max_frame_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_all),
"frame_like_bursts": len(binfo),
"c1_decodes": sum(r["mode"] == "C1" for r in dedup),
"t1_decodes": sum(r["mode"] == "T1" for r in dedup),
"unique_meters": len(meters),
"decoded_repeats": decoded_repeats,
"rf_repeat_pairs": len(pairs),
"expected_delay_ms": args.delay_ms,
"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},
# A decoded repeat is unambiguous. An RF pair alone is suggestive but
# not proof: a strong isolated burst can equally be a nearby meter, and
# our own repeat of a weak original appears as a strong singleton. Say
# so instead of forcing a binary verdict.
"verdict": ("confirmed" if decoded_repeats
else "likely" if pairs
else "not observed"),
"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/T1 telegrams decoded: {len(dedup)} from {len(meters)} meters")
print(f" RF bursts (all): {len(binfo_all)}")
print(f" frame-like bursts: {len(binfo)} (>= {MIN_FRAME_MS} ms, >= +{MIN_FRAME_DB:.0f} dB)")
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")
v = result["verdict"]
print(f"\n VERDICT: repeater activity {v.upper()}")
if v == "likely":
print(" (RF pairs only -- suggestive, not proof. A strong isolated")
print(" burst may be a nearby meter, and a repeat of a weak original")
print(" looks like a singleton. Read the firmware counters over USB")
print(" for an unambiguous answer.)")
elif v == "not observed":
print(" (No frame-like burst pairs and no decoded hop transitions. Either")
print(" the device is not transmitting, or it transmitted nothing in")
print(" this window. Firmware counters over USB are decisive.)")
sys.exit(0 if result["verdict"] == "confirmed" else 1)