Files
heltec-repeater/hil/verify_standalone.py
T

204 lines
8.4 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 - 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("--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(),
"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_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 --
# 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.delay_ms + args.delay_tol_ms:
break
# A repeat re-sends the SAME frame, 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": len(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 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 duplicates. 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)