Websocket¶

The embedded Websocket server provides push notifications to applications which require real-time feedback from devices like lights, groups, switches, and sensors.

Since deCONZ version 2.04.40.

Websocket Configuration ¶

The Websocket server is started on an unused proxy friendly port which, depending on the system, is either 443, 8080, 8088, 20877, or any other unused random port.

The Websocket server can be configured to include all state or config attributes in the message, or only the changed attributes.

The Websocket used port and setting are listed in the configuration API endpoint:

GET /api/<apikey>/config

Parameters¶

None

Response¶

HTTP/1.1 200 OK

{
    ...
    "websocketnotifyall": true,
    "websocketport": 8088,
    ...
}

Possible errors¶

403 Forbidden

503 Service Unavailable

---

Open Connection ¶

How to establish a connection to a Websocket server depends on the underlying programming environment.

Javascript example¶

The following example demonstrates how to establish a connection with Javascript in a browser or NodeJS implementation.

const WebSocket = require('ws');

const host = '192.168.1.202';
const port = 8088;

const ws = new WebSocket('ws://' + host + ':' + port);

ws.onmessage = function(msg) {
    console.log(JSON.parse(msg.data));
}

---

Message Format ¶

Messages received over a Websocket connection contain data in JSON format.

Light state change example¶

{
    "e": "changed",
    "id": "1",
    "r": "lights",
    "state": {
        "bri": 1,
        "on": true,
        "x": 65279,
        "xy": [
            0.9961,
            0.9961
        ],
        "y": 65279
    },
    "t": "event",
    "uniqueid": "00:0b:57:ff:fe:9a:46:ab-01"
}

Note that x and y are included in the state for backwards compatibility. New apps should use xy instead.

Group state change example¶

{
    "e": "changed",
    "id": "1",
    "r": "groups",
    "state": {
        "all_on": true,
        "any_on": true
    },
    "t": "event"
}

Sensor button event example¶

{
    "e": "changed",
    "id": "5",
    "r": "sensors",
    "state": {
        "buttonevent": 2002,
        "lastupdated": "2019-03-15T20:16:30"
    },
    "t": "event",
    "uniqueid": "00:0d:6f:00:10:65:8a:6e-01-1000"
}

Sensor name change example¶

{
    "e": "changed",
    "id": "10",
    "name": "Pulse 2",
    "r": "sensors",
    "t": "event",
    "uniqueid": "00:0d:6f:00:10:65:8a:6e-01-1000"
}

Sensor added example¶

{
    "e": "added",
    "id": "10",
    "r": "sensors",
    "sensor": {
        "config": {
            "battery": null,
            "on": true,
            "reachable": true
        },
        "ep": 1,
        "etag": "7088b28f8a8a2c786e6e48d95c547fa4",
        "id": "10",
        "manufacturername": "icasa",
        "mode": 1,
        "modelid": "ICZB-KPD12",
        "name": "ICZB-KPD12 10",
        "state": {
            "buttonevent": null,
            "lastupdated": "none"
        },
        "type": "ZHASwitch",
        "uniqueid": "00:0d:6f:00:10:65:8a:6e-01-1000"
    },
    "t": "event",
    "uniqueid": "00:0d:6f:00:10:65:8a:6e-01-1000"
}

Scene Recall example¶

{
    "e": "scene-called",
    "gid": "0",
    "r": "scenes",
    "scid": "2",
    "t": "event"
}

Message fields¶

Field	Type	Description
t	String	The type of the message: event - the message holds an event.
e	String	The event type of the message: added - resource has been added; changed - resource attributes have changed; deleted - resource has been deleted. scene-called - a scene has been recalled.
r	String	The resource type to which the message belongs: groups - message relates to a group resource; lights - message relates to a light resource; scenes - message relates to a scene under a group resource; sensors - message relates to a sensor resource.
id	String	The id of the resource to which the message relates, e.g. 5 for /sensors/5. Not for scene-called events.
uniqueid	String	The uniqueid of the resource to which the message relates, e.g. 00:0d:6f:00:10:65:8a:6e-01-1000. Only for light and sensor resources.
gid	String	The group id of the resource to which the message relates. Only for scene-called events.
scid	String	The scene id of the resource to which the message relates. Only for scene-called events.
config	Map	Depending on the websocketnotifyall setting: a map containing all or only the changed config attributes of a sensor resource. Only for changed events.
name	String	The (new) name of a resource. Only for changed events.
state	Map	Depending on the websocketnotifyall setting: a map containing all or only the changed state attributes of a group, light, or sensor resource. Only for changed events.
group	Map	The full group resource. Only for added events of a group resource.
light	Map	The full light resource. Only for added events of a light resource.
sensor	Map	The full sensor resource. Only for added events of a sensor resource.

Note that one changed event can contain one or multiple config, name, or state attributes.

The Websocket functionality is still under development. Notably added and deleted notifications might not be issued under all circumstances.