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.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | device name | NO | String | MQTT Device <serialNumber> |
2 | device type | NO | String | c8y_MQTTDevice |
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.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | unique child ID | YES | String | |
2 | device name | NO | String | MQTT Device <serialNumber> |
3 | device type | NO | String | c8y_MQTTChildDevice |
Example
101,uniqueChildId,myChildDevice,myChildType
Service creation (102)
Create a new software service for given device.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1 | service unique external id | YES | String |
2 | service type | YES | String |
3 | service name | YES | String |
4 | service status | YES | String |
Example
102,myDatabaseDevice,systemd,DatabaseService,up
Service status update (104)
Set a status for given software service.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1 | service status | YES | String |
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.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1… | fragmentName | YES | String |
Example
107,c8y_Position,c8y_Configuration
Configure Hardware (110)
Update the hardware properties of the device.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1 | serialNumber | NO | String |
2 | model | NO | String |
3 | revision | NO | String |
Example
110,1234567890,myModel,1.2.3
Configure Mobile (111)
Update the mobile properties of the device.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1 | imei | NO | String |
2 | iccid | NO | String |
3 | imsi | NO | String |
4 | mcc | NO | String |
5 | mnc | NO | String |
6 | lac | NO | String |
7 | cellId | NO | String |
Example
111,1234567890,,54353
Configure Position (112)
Update the position properties of the device.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1 | latitude | NO | Number |
2 | longitude | NO | Number |
3 | altitude | NO | Number |
4 | accuracy | NO | Integer |
Example
112,50.323423,6.423423
Set Configuration (113)
Update the configuration properties of the device.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1 | configuration | NO | String |
Example
113,"val1=1\nval2=2"
Set supported operations (114)
Set the supported operations of the device.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1… | List of supported operations | NO | String |
Example
114,c8y_Restart,c8y_Configuration,c8y_SoftwareList
114, c8y_Restart,c8y_Configuration
in order to remove c8y_SoftwareList
after the request from the example above.Set firmware (115)
Set the firmware installed on the device.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1 | name | NO | String |
2 | version | NO | String |
3 | url | NO | String |
Example
115,firmwareName,firmwareVersion,firmwareUrl
Set software list (116)
Set the list of software installed on the device.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1… | List of 3 values per software | NO | (n/a) |
1.1 | name | NO | String |
1.2 | version | NO | String |
1.3 | url | NO | String |
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.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1 | Required interval | NO | Integer |
Example
117,60
Set supported logs (118)
Set the supported logs of the device.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1… | List of supported logs | NO | String |
Example
118,ntcagent,dmesg,logread
Set supported configurations (119)
Set the supported configurations of the device.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1… | List of supported configurations | NO | String |
Example
119,modbus,system
Set currently installed configuration (120)
Set currently installed configuration of the device.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | Configuration type | YES | String | |
2 | Configuration file download URL | YES | String | |
3 | File name | NO | String | Configuration type |
4 | Date and time when the configuration was applied | NO | Date | Current date and time |
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.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | Profile executed | YES | String | |
2 | Profile ID | NO | String | Profile ID from the oldest EXECUTING device profile operation |
Example
121,true,8473
Set device agent information (122)
Allows a device to provide information about the agent running on it.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | Name of the agent | YES | String | |
2 | Version of the agent | YES | String | |
3 | The agent URL | NO | String | |
4 | Maintainer of the agent | YES | String |
Example
122,thin-edge.io,0.6,https://thin-edge.io,Cumulocity
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.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | Name of the software | YES | String | |
2 | Version of the software | YES | String | |
3 | Type of the software | NO | String | |
4 | URL of the software | NO | String |
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.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | Name of the software | YES | String | |
2 | Version of the software | YES | String | |
3 | Type of the software | NO | String | |
4 | URL of the software | NO | String |
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.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | Name of the software | YES | String | |
2 | Version of the software | YES | String |
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.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1… | List of supported software types | NO | String |
Example
143,yum,docker
Measurement templates (2xx)
Create custom measurement (200)
Create a measurement with a given fragment and series.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | fragment | YES | String | |
2 | series | YES | String | |
3 | value | YES | Number | |
4 | unit | NO | String | |
5 | time | NO | Date | Current server time |
Example
200,c8y_Temperature,T,25
Create a custom measurement with multiple fragments and series (201)
Create a measurement with multiple fragments and series.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | type | YES | String | |
2 | time | NO | Date | |
3 | List of 4 values per fragment-series combination | YES | (n/a) | |
3.1 | fragment | YES | String | |
3.2 | series | YES | String | |
3.3 | value | YES | Number | |
3.4 | unit | NO | String |
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
.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | rssi value | YES, if 2 not set | Number | |
2 | ber value | YES, if 1 not set | Number | |
3 | time | NO | Date | Current server time |
Example
210,-90,23,2016-06-22T17:03:14.000+02:00
Create temperature measurement (211)
Create a measurement of type c8y_TemperatureMeasurement
.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | temperature value | YES | Number | |
2 | time | NO | Date | Current server time |
Example
211,25,2016-06-22T17:03:14.000+02:00
Create battery measurement (212)
Create a measurement of type c8y_Battery
.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | battery value | YES | Number | |
2 | time | NO | Date | Current server time |
Example
212,95,2016-06-22T17:03:14.000+02:00
Alarm templates (3xx)
Create CRITICAL alarm (301)
Create a CRITICAL alarm.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | type | YES | String | |
2 | text | NO | String | Alarm of type alarmType raised |
3 | time | NO | Date | Current server time |
Example
301,c8y_TemperatureAlarm
Create MAJOR alarm (302)
Create a MAJOR alarm.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | type | YES | String | |
2 | text | NO | String | Alarm of type alarmType raised |
3 | time | NO | Date | Current server time |
Example
302,c8y_TemperatureAlarm,"This is an alarm"
Create MINOR alarm (303)
Create a MINOR alarm.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | type | YES | String | |
2 | text | NO | String | Alarm of type alarmType raised |
3 | time | NO | Date | Current server time |
Example
303,c8y_TemperatureAlarm
Create WARNING alarm (304)
Create a WARNING alarm.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | type | YES | String | |
2 | text | NO | String | Alarm of type alarmType raised |
3 | time | NO | Date | Current server time |
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.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1 | type | YES | String |
2 | severity | YES | String |
Example
305,c8y_TemperatureAlarm,CRITICAL
Clear existing alarm (306)
Clear an existing alarm.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1 | type | YES | String |
Example
306,c8y_TemperatureAlarm
Clear alarm’s fragment (307)
Remove one or more fragments from an alarm of a specific type.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1 | alarmType | YES | String |
2… | fragmentName | YES | String |
Example
307,c8y_TemperatureAlarm,c8y_Position,c8y_Configuration
Event templates (4xx)
Create basic event (400)
Create an event of given type and text.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | type | YES | String | |
2 | text | YES | String | |
3 | time | NO | Date | Current server time |
Example
400,c8y_MyEvent,"Something was triggered"
Create location update event (401)
Create typical location update event containing c8y_Position
.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | latitude | NO | Number | |
2 | longitude | NO | Number | |
3 | altitude | NO | Number | |
4 | accuracy | NO | Number | |
5 | time | NO | Date | Current server time |
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.
Position | Parameter | Mandatory | Type | Default value |
---|---|---|---|---|
1 | latitude | NO | Number | |
2 | longitude | NO | Number | |
3 | altitude | NO | Number | |
4 | accuracy | NO | Number | |
5 | time | NO | Date | Current server time |
Example
402,51.151977,6.95173,67
Clear event’s fragment (407)
Remove one or more fragments from an event of a specific type.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1 | eventType | YES | String |
2… | fragmentName | NO | String |
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.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1 | fragment | YES | String |
Example
501,c8y_Restart
Set operation to FAILED (502)
Set the oldest EXECUTING operation with given fragment to FAILED.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1 | fragment | YES | String |
2 | failureReason | NO | String |
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).
Position | Parameter | Mandatory | Type |
---|---|---|---|
1 | fragment | YES | String |
2… | parameters | NO | String |
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.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1 | operationId | YES | String |
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.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1 | operationId | YES | String |
2 | failureReason | NO | String |
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.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1 | operationId | YES | String |
2… | parameters | NO | String |
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.
Position | Parameter | Mandatory | Type |
---|---|---|---|
1 | fragment | NO | String |
2 | failureReason | NO | String |
Example
507,c8y_Restart,"Unexpected device restart"
Subscribe templates
Inventory templates (1xx)
Get children of device (106)
List all children of the device.
Position | Parameter | Type |
---|---|---|
1… | child | String |
Example
106,child1,child2,child3
Get the device managed object ID (124)
Retrieve the ID of the device managed object.
Position | Parameter | Type |
---|---|---|
1 | id | String |
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.
Position | Parameter | Type |
---|---|---|
1 | Command text | String |
Example
511,DeviceSerial,execute this
Configuration (513)
Set the configuration being sent in the operation.
Position | Parameter | Type |
---|---|---|
1 | configuration | String |
Example
513,DeviceSerial,"val1=1\nval2=2"
Firmware (515)
Install the firmware from the url.
Position | Parameter | Type |
---|---|---|
1 | firmware name | String |
2 | firmware version | String |
3 | url | String |
Example
515,DeviceSerial,myFirmware,1.0,http://www.my.url
Software list (516)
Install the software sent in the operation.
Position | Parameter | Type |
---|---|---|
1… | List of 3 values per software | (n/a) |
1.1 | name | String |
1.2 | version | String |
1.3 | url | String |
Example
516,DeviceSerial,softwareA,1.0,url1,softwareB,2.0,url2
Measurement request operation (517)
Send the measurements specified by the request name.
Position | Parameter | Type |
---|---|---|
1 | request name | String |
Example
517,DeviceSerial,LOGA
Relay (518)
Open or close the relay.
Position | Parameter | Type |
---|---|---|
1 | Relay state | String |
Example
518,DeviceSerial,OPEN
RelayArray (519)
Open or close the relays in the array.
Position | Parameter | Type |
---|---|---|
1… | List of relay state | String |
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.
Position | Parameter | Type |
---|---|---|
1 | url | String |
Example
521,DeviceSerial,http://www.my.url
Logfile request (522)
Upload a log file for the given parameters.
Position | Parameter | Type |
---|---|---|
1 | Log file name | String |
2 | Start date | Date |
3 | End date | Date |
4 | Search text | String |
5 | Maximum lines | Integer |
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.
Position | Parameter | Type |
---|---|---|
1 | mode | String |
Example
523,DeviceSerial,SMS
Download configuration file with type (524)
Download a configuration file from the URL with type.
Position | Parameter | Type |
---|---|---|
1 | URL | String |
2 | configuration type | String |
Example
524,DeviceSerial,http://www.my.url,type
Firmware from patch (525)
Install the firmware from the patch.
Position | Parameter | Type |
---|---|---|
1 | firmware name | String |
2 | firmware version | String |
3 | URL | String |
4 | dependency | String |
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.
Position | Parameter | Type |
---|---|---|
1 | configuration type | String |
Example
526,DeviceSerial,type
Set device profiles (527)
Set the device profiles
Position | Parameter | Type |
---|---|---|
1 | firmware marker | (n/a) |
1… | 5 values of firmware | (n/a) |
1.1 | firmware name | String |
1.2 | firmware version | String |
1.3 | firmware URL | String |
1.4 | firmware isPatch | String |
1.5 | firmware dependency | String |
2 | software marker | (n/a) |
2… | List of 4 values per software | (n/a) |
2.1 | software name | String |
2.2 | software version | String |
2.3 | software URL | String |
2.4 | software action | String |
3 | configuration marker | (n/a) |
3… | List of 2 values per configuration | (n/a) |
3.1 | configuration URL | String |
3.2 | configuration type | String |
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.
Position | Parameter | Type |
---|---|---|
1… | List of 4 values per software | (n/a) |
1.1 | name | String |
1.2 | version | String |
1.3 | URL | String |
1.4 | action | String |
Example
528,DeviceSerial,softwareA,1.0,url1,install,softwareB,2.0,url2,install
The action can either be install
or delete
.
When the install
action is received, the device agent ensures that the software will appear in the c8y_SoftwareList
fragment of the device after it has completed the installation.
The agent will also determine if there is a previous version of the software and replace it with the new version, resulting in an update.
When the delete
action is received, the device agent ensures that the software will no longer appear in the c8y_SoftwareList
fragment of the device after the software update operation has completed.
Update advanced software (529)
Update the software installed on the device.
Position | Parameter | Type |
---|---|---|
1… | List of 5 values per software | (n/a) |
1.1 | name | String |
1.2 | version | String |
1.3 | type | String |
1.4 | URL | String |
1.5 | action to be performed | String |
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.
Position | Parameter | Type |
---|---|---|
1 | hostname | String |
2 | port | Integer |
3 | connection key | String |
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.
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) |