WebSocket Usage

WebSocket communication uses JSON as data format.

Socket endpoints are:

• wss://[device]/api/ws for encrypted connections
• ws://[device]/api/ws for unencrypted connections

note

Encrypted connections require a valid HTTPS certificate for the device.

General Data Structure

Transmission data is formatted in JSON.

Requests

Messages from client to server generally have the following values:

{"msgID":1, "method":""}

• msgID (optional) can be any value and will be returned by the device to uniquely assign responses to requests.
• method (required) tells the device what to do.

Every other value depends on the selected method.

---

Responses

Messages from server to client generally have the following values:

{"msgID":1, "method":""}

Every other value depends on the selected method, as specified.

---

Methods

The following methods are supported

auth

Required after connecting to the WebSocket to authenticate the connection. Without a valid authentication, no other commands will be accepted. Also required when reconnecting.

Request:

{"msgID":1, "method":"auth", "token":"XYZ"}

Answer:

{"msgID":1, "method":"auth", "token":"XYZ", "success": "true"}

• token` (required): DHD token

get

Query a node or value (single time)

note

Only use get command, if you want to redeem information once. We do not recommend polling for updates. Use subscribe method instead.

Request:

{"msgID":1, "method":"get", "path":"/audio/mixers/0/automix/1/"}

Answer:

{"msgID":1, "method":"get", "path":"/audio/mixers/0/automix/1/","payload":{"_active":true,"attmax":12,"attpassive":15,"hold":0,"ratio":1.5,"release":8.5},"success":true}

• path (required): the data path you are addressing
• payload (returned value only): the queried data. Can be object, array or single value, if queried.

set

Set one or multiple values Request (single value):

{"msgID":1, "method":"set", "path":"/audio/mixers/0/automix/1/attmax", "payload": 14}

Answer:

{"msgID":1, "method":"set", "path":"/audio/mixers/0/automix/1/attmax", "payload":14 ,"success":true}

Request (multiple values):

{"msgID":1, "method":"set", "path":"/audio/mixers/0/automix/1/attmax", "payload": {"attmax":12, "hold":20}}

Answer:

{"msgID":1, "method":"set", "path":"/audio/mixers/0/automix/1/", "payload":{"attmax":12, "hold":20} ,"success":true}

tip

You can only transmit the values you want to change within the same or multiple sub-objects of a path, as long as it replicates the given data structure correctly.

tip

If you set multiple values, of which some are incorrect, the correct ones will still be applied. Return will look like this:

{"method":"set","path":"/audio/mixers/0/automix/1/","payload":{"attmax":["error",{"code":-32602,"message":"invalid params"}],"hold":20},"success":false}

subscribe

To receive updates for changed values and avoid polling, use subscribe method.
Subscribe to a node (e.g. level detect 0):

{"msgID":1, "method":"subscribe", "path":"/audio/levels/0"}

Return (confirmation):

{"msgID":1, "method":"subscribe", "path":"/audio/levels/0", "success":true}

Notification on updated data:

{ "method": "update", "payload": { "audio": { "levels": { "0": { "_left": -14.2, "_right": -14.2 } } } } }

note

Updated data payload will always contain all changed data within the root data structure. If concurrent changes appear between two updates, they will both appear within the same update message.

unsubscribe

To stop receiving updates, use the unsubscribe command.
Unsubscribe from a node (e.g. level detect 0):

{"msgID":1, "method":"unsubscribe", "path":"/audio/levels/0"}

Return (confirmation):

{"msgID":1, "method":"unsubscribe", "path":"/audio/levels/0", "success":true}

---

Error handling

Control API is designed to be fault tolerant. If errors occur, the messages will be formatted the following way:

Failed authentication:

{"msgID":1, "method":"auth", "token":"XYZ", "success": "false", "error": {"code":-32002, "message": "invalid token"}}

Socket Timeout

Control API WebSocket connections time out after 60 seconds of inactivity. Any data transmission on the socket will reset that inactivity timer. We recommend sending a heartbeat, such as the WebSocket Pings and Pongs control frame at least every 30 seconds. The console will respond with the according pong. Read more on websocket pings and pongs here.