Overview
Command Protocol v2 is the wire protocol a SplashMe controller speaks on firmware 2.5.46 and later. It is a compact binary protocol in which every message is authenticated with a key unique to the controller. The cloud uses it behind Device API v2; you can also use it yourself, directly against a controller on the local network, with your own application handling users and permissions.
Design in one paragraph
Section titled “Design in one paragraph”Every message is wrapped in a signed envelope: a protocol version, a counter and an authentication tag computed with the controller’s own key. The controller publishes its state as a state frame whenever something changes, answers queries, executes actions and uploads audit events; the payload layouts are part of the wire specification. In the cloud these messages travel over MQTT between the controller and SplashMe; on the LAN the same signed bytes travel inside a small JSON envelope over HTTP on port 8080.
Message types
Section titled “Message types”| Message | Direction | Signed | Purpose |
|---|---|---|---|
| State frame | Controller → clients | Yes | Telemetry, configuration and timers |
| State request | Client → controller | Not checked | Ask for a full state frame now |
| Query | Client → controller | Yes, replay-protected | Read something the state frame does not carry |
| Query reply | Controller → client | Yes | |
| Action | Client → controller | Yes, replay-protected | Change something |
| Event batch | Controller → cloud | Yes | Audit records |
| Event acknowledgement | Cloud → controller | Yes | Let the controller discard uploaded records |
Transports
Section titled “Transports”| Transport | Who can use it | Documented in |
|---|---|---|
| Cloud API | SplashMe development team only at present | Device API v2 |
| LAN, HTTP on port 8080 | Anyone on the controller’s network; open for testing now | LAN access |
| MQTT | SplashMe cloud only | MQTT transport, for reference |
Third parties do not receive MQTT broker credentials. The MQTT chapter is included so that the cloud API’s behaviour, and the frames you see on the LAN, are fully explained. The LAN is the transport open to third-party developers today; see What is available today.
Conventions
Section titled “Conventions”{deviceId}is the controller’s identifier, its MAC address upper-cased with underscores, for example02_53_4D_00_00_01.
Reference implementations
Section titled “Reference implementations”- The SplashMe cloud is the authoritative decoder for every frame described here.
- Reference code for wrapping, verifying and decoding frames is supplied with the wire specification.

