64 lines
5.5 KiB
Markdown
64 lines
5.5 KiB
Markdown
# Robot Market MQTT 5 test environment
|
||
|
||
Status: **Sprints 1–4 implemented; local tests pass. Functional testing now uses raw observation and unrestricted broker topics.** The Go MQTT 5 observer, command CLI, simulator and optional loopback browser viewer are available. Remote TLS/plaintext MQTT checks remain available for the observer and simulator.
|
||
|
||
This independent project will test a local Go backend and simulator against an isolated Mosquitto broker. The intended remote topology requires only outbound connections from the development computer and devices.
|
||
|
||
The user authorized Sprints 1–4 on 2026-10-06 and requested a server-deployable broker with TLS plus optional plaintext access. Existing projects remain read-only references. Continue one sprint at a time with verification and authorization for the next sprint.
|
||
|
||
- [Complete plan](docs/PLAN.md): findings, architecture, dependencies, contracts, security, logging/browser visibility, compatibility, deployment, and verification.
|
||
- [Sprint breakdown and implementation prompts](docs/SPRINTS.md): index linking seven separate sprint files, each with a copy-ready prompt and mandatory end-of-sprint tests, checks, fixes, and evidence reporting.
|
||
|
||
## Intended experience
|
||
|
||
1. Deploy the isolated test broker on the server, then start the local Go backend.
|
||
2. Start the simulator, then optionally a dedicated physical test device.
|
||
3. Read structured logs showing inbound/outbound MQTT messages, topic, safe payload preview, protocol properties, request correlation, and outcomes.
|
||
4. Open the optional Go-served viewer at `http://127.0.0.1:8080` to inspect the same events, connection state, counters, and compatibility results.
|
||
5. Run harmless `ping` or `get_version` commands from the CLI and observe transport acknowledgement, device acceptance, and completion separately.
|
||
6. Inspect compatibility evidence separately for simulator and physical devices.
|
||
|
||
The broker, offline configuration validation, MQTT observer/command CLI, simulator and browser viewer are implemented. See [the run guide](docs/RUNNING.md) for operation and visible input/output logs. Physical-device verification remains outstanding.
|
||
|
||
The Go observer/viewer and simulator also have a local Docker image and Compose setup. The Compose file connects to the already deployed remote test broker; broker deployment remains under `deploy/`.
|
||
|
||
On Linux, copy `.env.docker.example` to `.env`, confirm the local CA/credential file paths, then run `docker compose up --build -d observer` and `docker compose --profile simulator up -d simulator`. The viewer opens at <http://127.0.0.1:8080>. See [Docker run details and commands](docs/RUNNING.md#run-with-docker-compose).
|
||
|
||
## Scope boundaries
|
||
|
||
- All new implementation belongs in this directory.
|
||
- Do not modify the existing vending backend, device repositories, production broker, credentials, listeners, or data.
|
||
- No vending, motor, payment, credential-change, or OTA commands.
|
||
- Browser viewer is read-only, optional, loopback-bound, and served by Go with embedded HTML/JavaScript; no separate frontend build system is required.
|
||
- No database, cloud dashboard, Kubernetes, or monitoring stack.
|
||
- Simulator success is never reported as hardware verification.
|
||
|
||
Sprint 1 verification is recorded in [its sprint document](docs/sprints/01-foundation.md#completion-evidence). Sprint 2 server runtime and external MQTT connectivity are verified; Sprint 3 [acceptance evidence](docs/sprints/03-backend-simulator.md#completion-evidence) records unit/race, CLI and real-broker checks. Sprint 4 [acceptance evidence](docs/sprints/04-browser-viewer.md#completion-evidence) records viewer tests and the browser verification status. Deployment instructions are available below.
|
||
|
||
## ESP32 connection reference
|
||
|
||
Share the [ESP32 test ZIP](esp32-test-kit.zip) with the firmware developer. It contains a short [test guide](docs/ESP32-DEVELOPER-HANDOFF.md), actual ESP32 test credentials in plaintext, and the CA for optional TLS.
|
||
|
||
The supplied `Esp32MqttConfig` describes Wi-Fi, broker host/port, credentials, subscription/publication topic and CA trust. It is not a payload schema and does not block the Go backend. [The plan](docs/PLAN.md#61-esp32-connection-configuration-supplied-by-user) records the exact struct, field mapping, MQTT 5 selection checks and the single-publication-topic limitation to inspect during device integration.
|
||
|
||
## Available now
|
||
|
||
```sh
|
||
cd /home/ryan/Media/Code/Code/robot-market/test-mqtt-5
|
||
rtk go run ./cmd/test-mqtt5 --config config.example.toml check-config
|
||
```
|
||
|
||
For MQTT observer/simulator/command usage, start with [RUNNING.md](docs/RUNNING.md).
|
||
|
||
See [configuration and CLI usage](docs/CONFIGURATION.md) and [implemented payload contracts](docs/CONTRACTS.md). `check-config` does not connect to a broker or validate remote credentials/certificates.
|
||
|
||
## Server broker deployment package
|
||
|
||
- [TLS Compose](deploy/compose.yaml)
|
||
- [Optional plaintext override](deploy/compose.insecure.yaml)
|
||
- [Deployment/setup/verification instructions](docs/DEPLOYMENT.md)
|
||
|
||
Deploy the copied deploy/ directory on your server. The base file publishes TLS on 8884; adding the insecure override also publishes authenticated plaintext on 1884. The setup helper creates dedicated test certificates/credentials. The user deployed the broker; server runtime checks and external TLS/plaintext exchanges passed.
|
||
|
||
The Docker viewer subscribes to `robot-market/test/v1/#` and shows raw messages without schema, timestamp or device-ID checks. Any authenticated test account may publish/subscribe to any broker topic. See [the current diagnostic report](docs/DEVICE-MESSAGE-DIAGNOSTICS.md).
|