DD3-LoRa-Bridge-MultiSender/docs/engineering/hil-strategy.md

HIL Strategy

This document is design-only. Do not flash hardware or run destructive hardware operations from the non-hardware verifier.

Goals

• Exercise one sender board and one receiver board as a pair.
• Capture serial logs from both boards.
• Configure serial ports, baud rates, reset controls, and power controls outside source control.
• Simulate a DD3 smart meter over UART.
• Use a test MQTT broker and controlled Wi-Fi conditions.
• Optionally inject SD faults.

Proposed Stack

• Python pytest for orchestration.
• pyserial for sender, receiver, and smart-meter simulator UARTs.
• A local MQTT broker such as Mosquitto in a test container.
• Runner-side power/reset control through a safe abstraction, for example USB relay, programmable hub, or lab PSU API.
• Local configuration in ignored files such as hil_tests/config.local.yaml.

Hardware Topologies

Topology	Purpose
One sender board	Sender boot, time bootstrap request, meter parsing, backlog behavior, power telemetry.
One receiver board	AP/STA web behavior, MQTT publish behavior, SD behavior, malformed packet handling where injectable.
Sender + receiver pair	Normal LoRa transfer, ACK behavior, duplicate handling, long soak.
Receiver + smart-meter simulator	Receiver-only paths are limited; most meter simulation is sender-side.

Test Scenarios

Scenario	Required equipment	Assertions
Time bootstrap	Sender + receiver	Sender stays sync-only before valid ACK and starts normal flow after valid ACK time.
Normal batch transfer	Pair + meter simulator + MQTT broker	Receiver ACKs, publishes MQTT JSON, updates last batch, and logs CSV if SD enabled.
ACK loss	Pair with RF shield/control or receiver ACK suppression build fixture	Sender retries within BATCH_MAX_RETRIES and preserves stop-and-wait behavior.
Duplicate batches	Pair with induced ACK loss	Receiver ACKs duplicates but suppresses duplicate publish/log.
Malformed and truncated LoRa packets	Receiver plus packet injector fixture	Receiver rejects without ACK, SD, MQTT, or web updates.
Sender backlog	Sender + receiver + meter simulator	Backlog drains with single inflight batch and no queue overflow beyond policy.
Receiver restart	Pair with reset control	Sender recovers after receiver reboot and resumes ACKed transfers.
Meter failure	Sender + UART simulator	Fault counters increase according to stale/failure semantics.
Meter timestamp jumps	Sender + UART simulator	Jump is detected, counted once per event, and timestamp anchor recovers.
MQTT failure	Receiver + broker control	Receiver continues LoRa ACK path and reconnects MQTT without corrupting state.
Wi-Fi failure and AP fallback	Receiver + Wi-Fi control	AP fallback starts, saved config retry returns to STA when Wi-Fi recovers.
Missing or full SD	Receiver + SD fault fixture	Firmware continues without crashing; history endpoints report errors.
Repeated resets	Pair + reset control	No persistent config corruption; role detection remains stable.
Watchdog recovery	Pair + fault injection	Watchdog resets are visible and system returns to expected role behavior.
Heap and stack regression	Pair with telemetry parsing	Minimum heap/stack stay above agreed thresholds during web/history/LoRa load.
Long-duration soak	Pair + broker + meter simulator + SD	No hangs, reset storms, queue runaway, or publish/log drift over target duration.

Configuration Rules

• Keep local serial ports, Wi-Fi SSIDs, MQTT credentials, power-control endpoints, and board IDs out of source control.
• Use ignored local config files under hil_tests/.
• Commit only sanitized examples that contain fake ports, fake hosts, and no usable secrets.
• HIL runners must be labeled separately from non-hardware CI runners and must not run untrusted pull-request code.

Safety Gates

• Non-hardware CI must never flash boards.
• HIL jobs must require explicit labels and a trusted branch or manual approval.
• Power-cycle operations must validate configured device paths before acting.
• Firmware flashing, eFuse changes, secure boot, flash encryption, and OTA signing are outside this harness task.