From 916cd93315c1770985bf380d5839d20c8e0ce544 Mon Sep 17 00:00:00 2001 From: Lars Nolden Date: Tue, 1 Sep 2026 11:44:51 +0200 Subject: [PATCH] docs: sync command reference; drop iq_bursts.py superseded by verify_repeats_iq.py --- README.md | 7 ++---- docs/TESTING.md | 33 +++++++++++++++++++++---- hil/iq_bursts.py | 63 ------------------------------------------------ 3 files changed, 30 insertions(+), 73 deletions(-) delete mode 100755 hil/iq_bursts.py diff --git a/README.md b/README.md index 78cafeb..30e488b 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,7 @@ This is **not** a standards-compliant repeater. See ``` firmware/ ESP-IDF app: SX1262 GFSK driver, wM-Bus C1 RX/TX, repeater state machine, recovery ladder, JSON telemetry +firmware/test/ host-side frame-layer tests (run under AddressSanitizer) hil/ hardware-in-the-loop harness (run.sh is the entry point) tools/ device discovery, flashing, reset docs/ hardware evidence, RF config, findings, timing, gaps @@ -37,11 +38,7 @@ Serial console (scriptable, JSON output): ```bash ./result-py/bin/python3 hil/dut_cmd.py --listen 5 status stats -# status | stats | clear_stats | radio_status | radio_reset | probe -# test_tx | test_burst | reboot -# set repeat_delay_ms N | set tx_power N | set repeat_enabled 0|1 -# set verbose 0|1 | set fem_rx_csd 0|1 | set pa_low 0|1 -# set test_lfield N | set whitelist ID[,ID...] | set whitelist clear +# full command list: docs/TESTING.md ``` ## Results (measured, not inferred) diff --git a/docs/TESTING.md b/docs/TESTING.md index 4ab7945..dc86a87 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -36,16 +36,39 @@ setup.log DUT configuration acks ./tools/flash.sh # build + flash ./hil/capture_sdr.sh 60 /tmp/sdr.log # SDR-only capture ./result-py/bin/python3 hil/dut_cmd.py PORT --listen 10 status stats -./result-py/bin/python3 hil/iq_energy.py iq.raw # burst energy probe -./result-py/bin/python3 hil/iq_spectrum.py iq.raw # spectrum sanity +./result-py/bin/python3 hil/iq_energy.py iq.raw # burst energy probe +./result-py/bin/python3 hil/iq_spectrum.py iq.raw # spectrum sanity +./result-py/bin/python3 hil/sdr_health.py # observer sensitivity +./firmware/test/run_tests.sh # frame-layer tests (ASan) ``` ## DUT serial commands +All output is single-line JSON; every line the HIL parses starts with `{`. + ``` -status | stats | clear_stats | radio_status | radio_reset | test_tx -set repeat_delay_ms N | set tx_power N | set repeat_enabled 0|1 -set verbose 0|1 | set whitelist ID[,ID...] | set whitelist clear | reboot +status current configuration + duty-cycle usage +stats all counters (incl. tx_airtime_us, tx_duty_cycle_ppm) +clear_stats +radio_status chip mode, command status, device errors, RSSI +radio_reset queue a full radio re-init +probe low-level scripted SPI/IRQ/TX diagnostic with raw dumps +test_tx transmit one synthetic C1 frame +test_burst transmit the same frame twice, repeat_delay_ms apart +inject standby fault injection: leave the radio out of RX +inject sleep fault injection: destroy the radio configuration +reboot + +set repeat_delay_ms N 20..200 +set tx_power N -9..14 (configured SX1262 level; FEM adds gain) +set repeat_enabled 0|1 +set verbose 0|1 +set fem_rx_csd 0|1 KCT8103L CSD level while in RX (LNA experiment) +set pa_low 0|1 1 = lowest documented PA table +set preamble_bits N 0|8|16|24|32 preamble detector length +set duty_budget_ppm N rolling-hour TX airtime cap; 1000 = 0.1 %, 0 = off +set test_lfield N 19..200, length of synthetic test frames +set whitelist ID[,ID...] | set whitelist clear ``` ## Known pitfalls diff --git a/hil/iq_bursts.py b/hil/iq_bursts.py deleted file mode 100755 index afd9bd8..0000000 --- a/hil/iq_bursts.py +++ /dev/null @@ -1,63 +0,0 @@ -#!/usr/bin/env python3 -"""List RF bursts in a raw rtl_sdr u8 IQ capture and the gaps between them. - -Usage: iq_bursts.py iq.raw [sample_rate] [threshold_db] - -Purpose: distinguish "transmitter produced no RF" from "RF exists but the -decoder cannot decode it". A repeater under test should produce burst PAIRS -separated by approximately the configured repeat delay. -""" -import sys -import numpy as np - -path = sys.argv[1] -fs = int(sys.argv[2]) if len(sys.argv) > 2 else 1_600_000 -thr_db = float(sys.argv[3]) if len(sys.argv) > 3 else 9.0 - -WIN = fs // 1000 # 1 ms resolution -CHUNK = fs * 2 # 1 s of bytes - -env = [] -with open(path, "rb") as f: - while True: - raw = f.read(CHUNK) - 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] - p = np.abs(iq) ** 2 - p = p[: (len(p) // WIN) * WIN].reshape(-1, WIN).mean(axis=1) - env.append(p) - -db = 10 * np.log10(np.concatenate(env) + 1e-9) -floor = np.median(db) -print(f"windows={len(db)} floor={floor:.1f}dB p99={np.percentile(db,99):.1f} max={db.max():.1f}") - -active = db > floor + thr_db -idx = np.where(active)[0] -bursts = [] -if len(idx): - start = prev = idx[0] - for i in idx[1:]: - if i > prev + 3: # >3 ms silence splits bursts - bursts.append((start, prev)) - start = i - prev = i - bursts.append((start, prev)) - -print(f"bursts (>{thr_db:.0f} dB over floor): {len(bursts)}") -prev_end = None -pairs = [] -for s, e in bursts: - gap = (s - prev_end) if prev_end is not None else None - dur = e - s + 1 - peak = db[s:e + 1].max() - floor - gtxt = f"gap={gap:>5} ms" if gap is not None else "gap= - " - print(f" t={s/1000:8.3f}s dur={dur:>3} ms peak=+{peak:5.1f} dB {gtxt}") - if gap is not None and 10 <= gap <= 300: - pairs.append((prev_end, s, gap)) - prev_end = e - -print(f"\nburst pairs with 10-300 ms spacing (repeat candidates): {len(pairs)}") -for a, b, g in pairs[:40]: - print(f" original ends {a/1000:.3f}s -> next starts {b/1000:.3f}s (gap {g} ms)")