Skip to content

API Overview ​

Twinkle exposes two transports:

  • WebSocket for control, configuration, and live state — ws://<device-ip>/ws on port 80.
  • HTTP for filesystem operations (/api/fs/*) and firmware updates (/api/ota).

All WebSocket messages are JSON text frames. There is one socket for the whole device; requests are routed by the first segment of their path.

Connecting ​

js
const ws = new WebSocket(`ws://${location.hostname}/ws`);

ws.addEventListener('open', () => {
  ws.send(JSON.stringify({
    id: 1,
    method: 'get',
    path: 'global'
  }));
});

ws.addEventListener('message', (event) => {
  const msg = JSON.parse(event.data);

  if (msg.event) {
    // Unsolicited broadcast (state changed on the device)
    console.log('event', msg.event, msg.data);
    return;
  }

  // Reply to a request: id/path are echoed from the request
  console.log('reply', msg.id, msg.path, msg.data, msg.error);
});

The device does not require authentication. Anyone on the same network can connect and control it.

Request Envelope ​

json
{
  "id": 1,
  "method": "get",
  "path": "scene.0.state",
  "data": {}
}
FieldTypeRequiredDescription
idanynoClient-chosen identifier. Echoed verbatim in the reply; defaults to 0 when omitted.
methodstringyesOne of get, set, cmd, add, del.
pathstringyesResource path. The first segment selects the controller.
dataanydependsPayload for set, cmd, add, del. Usually an object.

Response Envelope ​

Replies to get and set:

json
{
  "id": 1,
  "path": "scene.0.state",
  "data": { "duration": 5000 }
}

Errors:

json
{
  "id": 1,
  "path": "scene.99",
  "error": "unknown scene"
}

id and path are always copied verbatim from the request. A reply contains either data or error, never both.

Methods ​

MethodPurposeSuccess reply
getRead a resource.Unicast reply with data.
setPatch a configuration or state.Unicast reply with data (usually an echo of the submitted values), unless the change is announced by broadcast only.
cmdRun an action.No unicast reply. The result is announced to every client as an event (for example global.state). Failures are sent to the requester only.
addCreate a resource.Usually no unicast reply; the change is announced as a collection event (automation, playlist).
delDelete a resource.Usually no unicast reply; the change is announced as a collection event.

add and del follow the same transport rule as cmd: the handler only sends a unicast reply when it sets error or data. A successful action with no explicit reply is normal — wait for the event on the socket.

Path Routing ​

The path prefix is matched against the registered controllers. A prefix only matches at a segment boundary: scene matches scene and scene.0 (and scene/0 at the routing level), but not sceneX.

PrefixTransportDescription
sceneWebSocketScenes, scene configuration, scene switching.
providerWebSocketData providers (time, prayer time, Hijri, location, moon phase).
globalWebSocketDevice info, global configuration, brightness, license, reboot.
audioWebSocketDFPlayer audio playback and track list.
buzzerWebSocketBuzzer melody listing and playback.
automationWebSocketAutomation rules (triggers and actions).
playlistWebSocketScene playlists.
fontWebSocketRead-only font catalog.
/api/fs/*HTTPFilesystem list/read/write/upload/copy/move/delete.
/api/otaHTTPFirmware upload.

Use . between path segments, for example scene.0.state. A leading / reaches the controller verbatim and is not interpreted as a separator, so use the dotted form in requests.

Transport-Level Errors ​

These are produced by the WebSocket dispatcher before a controller is reached.

ErrorCause
invalid jsonThe frame is not valid JSON.
missing pathpath is missing or empty.
missing methodmethod is missing or empty.
unknown methodmethod is not one of get, set, cmd, add, del.
unknown pathNo controller matches the first path segment.

Broadcast Events ​

Events are sent to every connected client without an id or path:

json
{
  "event": "global.state",
  "data": { "brightness": 128 }
}
EventEmitted when
global.stateActive scene or playlist changed, or display brightness changed.
audio.stateAudio playback state, volume, or equalizer changed.
buzzer.stateBuzzer started or stopped (including natural playback end).
automationAn automation was added, changed, or deleted.
playlistA playlist was added, changed, or deleted.

See Events for exact payloads.

Multiple producers can emit global.state with different partial payloads. Merge the fields you care about instead of replacing your local state object wholesale.

Schema Type Vocabulary ​

*.schema endpoints return a map of field name to a type hint. The values describe how an editor should render or validate a field; the wire values are plain JSON numbers, strings, and booleans.

TypeMeaning
boolBoolean.
int8, int16, int32Signed integer.
uint8, uint16, uint32Unsigned integer.
floatFloating-point number.
char8, char16, char32, char36, char48, char64String with a maximum length (the number is the buffer size).
password16String up to 15 characters, rendered as a password field.
color1616-bit RGB565 color encoded as an integer.
fontFont identifier from the font catalog.
clockMinute of day, 0–1439.
easingEasing selector encoded as an integer.
arrayEnumerated allowed values, for example [1, 2, 3].

HTTP Endpoints ​

EndpointPurpose
GET /api/fs/list?path=/configList a directory.
GET /api/fs/file?path=/config/global.jsonDownload or view a file.
POST /api/fs/file?path=/test.txtOverwrite a file with the raw request body.
POST /api/fs/upload?path=/folderUpload a file as multipart/form-data.
POST /api/fs/mkdir?path=/hello/worldCreate a directory (idempotent).
POST /api/fs/create?path=/hello/world.txtCreate an empty file (idempotent).
POST /api/fs/copyCopy a file; body {"src":"/a.txt","dst":"/b.txt"}.
POST /api/fs/moveMove a file or directory; same body.
POST /api/fs/renameAlias for move.
DELETE /api/fs/file?path=/file.txtDelete a file or an empty directory.
POST /api/otaUpload firmware as multipart/form-data.

See Filesystem API and OTA API.

Limits ​

LimitValue
HTTP port80
WebSocket path/ws
Small-reply stack buffer2048 bytes; larger replies are allocated from PSRAM/heap.
Scene count20
Provider count5
Automation rules8 free, 32 premium
Actions per automation16
Playlist count2 free, 32 premium
Entries per playlist32
Audio tracksIDs 1–3000
Buzzer file pathUp to 63 characters, must end in .rtttl.