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
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:
|
`e` | String |
The **event type** of the message:
|
`r` | String |
The **resource type** to which the message belongs:
|
`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.