Files
heltec-repeater/docs/TESTING.md
T

3.5 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).

Long reliability soak (DUT only, no SDR)

nix develop --command ./hil/soak.sh 9000     # seconds

Measures firmware-side reliability over hours: repeat success rate, timing stability, radio recoveries, config-integrity failures and MCU resets, and reports progress against the milestone targets. Deliberately does not use the SDR, which cannot stream for hours without faulting.

Fault injection (verifying the recovery ladder)

./result-py/bin/python3 hil/dut_cmd.py <port> --listen 26 "inject standby"
./result-py/bin/python3 hil/dut_cmd.py <port> --listen 26 "inject sleep"

standby leaves the radio out of RX with its configuration intact; sleep additionally destroys the configuration. The heartbeat probe must detect both and the recovery ladder must restore RX. Verified behaviour:

inject standby -> heartbeat chip_mode=2, config_intact=true
               -> radio_recovery level 1 -> rx_restored
inject sleep   -> heartbeat chip_mode=0, config_intact=false
               -> radio_recovery level 1 -> failed   (correctly refuses)
               -> radio_recovery level 2 -> rx_restored