MQTT transport

Controllers keep one TLS connection to the SplashMe MQTT broker, authenticated with an X.509 client certificate. Third parties do not receive broker credentials; this page explains what happens behind Device API v2 and what the frames you see on the LAN look like in the cloud.

Message flow

Every message is a signed envelope. Between the controller and the cloud the following messages are exchanged; each maps one-to-one onto a Device API v2 operation.

Message	Direction	Payload	Notes
State push	Controller → cloud	State frame	Pushed on change and heartbeat, and in reply to a state request
State request	Cloud → controller	Ignored	Controller replies with a full frame
Action	Cloud → controller	Action arguments	No reply; the next state push confirms
Query	Cloud → controller	Query request
Query reply	Controller → cloud	Query payload	Only when the reply is non-empty
Event batch	Controller → cloud	Event batch
Event acknowledgement	Cloud → controller	Acknowledged sequence number

Nothing is retained on the broker. A subscriber that connects late sees nothing until the next push or a state request.

When the controller pushes

Trigger	What is sent	Latency
Critical change: a flag, a pump mode, an equipment slot, a sanitiser state	Telemetry section and timer tail	Within 300 ms
Telemetry drift beyond a quantisation step: 0.5 °C, 0.1 pH, 10 mV, 5 L/min or kPa, 20 W, 10 mA, 1 % pump speed, 1 °C drive temperature	Telemetry and tail	At most every 30 s
Configuration change	Configuration section	Immediately
Nothing changed	Telemetry and tail	Every 90 s

Pushes are suppressed while a light colour sequence, a backwash or a flow calibration is running; one settled frame follows. Use a state request for a mid-operation read.

Names

Each action and query is addressed by name. The cloud restricts names to ^[a-z0-9_]{1,32}$. An unknown query name produces no reply; an unknown action name is ignored.