Skip to content

Events ​

The device pushes unsolicited messages to every connected WebSocket client. Event frames carry no id or path and have the shape:

json
{ "event": "<name>", "data": { } }

Events are queued and broadcast from the main loop, so they may arrive a few milliseconds after the request that caused them. Unsolicited events also arrive when the device changes state on its own, for example when a playlist advances, a sceneOnce expires, or a melody finishes.

Event Summary ​

EventTriggerData
global.stateScene change, brightness change, playlist switchScene, playlist, or brightness
audio.stateAudio command or playback state changestate, vol, or eq
buzzer.stateBuzzer command or melody finishedstate, file
automationAutomation created, updated, or deletedA row or the full list
playlistPlaylist created, updated, or deletedA row or the full list

global.state ​

Emitted when the active scene changes, when a playlist advances, or when brightness changes. Scene changes send scene and playlist fields; brightness changes send only brightness.

Scene change:

json
{
  "event": "global.state",
  "data": {
    "activeScene": 2,
    "activePlaylist": -1,
    "playlistIndex": 0,
    "playlistOnce": false
  }
}

Playlist switch or advance:

json
{
  "event": "global.state",
  "data": {
    "activeScene": 16,
    "activePlaylist": 1,
    "playlistIndex": 2,
    "playlistOnce": false
  }
}

Brightness change (set global.state):

json
{ "event": "global.state", "data": { "brightness": 200 } }
FieldTypeDescription
activeSceneintegerActive scene ID.
activePlaylistintegerActive playlist ID, or -1.
playlistIndexintegerCurrent playlist entry.
playlistOncebooleanWhether the playlist runs once.
brightnessintegerBrightness 0–255; only on brightness changes.

A scene-change event is also emitted when the device automatically returns from a sceneOnce or when a playlist advances on its own.

audio.state ​

Partial payloads, depending on what changed.

State change:

json
{ "event": "audio.state", "data": { "state": 1, "file": 2 } }

file is present only when state is 1 (playing).

Volume change:

json
{ "event": "audio.state", "data": { "vol": 20 } }

Equalizer change:

json
{ "event": "audio.state", "data": { "eq": 3 } }
FieldTypeDescription
stateinteger0 stopped, 1 playing, 2 paused.
fileintegerCurrent track ID.
volintegerVolume 0–30.
eqintegerEqualizer preset 0–5.

buzzer.state ​

Emitted on every playback state change, including natural completion.

json
{ "event": "buzzer.state", "data": { "state": 1, "file": "/buzzer/assembly.rtttl" } }
json
{ "event": "buzzer.state", "data": { "state": 0, "file": "" } }
FieldTypeDescription
stateinteger0 stopped, 1 playing.
filestringPlaying file path, melody name, or "" when stopped.

automation ​

After set or add, data is an array containing the single changed row. After del, data is the full list.

json
{
  "event": "automation",
  "data": [[1, "Morning", 1, 127, 300, "time", ["scene", "brightness"]]]
}

See Automation API for the row format.

playlist ​

After set or add, data is an array containing the single changed row. After del, data is the full list.

json
{ "event": "playlist", "data": [[1, "Pagi", 3]] }

See Playlist API for the row format.