Communication Protocol

The communication protocol was designed to be simple to use, human readable, and easy to parse or serialize.

How it works?

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

pageQuick Setup Guide

An open source implementation of the communication protocol based on Arduino can be found on our Github page.

✉️ Send ➡ Device Status Code


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

pageDiagnostic Tool




Statuscodes starting with 2 are interpreted as everything is okay


Statuscodes starting with 4 indicate some expected failures


Statuscodes starting with 5 indicate errors

You can define your own status codes but we recommend sticking to these semantics

✉️ Send ➡ Item Status Code


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

pageDevice Onboarding

As before in the protocol description for Device Status Code, we recommend our default status code semantic.

✉️ Send ➡ Item State + Item Status Code


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.




Sends integer values. Can also be used to send percentage values


Sends floating point numbers


Sends true (1) or false (0). Can be used to turn something on and off

✉️ Send ➡ Log Message for Device


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.

pageDiagnostic 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.




Information that is diagnostically helpful to track the flow of your device


Generally useful information that highlight the progress your device


Anything that can potentially cause issues on your device


Any error which is fatal to the operation of your device

✉️ Send ➡ Log Message for Item


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.

✉️ Send ➡ Deep Sleep


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.

✉️ Receive ⬅ Item State


For incoming messages, your device must also receive the messages from the gateway. This allows your device to be remotely controlled via the app.

✉️ Check Health State

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



When any message is received in the cloud, independent of the message type, the health status is updated.


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.


The digital twin of your device is offline if no messages are received in the cloud at all.

✉️ Send ➡ Pong


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

pageDevice Configuration

✉️ Receive ⬅ Ping


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.

Last updated