Notifications
Shelly components support two types of notifications through the methods NotifyStatus
and NotifyEvent
. The structure of the notification frames is described on the RPC Protocol page. More information about the notifications sent over each of the supported channels can found on this page.
Briefly:
- notifications cannot be received over HTTP;
- to start receiving notifications over websocket you have to send at least one request frame with a valid source (
src
); - to receive notifications over MQTT you have to subscribe to the topic
<shelly-id_>/events/rpc
.
NotifyStatus
This method notifies about change in the status of a component, and carries information about the changes which occurred. It is defined by:
method
: "NotifyStatus"params
:
Property | Type | Description |
---|---|---|
| number | Unix timestamp (in UTC) |
| object | With the same structure as the status object of the component. Some or all unchanged attributes of the status object may not be visible. |
The intended use of these notifications is to overlay the changes from NotifyStatus
over a known status. This should yield identical results to what would be returned by a fresh GetStatus
call.
Certain status keys will only exist in certain situations. When such keys disappear from the status payload, the NotifyStatus
payload which notifies about the change will include the key with a null
value.
Example 1:
Notify that a button has changed the output state of the switch with id=0.{
"src": "shellypro4pm-f008d1d8b8b8",
"dst": "user_1",
"method": "NotifyStatus",
"params": {
"ts": 1631186545.04,
"switch:0": {
"id": 0,
"output": true,
"source": "button"
}
}
}
Example 2:
Notify that this device has lost connection to the cloud.{
"src": "shellypro4pm-f008d1d8b8b8",
"dst": "user_1",
"method": "NotifyStatus",
"params": {
"ts": 1624348482.25,
"cloud": {
"connected": false
}
}
}
Example 3:
Notify that config for this device has changed.{
"src": "shellyplus1-a8032abe54dc",
"dst": "user_1",
"method": "NotifyStatus",
"params": {
"ts": 1655369046.4,
"sys": {
"cfg_rev": 19
}
}
}
NotifyFullStatus
Since version 0.11.0
This method has the same semantics as NotifyStatus
, but the payload contains the full status of all components.
method
: "NotifyFullStatus"params
:ts
: number, unix timestamp (in UTC)<component>
: JSON object, with the same structure as the status object of the component.
Example 1:
{
"src": "shellyplusht-f008d1d8b8b8",
"dst": "user_1",
"method": "NotifyFullStatus",
"params": {
"ts": 1631186545.04,
"ble": {},
"cloud": {
"connected": false
},
"mqtt": {
"connected": false
},
"sys": {
"mac": "F008D1E62338",
"restart_required": false,
"time": null,
"unixtime": null,
"uptime": 41,
"ram_size": 254948,
"ram_free": 146620,
"fs_size": 458752,
"fs_free": 229376,
"cfg_rev": 0,
"available_updates": {}
},
"wifi": {
"sta_ip": null,
"status": "disconnected",
"ssid": null,
"rssi": 0
},
"temperature:0": {
"id": 0,
"tC": 20.0,
"tF": 68.0
},
"humidity:0": {
"id": 0,
"rh": 50.0
},
"devicepower:0": {
"id": 0,
"battery": {
"V": 4.59,
"percent": 11
},
"external": {
"present": false
}
},
"ht_ui": {}
}
}
The notification is emitted:
- over outbound websocket RPC channel for all devices
- over outbound websocket, MQTT and outbound UDP channels on battery-operated (sleeping) devices.
NotifyEvent
This method notifies about an occurred event that is not reflected in the status of a component (e.g., pushed button, changed configuration, ...). It is defined by:
method
: "NotifyEvent"params
:Property Type Description ts
number
Unix timestamp (in UTC)
events
array of objects
Containing all the events occurred. Each JSON object describes an event and contains different attributes according to the type of the event
The following attributes are common for every JSON object present in the events
array:
Property | Type | Description |
---|---|---|
| number | Unix timestamp (in UTC) |
| string | Component key ( |
| number | Component |
| string | Event name |
Example 1:
Notify that a button single push event has occurred.{
"src": "shellypro4pm-f008d1d8b8b8",
"dst": "user_1",
"method": "NotifyEvent",
"params": {
"ts": 1631266595.44,
"events": [
{
"component": "input:0",
"id": 0,
"event": "single_push",
"ts": 1631266595.44
}
]
}
}
Common event notifications
The following notifications are common for all functional and system components.
- Configuration change
Example 1:
Notify that the configuration of input with id=0 has been changed.{
"src": "shellypro4pm-f008d1d8b8b8",
"dst": "user_1",
"method": "NotifyEvent",
"params": {
"ts": 1631266460.71,
"events": [
{
"component": "input:0",
"id": 0,
"event": "config_changed",
"restart_required": false,
"ts": 1631266460.71,
"cfg_rev": 18
}
]
}
}