Files
heltec-repeater/hil/report.py
T

167 lines
5.6 KiB
Python
Executable File

#!/usr/bin/env python3
"""Render a human-readable HIL report from correlate.py JSON.
Usage: report.py report.json [options]
Exit code 0 = PASS, 1 = FAIL.
"""
import argparse
import json
import os
import sys
ap = argparse.ArgumentParser()
ap.add_argument("report")
ap.add_argument("--min-repeats", type=int, default=1,
help="minimum SDR-verified repeats for PASS")
ap.add_argument("--min-rx-rate", type=float, default=0,
help="minimum Heltec RX match rate in %% for PASS")
ap.add_argument("--duration", type=float, default=0)
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("--rf-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 {}
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)
rfp = load_json(args.rf_proof)
def fmt(v, unit=""):
if v is None:
return "n/a"
if isinstance(v, float):
return f"{v:.1f}{unit}"
return f"{v}{unit}"
fail = []
if r.get("sdr_originals", 0) == 0:
fail.append("SDR observed no original meter frames")
if r.get("heltec_rx", 0) == 0:
fail.append("Heltec received nothing")
if r.get("sdr_repeats", 0) < args.min_repeats:
fail.append(f"SDR-verified repeats {r.get('sdr_repeats', 0)} < {args.min_repeats}")
if args.min_rx_rate and (r.get("rx_match_rate_pct") or 0) < args.min_rx_rate:
fail.append("RX match rate below threshold")
if fw.get("boots", 0) > 1:
fail.append(f"unexpected MCU resets: {fw['boots'] - 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")
# Decoded H=0 -> H=1 transitions are preferred. Meter-anchored, spectrally
# classified FSK at firmware repeat times is an independent RF proof when
# the nearby transmission overloads the decoder.
rf_confirmed = (rfp is not None
and rfp.get("rf_state") in ("strong", "weak")
and rfp.get("tx_events", 0) >= args.min_repeats)
if rf_confirmed:
fail = [f for f in fail if not f.startswith("SDR-verified repeats")]
verdict = "PASS" if not fail else "FAIL"
print("=" * 50)
print("SOLENOS WMBUS HIL TEST")
print("=" * 50)
print(f"""
DUT:
Heltec WiFi LoRa 32 V4.3 (HTIT-WB32LAF)
ESP32-S3 + SX1262 + KCT8103L FEM
RF:
frequency: 868.950 MHz
mode: C1 (2-FSK, 100 kbps, +/-45 kHz)
configured TX power: {args.tx_power} dBm (SX1262; external PA adds gain)
repeat delay: {args.repeat_delay} ms
TEST:
duration: {args.duration:.0f} s
SDR usable time: {args.sdr_streamed} s
SDR sensitivity: {args.sdr_sensitivity}""")
if proof is not None:
print(f"""
TX DECODABILITY PROOF (synthetic C1, independent of meters):
bursts transmitted: {proof.get('bursts_requested')}
firmware TX ok: {proof.get('tx_reported_ok')}
SDR decoded as C1: {proof.get('bursts_with_sdr_decode')}
both airings decoded: {proof.get('bursts_with_both_airings_decoded')}""")
if rfp is not None:
print(f"""
RF-LEVEL TX PROOF (meter-anchored IQ + non-TX controls):
clock anchors: {rfp.get('clock_matched')}
clock median error: {rfp.get('clock_err_ms')} ms
observer state: {rfp.get('observer')}
meter level over floor: {rfp.get('meter_median_db')} dB
firmware TX events: {rfp.get('tx_events')}
RF state: {rfp.get('rf_state')}
TX median over floor: {rfp.get('tx_median_db')} dB
control median: {rfp.get('control_median_db')} dB
FSK-selective excess: {rfp.get('fsk_excess_db')} dB
spectral windows: {rfp.get('fsk_windows')}""")
print(f"""
SDR (independent observer):
decode lines: {r.get('sdr_frames_total')}
C1 CRC-ok bursts: {r.get('sdr_c1_crc_ok')}
T1 CRC-ok bursts: {r.get('sdr_t1_crc_ok', 0)}
classified originals: {r.get('sdr_originals')}
classified repeats: {r.get('sdr_repeats')}
unique meters: {len(r.get('per_meter') or {})}
HELTEC RX:
frames: {r.get('heltec_rx')}
CRC ok: {r.get('heltec_rx_crc_ok')}
matched SDR originals: {r.get('rx_matched')}
match rate: {fmt(r.get('rx_match_rate_pct'), ' %')}
HELTEC TX:
attempts: {r.get('heltec_tx_attempts')}
reported success: {r.get('heltec_tx_ok')}
SDR-VERIFIED REPEATS:
H=0 -> H=1 pairs: {r.get('sdr_repeats')}
fully correlated: {r.get('fully_correlated_repeats')}
vs TX attempts: {fmt(r.get('repeat_success_rate_pct'), ' %')}
TIMING (SDR-observed original -> repeat):
median: {fmt(d.get('median'), ' ms')}
minimum: {fmt(d.get('min'), ' ms')}
maximum: {fmt(d.get('max'), ' ms')}
ERRORS:
radio recoveries: {fw.get('recoveries')}
MCU boots seen: {fw.get('boots')}
""")
if r.get("per_meter"):
print(f"{'METER':>10} {'SDR':>6} {'HELTEC':>7} {'MATCHED':>8}")
for m, v in sorted(r["per_meter"].items(),
key=lambda kv: -kv[1]["sdr"]):
print(f"{m:>10} {v['sdr']:>6} {v['heltec']:>7} {v['matched']:>8}")
print()
if fail:
print("FAIL REASONS:")
for f in fail:
print(f" - {f}")
print()
print(f"RESULT:\n {verdict}")
sys.exit(0 if verdict == "PASS" else 1)