Files
heltec-repeater/hil/meter_anchored.py
T

248 lines
9.2 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 (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()