HIL harness, docs, SDR PLL-wedge workaround; firmware flashed and in RX
This commit is contained in:
@@ -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.
|
||||||
@@ -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.
|
||||||
@@ -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.
|
||||||
@@ -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
|
||||||
|
@@ -61,7 +61,7 @@
|
|||||||
]);
|
]);
|
||||||
in
|
in
|
||||||
{
|
{
|
||||||
packages.${system} = { inherit rtl-wmbus wmbusmeters; };
|
packages.${system} = { inherit rtl-wmbus wmbusmeters; hil-python = pythonEnv; };
|
||||||
|
|
||||||
devShells.${system}.default = pkgs.mkShell {
|
devShells.${system}.default = pkgs.mkShell {
|
||||||
name = "heltec-repeater-dev";
|
name = "heltec-repeater-dev";
|
||||||
|
|||||||
Executable
+11
@@ -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
|
||||||
Executable
+7
@@ -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
|
||||||
Executable
+222
@@ -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<mode>[TCS]1);(?P<crc>\d);(?P<x>\d);"
|
||||||
|
r"(?P<ts>[\d\- :.]+);(?P<prssi>\d+);(?P<rssi>\d+);"
|
||||||
|
r"(?P<serial>[0-9A-Fa-f]{8});0x(?P<hex>[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())
|
||||||
Executable
+31
@@ -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()
|
||||||
Executable
+47
@@ -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)
|
||||||
Executable
+39
@@ -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}")
|
||||||
Executable
+103
@@ -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)
|
||||||
Executable
+97
@@ -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"
|
||||||
Reference in New Issue
Block a user