Envelope and keys
The envelope
Section titled “The envelope”Every Command Protocol v2 message is wrapped in a signed envelope made of a protocol version, a counter, the payload and an authentication tag computed with the controller’s key. The tag covers the version, the counter and the payload, so any corruption or tampering makes verification fail; there is no separate checksum.
The byte layout of the envelope, the tag algorithm, test vectors and reference code are part of the wire specification, which SplashMe provides to integrators on request.
The per-device key
Section titled “The per-device key”Each controller has its own key, unique to that controller. A key cannot be used to derive any other controller’s key, and SplashMe issues keys only through the API described below. If you need a key for a controller you cannot reach through the cloud, contact support@splashmepool.com.au.
You obtain a controller’s key from the cloud with GET …/envelope-key, which requires an OAuth token for an account that owns the controller. Treat it as a credential: whoever holds it can control that controller on its LAN.
Counters
Section titled “Counters”Every signed request you send to a controller carries a counter. The controller accepts a request only if its counter is greater than the last one it accepted, and rejected requests are recorded as VERIFY_FAIL audit events. Actions and queries share one sequence, and so do all senders, including the SplashMe cloud and apps.
To coexist with them, use the current Unix time in seconds as your counter, keep your clock synchronised, and never send a counter far ahead of real time. Two senders in the same second collide: the second request is dropped and should be retried a second later.
Frames the controller sends carry its own counter. Receivers do not enforce ordering on those; use the value to detect reboots if you wish.
The state request on the LAN is the one message that carries no signature: the controller answers any request with a full, signed state frame.
Action and query names are 1 to 32 characters from a-z, 0-9 and _. An unknown query name produces no reply; an unknown action name is ignored.