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

since 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.