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