Files
heltec-repeater/docs/TESTING.md
T

105 lines
3.5 KiB
Markdown

# 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
```