MQTT Static templates

To ease device integration Cumulocity already supports a number of static templates that can be used by any client without the need to create your own templates. These templates focus on the most commonly used messages for device management purposes.

To use the templates listed below, you must 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. Refer to Processing mode for further information.

You must subscribe to the topic s/ds to receive operations with the static templates.

Templates quick reference

Click the commands below to see more information on the respective template. If a parameter is in square brackets, it is optional.

The client can receive the following templates when subscribing to 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 the one you want to place the new child.

Handling non-mandatory parameters

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

100,,myType

Tailing commas is 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. Refer to Processing mode for more information about the t/ topic for transient data processing.

Inventory templates (1xx)

Device creation (100)

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.

Example

100,myDevice,myType

Child device creation (101)

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.

Example

101,uniqueChildId,myChildDevice,myChildType

Service creation (102)

Create a new software service for given device.

Example

102,myDatabaseDevice,systemd,DatabaseService,up

Service status update (104)

Set a status for given software service.

Example

104,up

Get child devices (105)

Trigger the sending of child devices of the device.

Example

105

Clear device’s fragment (107)

Remove one or more fragments from a device.

Example

107,c8y_Position,c8y_Configuration

Configure Hardware (110)

Update the hardware properties of the device.

Example

110,1234567890,myModel,1.2.3

Configure Mobile (111)

Update the mobile properties of the device.

Example

111,1234567890,,54353

Configure Position (112)

Update the position properties of the device.

Example

112,50.323423,6.423423

Set Configuration (113)

Update the configuration properties of the device.

Example

113,"val1=1\nval2=2"

Set supported operations (114)

Set the supported operations of the device.

Example

114,c8y_Restart,c8y_Configuration,c8y_SoftwareList

Set firmware (115)

Set the firmware installed on the device.

Example

115,firmwareName,firmwareVersion,firmwareUrl

Set software list (116)

Set the list of software installed on the device.

Example

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

Set required availability (117)

Set the required interval for availability monitoring as an integer value representing minutes. For more information, see c8y_RequiredAvailability in Device availability. This will only set the value if it does not exist. Values entered, for example, through the UI, are not overwritten.

Example

117,60

Set supported logs (118)

Set the supported logs of the device.

Example

118,ntcagent,dmesg,logread

Set supported configurations (119)

Set the supported configurations of the device.

Example

119,modbus,system

Set currently installed configuration (120)

Set currently installed configuration of the device.

Example

120,myType,http://www.my.url,config.bin,2020-07-22T17:03:14.000+02:00

Set device profile that is being applied (121)

Set device profile that is being applied to the device.

Example

121,true,8473

Set device agent information (122)

Allows a device to provide information about the agent running on it.

Example

122,thin-edge.io,0.6,https://thin-edge.io,Software AG

Send heartbeat (125)

Sends a heartbeat from the device to update its availability status.

Example

125

Set advanced software list (140)

Sets the list of advanced software installed on the device. Any existing list will be overwritten.

Example

140,docker,3.2.1,systemd,https://www.docker.com/,nginx,1.6,container,https://www.nginx.com/

Get the device managed object ID (123)

Retrieve the ID of the device managed object.

Example

123

Append advanced software items (141)

Appends advanced software items to the list that exists for the device.

Example

141,docker,3.2.1,systemd,https://www.docker.com/,nginx,1.6,container,https://www.nginx.com/

Remove advanced software items (142)

Removes advanced software items from the list that exists for the device.

Example

142,docker,3.2.1,nginx,1.6

Set supported software types (143)

Set the supported software types of the device. Ignores empty elements. An empty list removes the c8y_SupportedSoftwareTypes fragment entirely.

Example

143,yum,docker

Measurement templates (2xx)

Create custom measurement (200)

Create a measurement with a given fragment and series.

Example

200,c8y_Temperature,T,25

Create a custom measurement with multiple fragments and series (201)

Create a measurement with multiple fragments and series.

Example

201,KamstrupA220Reading,2022-03-19T12:03:27.845Z,c8y_SinglePhaseEnergyMeasurement,A+:1,1234,kWh,c8y_SinglePhaseEnergyMeasurement,A-:1,2345,kWh,c8y_ThreePhaseEnergyMeasurement,A+:1,123,kWh,c8y_ThreePhaseEnergyMeasurement,A+:2,234,kWh,c8y_ThreePhaseEnergyMeasurement,A+:3,345,kWh

Create signal strength measurement (210)

Create a measurement of type c8y_SignalStrength.

Example

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

Create temperature measurement (211)

Create a measurement of type c8y_TemperatureMeasurement.

Example

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

Create battery measurement (212)

Create a measurement of type c8y_Battery.

Example

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

Alarm templates (3xx)

Create CRITICAL alarm (301)

Create a CRITICAL alarm.

Example

301,c8y_TemperatureAlarm

Create MAJOR alarm (302)

Create a MAJOR alarm.

Example

302,c8y_TemperatureAlarm,"This is an alarm"

Create MINOR alarm (303)

Create a MINOR alarm.

Example

303,c8y_TemperatureAlarm

Create WARNING alarm (304)

Create a WARNING alarm.

Example

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

Update severity of existing alarm (305)

Change the severity of an existing alarm.

Example

305,c8y_TemperatureAlarm,CRITICAL

Clear existing alarm (306)

Clear an existing alarm.

Example

306,c8y_TemperatureAlarm

Clear alarm’s fragment (307)

Remove one or more fragments from an alarm of a specific type.

Example

307,c8y_TemperatureAlarm,c8y_Position,c8y_Configuration

Event templates (4xx)

Create basic event (400)

Create an event of given type and text.

Example

400,c8y_MyEvent,"Something was triggered"

Create location update event (401)

Create typical location update event containing c8y_Position.

Example

401,51.151977,6.95173,67

Create location update event with device update (402)

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

Example

402,51.151977,6.95173,67

Clear event’s fragment (407)

Remove one or more fragments from an event of a specific type.

Example

407,c8y_MyEvent,c8y_Position,c8y_Configuration

Operation templates (5xx)

Get PENDING operations (500)

Trigger the sending of all PENDING operations for the agent.

Example

500

Set operation to EXECUTING (501)

Set the oldest PENDING operation with given fragment to EXECUTING.

Example

501,c8y_Restart

Set operation to FAILED (502)

Set the oldest EXECUTING operation with given fragment to FAILED.

Example

502,c8y_Restart,"Could not restart"

Set operation to SUCCESSFUL (503)

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 sent as fragment (see Section Updating operations).

Example

503,c8y_Restart

Set operation to EXECUTING (504)

Set the operation with the given ID to EXECUTING. The operation must exist and must have the requesting device as the source.

Example

504,123

Set operation to FAILED (505)

Set the operation with the given ID to FAILED. The operation must exist and must have the requesting device as the source.

Example

505,123,"Could not restart"

Set operation to SUCCESSFUL (506)

Set the operation with given ID to SUCCESSFUL. The operation must exist and must have the requesting device as the source.

This may let the device send additional parameters that trigger further steps based on the type of the operation, also see Updating operations.

Example

506,123

Set EXECUTING operations to FAILED (507)

Set EXECUTING operations with a given fragment to FAILED. If the fragment parameter is empty, all EXECUTING operations are set to FAILED.

Example

507,c8y_Restart,"Unexpected device restart"

Subscribe templates

Inventory templates (1xx)

Get children of device (106)

List all children of the device.

Example

106,child1,child2,child3

Get the device managed object ID (124)

Retrieve the ID of the device managed object.

Example

124,12345

Operation templates (5xx)

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

Restart (510)

Restart a device.

Example

510,DeviceSerial

Command (511)

Run the command being sent in the operation.

Example

511,DeviceSerial,execute this

Configuration (513)

Set the configuration being sent in the operation.

Example

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

Firmware (515)

Install the firmware from the url.

Example

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

Software list (516)

Install the software sent in the operation.

Example

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

Measurement request operation (517)

Send the measurements specified by the request name.

Example

517,DeviceSerial,LOGA

Relay (518)

Open or close the relay.

Example

518,DeviceSerial,OPEN

RelayArray (519)

Open or close the relays in the array.

Example

519,DeviceSerial,OPEN,CLOSE,CLOSE,OPEN

Upload configuration file (520)

Upload the current configuration to Cumulocity.

Example

520,DeviceSerial

Download configuration file (521)

Download a configuration file from the URL.

Example

521,DeviceSerial,http://www.my.url

Logfile request (522)

Upload a log file for the given parameters.

Example

522,DeviceSerial,logfileA,2013-06-22T17:03:14.000+02:00,2013-06-22T18:03:14.000+02:00,ERROR,1000

Communication mode (523)

Change the communication mode.

Example

523,DeviceSerial,SMS

Download configuration file with type (524)

Download a configuration file from the URL with type.

Example

524,DeviceSerial,http://www.my.url,type

Firmware from patch (525)

Install the firmware from the patch.

Example

525,DeviceSerial,firmwareName,1.0,http://www.my.url,dependency

Upload configuration file with type (526)

Configuration is uploaded from Cumulocity to the device with type.

Example

526,DeviceSerial,type

Set device profiles (527)

Set the device profiles

Example

527,DeviceSerial,$FW,firmwareName,1.0,http://www.my.url,true,dependency,$SW,softwareA,1.0,http://www.my.url1,action1,softwareB,2.0,http://www.my.url2,action2,$CONF,http://www.my.url1,type1,http://www.my.url2,type2

Update software (528)

Update the software installed on the device.

Example

528,DeviceSerial,softwareA,1.0,url1,install,softwareB,2.0,url2,install

Update advanced software (529)

Update the software installed on the device.

Example

529,DeviceSerial,softwareA,1.0,url1,install,softwareB,2.0,url2,install

Cloud Remote Access connect (530)

Establish tunneling by Remote Access device agent.

Example

530,DeviceSerial,10.0.0.67,22,eb5e9d13-1caa-486b-bdda-130ca0d87df8

Updating operations

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