Architecture

   Pool controller (ESP32)  ⇄  SplashMe MQTT broker (TLS, client certificate)
            │                          ⇅
            │  LAN (HTTP, pv2)   SplashMe API server
            │                    ┌───────────────────────────────┐
            │                    │ /api-gateway/v1  OAuth2 + REST │
            │                    │ /api-gateway/v2  signed v2 API │
            │                    └───────────────────────────────┘
            │                          ⇅
            ▼                 Your application / integration
   Your LAN client ◄──── envelope key obtained once via the cloud

The pieces

The controller keeps one outbound TLS connection to the SplashMe cloud, authenticated with a per-device client certificate. Over it the controller publishes its state and receives commands. Controllers on firmware 2.5.46 or later also run a small HTTP server on the local network for LAN access.

The SplashMe API server is the only party that talks to controllers on your behalf in the cloud. It authenticates users, checks that the user owns the controller in question, translates REST calls into device commands, and returns the result. It never exposes the MQTT broker to third parties.

Your application talks HTTPS to the API server with an OAuth2 bearer token. It can also talk directly to a controller on the same LAN using the v2 protocol, once it holds that controller’s envelope key.

Two command paths

v1: shadow and JSON commands

The controller mirrors its configuration into a cloud device shadow. A v1 read asks the controller for a fresh copy of the relevant section; a v1 write sends a JSON command that the controller applies and acknowledges. The API server serialises commands per controller, so a burst of requests to one controller is queued, and if the queue gets too deep you receive a 429 with a retry hint rather than a timeout. See Rate limits and throttling.

v2: signed binary frames

On v2 firmware the controller pushes a signed binary state frame whenever something changes and at a regular heartbeat. The API server verifies the signature with that controller’s own key, merges the frame into a state document, and serves it instantly from cache. Actions and queries are signed the same way in the other direction. Because every frame is authenticated end to end, the same frames can be exchanged directly on the LAN without the cloud. See Command Protocol v2.

Ownership and consent

Every device endpoint is guarded by two checks: the bearer token must be valid, and the user it represents must own, or be a member of a site that owns, the controller named in the URL. Ownership comes from the SplashMe account system and is refreshed when the user signs in. There is no way to address a controller a user has not been granted access to.