72 lines
6.9 KiB
Markdown
72 lines
6.9 KiB
Markdown
# Sprint 7 — Conditional real-device compatibility
|
|
|
|
Status: proposed; not implemented. Read [the plan](../PLAN.md), [sprint index and shared rules](../SPRINTS.md), and [README](../../README.md).
|
|
|
|
|
|
### Goal and scope
|
|
|
|
Determine and verify actual device behavior without modifying existing device projects or operating real machinery.
|
|
|
|
### Deliverables and likely files
|
|
|
|
- `docs/DEVICE-SETUP.md` with verified framework/client/protocol and test configuration.
|
|
- Device-specific compatibility results in `docs/VERIFICATION.md`.
|
|
- Only if separately approved: a small independent test firmware/application under `device/` inside this project.
|
|
|
|
### Tasks
|
|
|
|
- Inspect how Esp32MqttConfig is consumed: host versus URI, ca_cert PEM versus path, TLS hostname checks, selected protocol and library version, and whether publish calls can target telemetry/status/ACK topics separately. Propose only necessary device-side settings; this struct is not a payload contract.
|
|
|
|
1. Inspect supplied Linux device and/or ESP32 source read-only; identify framework, exact client version, configured MQTT protocol, TLS/session handling, identities, payloads and command paths.
|
|
2. Determine direct ESP32-to-broker versus gateway architecture and select one initial endpoint with the user.
|
|
3. Map supported existing behavior to the test contract. Identify required source changes explicitly; do not modify existing projects or silently add a compatibility bridge.
|
|
4. Use a dedicated safe test instance/board. If required, propose an isolated test application in this project and obtain authorization before flashing hardware or writing that new device implementation.
|
|
5. Configure test credentials/CA/clock/topic identity; verify actual protocol and native-property evidence, telemetry/status, harmless command lifecycle, reconnect, expiry and duplicate handling where supported.
|
|
6. Update comparison results and limitations. Leave unavailable features unsupported/not_tested/blocked with reasons.
|
|
|
|
### Dependencies and required inputs
|
|
|
|
Sprint 5 minimum; Sprint 6 if using the remote broker. Actual device repositories, board model, hardware/access, framework/toolchain and explicit authorization for flashing/test-device changes. Hardware unavailable means this sprint remains blocked; prior simulator work remains useful.
|
|
|
|
### Acceptance criteria
|
|
|
|
- “Device backend” is resolved using actual source and deployment evidence.
|
|
- Exact tested SDK/client/protocol and environment are recorded.
|
|
- Only harmless commands run; production/device repositories remain unchanged.
|
|
- Native MQTT 5 features are marked passed only with actual end-to-end evidence. JSON-only interoperability is labeled separately.
|
|
- No simulator result is substituted for hardware verification.
|
|
|
|
### Automated checks
|
|
|
|
Approved isolated device builds/contract checks and backend integration tests appropriate to the identified stack. Do not install arbitrary SDKs before choosing the actual target.
|
|
|
|
### Manual verification
|
|
|
|
Observe device traffic in backend logs/browser; issue ping/get_version; exercise approved device reconnect/restart and record actual outcomes. Inspect test-broker/client evidence of protocol selection.
|
|
|
|
### Risks and unresolved decisions
|
|
|
|
Hardware availability, flashing permissions, clock/certificate resources, SDK support and unknown device contract. Existing firmware may require changes outside authorized scope; stop at a concrete change proposal rather than modifying it.
|
|
|
|
### Mandatory end-of-sprint testing and completion gate
|
|
|
|
After implementing this sprint, run its automated checks and manual verification above. Inspect the final changes for correctness, scope, secret exposure, and compatibility with completed sprints. Fix failures and rerun affected checks before declaring completion.
|
|
|
|
Record the exact commands/checks, actual outcomes, verification environment, and each acceptance criterion as PASS, FAIL, or BLOCKED. Include applicable regression checks for previously completed behavior. A skipped/unavailable required check is BLOCKED, never PASS; do not claim full sprint completion while required checks fail or remain blocked. Do not run unrelated or production-project tests.
|
|
|
|
Report the results and remaining limitations to the user. Wait for authorization before the next sprint unless continued execution was explicitly authorized. Even with permission to continue, do not bypass this verification gate.
|
|
|
|
### Copy-ready implementation prompt
|
|
|
|
```text
|
|
Perform Sprint 7 only after explicit authorization, using /home/ryan/Media/Code/Code/robot-market/test-mqtt-5 as the only writable project. Read applicable AGENTS.md, /home/ryan/.codex/RTK.md, README.md, docs/PLAN.md and docs/sprints/07-device-compatibility.md. Prefix shell commands with rtk. Existing device/server projects are read-only. No vending, motor, payment, credentials-change or OTA commands.
|
|
|
|
Obtain the actual Linux device/ESP32 repositories and board/access details. Inspect framework, exact MQTT client/version, configured protocol, TLS/session/topic/identity/correlation behavior. Resolve whether the target is direct ESP32 MQTT or a gateway and identify one initial test endpoint. Map compatibility to the isolated test contract; do not infer MQTT 5 support from broker capability or message delivery. If device changes are needed, present the concrete changes and prefer a separately authorized independent test application inside this project. Do not modify existing firmware or flash hardware without authorization.
|
|
|
|
On authorized dedicated test hardware, verify TLS/time, telemetry/status, ping/get_version ACK stages, native Response Topic/Correlation Data, reconnect/session/expiry/dedup behavior where supported. Inspect real connection/property evidence. Document exact versions, setup, results and limits in docs/DEVICE-SETUP.md and docs/VERIFICATION.md. If hardware/source/access is missing, report blocked/not_tested rather than substituting simulator evidence. Report acceptance status and stop.
|
|
|
|
ESP32 reference: read docs/PLAN.md section 6.1 for the supplied Esp32MqttConfig. It is connection configuration, not a payload schema or a blocker for Go implementation. Preserve the proposed Go test contracts. Device-specific MQTT 5 selection depends on the actual C library/build/init; inspect TLS/CA handling, role-specific credentials and single publish_topic limitations during device integration. Do not modify existing C projects. Separate MQTT 3.1.1 payload interoperability from native MQTT 5 feature evidence.
|
|
|
|
Mandatory completion gate: after implementing this sprint, run its listed automated and manual checks plus relevant regression checks, inspect the final changes for correctness/scope/secrets/compatibility, fix failures and rerun affected checks. Report exact checks, real outcomes, environment, and every acceptance criterion as PASS/FAIL/BLOCKED. Missing required checks are BLOCKED, never a pass. Do not mark the sprint complete with unresolved failures/blockers or bypass verification when continuing to another sprint.
|
|
```
|