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.


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.


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: