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

FieldTypeDescription
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 only one of config, name, or state will be present per changed event.

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