Queries and actions

The cloud signs each request with the controller’s key, publishes it, and for queries waits for the reply. Here you use typed JSON and let the cloud encode; the binary layouts are part of the wire specification.

Queries

POST/api-gateway/v2/iot-shadow/device/{deviceId}/query/{name}

name is 1 to 32 characters of a-z, 0-9 and _. The body is optional.

{
  "status": "SUCCESS",
  "data": { "query": "schedules", "counter": 327690, "encoding": "native", "data": … }
}

counter is the controller’s envelope counter on its reply. encoding tells you how data was produced.

Query	Body	encoding	data
aux_names	none	native	Array of slot labels, one per slot
pump_id	none	native	{ "pump_type", "pump_brand", "pump_model" }
schedules	none	native	Array of 20 schedule records, see below
events	{ "count": 20 }, 1 to 100	native	The newest count audit events, oldest first, in the event JSON shape
a supported v1 read command	{ "payload_hex": "<hex of the command's JSON body>" }, optional	json	That command’s JSON reply. Reserved commands are refused with 403
a v1 read command whose reply is not JSON	{ "payload_hex": "…" }	hex	Raw reply bytes as hex
an unknown name			The controller does not reply; the cloud returns 504

A schedule record:

{
  "index": 2, "enabled": true, "aux_slot": 2, "aux_type": 12, "turnover": 0, "pump_speed": 0,
  "start_min": 480, "end_min": 1080, "week_day": 127, "name": "Evening light"
}

index is the 0-based schedule number used by the schedule action. Unused records report aux_slot 99. week_day is a 7-bit day mask; 127 is every day.

Queries wait up to 8 seconds and return 504 if the controller does not reply. Right after a reboot pump_id may report a generic brand until the drive has been identified.

Actions

POST/api-gateway/v2/iot-shadow/device/{deviceId}/action/{name}

{ "status": "SUCCESS", "data": { "action": "aux", "counter": 1758400123, "confirmed": true } }

counter is the value the cloud signed with. confirmed is true when the controller pushed a state frame within 2 seconds of the action. false is not a failure: pushes are suppressed during some operations. The controller does not acknowledge actions individually; confirm the effect by reading state.

aux: switch an equipment slot

{ "slot": 3, "on": true, "trump": true }

Field	Meaning
slot	0 to 36. Slot 0 is the main pump
on	Desired state
trump	true to override the schedule until the next schedule boundary; false to let the scheduler take over again immediately

With trump: false an active schedule reverts the change within about a second. To switch the main pump with a speed, use the cmd action with v2_manual_set instead, as the SplashMe app does:

{ "command": "v2_manual_set", "body": { "aux_switch_state": true, "aux_slot_num": 0, "pump_speed": 60 } }

set_time: set the clock

{ "utc": 1758400000, "tz_offset_factor": 40 }

tz_offset_factor is the UTC offset in 15-minute steps, signed: 40 is UTC+10, 38 is UTC+9:30, -20 is UTC−5.

schedule: manage schedules

{
  "schedule": {
    "op": 0,
    "aux_slot": 2, "aux_type": 12, "turnover": 0, "pump_speed": 0,
    "start_min": 480, "end_min": 1080, "week_day": 127, "name": "Evening light"
  }
}

op	Meaning	Fields
0	Create	aux_slot, aux_type, turnover, pump_speed, start_min, end_min, week_day, name
1	Update	sched_num plus the create fields
2	Delete	sched_num
3	Enable or disable	sched_num, status (1 or 0)

sched_num is the 0-based index from the schedules query, 0 to 19. Read config.sched_enabled or the schedules query to see the result.

cmd: run a v1 command

{ "command": "set_ph_settings", "body": { "ph_dosing": true, "desired_ph_level": 74, … } }

Runs a v1 JSON command on the controller with a signature. Keep command to 63 characters or fewer: the cloud accepts longer names, but the controller ignores them. Commands reserved for SplashMe installation and service tooling are refused with 403; the list of supported commands is available from support@splashmepool.com.au. v1 “set” commands replace the whole settings object and zero any field you omit, so read the current values first. The command’s own JSON reply is not returned; observe the result in the next state frame.

evt_rewind: re-upload events

{ "from_seq": 0 }

See Events.

Raw payload

Any action can also be sent pre-encoded:

{ "payload_hex": "030101" }

Typed fields take precedence over payload_hex when both are present.

Errors

Status	message examples
400	Invalid action name, payload_hex is not valid hex, action body is missing its typed fields or payload_hex
403	The controller does not own you, or a cmd/query names a command reserved for SplashMe installation and service tooling
409	Controller not v2-capable
429	Controller cooling down
504	Query only: no reply within 8 seconds