From 3b8547fb8ac32a9c8c4eb590f227dd8a0c8a0a49 Mon Sep 17 00:00:00 2001 From: Lars Nolden Date: Mon, 31 Aug 2026 22:23:26 +0200 Subject: [PATCH] HIL harness, docs, SDR PLL-wedge workaround; firmware flashed and in RX --- docs/HARDWARE.md | 80 ++++++++++++++ docs/RF_CONFIG.md | 58 ++++++++++ docs/STANDARDS_GAPS.md | 18 ++++ docs/devboard_signals.csv | 13 +++ flake.nix | 2 +- hil/capture_sdr.sh | 11 ++ hil/capture_serial.sh | 7 ++ hil/correlate.py | 222 ++++++++++++++++++++++++++++++++++++++ hil/dut_cmd.py | 31 ++++++ hil/iq_energy.py | 47 ++++++++ hil/iq_spectrum.py | 39 +++++++ hil/report.py | 103 ++++++++++++++++++ hil/run.sh | 97 +++++++++++++++++ 13 files changed, 727 insertions(+), 1 deletion(-) create mode 100644 docs/HARDWARE.md create mode 100644 docs/RF_CONFIG.md create mode 100644 docs/STANDARDS_GAPS.md create mode 100644 docs/devboard_signals.csv create mode 100755 hil/capture_sdr.sh create mode 100755 hil/capture_serial.sh create mode 100755 hil/correlate.py create mode 100755 hil/dut_cmd.py create mode 100755 hil/iq_energy.py create mode 100755 hil/iq_spectrum.py create mode 100755 hil/report.py create mode 100755 hil/run.sh diff --git a/docs/HARDWARE.md b/docs/HARDWARE.md new file mode 100644 index 0000000..dd12f00 --- /dev/null +++ b/docs/HARDWARE.md @@ -0,0 +1,80 @@ +# Hardware + +## Board + +``` +Board: Heltec WiFi LoRa 32 V4.3 +Model: HTIT-WB32LAF +MCU: ESP32-S3 (16 MB flash, 2 MB PSRAM) +Radio: Semtech SX1262 +FEM: KCT8103L (868-928 MHz high-power variant) +``` + +DUT USB identity (native ESP32-S3 USB): +- factory Arduino firmware enumerates as `usb-Espressif_Systems_heltec_wifi_lora_32_v4__16_MB_FLASH__2_MB_PSRAM__F85B1BA1F86C-if00` +- our ESP-IDF firmware / ROM bootloader enumerate as `usb-Espressif_USB_JTAG_serial_debug_unit_F8:5B:1B:A1:F8:6C-if00` + +`tools/discover_devices.sh` handles both. + +## SX1262 pin mapping — DOCUMENTED + EXPERIMENTALLY VERIFIED + +``` +SX1262: + NSS GPIO8 + SCK GPIO9 + MOSI GPIO10 + MISO GPIO11 + RESET GPIO12 + BUSY GPIO13 + DIO1 GPIO14 +``` + +Verified: SPI register write/readback passes and GFSK RX runs +(`radio_init` diagnostic: `spi:true, reset:true, tcxo:true`, heartbeat +`chip_mode:5` = RX with plausible RSSI). See docs/FINDINGS.md. + +Sources: +- Heltec product manual / wiki, "WiFi LoRa 32 V4": + https://wiki.heltec.org/docs/devices/open-source-hardware/esp32-series/lora-32/wifi-lora-32-v4/ +- Heltec schematic: https://resource.heltec.cn/download/WiFi_LoRa_32_V4/Schematic/HTIT-WB32LAF_V4.3.pdf +- RNode_Firmware 1.86 board table via jrl290/RTNode-HeltecV4 `Boards.h` + (working firmware for this exact board): + https://github.com/jrl290/RTNode-HeltecV4 + +## KCT8103L FEM — DOCUMENTED + EXPERIMENTALLY VERIFIED + +``` +FEM: + POWER GPIO7 supply enable, drive HIGH + CSD GPIO2 chip enable, drive HIGH (internal pull-up on KCT8103L) + CTX GPIO5 path select: LOW = RX/LNA, HIGH = TX/PA + CPS -- wired to SX1262 DIO2 (enable DIO2-as-RF-switch) +``` + +Notes: +- V4.2 boards use a GC1109 FEM with different control (CSD + CPS, CTX on + DIO2). Do NOT copy V4.2 configuration. +- RNode 1.86 auto-detects the FEM by reading CSD as input after powering + the FEM: KCT8103L pulls HIGH, GC1109 pulls LOW. +- After TX, CTX must be driven LOW again or the FEM stays in TX-bypass and + RX is dead (documented failure mode in RTNode sx126x.cpp). + +## TCXO — DOCUMENTED (RNode 1.86), verified working + +- DIO3-controlled TCXO, 1.8 V (`SetDIO3AsTCXOCtrl` code 0x02), ~4 ms start. +- After enabling the TCXO, recalibrate all blocks or `XOSC_START_ERR` + persists in device errors. +- OCP register set to 0x28 (RNode 1.86 "OCP_TUNED" for the V4 PA chain). + +## SDR + +``` +Nooelec NESDR SMArt v5 +RTL2832U + R820T, USB ID 0bda:2838, serial 33999948 +``` + +Quirk (EXPERIMENTALLY VERIFIED): the R820T PLL can wedge ("PLL not +locked"), after which captures contain gain-independent white noise on any +frequency. A USB reset (`usbreset 0bda:2838`) recovers it. The HIL runner +resets the dongle before each session. Suspected trigger: `rtl_test -t`'s +direct-sampling probe. Avoid `rtl_test -t` in automation. diff --git a/docs/RF_CONFIG.md b/docs/RF_CONFIG.md new file mode 100644 index 0000000..ca100b7 --- /dev/null +++ b/docs/RF_CONFIG.md @@ -0,0 +1,58 @@ +# RF Configuration — Wireless M-Bus C1 (mode C, meter-to-other) + +## PHY parameters (EN 13757-4, cross-checked against rtl-wmbus source) + +``` +Frequency: 868.95 MHz +Chip/bit rate: 100 kbps NRZ (mode C is NOT 3-of-6 coded, unlike T) +Deviation: +/-45 kHz nominal +Preamble: alternating 01 chips +Sync: 0x543D (shared T/C access code) +Mode bytes: 0x54CD -> frame format A, 0x543D -> frame format B +``` + +Authority used: +- rtl-wmbus source (`t1_c1_packet_decoder.h`): `ACCESS_CODE_T1_C1 0x543d`, + `C1_MODE_A 0b010101001100`, `C1_MODE_B 0b010101000011`, trailer `0b1101` + — concatenated this yields sync sequences 0x543D54CD (A) / 0x543D543D (B). +- Frame lengths (over-the-air, incl. L and CRCs): + - format A: `1 + L + 2*((L-10+15)/16 + 1)` + - format B: `1 + L` + +## SX1262 register-level configuration (firmware/main/sx126x.c) + +``` +Packet type: GFSK +Bitrate: raw 0x002800 (32*32e6/100e3 = 10240 -> 100 kbps) +Deviation: raw 0x00B852 (45e3*2^25/32e6 = 47186) +Shaping: none (plain 2-FSK; may experiment with BT=0.5) +RX bandwidth: 234.3 kHz DSB (code 0x0A) -- signal occupies ~190 kHz +Sync word: 0x543D, 16 bits; mode bytes handled as payload so RX and + TX share one configuration +Preamble TX: 48 bits +Preamble det: 8 bits +Length mode: fixed, 255-byte capture, truncated in software using the + L-field formulas above (SX1262 variable-length mode cannot + express wM-Bus length semantics) +CRC: radio CRC off; EN 13757 CRC-16 (poly 0x3D65, complemented) + validated per block in software +Whitening: off +RX gain: boosted (reg 0x08AC = 0x96) +TX params: default -9 dBm configured (min), ramp 40 us; PA config + (0x02,0x02,0x00,0x01) = +14 dBm-optimal table, deliberately + capped -- the external KCT8103L PA adds gain on top +``` + +## Consequences of the fixed-255-byte RX capture + +RxDone fires ~ (255 - frame_len) * 80 us after the actual end of frame; +the firmware reconstructs the true end-of-frame timestamp. During that +tail the receiver cannot re-arm sync search, adding up to ~20 ms of dead +time per frame. Acceptable for the experiment; optimization candidate +(GetRxBufferStatus polling with early stop). + +## TX power + +Configured SX1262 power is NOT radiated power: the KCT8103L PA follows. +Development default is the SX1262 minimum (-9 dBm). Log lines carry +`configured_tx_dbm` to keep this distinction explicit. diff --git a/docs/STANDARDS_GAPS.md b/docs/STANDARDS_GAPS.md new file mode 100644 index 0000000..7782f10 --- /dev/null +++ b/docs/STANDARDS_GAPS.md @@ -0,0 +1,18 @@ +# Standards Gaps — experimental shortcuts vs EN 13757 / OMS + +This firmware is an RF feasibility experiment, NOT a standards-compliant +repeater. Known deviations: + +| # | Experimental behavior | Standard requirement | +|---|---|---| +| 1 | Repeats the raw telegram bit-exact, including hop-related fields | EN 13757-5 repeaters must manage the hop counter / C-field semantics so telegrams are not repeated endlessly | +| 2 | Fixed development repeat delay 20-200 ms (default 50 ms) | OMS repeaters use randomized delays in the seconds range to avoid collisions | +| 3 | Repeats every CRC-valid C1 telegram (optional dev whitelist) | Real repeaters filter by installation list | +| 4 | No duty-cycle accounting | EU 868.95 MHz band has duty-cycle limits (1% for 868.7-869.2 sub-band per ERC 70-03); a production repeater must budget its TX time | +| 5 | Duplicate suppression is a 2.5 s hash ring | Standard requires proper duplicate/loop protection semantics | +| 6 | No AES, no decryption, payload treated as opaque | OMS security profiles apply to end devices; a transparent repeater may pass ciphertext, but production behavior needs review | +| 7 | T1 telegrams are detected (shared 0x543D sync) but dropped | A combined C/T repeater would need 3-of-6 decode/encode | +| 8 | Format B frames >128 bytes CRC-checked but rare path untested | -- | + +None of these shortcuts may be carried into the production Solenos/Gebos +gateway without explicit review. diff --git a/docs/devboard_signals.csv b/docs/devboard_signals.csv new file mode 100644 index 0000000..7d2d9a3 --- /dev/null +++ b/docs/devboard_signals.csv @@ -0,0 +1,13 @@ +signal,device,gpio,direction,voltage,interrupt,timing_critical,test_point_required,header_required,reason +WMBUS_NSS,SX1262,8,output,3.3,false,true,true,true,SPI decode of radio commands during bring-up +WMBUS_SCK,SX1262,9,output,3.3,false,true,true,true,SPI decode +WMBUS_MOSI,SX1262,10,output,3.3,false,true,true,true,SPI decode +WMBUS_MISO,SX1262,11,input,3.3,false,true,true,true,SPI decode +WMBUS_RESET,SX1262,12,output,3.3,false,false,true,true,radio recovery verification +WMBUS_BUSY,SX1262,13,input,3.3,false,true,true,true,command-timing and stuck-BUSY debugging +WMBUS_DIO1,SX1262,14,input,3.3,true,true,true,true,RX/TX IRQ latency measurement +FEM_PWR_EN,KCT8103L,7,output,3.3,false,false,true,true,FEM power sequencing verification +FEM_CSD,KCT8103L,2,output,3.3,false,false,true,true,FEM enable + board-revision detection (pull level) +FEM_CTX,KCT8103L,5,output,3.3,false,true,true,true,RX/TX path switch timing vs TX start +ESP_USB_DN,ESP32-S3,19,bidir,3.3,false,false,false,true,flash/console; must stay accessible +ESP_USB_DP,ESP32-S3,20,bidir,3.3,false,false,false,true,flash/console diff --git a/flake.nix b/flake.nix index 19ba96e..efe0af0 100644 --- a/flake.nix +++ b/flake.nix @@ -61,7 +61,7 @@ ]); in { - packages.${system} = { inherit rtl-wmbus wmbusmeters; }; + packages.${system} = { inherit rtl-wmbus wmbusmeters; hil-python = pythonEnv; }; devShells.${system}.default = pkgs.mkShell { name = "heltec-repeater-dev"; diff --git a/hil/capture_sdr.sh b/hil/capture_sdr.sh new file mode 100755 index 0000000..640a957 --- /dev/null +++ b/hil/capture_sdr.sh @@ -0,0 +1,11 @@ +#!/usr/bin/env bash +# Capture wM-Bus frames with the RTL-SDR for a fixed duration. +# Usage: capture_sdr.sh DURATION_S OUTFILE [GAIN] +# timeout is applied to rtl_sdr itself so the pipeline dies cleanly +# (killing a wrapping shell orphans the children -- learned the hard way). +set -euo pipefail +cd "$(dirname "$0")/.." +DUR=$1; OUT=$2; GAIN=${3:-42.1} + +timeout "$DUR" rtl_sdr -f 868950000 -s 1600000 -g "$GAIN" - 2>"${OUT%.log}.err" \ + | rtl_wmbus -f > "$OUT" 2>/dev/null || true diff --git a/hil/capture_serial.sh b/hil/capture_serial.sh new file mode 100755 index 0000000..312507b --- /dev/null +++ b/hil/capture_serial.sh @@ -0,0 +1,7 @@ +#!/usr/bin/env bash +# Capture structured serial output from the DUT for a fixed duration. +# Usage: capture_serial.sh PORT DURATION_S OUTFILE +set -euo pipefail +cd "$(dirname "$0")/.." +PORT=$1; DUR=$2; OUT=$3 +exec ./result-py/bin/python3 hil/dut_cmd.py "$PORT" --listen "$DUR" status > "$OUT" 2>&1 diff --git a/hil/correlate.py b/hil/correlate.py new file mode 100755 index 0000000..b67f7f3 --- /dev/null +++ b/hil/correlate.py @@ -0,0 +1,222 @@ +#!/usr/bin/env python3 +"""Correlate Heltec serial events with SDR (rtl_wmbus) captures. + +Inputs: + --serial serial.log JSON-lines from the Heltec ({"event": ...}) + --sdr rtlwmbus.log rtl_wmbus CSV-ish lines: + [algo]C1;crc_ok;3of6ok;timestamp;pkt_rssi;rssi;serial;0xHEX +Output: JSON report on stdout. + +Correlation model (developer repeat delay ~50 ms): + SDR original <-> Heltec RX : same cooked bytes, |dt| < rx_window + Heltec RX <-> Heltec TX : same hash (firmware log) + Heltec TX <-> SDR repeat : same cooked bytes, dt in [min_delay, max_delay] + after the SDR original + +The Heltec logs raw over-the-air frames (with CRCs); rtl_wmbus prints +"cooked" frames (CRCs stripped). cook() below mirrors rtl-wmbus. +""" +import argparse +import json +import re +import sys +from datetime import datetime + + +def cook_a(frame: bytes): + """Strip block CRCs from a format A over-the-air frame.""" + if len(frame) < 12: + return None + out = bytearray(frame[:10]) + pos = 12 + while pos < len(frame): + n = min(16, len(frame) - pos - 2) + if n <= 0: + return None + out += frame[pos:pos + n] + pos += n + 2 + return bytes(out) + + +def cook_b(frame: bytes): + """Strip CRCs from a format B frame and rewrite L (mirrors rtl-wmbus).""" + if len(frame) < 12: + return None + out = bytearray() + rem = frame + while rem: + if len(rem) >= 128: + out += rem[:126] + rem = rem[128:] + else: + out += rem[:-2] + rem = b"" + # rewrite L: original L includes CRC bytes; cooked excludes them + out[0] = len(out) - 1 + return bytes(out) + + +def parse_serial(path): + """Heltec JSON-lines -> (rx_events, tx_events, other).""" + rx, tx, other = [], [], [] + with open(path, "r", errors="replace") as f: + for line in f: + line = line.strip() + if not line.startswith("{"): + continue + try: + ev = json.loads(line) + except json.JSONDecodeError: + continue + e = ev.get("event") + if e == "wmbus_rx": + raw = bytes.fromhex(ev.get("raw", "")) + fmt = ev.get("format", "A") + cooked = cook_a(raw) if fmt == "A" else cook_b(raw) + ev["_raw"] = raw + ev["_cooked"] = cooked + rx.append(ev) + elif e == "wmbus_tx": + tx.append(ev) + else: + other.append(ev) + return rx, tx, other + + +SDR_RE = re.compile( + r"^(?:[a-z0-9_]+;)?(?P[TCS]1);(?P\d);(?P\d);" + r"(?P[\d\- :.]+);(?P\d+);(?P\d+);" + r"(?P[0-9A-Fa-f]{8});0x(?P[0-9a-fA-F]+)" +) + + +def parse_sdr(path): + frames = [] + with open(path, "r", errors="replace") as f: + for line in f: + m = SDR_RE.match(line.strip()) + if not m: + continue + ts = datetime.strptime(m["ts"].strip(), "%Y-%m-%d %H:%M:%S.%f") + frames.append({ + "mode": m["mode"], + "crc_ok": m["crc"] == "1", + "t": ts.timestamp(), + "serial": m["serial"].lower(), + "cooked": bytes.fromhex(m["hex"]), + }) + return frames + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--serial", required=True) + ap.add_argument("--sdr", required=True) + ap.add_argument("--min-delay", type=float, default=0.010) + ap.add_argument("--max-delay", type=float, default=0.300) + ap.add_argument("--rx-window", type=float, default=2.0, + help="wall/mono clock skew tolerance for RX matching") + args = ap.parse_args() + + heltec_rx, heltec_tx, other = parse_serial(args.serial) + sdr = parse_sdr(args.sdr) + sdr_c1 = [s for s in sdr if s["mode"] == "C1" and s["crc_ok"]] + + # --- classify SDR frames into originals vs repeats --------------------- + # A repeat is an SDR frame with identical cooked bytes to an earlier SDR + # frame within [min_delay, max_delay]. Everything else is an original. + originals, repeats = [], [] + for i, s in enumerate(sdr_c1): + matched = None + for j in range(i - 1, -1, -1): + prev = sdr_c1[j] + dt = s["t"] - prev["t"] + if dt > args.max_delay: + break + if prev["cooked"] == s["cooked"] and args.min_delay <= dt <= args.max_delay: + matched = (j, dt) + break + if matched is not None: + repeats.append({"idx": i, "orig_idx": matched[0], "dt": matched[1], **s}) + else: + originals.append({"idx": i, **s}) + + # --- Heltec RX <-> SDR originals (exact cooked-bytes match) ------------ + # Serial timestamps are monotonic-us; SDR timestamps are wall clock. + # Estimate offset from the best byte-match pairs. + matched_rx = 0 + per_meter = {} + used_rx = set() + for o in originals: + ser = o["serial"] + pm = per_meter.setdefault(ser, {"sdr": 0, "heltec": 0, "matched": 0}) + pm["sdr"] += 1 + for k, r in enumerate(heltec_rx): + if k in used_rx or r["_cooked"] != o["cooked"]: + continue + used_rx.add(k) + matched_rx += 1 + pm["matched"] += 1 + o["heltec_rx"] = r + break + + for r in heltec_rx: + if r["_cooked"] is None: + continue + ser = r["_cooked"][4:8][::-1].hex() if len(r["_cooked"]) >= 8 else "?" + per_meter.setdefault(ser, {"sdr": 0, "heltec": 0, "matched": 0}) + per_meter[ser]["heltec"] += 1 + + # --- Heltec TX <-> SDR repeats ----------------------------------------- + tx_by_hash = {} + for t in heltec_tx: + tx_by_hash.setdefault(t.get("hash"), []).append(t) + + verified_repeats = 0 + for rep in repeats: + orig = sdr_c1[rep["orig_idx"]] + o_entry = next((o for o in originals if o["idx"] == rep["orig_idx"]), None) + hr = o_entry.get("heltec_rx") if o_entry else None + if hr and hr.get("hash") in tx_by_hash: + verified_repeats += 1 + rep["verified"] = True + + tx_ok = [t for t in heltec_tx if t.get("result") == "ok"] + delays = [r["dt"] * 1000 for r in repeats] + delays.sort() + + def pct(a, b): + return round(100.0 * a / b, 1) if b else None + + report = { + "sdr_frames_total": len(sdr), + "sdr_c1_crc_ok": len(sdr_c1), + "sdr_originals": len(originals), + "sdr_repeats": len(repeats), + "heltec_rx": len(heltec_rx), + "heltec_rx_crc_ok": sum(1 for r in heltec_rx if r.get("crc_ok")), + "heltec_tx_attempts": len(heltec_tx), + "heltec_tx_ok": len(tx_ok), + "rx_matched": matched_rx, + "rx_match_rate_pct": pct(matched_rx, len(originals)), + "sdr_verified_repeats": len(repeats), + "fully_correlated_repeats": verified_repeats, + "repeat_success_rate_pct": pct(len(repeats), len(tx_ok)), + "repeat_delay_ms": { + "median": delays[len(delays) // 2] if delays else None, + "min": delays[0] if delays else None, + "max": delays[-1] if delays else None, + }, + "per_meter": per_meter, + "firmware_events": { + "recoveries": sum(1 for e in other if e.get("event") == "radio_recovery"), + "boots": sum(1 for e in other if e.get("event") == "boot"), + }, + } + json.dump(report, sys.stdout, indent=2) + print() + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/hil/dut_cmd.py b/hil/dut_cmd.py new file mode 100755 index 0000000..886815f --- /dev/null +++ b/hil/dut_cmd.py @@ -0,0 +1,31 @@ +#!/usr/bin/env python3 +"""Send commands to the DUT and print JSON responses. + +Usage: dut_cmd.py PORT [--listen SECONDS] CMD [CMD...] +Each CMD is sent as a line; output is echoed for --listen seconds (default 3). +""" +import sys +import time +import serial + +port = sys.argv[1] +args = sys.argv[2:] +listen = 3.0 +if args and args[0] == "--listen": + listen = float(args[1]) + args = args[2:] + +s = serial.Serial(port, 115200, timeout=0.2) +time.sleep(0.2) +s.reset_input_buffer() +for cmd in args: + s.write((cmd + "\n").encode()) + s.flush() + time.sleep(0.1) + +end = time.time() + listen +while time.time() < end: + line = s.readline() + if line: + sys.stdout.write(line.decode(errors="replace")) + sys.stdout.flush() diff --git a/hil/iq_energy.py b/hil/iq_energy.py new file mode 100755 index 0000000..51a3910 --- /dev/null +++ b/hil/iq_energy.py @@ -0,0 +1,47 @@ +#!/usr/bin/env python3 +"""Detect burst energy in a raw rtl_sdr u8 IQ capture. + +Usage: iq_energy.py iq.raw [sample_rate] +Prints noise floor, and burst groups >9 dB above floor with 1 ms resolution. +Exit code 0 if at least one burst found, 2 otherwise. +""" +import sys +import numpy as np + +path = sys.argv[1] +fs = int(sys.argv[2]) if len(sys.argv) > 2 else 1_600_000 +win = fs // 1000 # 1 ms + +pows = [] +with open(path, "rb") as f: + while True: + raw = f.read(fs * 2) # 1 s + if len(raw) < win * 2: + break + buf = np.frombuffer(raw, dtype=np.uint8).astype(np.float32) - 127.5 + iq = buf[0::2] + 1j * buf[1::2] + w = np.abs(iq) ** 2 + w = w[: (len(w) // win) * win].reshape(-1, win).mean(axis=1) + pows.append(w) + +db = 10 * np.log10(np.concatenate(pows) + 1e-9) +floor = np.median(db) +print(f"windows: {len(db)} x 1ms, floor={floor:.1f} dB, " + f"p99={np.percentile(db, 99):.1f}, max={db.max():.1f}") + +idx = np.where(db > floor + 9)[0] +groups = [] +if len(idx): + start = prev = idx[0] + for i in idx[1:]: + if i > prev + 2: + groups.append((start, prev)) + start = i + prev = i + groups.append((start, prev)) + +print(f"burst groups (>9 dB over floor): {len(groups)}") +for g in groups[:40]: + print(f" t={g[0]/1000:.3f}s dur={g[1]-g[0]+1}ms " + f"peak=+{db[g[0]:g[1]+1].max()-floor:.1f}dB") +sys.exit(0 if groups else 2) diff --git a/hil/iq_spectrum.py b/hil/iq_spectrum.py new file mode 100755 index 0000000..89ae4df --- /dev/null +++ b/hil/iq_spectrum.py @@ -0,0 +1,39 @@ +#!/usr/bin/env python3 +"""Averaged power spectrum of a raw rtl_sdr u8 IQ capture. + +Usage: iq_spectrum.py iq.raw [sample_rate] [seconds] +Prints a coarse ASCII spectrum and the top peaks. +""" +import sys +import numpy as np + +path = sys.argv[1] +fs = int(sys.argv[2]) if len(sys.argv) > 2 else 1_600_000 +secs = float(sys.argv[3]) if len(sys.argv) > 3 else 5.0 + +NFFT = 4096 +acc = np.zeros(NFFT) +count = 0 +with open(path, "rb") as f: + raw = f.read(int(fs * 2 * secs)) +buf = np.frombuffer(raw, dtype=np.uint8).astype(np.float32) - 127.5 +iq = buf[0::2] + 1j * buf[1::2] +n = (len(iq) // NFFT) * NFFT +iq = iq[:n].reshape(-1, NFFT) +win = np.hanning(NFFT) +for row in iq[:2000]: + sp = np.fft.fftshift(np.abs(np.fft.fft(row * win)) ** 2) + acc += sp + count += 1 +db = 10 * np.log10(acc / count + 1e-9) +freqs = np.fft.fftshift(np.fft.fftfreq(NFFT, 1 / fs)) + +# collapse to 64 bins for display +B = 64 +cb = db[: (NFFT // B) * B].reshape(B, -1).max(axis=1) +lo, hi = cb.min(), cb.max() +print(f"spectrum dB range: {lo:.1f} .. {hi:.1f} (span {hi-lo:.1f} dB)") +for i, v in enumerate(cb): + bar = "#" * int(max(0, (v - lo) / max(1e-9, hi - lo) * 60)) + fk = freqs[i * (NFFT // B)] / 1e3 + print(f"{fk:+8.0f} kHz |{bar}") diff --git a/hil/report.py b/hil/report.py new file mode 100755 index 0000000..f148caf --- /dev/null +++ b/hil/report.py @@ -0,0 +1,103 @@ +#!/usr/bin/env python3 +"""Render a human-readable HIL report from correlate.py JSON. + +Usage: report.py report.json [--min-repeats N] [--min-rx-rate PCT] +Exit code 0 = PASS, 1 = FAIL. +""" +import argparse +import json +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="?") +args = ap.parse_args() + +r = json.load(open(args.report)) + +d = r.get("repeat_delay_ms") or {} +fw = r.get("firmware_events") or {} + +fail_reasons = [] +if r.get("sdr_originals", 0) == 0: + fail_reasons.append("SDR saw no original meter frames") +if r.get("heltec_rx", 0) == 0: + fail_reasons.append("Heltec received nothing") +if r.get("sdr_repeats", 0) < args.min_repeats: + fail_reasons.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_reasons.append("RX match rate below threshold") +if fw.get("boots", 0) > 1: + fail_reasons.append(f"unexpected MCU resets: {fw.get('boots', 0) - 1}") + +verdict = "PASS" if not fail_reasons else "FAIL" + +W = 50 +print("=" * W) +print("SOLENOS WMBUS HIL TEST") +print("=" * W) +print(f""" +DUT: + Heltec WiFi LoRa 32 V4.3 (HTIT-WB32LAF) + +RF: + frequency: 868.950 MHz + mode: C1 + configured TX power: {args.tx_power} dBm + repeat delay: {args.repeat_delay} ms + +TEST: + duration: {args.duration:.0f} s + +SDR: + frames total: {r.get('sdr_frames_total')} + C1 CRC-ok: {r.get('sdr_c1_crc_ok')} + originals: {r.get('sdr_originals')} + unique meters: {len(r.get('per_meter') or {})} + +HELTEC RX: + frames: {r.get('heltec_rx')} + crc ok: {r.get('heltec_rx_crc_ok')} + matched originals: {r.get('rx_matched')} + match rate: {r.get('rx_match_rate_pct')} % + +HELTEC TX: + attempts: {r.get('heltec_tx_attempts')} + reported success: {r.get('heltec_tx_ok')} + +SDR VERIFIED REPEATS: + matched: {r.get('sdr_repeats')} + fully correlated: {r.get('fully_correlated_repeats')} + success rate: {r.get('repeat_success_rate_pct')} % + +TIMING: + median repeat delay: {d.get('median')} ms + minimum: {d.get('min')} ms + maximum: {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()): + print(f"{m:>10} {v['sdr']:>6} {v['heltec']:>7} {v['matched']:>8}") + print() + +if fail_reasons: + print("FAIL REASONS:") + for fr in fail_reasons: + print(f" - {fr}") + print() + +print(f"RESULT:\n {verdict}") +sys.exit(0 if verdict == "PASS" else 1) diff --git a/hil/run.sh b/hil/run.sh new file mode 100755 index 0000000..692938b --- /dev/null +++ b/hil/run.sh @@ -0,0 +1,97 @@ +#!/usr/bin/env bash +# Full HIL loop: discover -> (build+flash) -> capture serial+SDR -> correlate -> report. +# +# Usage: ./hil/run.sh [--duration N] [--no-flash] [--tx-power N] [--delay MS] +# [--gain G] [--min-repeats N] +# Exit: 0 = PASS, nonzero = FAIL (report thresholds or infrastructure error). +set -euo pipefail +cd "$(dirname "$0")/.." + +DURATION=300 +FLASH=1 +TXPOW=-9 +DELAY=50 +GAIN=42.1 +MIN_REPEATS=1 +while [ $# -gt 0 ]; do + case "$1" in + --duration) DURATION=$2; shift 2 ;; + --no-flash) FLASH=0; shift ;; + --tx-power) TXPOW=$2; shift 2 ;; + --delay) DELAY=$2; shift 2 ;; + --gain) GAIN=$2; shift 2 ;; + --min-repeats) MIN_REPEATS=$2; shift 2 ;; + *) echo "unknown arg: $1" >&2; exit 2 ;; + esac +done + +PY=./result-py/bin/python3 +[ -x "$PY" ] || { echo "run 'nix build .#hil-python -o result-py' first" >&2; exit 2; } + +# 1-2. discover devices (abort on ambiguity) +eval "$(./tools/discover_devices.sh)" +echo "DUT: $DUT_PORT" +echo "SDR: Nooelec NESDR SMArt v5, index $SDR_INDEX, serial $SDR_SERIAL" + +# 3. SDR sanity: reset USB (rtl PLL can wedge; see docs/FINDINGS.md) and +# verify the device opens. +usbreset 0bda:2838 >/dev/null 2>&1 || true +sleep 1 + +# 4-6. build + flash + reset +if [ "$FLASH" = 1 ]; then + (cd firmware && idf.py build) >/dev/null + (cd firmware && idf.py -p "$DUT_PORT" flash) >/dev/null 2>&1 || { + # port re-enumerates when entering download mode; rediscover once + sleep 2 + eval "$(./tools/discover_devices.sh)" + (cd firmware && idf.py -p "$DUT_PORT" flash) >/dev/null + } + sleep 2 + eval "$(./tools/discover_devices.sh)" +fi + +RUN_DIR="captures/$(date +%Y-%m-%dT%H-%M-%S)-hil" +mkdir -p "$RUN_DIR" +echo "run dir: $RUN_DIR" + +# 7. configure DUT + start serial capture +$PY hil/dut_cmd.py "$DUT_PORT" --listen 2 \ + "set repeat_delay_ms $DELAY" "set tx_power $TXPOW" "clear_stats" \ + > "$RUN_DIR/setup.log" 2>&1 +$PY hil/dut_cmd.py "$DUT_PORT" --listen "$DURATION" status \ + > "$RUN_DIR/serial.log" 2>&1 & +SERIAL_PID=$! + +# 8. SDR capture (timeout applied to rtl_sdr itself; children die with it) +./hil/capture_sdr.sh "$DURATION" "$RUN_DIR/rtlwmbus.log" "$GAIN" & +SDR_PID=$! + +# 9-12. wait for both collectors +wait "$SDR_PID" || true +wait "$SERIAL_PID" || true + +# final stats snapshot +$PY hil/dut_cmd.py "$DUT_PORT" --listen 3 stats > "$RUN_DIR/final_stats.log" 2>&1 || true +cat "$RUN_DIR/final_stats.log" >> "$RUN_DIR/serial.log" + +# 13-14. correlate +$PY hil/correlate.py --serial "$RUN_DIR/serial.log" --sdr "$RUN_DIR/rtlwmbus.log" \ + > "$RUN_DIR/report.json" + +# 15. lockup detection: heartbeats should keep arriving +HB=$(grep -c '"event":"heartbeat"' "$RUN_DIR/serial.log" || true) +EXPECTED_HB=$((DURATION / 10 - 2)) +if [ "$HB" -lt "$EXPECTED_HB" ]; then + echo "WARNING: only $HB heartbeats seen (expected >= $EXPECTED_HB) - possible lockup" \ + | tee "$RUN_DIR/lockup_warning.txt" +fi + +# 16-18. report +$PY hil/report.py "$RUN_DIR/report.json" \ + --min-repeats "$MIN_REPEATS" --duration "$DURATION" \ + --tx-power "$TXPOW" --repeat-delay "$DELAY" \ + | tee "$RUN_DIR/report.txt" +RC=${PIPESTATUS[0]} +echo "artifacts: $RUN_DIR" +exit "$RC"