Processing modes: Control whether data is persisted in Cumulocity database, transiently passed to real-time processing, processed using quiescent mode which ensures that real-time notifications are disabled or is processed using CEP mode that ensures data is transiently sent to real-time processing engine only with real-time notifications disabled.

Full bi-directional communication.

MQTT over WebSockets support.

TLS support.

Full horizontal scalability.

The MQTT section is structured as follows:

Hello MQTT provides an easy introduction to the Cumulocity MQTT protocol using a popular MQTT client.

Hello MQTT C provides an introduction on how to use the MQTT client in C with Cumulocity using pre-defined messages (called "static templates").

Hello MQTT C# provides an introduction on how to use the C# MQTT client with Cumulocity using pre-defined messages (called "static templates").

Hello MQTT Java provides an introduction on how to use the Java MQTT client with Cumulocity using pre-defined messages (called "static templates").

Hello MQTT Javascript provides an introduction on how to use the Javascript MQTT client with Cumulocity using pre-defined messages (called "static templates").

Hello MQTT Python provides an introduction on how to use the Python MQTT client with Cumulocity using pre-defined messages (called "static templates").

MQTT implementation gives a detailed reference of protocol-level aspects in the Cumulocity implementation of MQTT.

Device integration walks you through the process of interfacing devices with Cumulocity through MQTT.

MQTT static templates provides a reference of pre-defined payload formats that you can use straight away.

Handling IDs describes how IDs are handled in the Cumulocity MQTT protocol.

This section does not describe the basics of MQTT communication. If you are unfamiliar with MQTT, we recommend consulting one of the numerous introductions in the Internet. Some references can be found on the MQTT web site.

Info: For all MQTT connections to our platform, the maximum accepted payload size is 8092 bytes(8KB).

Hello MQTT

In this tutorial, you will learn how to use MQTT with Cumulocity using pre-defined messages (called "static templates").

Prerequisites

In order to follow this tutorial, check the following prerequisites:

You have a valid tenant, a user and a password in order to access Cumulocity.

Info: The screenshots in the tutorial use MQTTBox. Other tools may look slightly different.

Talking MQTT

Configuring the MQTT connection

To configure the MQTT connection, you need to pass the following connection parameters (see the screenshot below).

Hostname: For this example, use TCP and Port 1883. You also need to pass the URL to your tenant (e.g. mqtt.cumulocity.com).

Client ID: You can use the "Generate a random ID" button (most tools will offer such a button) or fill one in yourself. This ID will be linked to your device. To reconnect to the same device, use the same ID.

Username: You need to enter your tenant and username separated by a slash (tenant/username). You can use the same user that you use for logging into Cumulocity for this example.

Password: The password of the user.

The other configurations like "clean session" are not important for this example. You can change them to your needs. After clicking Save changes, you will see a screen similar to the following screenshot.

If there is a blue button on the top bar with a label "Not Connected", verify your configuration (especially username and password). If the button is green, you successfully established an MQTT connection to Cumulocity.

Sending data

All MQTT "publish messages" in this tutorial will be sent to the topic "s/us". This is the topic used for Cumulocity's pre-provided static templates.

Creating the device

The first message sent will create our device. Although the static templates support automatic device creation, in this example we will create the device manually. The template "100" will create a new device. It can be used with two optional parameters (deviceName, deviceType).

100,My first MQTT device,c8y_MQTTdevice

Afterwards, you will find this device in the Device Management application as a new device. If you switch to the "Identity" tab of the device you will notice that there was an identity created automatically to link the device to the MQTT ClientId.

Besides the name and the type, the device is empty so master data needs to be added.

You can use multiple static templates per publishing separated by a line break (one template per row). This feature is used to set the hardware and the required interval for the device in a single published message.

The hardware can be set with the template "110". It can take 3 parameters (serialNumber, model, revision). Optional parameters in static templates can be left empty if you don't want to set them. For the hardware all parameters are optional.

The required interval can be set with the template "117" and just takes a single parameter (the interval in minutes).

110,,MQTT test model,1.2.3117,10

After a reload of the "Info" page of your device in Device Management, you should see the information we just added.

Creating measurements

Now the device has some master data and we can start sending some measurements.
There are a couple of measurements that can be created directly by using a static template:

210: Signal strength measurement

211: Temperature measurement

212: Battery measurement

The temperature and battery measurement just take the value and time as parameters. For the signal strength, you can pass two values (RSSI and BER).

Passing timestamps in the Cumulocity MQTT implementation is always optional. If you don't pass them along, the server will automatically create a timestamp with the current server time.

We will make use of this feature in this example. Also, if you don't set the last parameters you do not need to enter the remaining commas.

210,-87211,24212,95

Besides the measurements above we can also use the template "200" to create a more custom measurement. It will take the measurement fragment, series, value, unit and time as its parameters.

200,myCustomTemperatureMeasurement,fahrenheit,75.2,F

After a reload in the Device Management application you should see 4 graphs with the newly added measurements in the "Measurements" tab of your device.

Creating alarms

In the next step, we want to create some alarms for this device. There are 4 templates to create alarms for the 4 alarm severities:

301: CRITICAL

302: MAJOR

303: MINOR

304: WARNING

Each of them note a type (which is mandatory), a text and a time (both optional).

301,gpio_critical,There is a GPIO alarm
304,simple_warning

The alarm list of your device should now contain one critical alarm and one warning.
Note that we did not set any text for the warning therefore it was created with a default alarm text.

With the next step, we want to clear the critical alarm again.
To achieve this we use the template "306" which refers to the type of the alarm that should be cleared.

306,gpio_critical

Afterward, the critical alarm should be cleared.
Note that you did not have to handle any alarm IDs with the MQTT implementation. Cumulocity will take over this part so that the device communication can be as easy as possible.

Creating events

Next, we want to create some location events for the device. You can use the link http://www.latlong.net/ to get the latitude and longitude for your city if you want.

The template "401" lets you create location events and takes latitude, longitude, altitude, accuracy and the time as parameters, but for now we will just use the first two.

401,51.227741,6.773456

In the Device Management application, you can see one event in the event list but the location has not been updated. This is because on REST these are different requests. Instead of the template "401" you can use the template "402" in MQTT. It works exactly the same as "401" but additionally it also updates the position of the device itself.

402,51.227741,6.773456

Now you should see both the "Location" and the "Tracking" tab in the device with the "Location" tab having the same latitude longitude as the last location event.

Receiving data

So far we have only used MQTT to send data from the client to the server. Now we want to send data from the server to the client.

To achieve that, we first need to subscribe to the responsible topic. We will do two subscriptions:

s/ds : This will subscribe to the static operation templates for the device

s/e : This will subscribe to an error topic that can be used for debugging

You can enter both topics after another in the "Subscribe" field and click Subscribe. The QoS selection does not matter for this example.

Afterward, your MQTTBox should look like this:

Receiving operations

At the current state the UI does not show any tabs for operations. Up to this point it was unknown what exactly the device supports. But the list of supported operations can be modified with the template "114". A list of supported operations can be added here.

We will add support for the configuration and shell.

114,c8y_Command,c8y_Configuration

After reloading the UI, the two new tabs will appear ("Configuration" and "Shell").

We can now create a shell command from the UI and click Execute.

In the MQTTBox you should now have received a new message for the s/ds subscription.

The "511" is indicating what kind of operation we received (in this case c8y_Command). This will be followed by the deviceIdentifier to locate the device with the dedicated operation. This is required if you have a hierarchy with multiple children. In that case, you need to know for which of the children the operation was dedicated. Finally, you have the operation specific parameters which in the case of c8y_Command is only the command text.

After receiving the operation we can start EXECUTING it to initiate the client's handling the operation. Similar to changing the status of an alarm you can add the type of operation to the template.

501,c8y_Command

After finishing the handling the operation can be set to successful with the template "503".

Besides the operation type, this operation can also take additional parameters based on what kind of operation it was. For the c8y_Command we can return a result.

503,c8y_Command,Everything went fine

Learning from errors

The topic s/e can help you debugging in case something went wrong.

If we for example try to send

999,I made this up

we can see a message on the topic because the template "999" is unknown.

40,999,No static template forthis message id

Hello MQTT C

In this tutorial, you will learn how to use MQTT client in C with Cumulocity using pre-defined messages (called "static templates").

Prerequisites

In order to follow this tutorial, check the following prerequisites:

You have a valid tenant, a user, and a password in order to access Cumulocity.

Verify that you have a gcc compiler installed:

gcc --version
gcc (Ubuntu 5.4.0-6ubuntu1~16.04.4) 5.4.020160609
Copyright (C) 2015 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Download, compile and install the MQTT C Paho Client. You will find more details about Paho on the Paho website.

Developing the "Hello, MQTT world!" client

To develop a very simple "Hello, world!" MQTT client for Cumulocity, you need to

create the application,

build and run the application.

Creating the application

Create a source file, for example "hello_mqtt.c" with the following content:

The Cumulocity MQTT protocol supports both unsecured TCP and secured SSL connections (e.g. tcp://mqtt.cumulocity.com:1883 or ssl://mqtt.cumulocity.com:8883), so as the "<<serverUrl>>" you can pick the one which fits for you.
When using SSL remember to configure MQTTClient_SSLOptions and set it in the MQTTClient_connectOptions.

What does the code in "main" do?

Configure an MQTT connection.

Register a on_message callback function which will print incoming messages.

Connect with Cumulocity via an MQTT protocol.

Create a new device with aC MQTT name and ac8y_MQTTDevice type.

Update the device hardware information by putting a S123456789 serial, a MQTT test model model and a Rev0.1 revision.

Subscribe to the static operation templates for the device - this will result in a on_message method call every time a new operation is created.

Send temperature measurement every 3 seconds.

What does the code in "publish" do?

Create a new MQTT message and set a payload.

Publish message via MQTT protocol.

Wait maximum 1 second for a message delivered ACK from the server.

Note that the subscription is established after the device creation, otherwise if there is no device for a given clientId the server will not accept it.

Building and running the application

After starting the application you should see a new device in the Device Management application in the device list.
Additionally, if there will be a new operation created for this device, (for example c8y_Restart) information about it will be printed to the console.

Improving the agent

Now that you have done your first step, check out the section Hello MQTT to learn more about Cumulocity MQTT and improve your application.

Hello MQTT Java

In this tutorial, you will learn how to use the Java MQTT client with Cumulocity using pre-defined messages (called "static templates").

Prerequisites

In order to follow this tutorial, check the following prerequisites:

You have a valid tenant, a user, and a password in order to access Cumulocity.

Cumulocity MQTT protocol supports both unsecured TCP and secured SSL connections (e.g. tcp://mqtt.cumulocity.com:1883 or ssl://mqtt.cumulocity.com:8883), so as the "<<serverUrl>>" you can pick the one which fits for you.

What does the code in "main" do?

Configure the MQTT connection.

Connect with Cumulocity via a MQTT protocol.

Create a new device with a My MQTT device name and a c8y_MQTTDevice type.

Update the device hardware information by putting a S123456789 serial, a MQTT test model model and a Rev0.1 revision.

Subscribe to the static operation templates for the device, print all received operations to the console and in case of a c8y_Restart operation simulate device restart.

Create a new thread which sends temperature measurement every 3 seconds.

Note that the subscription is established after the device creation, otherwise if there is no device for a given clientId the server will not accept it.

After starting the application you should see a new device in the Device Management application in the device list.
Additionally if there will be a new operation created for this device, (for example c8y_Restart) information about it will be printed to the console.

Improving the agent

Now that you have done your first step, check out the Section Hello MQTT to learn more about Cumulocity MQTT and improve your application.

Hello MQTT JavaScript

In this tutorial, you will learn how to use the JavaScript MQTT client with Cumulocity using pre-defined messages (called "static templates").

Prerequisites

In order to follow this tutorial, check the following prerequisites:

You have a valid tenant, a user, and a password in order to access Cumulocity.

Developing the "Hello, MQTT world!" client

To develop a very simple "Hello, world!" MQTT client for Cumulocity, you need to

create a JavaScript application,

run the application.

Creating a JavaScript application

Create an HTML file, for example "hello_mqtt_js.html" with the following content:

The Cumulocity MQTT protocol supports both unsecured TCP and also secured SSL connections (e.g. ws://mqtt.cumulocity.com/mqtt or wss://mqtt.cumulocity.com/mqtt), so as <<serverUrl>> select the one which fits for you.

What does the code do?

Configure the MQTT connection.

Register onMessageArrived a callback function which will print all incoming messages and in case of c8y_Restart operation it will simulate a device restart.

Register onMessageDelivered a callback function which will be called after a publish message has been delivered.

After the page is fully loaded, call init function which connects with Cumulocity via a MQTT protocol.

When the connection is established call a createDevice function.

Create a new device with a JS MQTT name and a c8y_MQTTDevice type.

Update the device hardware information by putting a S123456789 serial, a MQTT test model model and a Rev0.1 revision.

Subscribe to the static operation templates for the device - this will result in onMessageArrived method call every time a new operation is created.

Send temperature measurement every 3 seconds.

Note that subscription is established after the device creation, otherwise if there is no device for a given clientId the server will not accept it.

Running the application

Open "hello_mqtt_js.html" in a browser. You should see the new device in the Cumulocity application in the device list.

Additionally if there is a new operation created for this device (for example c8y_Restart), related information will be printed in the browser page.

Improving the agent

Now that you have done your first step, check out the section Hello MQTT to learn more about Cumulocity MQTT and improve your application.

Hello MQTT Python

In this tutorial, you will learn how to use the Python MQTT client with Cumulocity using pre-defined messages (called "static templates").

Prerequisites

In order to follow this tutorial, check the following prerequisites:

You have a valid tenant, a user, and a password in order to access Cumulocity.

Cumulocity MQTT protocol supports both unsecured TCP and secured SSL connections, so when configuring a port remember to use the correct one. No matter which connection type you choose your "<<serverHost>>" should stay the same (like mqtt.cumulocity.com).

The above example uses a TCP connection. If you would like to use an SSL connection, remember the proper configuration in the Paho MQTT client. Further information can be found in www.eclipse.org.

What does the script do?

Configure a MQTT connection.

Register an on_message callback function which will print incoming messages and in case of a c8y_Restart operation will simulate a device restart.

Register an on_publish callback function which will be called after a publish message has been delivered.

Connect with Cumulocity via the MQTT protocol.

Create a new device with a Python MQTT name and a c8y_MQTTDevice type.

Update the device hardware information by putting a S123456789 serial, a MQTT test model model and a Rev0.1 revision.

Subscribe to the static operation templates for the device - this will result in an on_message method call every time a new operation is created.

Call the sendMeasurements method which sends a temperature measurement every 3 seconds.

What does the publish message do?

Publish a given message about the given topic via MQTT.

When publishing the message it uses QoS 2. So to be sure that the message was delivered it will wait for server ACK (until the on_publish method is called with the matching message ID).

Note that the subscription is established after the device creation, otherwise if there is no device for a given clientId the server will not accept it.

Running the script

To run the script just call:

python hello_mqtt.py

After starting the application you should see a new device in the Device Management application in the device list.
Additionally if there will be a new operation created for this device, (for example c8y_Restart) information about it will be printed to the console.

In the console you should see following output:

Sending temperature measurement
...

Improving the agent

Now that you have done your first step, check out the section Hello MQTT to learn more about Cumulocity MQTT and improve your application.

MQTT implementation

This section will list the implementation details for the MQTT protocol. The Cumulocity implementation supports MQTT Version 3.1.1.

Connecting via MQTT

Cumulocity supports MQTT both via TCP and WebSockets. As URL you use "mqtt.cumulocity.com".

Available ports:

TCP

WebSockets

SSL

8883

443

no SSL

1883

80

Info: To use WebSockets you need to connect to the path "/mqtt" and follow the MQTT standard for WebSocket communication.

SmartREST Payload

The Cumulocity MQTT implementation uses SmartREST as a payload. SmartREST is a CSV-like message protocol that uses templates on the server side to create data in Cumulocity.

Info: For all MQTT connections to our platform the maximum accepted payload size is 8092 bytes.

SmartREST basics

A SmartREST message is a single row in which each parameter is separated by comma. The first parameter is an ID that defines the message. You can send multiple messages in a single publish by using a line break between messages.

SmartREST escaping

The following characters within a parameter need to be enclosed in double quotes:

Comma (,)

Line break (\n)

Carriage return (\r)

Double quotes (")

Additionally, each double quote within the parameter needs to be escaped with a backslash ().

The same escaping rules apply to messages that will be send from the server to the client.

Publish example:

100,"This value, needs escaping",This value doesnot need escaping

Subscribe example:

511,myDeviceSerial,"execute this\nand this\nand \"this\""

Device hierarchies

MQTT sessions are linked to a single device but this device can have a freely configurable device hierarchy below it.

All children require a unique ID defined when creating the device. We recommend using a combination of the unique ID of the root device and an unique ID within the hierarchy.

To create data for a child instead of the root device the unique ID of the child is added as another section in the topic (e.g. "s/us/myChildDeviceIdentifier").

The client will automatically receive operations for every child in the hierarchy by subscribing to the respective topic. It is not required to subscribe for each child.

Every operation received will contain the template ID followed by the ID of the device/child for which the operation was created (followed by other operation parameters).

MQTT features

MQTT authentication

MQTT supports setting a username and a password. To connect to Cumulocity the MQTT username needs to include both tenant and username in the format "tenant/username".

MQTT ClientId

The MQTT ClientId is a field to uniquely identify each connected client. The Cumulocity implementation also uses the ClientId to link the client directly to a device. Therefore the following format should be used for the ClientId:

"connectionType:deviceIdentifier:defaultTemplateIdentifier"

Field

Mandatory

Description

connectionType

NO

Indication of connection type default: d (device)

deviceIdentifier

YES

A unique identifier for your device e.g. IMEI, Serial number, ...

defaultTemplateIdentifier

NO

Check the SmartREST section for more information about template identifiers

For the simplest version of a client the MQTT clientId can just be the deviceIdentfier. It will automatically be interpreted as device connection.

Example ClientIds:

mySerialNumberd:mySerialNumberd:mySerialNumber:myDefaultTemplate

The uniqueness of the MQTT ClientId is determined only by the deviceIdentifier. Therefore from the above examples only one client can be connected at the same time.

MQTT Quality of Service

The Cumulocity implementation supports all 3 levels of MQTT QoS

QoS 0: At most once

QoS 1: At least once

QoS 2: Exactly once

For subscriptions to the operation or error topics, we will deliver all messages in the QoS which the client defined when subscribing to the topic.

MQTT clean session

MQTT clients can set the clean session flag to "0" (false). This will ensure that in case the client disconnects your subscription will still work and when you reconnect the client will receive the missed messages.

Info: Cumulocity requires clean session to be set to "1" (true). Currently we cannot guarantee that disabling clean session will work reliably, hence we recommend to always enable clean session.

MQTT retained flag

In the current Cumulocity implementation, subscriptions to topics where devices publish data are not allowed. Publishing data with the retained flag on this topic is allowed but has no practical difference to sending it without the flag.
Messages published by Cumulocity like operations and errors do not contain the retained flag.

MQTT last will

In MQTT, the "last will" is a message that is specified at connection time and that is executed when the client loses the connection. For example, using

400,c8y_ConnectionEvent,"Device connection was lost."

as last will message and "s/us" as last will topic raises an event whenever the device loses the connection.

The execution of the "last will" updates the device availability.

Debugging

To support developers during development you can subscribe to the topic s/e.
On this topic the device can retrieve debug and error messages that occur during a publish from the device.

Info: This topic is purely designed to support the development of clients. It is not recommended to always subscribe to this channel as the messages are verbose and can significantly increase the data usage. Also you should not use this topic to trigger actions of the device based on what you receive on the topic. It is not a response channel.

Device integration

Overview

The basic life cycle for integrating devices into Cumulocity is discussed in Interfacing devices.

In this section, we will show how this life cycle can be managed using the MQTT implementation.

The life cycle consists of two phases, a startup phase and a cycle phase.

The startup phase can be as short as just checking the credentials:

Step 0: Request device credentials, if they have not been requested yet.

The device starts publishing continuous empty messages on the topic s/ucr to notify the server that it is ready to retrieve credentials.

Next, you should accept the connection from the device in the Device Registration page.

When the device sends the next empty message it should receive credentials in the following format:

70,<tenant>,<username>,<password>

After receiving the credentials the device can close the MQTT connection and create a new one with the received credentials.

Step 1: Verify device

As MQTT supports an automatic device creation if the client sends data and there is no device present, this step is only required if you want to create the device manually.

The device creation can be achieved by the static template 100. This template can be blindly used on every boot of the device as it will only create the device if it is not already present.

The device will automatically be linked to the ID the client uses with its MQTT ClientId.

Info:The topic used for Cumulocity's pre-provided static templates is "s/us".

100,Device Name,Device Type

Step 2: Verify children

Like the root device also children of it are covered by the automatic device creation.

For handling this step manually you can send the static template 101 for creating a child device. The template will only create the child if it does not already exist.

101,Unique Child ID,Child Name,Child Type

Step 3: Subscribe topics

If the device supports operations it should subscribe to all required topics (static templates and SmartREST 2.0).

Cycle phase

Step A: Send CSV data

While the device holds an active MQTT connection it can publish either on the topics for static templates or on the topics for a SmartREST template to send data to the server.

Based on the MQTT ClientId the physical device is directly connected to the device object in Cumulocity. Therefore any data you send is automatically connected to the device.

To send data to a child device, publish the data to the topics described in Device hierarchies.

Step B: Receive CSV operations

By subscribing to a topic the device automatically tells Cumulocity that it wants to receive operations. Any operation created will be automatically parsed using either the static templates or the templates the device defined.

SmartREST 1.0

This section describes how you can use your existing SmartREST 1.0 templates with MQTT.

Note, that SmartREST 1.0 was designed for HTTP request/response and also does not support the ID-less communication with MQTT. It only uses the MQTT connection to send exactly the same request as you would send using HTTP and therefore comes with some limitations as MQTT is not request/response.

The support for SmartREST 1.0 was added to ease transition if you have an existing implementation using it.

If you start a new device integration we highly recommend to use SmartREST 2.0.

MQTT ClientId

Although you need to send the IDs in the body of each message with SmartREST 1.0, it is still important to connect with the correct MQTT ClientId.

The MQTT ClientId needs to match the externalId with type "c8y_Serial" of your device. It is used to assign the correct operations and responses.

Sending SmartREST 1.0

To send data to the server you can publish the same content as you would POST to the SmartREST endpoint /s.

The X-Id header is part of the topic the client needs to publish on.

Topic:

s/ul/<X-ID>;

Processing mode

Since Cumulocity SmartREST protocol supports TRANSIENT processing mode for avoiding storage of sent data in the database, publishing on MQTT t/ topic instead of s/ topic will only pass the data to real-time processing.

Cumulocity SmartREST protocol also supports CEP processing mode for ensuring data is only sent to the real-time event processing engine with real-time notifications disabled by publishing on MQTT c/ topic instead of s/ topic. Currently, the CEP processing mode is applicable for measurements and events only.

Topic:

c/ul/<X-ID>;

Receiving SmartREST 1.0

If a template triggers a response template the returning message will be published by the server on the following topic.

Topic:

s/dl/<X-ID>;

This topic can be subscribed by the client.

Receiving operations

SmartREST 1.0 via HTTP offers the /devicecontrol/notifications endpoint to listen to realtime operations. You can receive the same content on the following MQTT topic.

Topic:

s/ol/<X-ID>;

Limitations

MQTT currently does not support request/response. Therefore if you send a request on the publish topic and receive a response on the subscribe topic the client cannot securely match that they belong together.

You can counter this limitation by designing the templates in a way that you never need to know what request triggered the response and the client automatically knows it by the messageId.

SmartREST 2.0

Overview

This section describes the SmartREST 2.0 payload format that can be used with the Cumulocity MQTT implementation.

SmartREST 2.0 was designed to make use of the MQTT protocol and therefore can reduce the payload even more than the SmartREST 1.0 via HTTP.

SmartREST 2.0 is only available via MQTT.

SmartREST 2.0 offers the following MQTT topics for the main communication:

Supported templates

SmartREST 2.0 lets you create templates for the following matching HTTP methods:

API

GET

POST

PUT

Inventory

x

x

x

Alarm

x

x

Event

x

Measurement

x

Operation

x

Additionally, you can create templates to return certain values from responses and operations.

Template collections

A template collection is a set of request and response templates that specify a device communication protocol. Each collection is referenced by a unique ID (called X-Id).

Creating templates via MQTT

Like in SmartREST 1.0 you need to pass all templates in a collection in one message. After the creation of a template collection it can no longer be modified through MQTT.

When creating templates the client needs to publish to the following topic:

s/ut/<X-ID>

To verify if a template collection exists the client can subscribe to the topic:

s/dt

When subscribed the client can send an empty message to the creation topic which will trigger a new message about the creation status of this X-ID.

Example

Empty publish to s/ut/myExistingTemplateCollection

20,myExistingTemplateCollection,<ID of collection>

Empty publish to s/ut/myNotExistingTemplateCollection

41,myNotExistingTemplateCollection

Request templates

A request template contains the following basic fields:

Field

Data type

Possible values

Mandatory

Description

messageId

String

YES

Unique ID to reference the template within the collection

method

String

GETPUTPOST

YES

Whether to get, update or create data

api

String

INVENTORYMEASUREMENTALARMEVENTOPERATION

YES

Cumulocity API to be used

response

Boolean

truefalse

NO

Whether the request should trigger response templates. For GET templates by default true otherwise by default false

mandatoryValues

List<String>

YES

Values for the mandatory fields on the API. The values depend on the API and method the template uses

customValues

List<CustomValue>

NO

Custom values that should be added to the object

A request template lists all the fragments in the object structure (mandatory and custom) that should be added when creating or updating the data.
It can set fixed values in the template that will then be replaced by the server. If it does not set the value in the template the value needs to be included in the publish message (this includes mandatoryValues).

Example

We create a template to create a measurement like this (measurements have two mandatory values - type and time):

This template declares one additional custom property for the measurement. It leaves two fields empty in the template declaration (time and the custom property) so to use the template the client needs to send these two values

999,2016-06-22T17:03:14.000+02:00,25// We can also use server time by leaving the time empty999,,25

The following sections will get into more detail of how to create and use different templates.

GET templates

The GET templates for the inventory do not need any mandatory or custom values. Instead they use two different fields.

With SmartREST 2.0 you have the option to either get an object from inventory by its ID or by an externalId directly. Therefore instead of the fields mandatoryValues and customValues the following two fields are used:

Field

Data type

Possible values

Mandatory

Description

byId

boolean

truefalse

YES

Whether the GET should be executed by Cumulocity ID (=true) or externalId (=false)

The PUT templates for operations use the fragment of the operation to find the operation.
It will first check the EXECUTING operations and if there is no EXECUTING operation it will check the PENDING operations.

Response templates

The SmartREST 2.0 response templates use the same structure as in SmartREST 1.0.

Field

Data type

Mandatory

Description

messageId

String

YES

Unique ID to reference the template within the collection

base

String

NO

A JsonPath prefix that all patterns will use

condition

String

NO

A JsonPath that needs to exist in the object to use the pattern

pattern

List<String>

YES

A list of JsonPath that will be extracted from the object and returned to the device

Response will be used for every operation and for any request template that defines the response field with true.
In each case the server will try every registered response template so there might be multiple response lines for a single operation or request.

SmartREST 2.0 will always return a response template if the condition is true (or no condition was defined). Patterns that did not resolve will be returned as empty string.

You should make use of the condition field to control when response templates should be returned.

Using a default collection

Having the X-ID as part of the topic gives you the freedom to easily use multiple template collections but adds additional bytes for every message.
If the device anyways uses mostly (or completely) a single collection it makes sense to specify this collection as you default collection.
With a default collection specified the client can use special topics which don't require the X-ID and instead the server will use the X-ID previously specified. The topics are "s/ud" for publishing and "s/dd" for subscribing.

You can specify one X-ID within your MQTT ClientID (see MQTT implementation).
Your MQTT ClientID could look like this:

d:myDeviceSerial:myDefaultTemplateXID

Info: If you use a default X-ID in the ClientId you need to include the "d:" at the beginning to specify that the client is a device.

It is not required that the default template exists at the time of establishing the MQTT connection (it will be verified once the client uses it).

MQTT Static templates

Overview

To ease device integration Cumulocity already supports a number of static templates that can be used by any client without the need for creating own templates.

These templates focus on the most commonly used messages for device management purposes.

To use the templates listed below you need to publish the messages to the topic "s/us" ("t/us" for transient processing of published content, "q/us" for quiescent processing of published content or "c/us" for CEP processing of published content, see SmartREST > Processing mode in the Reference guide for further information.

To receive operations with the static templates you need to subscribe to the topic "s/ds".

Automatic device creation

The topic for static templates supports an automatic creation of devices. Whenever there is no child associated with your MQTT ClientID and you send data, Cumulocity will automatically create a device for the MQTT ClientID. If you want to create the device on your own your first message must be the device creation.
In this case Cumulocity will create the device from the template.

The automatic creation of devices is also supported for 1st level child devices.
For child devices on a deeper level you must use the template for creating a child device by sending it to the topic of the child device under which you want to place the new child.

Handling none mandatory parameters

If a parameter is not declared as mandatory the client can send an empty string in that place.

Example:

100,,myType

Tailing commas are not required. The two lines below result in the same message.

100,,
100

Publish templates

The following templates can be used to publish data on the topics "s/us" as well as "t/us". For more information about t/ topic for transient data processing, refer to SmartRest > Processing mode in the Reference guide.

Inventory templates (1xx)

Device creation (100)

Will create a new device for the serial number in the inventory if not yet existing. An externalId for the device with type âc8y_Serialâ and the device identifier of the MQTT clientId as value will be created

Position

Parameter

Mandatory

Default

1

device name

NO

MQTT Device <serialNumber>

2

device type

NO

c8y_MQTTDevice

Example

100,myDevice,myType

Child device creation (101)

Will create a new child device for the current device. The newly created object will be added as child device. Additionally an externaId for the child will be created with type “c8y_Serial” and the value a combination of the serial of the root device and the unique child ID.

Position

Parameter

Mandatory

Default

1

unique child ID

YES

2

device name

NO

MQTT Device <serialNumber>

3

device type

NO

c8y_MQTTChildDevice

Example

101,uniqueChildId,myChildDevice,myChildType

Get child devices (105)

Will trigger the sending of child devices of the device.

Example

105

Configure Hardware (110)

Will update the hardware properties of the device.

Position

Parameter

Mandatory

1

serialNumber

NO

2

model

NO

3

revision

NO

Example

110,1234567890,myModel,1.2.3

Configure Mobile (111)

Will update the mobile properties of the device.

Position

Parameter

Mandatory

1imei

NO

2

iccid

NO

3

imsi

NO

4

mcc

NO

5

mnc

NO

6

lac

NO

7

cellId

NO

Example

111,1234567890,,54353

Configure Position (112)

Will update the position properties of the device.

Position

Parameter

Mandatory

1

latitude

NO

2

longitude

NO

3

altitude

NO

4

accuracy

NO

Example

112,50.323423,6.423423

Set Configuration (113)

Will update the configuration properties of the device.

Position

Parameter

Mandatory

1

configuration

NO

Example

113,"val1=1\nval2=2"

Set supported operations (114)

Will set the supported operations of the device.

Position

Parameter

Mandatory

1...

List of supported operations

Example

114,c8y_Restart,c8y_Configuration,c8y_SoftwareList

Set firmware (115)

Will set the firmware installed on the device.

Position

Parameter

Mandatory

1

name

NO

2

version

NO

3

url

NO

Example

115,firmwareName,firmwareVersion,firmwareUrl

Set software list (116)

Will set the list of software installed on the device.

Position

Parameter

Mandatory

1...

List of 3 values per software

NO

1.1

name

NO

1.2

version

NO

1.3

url

NO

Example

116,software1,version1,url1,software2,,url2,software3,version3

Set required availability (117)

Will set the required interval for availability monitoring. It will only set the value if does not exist. Values entered e.g. through UI are not overwritten.

Position

Parameter

Mandatory

1

Required interval

NO

Example

117,60

Measurement templates (2xx)

Create custom measurement (200)

Will create a measurement with given fragment and series.

Position

Parameter

Mandatory

Default

1

fragment

YES

2

series

YES

3

value

YES

4

unit

NO

5

time

NO

Current server time

Example

200,c8y_Temperature,T,25

Create signal strength measurement (210)

Will create a measurement of type c8y_SignalStrength.

Position

Parameter

Mandatory

Default

1

rssi value

YES, if 2 not set

2

ber value

YES, if 1 not set

3

time

NO

Current server time

Example

210,-90,23,2016-06-22T17:03:14.000+02:00

Create temperature measurement (211)

Will create a measurement of type c8y_TemperatureMeasurement.

Position

Parameter

Mandatory

Default

1

temperature value

YES

2

time

NO

Current server time

Example

211,25,2016-06-22T17:03:14.000+02:00

Create battery measurement (212)

Will create a measurement of type c8y_Battery.

Position

Parameter

Mandatory

Default

1

battery value

YES

2

time

NO

Current server time

Example

212,95,2016-06-22T17:03:14.000+02:00

Alarm templates (3xx)

Create CRITICAL alarm (301)

Will create a CRITICAL alarm.

Position

Parameter

Mandatory

Default

1

type

YES

2

text

NO

Alarm of type <alarmType> raised

3

time

NO

Current server time

Example

301,c8y_TemperatureAlarm

Create MAJOR alarm (302)

Will create a MAJOR alarm.

Position

Parameter

Mandatory

Default

1

type

YES

2

text

NO

Alarm of type <alarmType> raised

3

time

NO

Current server time

Example

302,c8y_TemperatureAlarm,âThis is an alarmâ

Create MINOR alarm (303)

Will create a MINOR alarm.

Position

Parameter

Mandatory

Default

1

type

YES

2

text

NO

Alarm of type <alarmType> raised

3

time

NO

Current server time

Example

303,c8y_TemperatureAlarm

Create WARNING alarm (304)

Will create a WARNING alarm.

Position

Parameter

Mandatory

Default

1

type

YES

2

text

NO

Alarm of type <alarmType> raised

3

time

NO

Current server time

Example

304,c8y_TemperatureAlarm,,2013-06-22T17:03:14.000+02:00

Update severity of existing alarm (305)

Will change the severity of an existing alarm.

Position

Parameter

Mandatory

1

type

YES

2

severity

YES

Example

305,c8y_TemperatureAlarm,CRITICAL

Clear existing alarm (306)

Will clear an existing alarm.

Position

Parameter

Mandatory

1

type

YES

Example

306,c8y_TemperatureAlarm

Event templates (4xx)

Create basic event (400)

Will create an event of given type and text.

Position

Parameter

Mandatory

Default

1

type

YES

2

text

YES

3

time

NO

Current server time

Example

400,c8y_MyEvent,"Something was triggered"

Create location update event (401)

Will create typical location update event containing c8y_Position.

Position

Parameter

Mandatory

Default

1

latitude

NO

2

longitude

NO

3

altitude

NO

4

accuracy

NO

5

time

NO

Current server time

Example

401,51.151977,6.95173,67

Create location update event with device update (402)

Will create typical location update event containing c8y_Position. Additionally the device will be updated with the same c8y_Position fragment.

Position

Parameter

Mandatory

Default

1

latitude

NO

2

longitude

NO

3

altitude

NO

4

accuracy

NO

5

time

NO

Current server time

Example

402,51.151977,6.95173,67

Operation templates (5xx)

Get PENDING operations (500)

Will trigger the sending of all PENDING operations for the agent.

Example:

500

Set operation to EXECUTING (501)

Will set the oldest PENDING operation with given fragment to EXECUTING.

Position

Parameter

Mandatory

1

fragment

YES

Example

501,c8y_Restart

Set operation to FAILED (502)

Will set the oldest EXECUTING operation with given fragment to FAILED.

Position

Parameter

Mandatory

1

fragment

YES

2

failureReason

NO

Example

502,c8y_Restart,"Could not restart"

Set operation to SUCCESSFUL (503)

Will set the oldest EXECUTING operation with given fragment to SUCCESSFUL.
It enables the device to send additional parameters that trigger additional steps based on the type of operation send as fragment (see section Updating operations).

Position

Parameter

Mandatory

1

fragment

YES

2...

parameters

NO

Example

503,c8y_Restart

Subscribe templates

The client can receive the following templates when subscribing to "s/ds".

Inventory templates (1xx)

Get children of device (106)

Lists all children of the device.

Position

Parameter

1...

child

Example

106,child1,child2,child3

Operation templates (5xx)

All operation responses have the same base structure leading with the message ID followed by the ID of either the root device or a child which should handle the operation.

Restart (510)

Tells the device to restart.

Example

510,DeviceSerial

Command (511)

Tells the device to run the command send in the operation.

Position

Parameter

1

Command text

Example

511,DeviceSerial,execute this

Configuration (513)

Tells the device to set the configuration send in the operation.

Position

Parameter

1

configuration

Example

513,DeviceSerial,"val1=1\nval2=2"

Firmware (515)

Tells the device to install the firmware from the url.

Position

Parameter

1

firmware name

2

firmware version

3

url

Example

515,DeviceSerial,myFimrware,1.0,http://www.my.url

Software list (516)

Tells the device to install the software send in the operation.

Position

Parameter

1...

List of 3 values per software

1.1

name

1.2

version

1.3

url

Example

516,DeviceSerial,softwareA,1.0,url1,softwareB,2.0,url2

Measurement request operation (517)

Tells the device to send the measurements specified by the request name.

Communication mode (523)

Tells the device to change the communication mode.

Position

Parameter

1

mode

Example

523,DeviceSerial,SMS

Updating operations

When using the template to set an operation to state SUCCESSFUL it supports sending additional parameters to trigger additional calls on the server.
The table below shows the operations that support this feature and what will be done with the parameters.

Fragment

Parameters

Action triggered

c8y_Command

result

Result will be added to operation

c8y_RelayArray

relay states

Device object will be updated with the states

c8y_CommunicationMode

no parameter needed

Device object will be updated with the mode

c8y_LogfileRequest

file url

File url will be added to operation

c8y_DownloadConfigFile

(optional) timestamp

Device object will be updated with the ID of the configuration dump and the timestamp (or server time)

Handling IDs

Concept of ID-less communication

The MQTT implementation of Cumulocity is specifically designed for device communication and therefore tries to remove as much unnecessary logic from the client side.

Using the REST (or SmartREST) protocol requires to know the ID of every object, alarm and operation you want to update.

Therefore a client needs to keep state of these IDs. For example, if it creates an alarm it needs to know the ID of the alarm so it can clear it afterwards.
With the MQTT implementation we want to reduce the logic required on the device to do such actions and move the logic to the server.

Example 1: ID of the device

To update data in the device object via REST you need to know the ID of the device object. Also this ID is required for every other data that needs to be associated with the device e.g. the source in a measurement, alarm or event.

To remove the necessity of persisting the ID on the device, Cumulocity offers the identity API where you can link external IDs (e.g. a serial number) to the object so you can query the ID any time.

Therefore a typical device start looks like this:

With MQTT we automatically use the identity API with the MQTT clientId.
This removes the necessity to tell the ID to the device and because the client sends also the other data on this connection we can associate every measurement, alarm, event, ... with the correct device.

Example 2: ID of alarms

When a client creates an alarm using the REST API it needs to ensure that it gets the ID of the alarm that was generated by Cumulocity in return.

The client will need this ID to later update the alarm for example to status CLEARED if the alarm is not active anymore.

In Cumulocity, a device can only have a single alarm per type in status ACTIVE. If it creates another alarm with the same type it will get de-duplicated.

Therefore the MQTT implementation uses the type of an alarm as identifier. The client only needs to send which type of alarm has been resolved and the server will find the correct alarm object.

JSON via MQTT

This section describes the JSON payload format that can be used with the Cumulocity MQTT implementation.

Compared to SmartREST 2.0, which only works with fixed templates, JSON support for MQTT was designed to combine the payload flexibility of our REST API with the low protocol overhead of MQTT.

The SmartREST way should still be the preferred way if it is important to reduce your payload to the minimum (mobile traffic, low capability device).

Topic structure

The topic structure in JSON MQTT is quite similar to the REST endpoints. The main difference is in the additional action part which is included in the topic.

To publish messages:

<api>/<resource>/<action>/<id>

To publish messages in TRANSIENT mode:

t/<api>/<resource>/<action>/<id>

To publish messages in QUIESCENT mode:

q/<api>/<resource>/<action>/<id>

To publish messages in CEP mode:

c/<api>/<resource>/<action>/<id>

Refer to Processing mode for more information about transient, quiescent and CEP data processing.

Topic actions

The action in the topic corresponds to the HTTP methods combined with the content-type header.

The following actions are available:

create - corresponds to HTTP POST

createBulk - corresponds to HTTP POST with the content-type header value set to collection media type, for example application/vnd.com.nsn.cumulocity.measurementCollection+json;charset=UTF-8;ver=0.9

update - corresponds to HTTP PUT

delete - corresponds to HTTP DELETE

Supported endpoint

The current JSON MQTT implementation does not cover all SmartREST 2.0 operations, so for example the whole device bootstrap process has to be done using SmartREST 2.0.

If the operation is not supported a proper error message will be send to the error topic.

For all of the above endpoints you can use the same payload like in the REST API. The only difference is in the source field - in REST this field is mandatory while for JSON MQTT there is no need to set the device ID here.
The source device ID will automatically be resolved based on the MQTT client ID. This value will always be used, no matter if there already is something defined there.

Receiving operations

A notification client can subscribe to the devicecontrol/notifications topic to receive notifications of newly created operations. Initially upon subscription all operations which are not yet forwarded will be published.

Additionally, it contains an External ID so the client can identify for which child the operation is executed.