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

Quick Setup Guide

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

✉️ Send ➡ Device Status Code

Protocol

S:D:Statuscode

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

Diagnostic Tool

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

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

Example

S:D:20

With this message you send the status code 20 to the cloud. This means that the entire device is working as expected and everything is ok. The S is used to inform the cloud that this is a status message. The D is used to inform the cloud that the status code applies to the entire device. Our gateway generates a timestamp for this message automatically.

1608104328:S:D:20

If you want to define your own timestamp for the message, you can prepend it to the message.

✉️ Send ➡ Item Status Code

Protocol

S:ItemNumber:Statuscode

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

Device Onboarding

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

Example

S:4:50

Use this message to send status code 50 to the cloud for the item with id 4. In this case it is set that the status of the given item is incorrect. This means that there is an error. The S is used to inform the cloud that this is a status message. Our gateway generates a timestamp for this message automatically.

1608104328:S:4:20

If you want to define your own timestamp for the message, you can prepend it to the message.

✉️ Send ➡ Item State + Item Status Code

Protocol

S:ItemNumber:Statuscode:DataType:Data

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

Example

S:1:20:INT:1337

With the data type INT you can transfer integer values for an item state. In this message the item with id 1 is set to 1337. In addition, the item status code 20 is transmitted to describe that everything is ok with the value and with the item. The S is used to inform the cloud that this is a status message.

S:4:20:INT:100

The data type INT can also be used to map a percentage scale. For this purpose, you can define the corresponding value range in your measuring device so that only values between 0 and 100 can be transmitted for this item. In the app, you can then flexibly set that a percentage scale is to be used for this item. In this example, the item with id 4 is set to 100%. Once again, the item status code 20 is transmitted to indicate that the item works fine.

S:5:50:DOUBLE:41.99

Floating point numbers can be sent with the DOUBLE data type. In this message, the value of the item with id 5 is set to 41.99. The item status code 50 is also appended to the status change. This means that this item is currently incorrect and therefore the value is probably also incorrect.

S:8:20:BOOLEAN:1

A BOOLEAN data type can be used for items that can have two states, e.g. on and off. This message sets the item with id 8 to true (1). At the same time the item status code is set to 20 which means that the item is working correctly.

1608104328:S:4:20:INT:1337

If you want to define your own timestamp for these messages, you can prepend it to the message. Otherwise the timestamp will be added automatically by the gateway.

✉️ Send ➡ Log Message for Device

Protocol

N:LOG:D:Level:Message

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.

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

Example

N:LOG:D:ERROR:An error has occurred

In this example, an ERROR LOG message is sent to the cloud that affects the entire device with the message An error has occurred. The N is used to inform the cloud that this is a notification message and the the D is used to inform that the log message applies to the entire device

1608104328:N:LOG:D:ERROR:An error has occurred

If you want to define your own timestamp for these messages, you can prepend it to the message. Otherwise the timestamp will be added automatically by the gateway.

✉️ Send ➡ Log Message for Item

Protocol

N:LOG:ItemNumber:Level:Message

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.

Example

N:LOG:3:INFO:Hello World

In this example, an INFO LOG message is sent to the cloud that affects only the item with the id 3 with the message Hello World. The N is used to inform the cloud that this is a notification message.

1608104328:N:LOG:3:INFO:Hello World

If you want to define your own timestamp for these messages, you can prepend it to the message. Otherwise the timestamp will be added automatically by the gateway

✉️ Send ➡ Deep Sleep

Protocol

N:DEEPSLEEP:TimeInSeconds

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.

Example

N:DEEPSLEEP:3600

This message sends a DEEPSLEEP notification to the gateway. It sends the gateway into a deep sleep mode for 3600 seconds. The N is used to inform that this is a notification message.

1608104328:N:DEEPSLEEP:3600

If you want to define your own timestamp for these messages, you can prepend it to the message. Otherwise the timestamp will be added automatically by the gateway.

✉️ Receive ⬅ Item State

Protocol

Timestamp:S:ItemNumber:Statuscode:DataType:Data

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

Protocol

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.

✉️ Send ➡ Pong

N: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

Device Configuration

✉️ Receive ⬅ Ping

Timestamp:N: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.