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

Every message is wrapped in a 9-byte envelope: a version byte, a 32-bit counter and a 4-byte AES-CMAC tag computed with the controller’s 16-byte 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

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

Transport	Who can use it	Documented in
Cloud API	Any OAuth client whose user owns the controller	Device API v2
LAN, HTTP on port 8080	Anyone on the controller’s network holding its key	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.

Conventions

• All multi-byte integers are little-endian. There is no padding.
• Strings are [len u8][utf8 bytes], length at most 255.
• Byte layouts are given as offset, size and meaning. Hex dumps are shown with spaces between bytes.
• {deviceId} is the controller’s identifier, its MAC address upper-cased with underscores, for example 02_53_4D_00_00_01.

Reference implementations

• The SplashMe cloud is the authoritative decoder for every frame described here.
• The code samples on Envelope and keys and LAN access show a minimal Python client: wrap and unwrap, a state read and a signed action.