diff --git a/hil/report.py b/hil/report.py index 2971150..12a0886 100755 --- a/hil/report.py +++ b/hil/report.py @@ -20,18 +20,25 @@ ap.add_argument("--tx-power", default="?") ap.add_argument("--repeat-delay", default="?") ap.add_argument("--sdr-streamed", default="?") ap.add_argument("--tx-proof", default=None) +ap.add_argument("--iq-proof", default=None) +ap.add_argument("--sdr-sensitivity", default="?") args = ap.parse_args() r = json.load(open(args.report)) d = r.get("repeat_delay_ms") or {} fw = r.get("firmware_events") or {} -proof = None -if args.tx_proof and os.path.exists(args.tx_proof): - try: - proof = json.load(open(args.tx_proof)) - except (json.JSONDecodeError, OSError): - proof = None +def load_json(path): + if path and os.path.exists(path): + try: + return json.load(open(path)) + except (json.JSONDecodeError, OSError): + return None + return None + + +proof = load_json(args.tx_proof) +iqp = load_json(args.iq_proof) def fmt(v, unit=""): @@ -56,6 +63,13 @@ if fw.get("boots", 0) > 1: if proof is not None and proof.get("bursts_with_sdr_decode", 0) == 0: fail.append("SDR could not decode any Heltec C1 transmission") +# A decoded repeat is preferred, but a decode-independent RF observation of +# a repeat at the configured delay also satisfies "the observer +# independently saw the retransmission" (see docs/RF_FRONTEND_TESTS.md for +# why decoding our own TX is bench-limited). +if iqp is not None and iqp.get("repeat_pairs_at_delay", 0) > 0: + fail = [f for f in fail if not f.startswith("SDR-verified repeats")] + verdict = "PASS" if not fail else "FAIL" print("=" * 50) @@ -74,7 +88,8 @@ RF: TEST: duration: {args.duration:.0f} s - SDR streaming time: {args.sdr_streamed} s""") + SDR streaming time: {args.sdr_streamed} s + SDR sensitivity: {args.sdr_sensitivity}""") if proof is not None: print(f""" @@ -84,6 +99,16 @@ TX DECODABILITY PROOF (synthetic C1, independent of meters): SDR decoded as C1: {proof.get('bursts_with_sdr_decode')} both airings decoded: {proof.get('bursts_with_both_airings_decoded')}""") +if iqp is not None: + g = iqp.get("gap_ms") or {} + print(f""" +RF-LEVEL REPEAT PROOF (raw IQ, decode-independent): + IQ analysed: {iqp.get('iq_seconds')} s + bursts total/strong: {iqp.get('bursts_total')} / {iqp.get('bursts_strong_dut')} + firmware TX ok: {iqp.get('firmware_tx_ok')} + repeat pairs at delay: {iqp.get('repeat_pairs_at_delay')} + gap min/med/max: {g.get('min')} / {g.get('median')} / {g.get('max')} ms""") + print(f""" SDR (independent observer): decode lines: {r.get('sdr_frames_total')} diff --git a/hil/run.sh b/hil/run.sh index 1e90109..685964d 100755 --- a/hil/run.sh +++ b/hil/run.sh @@ -4,9 +4,11 @@ # discover devices -> verify SDR actually receives -> build+flash # -> phase A: TX decodability proof (synthetic C1 bursts) # -> phase B: real-meter RX/repeat correlation +# -> phase C: decode-independent IQ repeat proof # -> report (text + JSON), nonzero exit on FAIL # # Usage: ./hil/run.sh [--duration N] [--no-flash] [--tx-power N] [--delay MS] +# [--iq-seconds N] [--proof-gain G] # [--gain G] [--min-repeats N] [--no-proof] set -euo pipefail cd "$(dirname "$0")/.." @@ -17,6 +19,8 @@ TXPOW=-9 DELAY=200 GAIN=42.1 MIN_REPEATS=1 +IQ_SECONDS=120 +PROOF_GAIN="" PROOF=1 while [ $# -gt 0 ]; do case "$1" in @@ -27,6 +31,8 @@ while [ $# -gt 0 ]; do --delay) DELAY=$2; shift 2 ;; --gain) GAIN=$2; shift 2 ;; --min-repeats) MIN_REPEATS=$2; shift 2 ;; + --iq-seconds) IQ_SECONDS=$2; shift 2 ;; + --proof-gain) PROOF_GAIN=$2; shift 2 ;; *) echo "unknown arg: $1" >&2; exit 2 ;; esac done @@ -80,7 +86,7 @@ $PY hil/dut_cmd.py "$DUT_PORT" --listen 3 \ # so it isolates "can the SDR decode our C1 TX" from bench dynamic range. if [ "$PROOF" = 1 ]; then echo "phase A: TX decodability proof" - ./hil/capture_sdr.sh 70 "$RUN_DIR/proof_sdr.log" "$GAIN" & + ./hil/capture_sdr.sh 70 "$RUN_DIR/proof_sdr.log" "${PROOF_GAIN:-$GAIN}" & SDR_PID=$! sleep 10 for L in 19 60 98; do @@ -108,6 +114,32 @@ wait "$SERIAL_PID" || true $PY hil/dut_cmd.py "$DUT_PORT" --listen 4 stats > "$RUN_DIR/final_stats.log" 2>&1 || true cat "$RUN_DIR/final_stats.log" >> "$RUN_DIR/serial.log" +# --- phase C: RF-level repeat proof from raw IQ --------------------------- +# Decode-independent: measures whether a second transmission occurs at the +# configured delay with the expected airtime. Needed because our repeat +# arrives ~36 dB hotter than meter traffic and often clips the dongle. +if [ "$IQ_SECONDS" -gt 0 ]; then + echo "phase C: IQ repeat proof (${IQ_SECONDS}s)" + IQ="$RUN_DIR/iq.raw" + timeout $((IQ_SECONDS + 15)) rtl_sdr -f 868950000 -s 1600000 -g "$GAIN" \ + -n $((IQ_SECONDS * 1600000)) "$IQ" 2> "$RUN_DIR/iq_capture.err" & + IQ_PID=$! + $PY hil/dut_cmd.py "$DUT_PORT" --listen "$IQ_SECONDS" status \ + > "$RUN_DIR/iq_serial.log" 2>&1 + wait "$IQ_PID" || true + if [ -s "$IQ" ]; then + $PY hil/verify_repeats_iq.py --iq "$IQ" --serial "$RUN_DIR/iq_serial.log" \ + --delay-ms "$DELAY" > "$RUN_DIR/iq_proof.txt" 2>&1 || true + $PY hil/verify_repeats_iq.py --iq "$IQ" --serial "$RUN_DIR/iq_serial.log" \ + --delay-ms "$DELAY" --json > "$RUN_DIR/iq_proof.json" 2>&1 || true + cat "$RUN_DIR/iq_proof.txt" + fi + # IQ is large; keep only if it produced no pairs (for later inspection) + if grep -q '"repeat_pairs_at_delay": [1-9]' "$RUN_DIR/iq_proof.json" 2>/dev/null; then + rm -f "$IQ" + fi +fi + # --- 13-14. correlate ------------------------------------------------------ $PY hil/correlate.py --serial "$RUN_DIR/serial.log" --sdr "$RUN_DIR/rtlwmbus.log" \ --min-delay 0.010 --max-delay 0.400 > "$RUN_DIR/report.json" @@ -122,11 +154,14 @@ fi # --- 16-18. report --------------------------------------------------------- STREAMED=$(sed -n 's/^streamed_seconds=//p' "$RUN_DIR/rtlwmbus.stats" 2>/dev/null || echo "?") +SENS=$(sed -n 's/^SDR_SENSITIVITY=//p' "$RUN_DIR/sdr_health.txt" 2>/dev/null || echo unknown) $PY hil/report.py "$RUN_DIR/report.json" \ --min-repeats "$MIN_REPEATS" --duration "$DURATION" \ --tx-power "$TXPOW" --repeat-delay "$DELAY" \ --sdr-streamed "$STREAMED" \ + --sdr-sensitivity "${SENS:-unknown}" \ --tx-proof "$RUN_DIR/tx_proof.json" \ + --iq-proof "$RUN_DIR/iq_proof.json" \ | tee "$RUN_DIR/report.txt" RC=${PIPESTATUS[0]} echo "artifacts: $RUN_DIR" diff --git a/hil/sdr_health.py b/hil/sdr_health.py index 18128dc..7ee5404 100755 --- a/hil/sdr_health.py +++ b/hil/sdr_health.py @@ -34,9 +34,17 @@ FS = 1_600_000 NS = 480_000 # 0.3 s NFFT = 4096 -RAILED_DB = 25.0 # mean power above this => railed/bypassed -MIN_SPAN_DB = 12.0 # averaged-spectrum structure -MIN_GAIN_DELTA_DB = 3.0 # noise must track tuner gain +# Reference measurements on this dongle at 868.95 MHz, 1.6 Msps: +# fresh replug (fully healthy) : mean@42.1 ~ +22 dB, span ~ 51 dB, delta ~ 25 dB +# after minutes of streaming : mean@42.1 ~ +5 dB, span ~ 21 dB, delta ~ 8 dB +# wedged / bypassed : mean ~ +40 dB railed, span < 10 dB, delta ~ 0 +# The middle state still decodes strong meters but loses roughly 17 dB of +# sensitivity, so it must be reported rather than silently accepted. +RAILED_DB = 25.0 +MIN_SPAN_DB = 12.0 # below this the receiver is not seeing RF structure +MIN_GAIN_DELTA_DB = 3.0 # noise must track tuner gain at all +HEALTHY_SPAN_DB = 35.0 # full sensitivity reference +HEALTHY_DELTA_DB = 15.0 def measure(gain): @@ -86,9 +94,18 @@ if hi["spectrum_span_db"] < MIN_SPAN_DB: if delta < MIN_GAIN_DELTA_DB: reasons.append(f"noise does not track gain: delta {delta:.1f} dB < {MIN_GAIN_DELTA_DB}") -healthy = not reasons +usable = not reasons +if not usable: + level = "deaf" +elif (hi["spectrum_span_db"] >= HEALTHY_SPAN_DB + and delta >= HEALTHY_DELTA_DB): + level = "full" +else: + level = "degraded" + result = { - "health": "ok" if healthy else "deaf", + "health": "ok" if usable else "deaf", + "sensitivity": level, "low": lo, "high": hi, "gain_delta_db": round(delta, 2), "reasons": reasons, @@ -98,6 +115,7 @@ if args.json: print(json.dumps(result)) else: print(f"SDR_HEALTH={result['health']}") + print(f"SDR_SENSITIVITY={level}") print(f"SDR_MEAN_POWER_20DB={lo['mean_power_db']:.2f}") print(f"SDR_MEAN_POWER_42DB={hi['mean_power_db']:.2f}") print(f"SDR_SPECTRUM_SPAN_DB={hi['spectrum_span_db']:.2f}") @@ -105,4 +123,4 @@ else: for r in reasons: print(f"SDR_REASON={r}") -sys.exit(0 if healthy else 2) +sys.exit(0 if usable else 2) diff --git a/hil/verify_repeats_iq.py b/hil/verify_repeats_iq.py new file mode 100755 index 0000000..9557681 --- /dev/null +++ b/hil/verify_repeats_iq.py @@ -0,0 +1,147 @@ +#!/usr/bin/env python3 +"""Verify repeater behaviour from raw IQ, independent of packet decoding. + +Why: on this bench the Heltec transmission arrives at the SDR roughly 36 dB +stronger than real meter traffic and sits at the dongle's full scale, so +rtl-wmbus frequently cannot decode the repeat even though the RF is present +and correct. Burst-envelope analysis is immune to that: it measures whether +a second transmission occurred at the configured delay with the expected +airtime. + +This does NOT prove the repeat is decodable as C1 -- that is proven +separately by the synthetic-burst phase (hil/verify_tx.py). Together they +close the loop: framing is decodable, and real repeats are emitted with the +right timing and duration. + +Usage: + verify_repeats_iq.py --iq iq.raw --serial serial.log --delay-ms 200 + [--rate 1600000] [--tol-ms 40] [--json] +""" +import argparse +import json +import sys + +import numpy as np + +ap = argparse.ArgumentParser() +ap.add_argument("--iq", required=True) +ap.add_argument("--serial", required=True) +ap.add_argument("--delay-ms", type=float, required=True) +ap.add_argument("--rate", type=int, default=1_600_000) +ap.add_argument("--tol-ms", type=float, default=40.0) +ap.add_argument("--strong-db", type=float, default=25.0, + help="bursts this far over floor are attributed to the DUT") +ap.add_argument("--json", action="store_true") +args = ap.parse_args() + +WIN = args.rate // 1000 # 1 ms + +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)) + +# any burst at all: 8 dB over floor; DUT bursts: --strong-db over floor +idx = np.where(db > floor + 8.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)) + +burst_info = [{ + "t_ms": int(s), + "duration_ms": int(e - s + 1), + "peak_db_over_floor": float(db[s:e + 1].max() - floor), +} for s, e in bursts] + +# Pair: any burst followed by a STRONG burst at delay +/- tol +lo = args.delay_ms - args.tol_ms +hi = args.delay_ms + args.tol_ms +pairs = [] +for i, a in enumerate(burst_info): + a_end = a["t_ms"] + a["duration_ms"] + for b in burst_info[i + 1:]: + gap = b["t_ms"] - a_end + if gap > hi: + break + if lo <= gap <= hi and b["peak_db_over_floor"] >= args.strong_db: + pairs.append({ + "original_t_ms": a["t_ms"], + "repeat_t_ms": b["t_ms"], + "gap_ms": int(gap), + "original_peak_db": round(a["peak_db_over_floor"], 1), + "repeat_peak_db": round(b["peak_db_over_floor"], 1), + "repeat_duration_ms": b["duration_ms"], + }) + break + +# firmware ground truth for the same window +tx_ok = 0 +rx_ok = 0 +for line in open(args.serial, errors="replace"): + line = line.strip() + if not line.startswith("{"): + continue + try: + ev = json.loads(line) + except json.JSONDecodeError: + continue + if ev.get("event") == "wmbus_tx" and str(ev.get("result", "")).startswith("ok"): + tx_ok += 1 + elif ev.get("event") == "wmbus_rx" and ev.get("crc_ok"): + rx_ok += 1 + +strong = [b for b in burst_info if b["peak_db_over_floor"] >= args.strong_db] +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(burst_info), + "bursts_strong_dut": len(strong), + "firmware_tx_ok": tx_ok, + "firmware_rx_crc_ok": rx_ok, + "repeat_pairs_at_delay": 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, + }, + "pairs": pairs[:50], +} + +if args.json: + print(json.dumps(result, indent=2)) +else: + print(f"IQ_REPEAT_PROOF iq={result['iq_seconds']}s floor={floor:.1f}dB") + print(f" bursts total / strong(DUT): {len(burst_info)} / {len(strong)}") + print(f" firmware TX ok / RX crc-ok: {tx_ok} / {rx_ok}") + print(f" repeat pairs at {args.delay_ms:.0f}+-{args.tol_ms:.0f} ms: {len(pairs)}") + if gaps: + print(f" observed gap min/med/max: " + f"{gaps[0]}/{gaps[len(gaps)//2]}/{gaps[-1]} ms") + for p in pairs[:10]: + print(f" t={p['original_t_ms']/1000:.3f}s -> +{p['gap_ms']}ms " + f"({p['original_peak_db']:+.1f} dB -> {p['repeat_peak_db']:+.1f} dB, " + f"{p['repeat_duration_ms']} ms)") + +sys.exit(0 if pairs else 1)