Files
heltec-repeater/hil/run.sh
T

210 lines
8.1 KiB
Bash
Executable File

#!/usr/bin/env bash
# Full HIL loop for the Heltec V4.3 wM-Bus C1 repeater.
#
# discover devices -> verify SDR actually receives -> build+flash
# -> phase A: TX decodability proof (synthetic C1 bursts)
# -> phase B: real-meter RX/repeat correlation
# -> phase C: decode-independent IQ repeat proof
# -> report (text + JSON), nonzero exit on FAIL
#
# Usage: ./hil/run.sh [--duration N] [--no-flash] [--tx-power N] [--delay MS]
# [--iq-seconds N] [--proof-gain G]
# [--gain G] [--min-repeats N] [--no-proof]
set -euo pipefail
cd "$(dirname "$0")/.."
DURATION=300
FLASH=1
TXPOW=-9
DELAY=200
GAIN=42.1
MIN_REPEATS=1
IQ_SECONDS=120
PROOF_GAIN=""
PROOF=1
while [ $# -gt 0 ]; do
case "$1" in
--duration) DURATION=$2; shift 2 ;;
--no-flash) FLASH=0; shift ;;
--no-proof) PROOF=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 ;;
--iq-seconds) IQ_SECONDS=$2; shift 2 ;;
--proof-gain) PROOF_GAIN=$2; shift 2 ;;
*) echo "unknown arg: $1" >&2; exit 2 ;;
esac
done
if ! [[ "$TXPOW" =~ ^-?[0-9]+$ ]] || (( TXPOW < -9 || TXPOW > 2 )); then
echo "--tx-power must be an integer in -9..2" >&2
exit 2
fi
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"
RUN_DIR="captures/$(date +%Y-%m-%dT%H-%M-%S)-hil"
mkdir -p "$RUN_DIR"
echo "run dir: $RUN_DIR"
# --- 3. SDR must demonstrably receive before any capture is trusted --------
for i in 1 2 3; do
if $PY hil/sdr_health.py > "$RUN_DIR/sdr_health.txt" 2>&1; then break; fi
echo "SDR unhealthy (try $i) - resetting" >&2
usbreset 0bda:2838 >/dev/null 2>&1 || true
sleep $((i * 5))
done
cat "$RUN_DIR/sdr_health.txt"
grep -q "SDR_HEALTH=ok" "$RUN_DIR/sdr_health.txt" || {
echo "ABORT: SDR observer is deaf; captures would be unattributable" >&2
exit 3
}
# --- 4-6. build + flash + reset --------------------------------------------
if [ "$FLASH" = 1 ]; then
# always the "test" profile: the configuration every reported number
# is measured with (see firmware/sdkconfig.defaults.test)
./tools/build.sh test > "$RUN_DIR/build.log" 2>&1
if ! (cd firmware && idf.py -B build-test -p "$DUT_PORT" flash) \
>> "$RUN_DIR/build.log" 2>&1; then
# the port re-enumerates when entering download mode; rediscover once
sleep 2
eval "$(./tools/discover_devices.sh)"
(cd firmware && idf.py -B build-test -p "$DUT_PORT" flash) \
>> "$RUN_DIR/build.log" 2>&1
fi
sleep 2
eval "$(./tools/discover_devices.sh)"
fi
# --- configure DUT --------------------------------------------------------
$PY hil/dut_cmd.py "$DUT_PORT" --listen 3 \
"set repeat_delay_ms $DELAY" "set tx_power $TXPOW" "clear_stats" \
> "$RUN_DIR/setup.log" 2>&1
# --- phase A: TX decodability proof ---------------------------------------
# Synthetic C1 frames, each aired twice at the repeat delay. Independent of
# meter traffic, and (unlike real repeats) not preceded by a weak frame,
# so it isolates "can the SDR decode our C1 TX" from bench dynamic range.
if [ "$PROOF" = 1 ]; then
echo "phase A: TX decodability proof"
./hil/capture_sdr.sh 70 "$RUN_DIR/proof_sdr.log" "${PROOF_GAIN:-$GAIN}" &
SDR_PID=$!
sleep 10
for L in 19 60 98; do
$PY hil/dut_cmd.py "$DUT_PORT" --listen 8 \
"set test_lfield $L" test_burst >> "$RUN_DIR/proof_serial.log" 2>&1
done
wait "$SDR_PID" || true
$PY hil/verify_tx.py --serial "$RUN_DIR/proof_serial.log" \
--sdr "$RUN_DIR/proof_sdr.log" > "$RUN_DIR/tx_proof.txt" 2>&1 || true
$PY hil/verify_tx.py --serial "$RUN_DIR/proof_serial.log" \
--sdr "$RUN_DIR/proof_sdr.log" --json > "$RUN_DIR/tx_proof.json" 2>&1 || true
cat "$RUN_DIR/tx_proof.txt"
# Second, independent decoder opinion on one of our transmitted frames:
# rtl-wmbus proves it demodulates, wmbusmeters proves the link layer is
# a structurally valid wM-Bus telegram.
FRAME=$(grep -o '"raw":"[0-9A-Fa-f]*"' "$RUN_DIR/proof_serial.log" \
| head -1 | sed 's/.*"raw":"//;s/"//')
if [ -n "${FRAME:-}" ]; then
COOKED=$($PY - "$FRAME" <<'PYCOOK'
import sys
sys.path.insert(0, "hil")
from correlate import cook_a
raw = bytes.fromhex(sys.argv[1])
c = cook_a(raw)
print(c.hex() if c else "")
PYCOOK
)
if [ -n "$COOKED" ]; then
if ./hil/verify_frame_semantics.sh "$COOKED" \
"$RUN_DIR/frame_semantics.txt"; then
echo "wmbusmeters link-layer cross-check: PASS"
else
echo "wmbusmeters link-layer cross-check: FAIL (see frame_semantics.txt)"
fi
fi
fi
fi
# --- phase B: real meter traffic, decodes + IQ from ONE stream -------------
# One rtl_sdr stream feeds both rtl_wmbus (meter originals) and a raw IQ
# file (our transmissions, measured decode-independently). Separate
# captures are not comparable: this dongle's sensitivity drifts ~17 dB
# over minutes (docs/FINDINGS.md).
echo "phase B: real-meter capture (${DURATION}s, decodes + IQ)"
IQ="$RUN_DIR/iq.raw"
$PY hil/dut_cmd.py "$DUT_PORT" --listen "$DURATION" status \
> "$RUN_DIR/serial.log" 2>&1 &
SERIAL_PID=$!
if [ "$IQ_SECONDS" -gt 0 ]; then
./hil/capture_both.sh "$DURATION" "$RUN_DIR/rtlwmbus.log" "$IQ" "$GAIN" &
else
./hil/capture_sdr.sh "$DURATION" "$RUN_DIR/rtlwmbus.log" "$GAIN" &
fi
SDR_PID=$!
wait "$SDR_PID" || true
wait "$SERIAL_PID" || true
$PY hil/dut_cmd.py "$DUT_PORT" --listen 4 stats > "$RUN_DIR/final_stats.log" 2>&1 || true
cat "$RUN_DIR/final_stats.log" >> "$RUN_DIR/serial.log"
# --- RF-level repeat proof from the same stream's IQ ----------------------
if [ -s "$IQ" ]; then
echo "RF-level repeat proof from meter-anchored IQ"
RF_RC=0
if ! $PY hil/meter_anchored.py --iq "$IQ" \
--serial "$RUN_DIR/serial.log" --json \
> "$RUN_DIR/rf_proof.json" 2> "$RUN_DIR/rf_proof.err"; then
RF_RC=$?
fi
if [ -s "$RUN_DIR/rf_proof.json" ]; then
cat "$RUN_DIR/rf_proof.json"
else
cat "$RUN_DIR/rf_proof.err"
fi
# Preserve weak, absent and unclassifiable RF for offline audit.
if [ "$RF_RC" = "0" ] \
&& grep -q '"rf_state": "strong"' "$RUN_DIR/rf_proof.json" 2>/dev/null; then
rm -f "$IQ"
fi
fi
# --- 13-14. correlate ------------------------------------------------------
MAXDELAY=$(awk "BEGIN{printf \"%.3f\", ($DELAY + 200) / 1000}")
$PY hil/correlate.py --serial "$RUN_DIR/serial.log" --sdr "$RUN_DIR/rtlwmbus.log" \
--min-delay 0.010 --max-delay "$MAXDELAY" > "$RUN_DIR/report.json"
# --- 15. lockup / reset detection -----------------------------------------
HB=$(grep -c '"event":"heartbeat"' "$RUN_DIR/serial.log" || true)
# heartbeats are emitted at >= 10 s cadence (the radio task also does RX/TX
# work between them), so allow slack; this catches real stalls, not drift.
EXPECTED_HB=$((DURATION / 14))
if [ "$HB" -lt "$EXPECTED_HB" ]; then
echo "WARNING: only $HB heartbeats (expected >= $EXPECTED_HB) - possible lockup" \
| tee "$RUN_DIR/lockup_warning.txt"
fi
# --- 16-18. report ---------------------------------------------------------
STREAMED=$(sed -n 's/^usable_seconds=//p' "$RUN_DIR/rtlwmbus.stats" 2>/dev/null || sed -n 's/^streamed_seconds=//p' "$RUN_DIR/rtlwmbus.stats" 2>/dev/null || echo "?")
SENS=$(sed -n 's/^SDR_SENSITIVITY=//p' "$RUN_DIR/sdr_health.txt" 2>/dev/null || echo unknown)
$PY hil/report.py "$RUN_DIR/report.json" \
--min-repeats "$MIN_REPEATS" --duration "$DURATION" \
--tx-power "$TXPOW" --repeat-delay "$DELAY" \
--sdr-streamed "$STREAMED" \
--sdr-sensitivity "${SENS:-unknown}" \
--tx-proof "$RUN_DIR/tx_proof.json" \
--rf-proof "$RUN_DIR/rf_proof.json" \
| tee "$RUN_DIR/report.txt"
RC=${PIPESTATUS[0]}
echo "artifacts: $RUN_DIR"
exit "$RC"