Files
heltec-repeater/docs/TESTING.md
T

2.4 KiB

Testing

One-command HIL test

nix develop --command ./hil/run.sh --duration 300

Performs: device discovery (aborts on ambiguity) -> SDR USB reset -> firmware build + flash -> DUT configuration -> concurrent serial + SDR capture -> correlation -> report (text + report.json). Exit 0 = PASS.

Useful flags:

  • --no-flash reuse the already-flashed firmware
  • --duration N capture window seconds
  • --tx-power N configured SX1262 dBm (-9..14; FEM adds gain!)
  • --delay MS repeat delay (20..200)
  • --gain G SDR tuner gain
  • --min-repeats N PASS threshold

Artifacts

Each run writes captures/<timestamp>-hil/:

serial.log      DUT JSON-lines (wmbus_rx / wmbus_tx / heartbeats / stats)
rtlwmbus.log    rtl_wmbus decodes
report.json     machine-readable correlation result
report.txt      human-readable report
setup.log       DUT configuration acks

Manual pieces

./tools/discover_devices.sh -v                 # device inventory
./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

DUT serial commands

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

Known pitfalls

  • SDR PLL wedge -> gain-independent white noise; usbreset 0bda:2838.
  • Never wrap the rtl pipeline in timeout bash -c (orphans children); apply timeout to rtl_sdr itself.
  • ESP32-S3 USB re-enumerates between app CDC and ROM bootloader; flash scripts rediscover the port on failure.

LNA / FEM A/B experiment (no SDR needed)

nix develop --command ./hil/lna_ab.sh 600     # seconds per arm

Runs two RX-only arms (CSD high vs CSD low) with retransmission disabled and reports frame counts, CRC success, unique meters and RSSI per arm. Result: docs/RF_FRONTEND_TESTS.md.

Interpreting observer state

Every run records SDR sensitivity: full | degraded from hil/sdr_health.py. Treat cross-run comparisons as invalid unless both runs report the same state -- this dongle loses ~17 dB within minutes of streaming (docs/HARDWARE.md).