Communication Protocol
The communication protocol was designed to be simple to use, human readable, and easy to parse or serialize.
Last updated
Was this helpful?
The communication protocol was designed to be simple to use, human readable, and easy to parse or serialize.
Last updated
Was this helpful?
Using this protocol, your measuring device is able to communicate with our cloud via our gateway. All you need to do is send a simple message to our gateway. Our gateway takes care of everything else to establish and perform secure and reliable communication with the cloud. Once you have connected the measuring device to the gateway, you can send messages to the gateway via its interfaces as shown in the following protocol definition. To learn how to connect the gateway to your measuring device, see
An open source implementation of the communication protocol based on Arduino can be found on our .
The device status code can be used to transfer the status of the device to the cloud. The status code is applied to the entire device, thus the status of the device can be read via the app.
The app can also be used to define status codes messages for used status codes. This has the advantage that the messages can be adapted flexibly without modifying the code of the device. For more information see
Statuscode
Description
2x
Statuscodes starting with 2 are interpreted as everything is okay
4x
Statuscodes starting with 4 indicate some expected failures
5x
Statuscodes starting with 5 indicate errors
Status codes can be sent not only at the level of the entire device, they can also be sent for each item individually. This allows items to share individualized information about their current condition. The ItemNumber is the id of an item as it was created in a device template for the digital twin. For information about the device template and how to find out the ItemNumber of an item see
As before in the protocol description for Device Status Code, we recommend our default status code semantic.
The main use case is transmitting and receiving state to and from the cloud. This message can be used to change the value of an item. An item can be any sensor or actor of the measuring device. When sending an item state, you should also send an item status code, which indicates if there are any problems with the item or if anything is still working as expected.
As before in the protocol description for Device Status Code, we recommend our default status code semantic.
DataType
Description
INT
Sends integer values. Can also be used to send percentage values
DOUBLE
Sends floating point numbers
BOOLEAN
Sends true (1) or false (0). Can be used to turn something on and off
You can send log messages to the cloud. The log messages will then be stored and can be analyzed via the app with the help of our diagnostic tool.
We use a standard protocol level hierarchy to set the definition for the protocol message. This allows messages of different importance and significance to be separated from each other. This also allows sorting and filtering via the app. So it allows to search for logs of a certain level.
Level
Description
DEBUG
Information that is diagnostically helpful to track the flow of your device
INFO
Generally useful information that highlight the progress your device
WARN
Anything that can potentially cause issues on your device
ERROR
Any error which is fatal to the operation of your device
With an item log message, a message can be sent explicitly for exactly one item. This makes it easier to assign messages to specific areas of the measuring device.
As before in the protocol description for Log Message for Item, we use a lightweight log level hierarchy.
Your device can initiate a deep sleep for the gateway. For this, it sends a deep sleep message via serial with the sleep time in seconds. The gateway will then go into deep sleep for the requested time.
For incoming messages, your device must also receive the messages from the gateway. This allows your device to be remotely controlled via the app.
The digital twin of your device in the cloud always has a health state that indicates the current state in terms of connectivity. The health state of the digital twin indicates the state of the connectivity of your physical device.
Health State
Description
ONLINE
When any message is received in the cloud, independent of the message type, the health status is updated.
UNRESPONSIVE
The digital twin of your device is considered unresponsive, when message from the gateway are transmitted to the cloud but your device is not sending any message to the gateway. This means that there is a problem with the connectivity between your device and the gateway.
OFFLINE
The digital twin of your device is offline if no messages are received in the cloud at all.
When there are no status messages to send from your device to the cloud, PONG messages can be sent to keep the digital twin in an online health state. The timeout, i.e., the period after which a device is considered offline/unresponsive when no message is received, can be configured via the app, see
It is also possible, that the cloud pings your device (e.g., when a user wants to check or update the health state vie the app). In this case a ping message will be received. This ping message should be answered with a pong message as soon as possible. Otherwise the device will be considered unresponsive.