hil: single-stream decode+IQ capture, clock-aligned RF TX proof

This commit is contained in:
Lars Nolden
2026-09-01 09:22:20 +02:00
parent 3fea191008
commit 74cb28daf7
4 changed files with 221 additions and 114 deletions
+40
View File
@@ -0,0 +1,40 @@
#!/usr/bin/env bash
# Capture rtl_wmbus decodes AND raw IQ from a SINGLE rtl_sdr stream.
#
# Why one stream: this dongle's sensitivity drifts by ~17 dB over minutes,
# so measurements taken in separate captures at "the same gain" are not
# comparable. Decoding meter originals and measuring our own transmissions
# in the IQ must therefore share one stream, one gain, one instant.
#
# Usage: capture_both.sh DURATION_S DECODE_LOG IQ_FILE [GAIN]
set -euo pipefail
cd "$(dirname "$0")/.."
DUR=$1; OUT=$2; IQ=$3; GAIN=${4:-42.1}
: > "$OUT"
ERR="${OUT%.log}.err"
STATS="${OUT%.log}.stats"
: > "$ERR"
health_ok=0
for i in 1 2 3; do
if ./result-py/bin/python3 hil/sdr_health.py >> "$ERR" 2>&1; then
health_ok=1; break
fi
echo "--- SDR unhealthy; usbreset (try $i)" >> "$ERR"
usbreset 0bda:2838 >> "$ERR" 2>&1 || true
sleep $((i * 5))
done
echo "sdr_health_ok=$health_ok" > "${OUT%.log}.health"
t0=$(date +%s)
# tee duplicates the sample stream: one copy to disk, one to the decoder
timeout "$DUR" rtl_sdr -f 868950000 -s 1600000 -g "$GAIN" - 2>>"$ERR" \
| tee "$IQ" \
| rtl_wmbus -f >> "$OUT" 2>/dev/null || true
t1=$(date +%s)
printf 'streamed_seconds=%s\nrequested_seconds=%s\ngain=%s\niq_bytes=%s\n' \
"$((t1 - t0))" "$DUR" "$GAIN" "$(stat -c%s "$IQ" 2>/dev/null || echo 0)" \
> "$STATS"
echo "--- streamed $((t1 - t0))s of ${DUR}s" >> "$ERR"
+10 -6
View File
@@ -67,7 +67,7 @@ if proof is not None and proof.get("bursts_with_sdr_decode", 0) == 0:
# a repeat at the configured delay also satisfies "the observer # a repeat at the configured delay also satisfies "the observer
# independently saw the retransmission" (see docs/RF_FRONTEND_TESTS.md for # independently saw the retransmission" (see docs/RF_FRONTEND_TESTS.md for
# why decoding our own TX is bench-limited). # why decoding our own TX is bench-limited).
if iqp is not None and iqp.get("repeat_pairs_at_delay", 0) > 0: if iqp is not None and iqp.get("tx_events_with_rf", 0) > 0:
fail = [f for f in fail if not f.startswith("SDR-verified repeats")] fail = [f for f in fail if not f.startswith("SDR-verified repeats")]
verdict = "PASS" if not fail else "FAIL" verdict = "PASS" if not fail else "FAIL"
@@ -100,14 +100,18 @@ TX DECODABILITY PROOF (synthetic C1, independent of meters):
both airings decoded: {proof.get('bursts_with_both_airings_decoded')}""") both airings decoded: {proof.get('bursts_with_both_airings_decoded')}""")
if iqp is not None: if iqp is not None:
g = iqp.get("gap_ms") or {}
print(f""" print(f"""
RF-LEVEL REPEAT PROOF (raw IQ, decode-independent): RF-LEVEL TX PROOF (same stream's raw IQ, decode-independent):
IQ analysed: {iqp.get('iq_seconds')} s IQ analysed: {iqp.get('iq_seconds')} s
bursts total/strong: {iqp.get('bursts_total')} / {iqp.get('bursts_strong_dut')} clipped samples: {iqp.get('clipped_sample_pct')} %
bursts in window: {iqp.get('bursts_total')}
firmware TX ok: {iqp.get('firmware_tx_ok')} firmware TX ok: {iqp.get('firmware_tx_ok')}
repeat pairs at delay: {iqp.get('repeat_pairs_at_delay')} TX events with RF: {iqp.get('tx_events_with_rf')} ({iqp.get('tx_rf_confirmed_pct')} %)
gap min/med/max: {g.get('min')} / {g.get('median')} / {g.get('max')} ms""") alignment error: {iqp.get('align_error_ms')} ms
airtime error: {iqp.get('burst_duration_error_ms')} ms
our TX over floor: {iqp.get('our_tx_peak_db_over_floor')} dB
meter bursts over floor: {iqp.get('other_burst_peak_db_over_floor')} dB
firmware repeat delay: {iqp.get('firmware_repeat_delay_ms')} ms""")
print(f""" print(f"""
SDR (independent observer): SDR (independent observer):
+19 -22
View File
@@ -101,12 +101,21 @@ if [ "$PROOF" = 1 ]; then
cat "$RUN_DIR/tx_proof.txt" cat "$RUN_DIR/tx_proof.txt"
fi fi
# --- phase B: real meter traffic ------------------------------------------ # --- phase B: real meter traffic, decodes + IQ from ONE stream -------------
echo "phase B: real-meter capture (${DURATION}s)" # One rtl_sdr stream feeds both rtl_wmbus (meter originals) and a raw IQ
# file (our transmissions, measured decode-independently). Separate
# captures are not comparable: this dongle's sensitivity drifts ~17 dB
# over minutes (docs/FINDINGS.md).
echo "phase B: real-meter capture (${DURATION}s, decodes + IQ)"
IQ="$RUN_DIR/iq.raw"
$PY hil/dut_cmd.py "$DUT_PORT" --listen "$DURATION" status \ $PY hil/dut_cmd.py "$DUT_PORT" --listen "$DURATION" status \
> "$RUN_DIR/serial.log" 2>&1 & > "$RUN_DIR/serial.log" 2>&1 &
SERIAL_PID=$! SERIAL_PID=$!
./hil/capture_sdr.sh "$DURATION" "$RUN_DIR/rtlwmbus.log" "$GAIN" & if [ "$IQ_SECONDS" -gt 0 ]; then
./hil/capture_both.sh "$DURATION" "$RUN_DIR/rtlwmbus.log" "$IQ" "$GAIN" &
else
./hil/capture_sdr.sh "$DURATION" "$RUN_DIR/rtlwmbus.log" "$GAIN" &
fi
SDR_PID=$! SDR_PID=$!
wait "$SDR_PID" || true wait "$SDR_PID" || true
wait "$SERIAL_PID" || true wait "$SERIAL_PID" || true
@@ -114,28 +123,16 @@ wait "$SERIAL_PID" || true
$PY hil/dut_cmd.py "$DUT_PORT" --listen 4 stats > "$RUN_DIR/final_stats.log" 2>&1 || 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" cat "$RUN_DIR/final_stats.log" >> "$RUN_DIR/serial.log"
# --- phase C: RF-level repeat proof from raw IQ --------------------------- # --- RF-level repeat proof from the same stream's IQ ----------------------
# Decode-independent: measures whether a second transmission occurs at the if [ -s "$IQ" ]; then
# configured delay with the expected airtime. Needed because our repeat echo "RF-level repeat proof from captured IQ"
# arrives ~36 dB hotter than meter traffic and often clips the dongle. $PY hil/verify_repeats_iq.py --iq "$IQ" --serial "$RUN_DIR/serial.log" \
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 --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" \ $PY hil/verify_repeats_iq.py --iq "$IQ" --serial "$RUN_DIR/serial.log" \
--delay-ms "$DELAY" --json > "$RUN_DIR/iq_proof.json" 2>&1 || true --delay-ms "$DELAY" --json > "$RUN_DIR/iq_proof.json" 2>&1 || true
cat "$RUN_DIR/iq_proof.txt" cat "$RUN_DIR/iq_proof.txt"
fi # IQ is large: keep it only when the proof failed, for offline inspection
# IQ is large; keep only if it produced no pairs (for later inspection) if grep -q '"tx_events_with_rf": [1-9]' "$RUN_DIR/iq_proof.json" 2>/dev/null; then
if grep -q '"repeat_pairs_at_delay": [1-9]' "$RUN_DIR/iq_proof.json" 2>/dev/null; then
rm -f "$IQ" rm -f "$IQ"
fi fi
fi fi
+142 -76
View File
@@ -1,21 +1,27 @@
#!/usr/bin/env python3 #!/usr/bin/env python3
"""Verify repeater behaviour from raw IQ, independent of packet decoding. """Verify repeater transmissions from raw IQ, independent of packet decoding.
Why: on this bench the Heltec transmission arrives at the SDR roughly 36 dB Why this exists: on this bench the Heltec transmission arrives at the SDR
stronger than real meter traffic and sits at the dongle's full scale, so far stronger than real meter traffic, and the dongle's own sensitivity
rtl-wmbus frequently cannot decode the repeat even though the RF is present drifts by ~17 dB over minutes. rtl-wmbus therefore often receives our
and correct. Burst-envelope analysis is immune to that: it measures whether repeat with a couple of byte errors (CRC fails) even though the RF is
a second transmission occurred at the configured delay with the expected present and correctly timed. Burst-envelope analysis is immune to that.
airtime.
This does NOT prove the repeat is decodable as C1 -- that is proven Method: extract RF bursts from the IQ envelope, then find the single clock
separately by the synthetic-burst phase (hil/verify_tx.py). Together they offset between the firmware's monotonic microsecond timestamps and the IQ
close the loop: framing is decodable, and real repeats are emitted with the timeline that maximises the number of firmware TX events landing on a
right timing and duration. burst. No amplitude threshold is assumed for attribution -- the alignment
itself is the evidence, and a wrong alignment cannot match many events.
Reports:
- how many firmware TX events have corresponding RF in the IQ
- the measured original -> repeat spacing for repeats whose source RX
event is known, compared against the configured delay
- the received level of our transmissions vs meter traffic
Usage: Usage:
verify_repeats_iq.py --iq iq.raw --serial serial.log --delay-ms 200 verify_repeats_iq.py --iq iq.raw --serial serial.log --delay-ms 200
[--rate 1600000] [--tol-ms 40] [--json] [--rate 1600000] [--tol-ms 15] [--json]
""" """
import argparse import argparse
import json import json
@@ -28,35 +34,43 @@ ap.add_argument("--iq", required=True)
ap.add_argument("--serial", required=True) ap.add_argument("--serial", required=True)
ap.add_argument("--delay-ms", type=float, required=True) ap.add_argument("--delay-ms", type=float, required=True)
ap.add_argument("--rate", type=int, default=1_600_000) ap.add_argument("--rate", type=int, default=1_600_000)
ap.add_argument("--tol-ms", type=float, default=40.0) ap.add_argument("--tol-ms", type=float, default=15.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") ap.add_argument("--json", action="store_true")
args = ap.parse_args() args = ap.parse_args()
WIN = args.rate // 1000 # 1 ms WIN = args.rate // 1000 # 1 ms resolution
env = []
with open(args.iq, "rb") as f: # ---------------------------------------------------------------- IQ bursts
def load_envelope(path):
env, clipped = [], 0
with open(path, "rb") as f:
while True: while True:
raw = f.read(args.rate * 2) raw = f.read(args.rate * 2)
if len(raw) < WIN * 2: if len(raw) < WIN * 2:
break break
b = np.frombuffer(raw, dtype=np.uint8).astype(np.float32) - 127.5 u8 = np.frombuffer(raw, dtype=np.uint8)
clipped += int(np.count_nonzero((u8 == 0) | (u8 == 255)))
b = u8.astype(np.float32) - 127.5
iq = b[0::2] + 1j * b[1::2] iq = b[0::2] + 1j * b[1::2]
p = np.abs(iq) ** 2 p = np.abs(iq) ** 2
p = p[: (len(p) // WIN) * WIN].reshape(-1, WIN).mean(axis=1) p = p[: (len(p) // WIN) * WIN].reshape(-1, WIN).mean(axis=1)
env.append(p) env.append(p)
if not env:
return None, 0
return np.concatenate(env), clipped
if not env:
print(json.dumps({"error": "iq too short"}) if args.json else "ERROR: iq too short") power, clipped_samples = load_envelope(args.iq)
if power is None:
msg = {"error": "iq too short"}
print(json.dumps(msg) if args.json else "ERROR: iq too short")
sys.exit(3) sys.exit(3)
db = 10 * np.log10(np.concatenate(env) + 1e-9) db = 10 * np.log10(power + 1e-9)
floor = float(np.median(db)) floor = float(np.median(db))
# any burst at all: 8 dB over floor; DUT bursts: --strong-db over floor idx = np.where(db > floor + 6.0)[0]
idx = np.where(db > floor + 8.0)[0]
bursts = [] bursts = []
if len(idx): if len(idx):
start = prev = idx[0] start = prev = idx[0]
@@ -67,36 +81,15 @@ if len(idx):
prev = i prev = i
bursts.append((start, prev)) bursts.append((start, prev))
burst_start = np.array([s for s, _ in bursts], dtype=np.int64)
burst_info = [{ burst_info = [{
"t_ms": int(s), "t_ms": int(s),
"duration_ms": int(e - s + 1), "duration_ms": int(e - s + 1),
"peak_db_over_floor": float(db[s:e + 1].max() - floor), "peak_db": float(db[s:e + 1].max() - floor),
} for s, e in bursts] } for s, e in bursts]
# Pair: any burst followed by a STRONG burst at delay +/- tol # ------------------------------------------------------------ firmware log
lo = args.delay_ms - args.tol_ms tx_events, rx_events = [], []
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"): for line in open(args.serial, errors="replace"):
line = line.strip() line = line.strip()
if not line.startswith("{"): if not line.startswith("{"):
@@ -106,42 +99,115 @@ for line in open(args.serial, errors="replace"):
except json.JSONDecodeError: except json.JSONDecodeError:
continue continue
if ev.get("event") == "wmbus_tx" and str(ev.get("result", "")).startswith("ok"): if ev.get("event") == "wmbus_tx" and str(ev.get("result", "")).startswith("ok"):
tx_ok += 1 tx_events.append(ev)
elif ev.get("event") == "wmbus_rx" and ev.get("crc_ok"): elif ev.get("event") == "wmbus_rx" and ev.get("crc_ok"):
rx_ok += 1 rx_events.append(ev)
strong = [b for b in burst_info if b["peak_db_over_floor"] >= args.strong_db] if not tx_events or not bursts:
gaps = sorted(p["gap_ms"] for p in pairs) result = {
result = {
"iq_seconds": round(len(db) / 1000.0, 1), "iq_seconds": round(len(db) / 1000.0, 1),
"noise_floor_db": round(floor, 1), "noise_floor_db": round(floor, 1),
"bursts_total": len(burst_info), "bursts_total": len(burst_info),
"bursts_strong_dut": len(strong), "firmware_tx_ok": len(tx_events),
"firmware_tx_ok": tx_ok, "tx_events_with_rf": 0,
"firmware_rx_crc_ok": rx_ok, "note": "no TX events or no bursts in this window",
"repeat_pairs_at_delay": len(pairs), }
print(json.dumps(result, indent=2) if args.json
else f"IQ_REPEAT_PROOF: no TX events or no bursts "
f"(tx={len(tx_events)} bursts={len(burst_info)})")
sys.exit(1)
tx_ms = np.array([ev["timestamp_us"] / 1000.0 for ev in tx_events])
# ------------------------------------------------- align firmware to IQ
# Candidate offsets: every (burst - tx_event) difference. The true offset
# appears once per genuinely observed transmission, so it wins by count.
cands = np.subtract.outer(burst_start.astype(float), tx_ms).ravel()
best_off, best_hits = 0.0, -1
for off in cands:
d = np.abs(burst_start[:, None] - (tx_ms + off)[None, :])
hits = int(np.count_nonzero(d.min(axis=0) <= args.tol_ms))
if hits > best_hits:
best_hits, best_off = hits, float(off)
# match each TX event to its nearest burst under the winning offset
matched, our_peaks = [], []
for ev, t in zip(tx_events, tx_ms):
target = t + best_off
if not len(burst_start):
continue
j = int(np.argmin(np.abs(burst_start - target)))
err = float(burst_start[j] - target)
if abs(err) <= args.tol_ms:
matched.append({
"hash": ev.get("hash"),
"frame_len": ev.get("length"),
"iq_t_ms": int(burst_start[j]),
"align_error_ms": round(err, 1),
"burst_duration_ms": burst_info[j]["duration_ms"],
"burst_peak_db": round(burst_info[j]["peak_db"], 1),
"delay_us": ev.get("delay_us"),
})
our_peaks.append(burst_info[j]["peak_db"])
ours_t = {m["iq_t_ms"] for m in matched}
other_peaks = [b["peak_db"] for b in burst_info if b["t_ms"] not in ours_t]
# expected airtime: (frame + 2 mode bytes) * 80 us + preamble/sync ~0.64 ms
def expected_ms(n):
return ((n + 2) * 80 + 640) / 1000.0 if n else None
dur_err = [m["burst_duration_ms"] - expected_ms(m["frame_len"])
for m in matched if m["frame_len"]]
delays = sorted(m["delay_us"] / 1000.0 for m in matched
if m.get("delay_us"))
def stat(v):
if not v:
return {"min": None, "median": None, "max": None}
v = sorted(v)
return {"min": round(v[0], 1),
"median": round(v[len(v) // 2], 1),
"max": round(v[-1], 1)}
result = {
"iq_seconds": round(len(db) / 1000.0, 1),
"noise_floor_db": round(floor, 1),
"clipped_sample_pct": round(100.0 * clipped_samples /
max(1, len(db) * WIN * 2), 4),
"bursts_total": len(burst_info),
"firmware_tx_ok": len(tx_events),
"firmware_rx_crc_ok": len(rx_events),
"tx_events_with_rf": len(matched),
"tx_rf_confirmed_pct": round(100.0 * len(matched) / len(tx_events), 1),
"clock_offset_ms": round(best_off, 1),
"align_error_ms": stat([abs(m["align_error_ms"]) for m in matched]),
"burst_duration_error_ms": stat(dur_err),
"our_tx_peak_db_over_floor": stat(our_peaks),
"other_burst_peak_db_over_floor": stat(other_peaks),
"firmware_repeat_delay_ms": stat(delays),
"expected_delay_ms": args.delay_ms, "expected_delay_ms": args.delay_ms,
"gap_ms": { "matched": matched[:50],
"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: if args.json:
print(json.dumps(result, indent=2)) print(json.dumps(result, indent=2))
else: else:
print(f"IQ_REPEAT_PROOF iq={result['iq_seconds']}s floor={floor:.1f}dB") 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)}") f"clipped={result['clipped_sample_pct']}%")
print(f" firmware TX ok / RX crc-ok: {tx_ok} / {rx_ok}") print(f" bursts in window: {len(burst_info)}")
print(f" repeat pairs at {args.delay_ms:.0f}+-{args.tol_ms:.0f} ms: {len(pairs)}") print(f" firmware TX ok / RX crc-ok: {len(tx_events)} / {len(rx_events)}")
if gaps: print(f" TX events with RF in IQ: {len(matched)}/{len(tx_events)} "
print(f" observed gap min/med/max: " f"({result['tx_rf_confirmed_pct']} %)")
f"{gaps[0]}/{gaps[len(gaps)//2]}/{gaps[-1]} ms") print(f" clock offset: {best_off:.0f} ms")
for p in pairs[:10]: print(f" alignment error min/med/max: {result['align_error_ms']}")
print(f" t={p['original_t_ms']/1000:.3f}s -> +{p['gap_ms']}ms " print(f" duration error vs airtime: {result['burst_duration_error_ms']} ms")
f"({p['original_peak_db']:+.1f} dB -> {p['repeat_peak_db']:+.1f} dB, " print(f" our TX level over floor: {result['our_tx_peak_db_over_floor']} dB")
f"{p['repeat_duration_ms']} ms)") print(f" other bursts over floor: {result['other_burst_peak_db_over_floor']} dB")
print(f" firmware repeat delay: {result['firmware_repeat_delay_ms']} ms "
f"(configured {args.delay_ms:.0f})")
sys.exit(0 if pairs else 1) sys.exit(0 if matched else 1)