Files
heltec-repeater/hil/meter_anchored.py
T

168 lines
6.0 KiB
Python
Executable File

#!/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 (hil/verify_repeats_iq.py, single-burst
mode): 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 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 = []
for t in tx:
w = winmax(t["timestamp_us"] / 1000.0 - off)
if w is None:
continue
events.append({"event": t.get("event", "wmbus_tx"),
"result": t.get("result"),
"window_db": round(w, 1),
"rf": 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_rf = sum(1 for e in events if e["rf"])
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_with_rf": n_rf,
"tx_levels_db": [e["window_db"] for e in events],
}
if args.json:
print(json.dumps(report, indent=2))
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 with RF: {n_rf}/{len(events)}")
for e in events:
print(f" {e['event']:>9} {e['result'] or '':>10} "
f"+{e['window_db']:>5.1f} dB {'RF' if e['rf'] else '--'}")
# exit 3 = observer unusable, 1 = TX dead while observer ok
if observer == "deaf":
sys.exit(3)
sys.exit(0 if (n_rf or not events) else 1)
if __name__ == "__main__":
main()