7. WebSocket
The WebSocket Connection allows the client to be notified of changes within the system. Each notification of the system results in an event with a unique type and content – each device/capability/product has a supported list of events.
Key features:
- Notify clients of changes within the system
How to initialize the WebSocket connection
The connection can be initialized by sending the following request with the request parameter token that needs the accessToken as a value.
wss://api.services-smarthome.de/API/1.1/events?token=<accessToken>
Heartbeat Mechanism
The API offers a heartbeat mechanism to support clients which cannot use the PING WebSocket protocol
(to detect disconnected sockets). The clients sends a predefined string, "{“hbeat”:”ping”}" and expects to read back "{“hbeat”:”pong”}". If no response is received the client should terminate the WebSocket and initiate a new connection.
Events
The Event entity contains all relevant information for signalling an event to the client. An event can be a well-defined system wide event like StateChanged, which can be related to any entity in the system. In addition, an event can be specific to one entity and only related to a certain type of the entity like the PushButtonSensor capability publishes a ButtonPressed event.
| Property / Attribute | Description | Type | Required |
|---|---|---|---|
| sequenceNumber | The event sequence number – the gateway keeps track and adds a sequence number to each event for the client to identify order and missing events. | integer | Yes |
| type | Specifies the type of the event. | string | Yes |
| desc | The full path to uniquely reference the event definition. | Link | Yes |
| namespace | The Product (context) that generated the event. | string | Yes |
| timestamp | Date and time when the event occurred in the system. | DateTime | Yes |
| source | Reference to the associated entity for the given event. | Link | Yes |
| properties | This container includes only properties, e.g. for the changed state properties. If there is other data than properties to be transported, the data container will be used. | Container-Property- | No |
| data | Data for the event, the data container can contain any type of entity dependent on the event type. For example, the DeviceFound events contains the entire Device entity rather than selected properties. | -object- | No |
Example Event
This is an example of a StateChanged event from the TemperatureSensor capability of a RadiatorSmartThermostat(RST2) that just measured a new temperature of 20.9°C.
{
"sequenceNumber": 80933,
"type": "StateChanged",
"desc": "/desc/device/RST2.RWE/1.0/capability/TemperatureSensor/event/StateChanged",
"namespace": "CosipDevices.RWE",
"timestamp": "2020-01-31T22:51:04.0249030Z",
"source": "/capability/cc294aa50acd4b638e593b9b89cffc7d",
"properties": {
"temperature": 20.9
}
}
More events can be found in the following sections: