65 lines
4.2 KiB
Markdown
65 lines
4.2 KiB
Markdown
# 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.
|