Websocket

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

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