Device management library

Overview

The device management library defines the data structures that are used in Cumulocity IoT for device management activities like, for example, software management and configuration management. The data structures are expressed as fragments that can be used inside managed objects, operations and other resources. More information on the fragment concept can be found in the Cumulocity IoT domain model in the Concepts guide.

In the following section you will find descriptions of the most important functionalities of a device, its managed objects and all its corresponding fragments to them. We will explain the relationship between the Cumulocity IoT UI, the device object managed in our databases and what is being communicated to and from the device itself.

If you are interested in details on exposing the Cumulocity IoT´s functionalities through our Rest API, see the Cumulocity IoT OpenAPI Specification for further information.

Moreover, see SmartREST for more information on SmartREST and a complete list of all SmartREST templates mentioned throughout the following sections.

To start with device management, open the All devices tab in the Devices menu of the Device Management application. Click on a device in the list to open the device details of this particular device. You will see various tabs and particular information on each of them.

Info
For a detailed explanation of each tab and its related configuration via the UI, see also Device Management > Device details in the User guide.

Device details

This list can be manipulated through the device fragments, that means, which tabs are shown depends on the capability the device supports. This is mainly operated by one fragment called c8y_SupportedOperations. Based on what is put in the array of this fragment, functionality such as tabs, buttons, and so on are enabled. For example if the c8y_SupportedOperations fragment contains c8y_Firmware, the firmware tab will be visible in the Device details page and the device can manage firmware objects.

c8y_SupportedOperations fragments

The following fragments can be added to the c8y_SupportedOperations fragment:

Fragment Definition
c8y_Availability Holds information about the device's status and its availability
c8y_Command Allows the user to carry out interactive sessions with a device
c8y_Configuration Contains the complete configuration state of the device including all control characters
c8y_ConfigurationDump Permits managing binary configuration files of the device
c8y_DeviceProfile Enables device profile functionality for a device
c8y_DownloadConfigFile Permits the download of configuration files as binaries
c8y_Firmware Contains information about a device's firmware
c8y_Hardware Contains basic hardware information for a device, such as make and serial number
c8y_LogfileRequest Requests a device to send a log file and view the log file in the log viewer
c8y_Mobile Holds basic connectivity-related information, such as the equipment identifier of the modem (IMEI) in the device or the SIM card (for example ICCID)
c8y_Network Sends data to the Network tab in the Device Management application and displays the network information
c8y_Position Reports the geographical location of an asset in terms of latitude, longitude and altitude
c8y_Profile Announces the target profile
c8y_Restart Restarts a device
c8y_SendConfiguration Allows reloading a configuration through the user interface
c8y_SoftwareList Contains the entire list of software that is installed on the device
c8y_SoftwareUpdate Contains a list of software to be installed or uninstalled
c8y_UploadConfigFile Permits the upload of configuration files as binaries

General concepts

Announcing capabilities

Devices may announce their supported capabilities using the c8y_SupportedOperations fragment in their own managed object. The fragment itself is an array of strings. It may contain built-in operations with their meaning or custom operations for specific use cases, which are described in the following sections.

PUT /inventory/managedObjects/<deviceId>
{
    "c8y_SupportedOperations": [
        "c8y_Restart",
        "c8y_Network"
    ]
}
Field Data type Mandatory Details
c8y_SupportedOperations array Yes Array of strings of the supported operations

Some capabilities also introduce their own c8y_Supported<...> fragments with a similar concept. These fragments allow devices to announce the ability to handle certain types of log files or configuration.

SmartREST example

The 114 static template is available for devices to announce their supported operations:

114,c8y_Restart,c8y_Configuration,c8y_SoftwareList

Communicating current status

Devices are responsible for communicating their current status to Cumulocity IoT. The status is usually communicated in the device’s own managed object. Cumulocity IoT provide specific fragments for each capability. The device must update this data whenever it detects a change to its local state.

In practice this usually means that a device should publish its local state concerning all of its supported capabilities during startup, when requested to change its local state, and whenever any external change has been detected.

Operation handling

Operations are always created with status PENDING. Devices are responsible for moving operations along into different statuses in their lifecycle. Before beginning to process an operation the device agent must update its status to EXECUTING. After processing is completed the device must set the operation status to SUCCESSFUL or FAILED depending on the outcome.

SmartREST 2.0

Cumulocity IoT provides the static templates 501, 502, and 503 to manipulate the operation status. These templates take the operation type as input parameter and always update the oldest operation in the preceding status. It is not possible to target specific operations to update if there are multiple ones pending. For this reason we recommend you to handle all operations sequentially in the order they arrive at the device.

Error handling during operation processing

If any error occurs during the processing of an operation the device must set the operation status to FAILED and provide a failure reason as descriptive as possible. This includes any unexpected or expected error conditions that prevent the operation to be fully completed and as expected. Even if only one step in an operation with multiple distinct steps fails, the entire operation must be considered as FAILED.

It is up to the device and its use case whether it should roll back any local state changes that happened before the error occurred. If any change of state remains after an operation failed the device must communicate this changed state with Cumulocity IoT.

Idempotent cases

In cases where a device receives an operation that requests a state that is already present, it is up to the device how the operation should be handled. This may for example be the case when a device is requested to install a software package that is already present in the requested version. Typically there are three different ways of handling such cases in device agents: skip, execute, or fail. In case of the mentioned software package that is already installed the following options could be selected:

  1. Consider the package as already installed and skip its installation because the requested state is already present
  2. Execute the operation as normal including re-installing the package
  3. Fail the operation because the requested state may indicate that the command was created under false preconditions

The ideal option depends on the use case and the concrete operation. Regardless of which option is selected the device must ensure that its local state and the on communicated to Cumulocity IoT remains consistent.

Alarms

The Alarm tab is always shown for all devices. Its content is filled by alarm statuses reported by the device and other sources like analytics or smart rules. Devices raise alarms in Cumulocity IoT as they occur. Once the alarm status was resolved the device must also update the status of its created alarm to CLEARED.

Raising alarms

A device may raise an alarm at any time. Typically alarms are used to communicate problem statuses in the devices environment.

POST /alarm/alarms
{
   "source": {
       "id": "4801"
   },
   "type": "c8y_TemperatureAlarm",
   "text": "CPU temperature too high",
   "severity": "MAJOR",
   "time": "2021-10-07T12:00:00.000Z"
}
Field Data type Mandatory Details
source object Yes The ID of the device
type string Yes Type of the alarm
text string Yes Alarm text, describing the alarm status
severity string Yes Alarm severity
time string Yes Time of alarm occurrence

In addition to the required parameters above, the device may also include custom fragments with more details about the alarm status into the alarm.

SmartREST example

Cumulocity IoT provides several static SmartREST templates for basic alarm management for device. They can be found with message IDs between 301 and 304 for different severities:

302,c8y_TemperatureAlarm,"CPU temperature too high"

Clearing alarms

When a device detects that the local alarm status was resolved it must clear the alarm. This is done by updating the alarm status to CLEARED.

PUT /alarm/alarms/<alarmId>
{
   "status": "CLEARED"
}
Field Data type Mandatory Details
status string Yes The new alarm status

SmartREST example

The 306 static template is provided to clear an active alarm of a specified type:

306,c8y_TemperatureAlarm

Critical alarms

When a device raises an alarm with the severity CRITICAL, the device is considered unavailable for the duration this alarm stays active. The aggregated availability overview in the Service monitoring tab will reflect this time as offline.

Devices should use the severity “CRITICAL alarm” only for alarm statuses that impact the device’s ability to fulfill its use case.

Child devices

The Child Devices tab shows a list of all child devices. It will be available only if the device has any child devices assigned to it.

Assign child device to parent device

In order to link a device the parent device must post to its inventory API the following request containing the ID of the child device.

POST /inventory/managedObjects/<deviceId>/childDevices
{
   "managedObject": {
      "id": "28067400"
   }
}
Field DataType Mandatory Details
managedObject.id string Yes ID of the child device to link

SmartREST example

To add a child device to an existing device you must connect the connected device and call the child create template:

101,uniqueChildId,myChildDevice,myChildType

Operating a gateway for child devices

Using the agent marker fragment com_cumulocity_model_Agent on the parent device but not on child devices effectively declares the device as a connected gateway for its children. The children are not directly connected to Cumulocity IoT but send and receive data through the device and its integration.

In this case operations for the child devices are delivered to the connected parent device. The parent device then must determine the addressed child device based on the included device ID or other information. Then the command must be forwarded to the correct child.

The built-in static SmartREST response templates of Cumulocity IoT always include a device identifier as first parameter to determine the targeted child device. Here is an example of the 510 static response template for the c8y_Restart operation with the device identifier highlighted.

510,DeviceSerial

Custom response templates also contain the targeted device’s external ID as first parameter. We recommend you to implement a similar mechanism there as well.

Configuration

The Configuration tab allows three different formats for device configuration:

They all follow a similar concept where the device may upload its current configuration to the platform and users may install a new configuration on the device. This tab appears for devices when they announce support for any of the available formats.

Text-based configuration

The most basic form of configuration is a simple text-based configuration. Here the configuration is stored and transferred directly as string. We recommend you to use this form for small human readable configuration files only, for example, for microcontroller-based devices.

The current configuration state of the device is communicated with the c8y_Configuration fragment in the device’s own managed object. It contains the complete configuration including all control characters as a string. Special care must be taken that encoding is performed properly. Cumulocity IoT supports UTF-8 characters, additionally escaping according to the JSON specification for JSON payloads, or the SmartREST specification for SmartREST payloads may be required.

We recommend you to upload the current configuration only on demand to save transfer data volume and device resources. There are specific operations designed to trigger a device to upload its current configuration to the platform documented below.

PUT /inventory/managedObjects/<deviceId>
{
   "c8y_Configuration": {
       "config": "c8y.url.http=https://management.cumulocity.com\nc8y.url.mqtt=mqtt.cumulocity.com\n"
   }
}
Name Type Mandatory Description
config string No Complete configuration text to be applied by the device

Upload current text configuration

For devices that include c8y_SendConfiguration in their c8y_SupportedOperations the Configuration tab offers a button to trigger a configuration upload from the device to Cumulocity IoT. When the button is clicked a c8y_SendConfiguration is created.

{
   "c8y_SendConfiguration": {}
}
Name Type Mandatory Description
c8y_SendConfiguration object Yes Send configuration marker object designating the operation as a command to trigger the device to upload its configuration

The device is expected to perform the following actions:

  1. Set operation status to EXECUTING
  2. Upload the current configuration to its own managed object using the c8y_Configuration fragment
  3. Set operation status to SUCCESSFUL

SmartREST example

There is no built-in static response template available for the c8y_SendConfiguration operation. Devices must create a custom template to implement this capability. Here is an example how such a template and its use could work.

Template creation:
11,100,,c8y_SendConfiguration,deviceId

Receiving the operation:

  1. Receive the c8y_SendConfiguration operation using the custom template created above
    100,DeviceSerial,4801
  2. Set operation status to EXECUTING 501,c8y_SendConfiguration
  3. Upload the current configuration state using the 113 static template 113,"c8y.url.http=https://management.cumulocity.com\nc8y.url.mqtt=mqtt.cumulocity.com\n"
  4. Set operation status to SUCCESSFUL 503,c8y_SendConfiguration

Install text configuration

Devices that support installing configuration can communicate this by adding c8y_Configuration to their c8y_SupportedOperations. Then the Configuration tab will offer a button to send a user configured configuration to the device. This action consequently creates a c8y_Configuration operation with the same fragment signature as found in the device’s managed object.

The device is expected to perform the following actions:

  1. Set operation status to EXECUTING
  2. Install and apply configuration as included in the nested config property with the c8y_Configuration fragment
  3. Update the c8y_Configuration fragment in the device’s managed object
  4. Set operation status to SUCCESSFUL

SmartREST example

The 513 static response template is available to receive c8y_Configuration operations:

  1. Receive c8y_Configuration operation
    511,DeviceSerial,"c8y.url.http=https://management.cumulocity.com\nc8y.url.mqtt=mqtt.cumulocity.com\n"
  2. Set operation status to EXECUTING
    501,c8y_Configuration
  3. Install and apply configuration as included
  4. Update the c8y_Configuration fragment
    113,"c8y.url.http=https://management.cumulocity.com\nc8y.url.mqtt=mqtt.cumulocity.com\n"
  5. Set operation status to SUCCESSFUL
    503,c8y_Configuration

Legacy file-based configuration

Devices that want to manage configuration as files can achieve a basic form using legacy file-based configuration. For new device integrations we recommend you to implement typed file-based configuration instead because it is more versatile.

This approach stores and transfers configuration as binary files.

Upload current legacy configuration

Devices may signal their support for uploading their current configuration to Cumulocity IoT by adding c8y_UploadConfigFile to their c8y_SupportedOperations. This enables a Get snapshot from device button in the Configuration tab. Clicking it generates a c8y_UploadConfigFile operation for the device.

{
   "c8y_UploadConfigFile": {}
}
Name Type Mandatory Description
c8y_ UploadConfigFile object Yes Upload configuration file marker object designating the operation as a command to trigger the device to upload its configuration file

When uploading its configuration, the device must first upload the configuration file into Cumulocity IoT inventory binaries, and then create a configuration repository entry as a managed object of type c8y_ConfigurationDump in the inventory. This object must then contain a link to the just uploaded file. We recommend you to create this entry with an easily recognizable name and description that allows users to find the desired configuration in the repository.

POST /inventory/managedObjects
{
   "name": "myDevice configuration",
   "description": "Uploaded by myDevice on 2021-09-15T12:00:00+0200",
   "url": "https://demos.cumulocity.com/inventory/binaries/154702",
   "type": "c8y_ConfigurationDump"
}
Name Type Mandatory Description
name string Yes Name of the configuration
description string No Description of the configuration
url string Yes URL where the configuration file was uploaded to
type string Yes Type of the configuration repository entry object; must always be “c8y_ConfigurationDump”

The device is expected to perform the following actions:

  1. Set operation status to EXECUTING
  2. Upload the configuration file into Cumulocity IoT inventory binaries
  3. Create a configuration repository entry
  4. Set the operation status to SUCCESSFUL

SmartREST example

The 520 static response template is available for this functionality:

  1. Receive c8y_UploadConfigFile operation
    520,DeviceSerial
  2. Set operation status to EXECUTING
    501,c8y_UploadConfigFile
  3. Upload configuration to inventory binaries API using REST
  4. Create configuration repository entry in inventory using REST
  5. Set operation status to SUCCESSFUL
    503,c8y_UploadConfigFile

Install legacy configuration

Devices that are capable of installing configuration remotely can announce this by adding c8y_DownloadConfigFile to their c8y_SupportedOperations. Then the Configuration tab offers a Send configuration to device button. When clicked, a c8y_DownloadConfigFile operation is created for the device.

{
   "c8y_DownloadConfigFile": {
       "url": "https://demos.cumulocity.com/inventory/binaries/9100",
       "c8y_ConfigurationDump": {
           "id": "9200"
       }
   }
}
Name Type Mandatory Description
url string Yes URL where the configuration file should be obtained from
c8y_ConfigurationDump object Yes Configuration dump reference object containing the ID of the configuration repository entry object

After downloading the configuration from the specified URL and installing it, the device must reference its currently installed configuration in its own managed object. This is done by transferring the nested c8y_ConfigurationDump fragment entirely into the device’s own managed object.

PUT /inventory/managedObjects/<deviceId>
{
   "c8y_ConfigurationDump": {
       "id": "9200"
   }
}
Name Type Mandatory Description
id string Yes ID of the referenced configuration object

The device is expected to perform the following actions:

  1. Set operation status to EXECUTING
  2. Download the configuration file from the specified URL
  3. Install the configuration file
  4. Update the currently installed configuration dump in the device’s managed object
  5. Set the operation status to SUCCESSFUL

SmartREST example

The 521 static response template is available for this functionality:

  1. Receive c8y_DownloadConfigFile operation
    521,DeviceSerial,https://demos.cumulocity.com/inventory/binaries/9100
  2. Set operation status to EXECUTING
    501,c8y_DownloadConfigFile
  3. Download configuration from the URL specified
  4. Install the configuration file
  5. Set operation status to SUCCESSFUL and set the currently installed c8y_ConfigurationDump fragment implicitly
    503,c8y_DownloadConfigFile

Typed file-based configuration

The most versatile way of managing device configuration is typed file-based configuration. Here a device can manage multiple configuration files at the same time. Typed file configuration is activated for a device by adding the c8y_SupportedConfiguration fragment to the device’s own managed object.

PUT /inventory/managedObjects/<deviceId>
{
   "c8y_SupportedConfigurations": [
       "agent_conf",
       "ssh_conf"
   ]
}
Name Type Mandatory Description
c8y_SupportedConfigurations array Yes Array of strings of the supported configuration for this device

Cumulocity IoT does not validate or further process configuration types. From a platform perspective they are simple strings. Associating these type strings to configuration files is responsibility of the device agent.

SmartREST example

The c8y_SupportedConfiguration fragment can be uploaded using the static template 119:
119,agent_conf,ssh_conf

Upload current configuration file

Similarly to legacy configuration, uploading typed configuration is announced by adding the c8y_UploadConfigFile to the c8y_SupportedOperations. In this case clickinging the button creates a very similar c8y_UploadConfigFile operation with the targeted configuration type as additional parameter.

{
   "c8y_UploadConfigFile": {
       "type": "agent_conf"
   }
}
Name Type Mandatory Description
type string Yes Type of the configuration to upload

Then the device must create an event with the type equal to the configuration type. Cumulocity IoT uses events here instead of the inventory like in legacy file-based config because events are automatically associated to the device and old events (and their binary attachments) included can be automatically cleaned up using retention rules.

POST /event/events
{
   "source": {
       "id": "4801"
   },
   "type": "agent_conf",
   "time": "2021-09-15T15:57:41.311Z",
   "text": "agent_conf upload requested"
}
Name Type Mandatory Description
source object Yes ID of the device object
type string Yes Type of the configuration uploaded
time string Yes ISO datetime when the configuration was uploaded
text string Yes Label text for the configuration

In order to attach the configuration file to the just uploaded event, the Event binaries API should be used. The file is attached using a multipart/form-data request.

POST /event/events/<eventId>/binaries

Host: https://<TENANT_DOMAIN>
Authorization: <AUTHORIZATION>
Accept: application/json
Content-Type: multipart/form-data;boundary="boundary"

--boundary
Content-Disposition: form-data; name="object"

{ "name": "agent.conf", "type": "text/plain" }
--boundary
Content-Disposition: form-data; name="file"; filename="agent.conf"
Content-Type: text/plain

c8y.url.http=https://management.cumulocity.com
c8y.url.mqtt=mqtt.cumulocity.com
--boundary--

The device is expected to perform the following actions:

  1. Set operation status to EXECUTING
  2. Create a configuration type event
  3. Attach the configuration file to the event
  4. Set the operation status to SUCCESSFUL

SmartREST example

Cumulocity IoT provides the 526 static SmartREST template for typed c8y_UploadConfigFile operations:

  1. Receive typed c8y_UploadConfigFile operation
    526,DeviceSerial,agent_conf
  2. Set operation status to EXECUTING
    501,c8y_UploadConfigFile
  3. Create a config type event using REST API
  4. Attach the targeted config file to the event using REST API
  5. Set operation status to SUCCESSFUL
    503,c8y_UploadConfigFile

Install configuration file

Installing typed configuration also works very similarly to the legacy configuration. Adding the c8y_DownloadConfigFile to the device’s c8y_SupportedOperations controls the availability of the Send configuration to device button. When it is clicked a c8y_DownloadConfigFile operation with the configuration type included is created.

{
   "c8y_DownloadConfigFile": {
       "type": "agent_conf",
       "url": "https://demos.cumulocity.com/inventory/binaries/156719"
   }
}
Name Type Mandatory Description
type string Yes Type of the configuration to apply
url string Yes URL where the configuration file should be obtained from

When the device has downloaded and installed the configuration it must update the currently installed configuration of this specific type in its own managed object. This is done by adding the c8y_Configuration_<config type> fragment to the device’s own managed object.

PUT /inventory/managedObjects/<deviceId>
{
   "c8y_Configuration_agent_conf": {
       "name": "agent_conf",
       "time": "2021-09-15T15:47:13.721Z",
       "type": "agent_conf",
       "url": "https://demos.cumulocity.com/inventory/binaries/156719"
   }
}
Name Type Mandatory Description
c8y_Configuration_agent_conf object Yes Fragment name with prefix "c8y_Configuration_" followed by the configuration type containing details of the currently installed configuration of that particular type
name string Yes Optional name of the installed configuration file
time string Yes ISO datetime indicating when the configuration was applied
type string Yes Type of the configuration
url string Yes URL where the configuration was obtained from

The device is expected to perform the following actions:

  1. Set operation status to EXECUTING
  2. Download configuration file from the included URL
  3. Install the configuration file
  4. Update the device’s currently installed configuration with the typed configuration fragment in the device’s own managed object
  5. Set the operation status to SUCCESSFUL

SmartREST example

The 524 static SmartREST response template is available for typed c8y_DownloadConfigFile operations, and the 120 static template is prepared for uploading the current configuration:

  1. Receive typed c8y_UploadConfigFile operation
    524,DeviceSerial,https://demos.cumulocity.com/inventory/binaries/156719,agent_conf
  2. Set operation status to EXECUTING
    501,c8y_DownloadConfigFile
  3. Download configuration from the included URL
  4. Install the configuration as the targeted configuration type
  5. Set the currently installed configuration
    120,agent_conf,https://demos.cumulocity.com/inventory/binaries/156719,agent_conf.txt,2021-09-15T15:47:13.721Z
  6. Set operation status to SUCCESSFUL
    503,c8y_DownloadConfigFile

Connectivity

The Connectivity tab integrates with a 3rd party SIM management platform to provide SIM management functionality within Cumulocity IoT Device Management. The tab appears for a device when all of the following criteria are met:

  1. Connectivity microservice is subscribed and configured
  2. The device managed object contains the c8y_Mobile fragment with the MSISDN or ICCID property set
  3. The SIM referenced by the device is managed by the SIM management provider configured for the tenant
PUT /inventory/managedObjects/<deviceId>
{
   "c8y_Mobile": {
       "msisdn": "380561234567",
       "iccid": "89100423481F445593U"
   }
}
Name Type Mandatory Description
msisdn string No MSISDN of the installed SIM
iccid string No ICCID of the installed SIM

Depending on the configured connectivity provider either MSISDN or ICCID may be used to identify the SIM present in the device. We recommend you to always include both into the c8y_Mobile fragment. There are many more mobile connection related properties that may also be attached to the c8y_Mobile fragment, but only MSISDN or ICCID are relevant for connectivity management.

SmartREST example

The 111 static template is provided for devices to communicate their mobile information:

111,1234567890,8930000000000000459,54353

Device availability

The Device availability tab shows the device’s availability and connection status. To achieve this the device must communicate its required interval using the c8y_RequiredAvailability fragment in the device’s own managed object. This action activates availability and connection monitoring for the device.

PUT /inventory/managedObjects/<deviceId>
{
   "c8y_RequiredAvailability": {
       "responseInterval": 15
   }
}
Name Type Mandatory Description
responseInterval integer No Expected response interval of the device in minutes. If it is <= 0 the device is considered in maintenance mode.

Usually devices should set their required interval only once during its first connection to the platform with a default value. Later changes can be left to platform users.

SmartREST example

The static template 117 is provided to set the required availability for SmartREST connected devices. This template can be sent in a fire-and-forget approach during device startup because it doesn’t override already existing required availability configuration:

117,15

Availability monitoring

The response interval set in the c8y_RequiredAvailability fragment is used as interval in which the platform expects to receive data from the device. If no data is received in this interval the device will be marked as offline and an alarm of type c8y_UnavailabilityAlarm will be raised automatically. This alarm will also be cleared automatically when the device sends data again. No further action from the device is necessary.

The following requests are considered a device’s heartbeat and will mark the device as available:

Connection monitoring

Cumulocity IoT also provides connection monitoring for devices. When the device establishes a connection where it is able to receive operations the platform considers this device as connected. This applies to HTTP longpolling connection or a MQTT session equally.

Device information

The Device information tab is a predefined dashboard with several widgets that combine default device information. The status widget, for example, will get its information from the c8y_Availability fragment, which holds information about the device’s status and when it was last available. For details see Device Management > Monitoring and controlling devices > Availability in the User guide.

Device status

Device marker

A device is marked in the inventory with a c8y_IsDevice fragment in its own managed object. Only devices with this fragment appear in the all All devices list in the Device Management application.

PUT /inventory/managedObjects/<deviceId>
{
   "c8y_IsDevice": {}
}
Info
Devices created through SmartREST 2.0 will automatically contain this fragment.

Agent marker

In order to receive any operation a device must declare the agent marker fragment in its own managed object. This will enable the platform to send operations to this device to for all child devices in its child hierarchy that don’t carry this fragment themselves.

PUT /inventory/managedObjects/<deviceId>
{
   "com_cumulocity_model_Agent": {}
}
Info
Devices created through SmartREST 2.0 will automatically contain this fragment.

Device restart

Devices capable of restarting remotely can announce this capability by adding the c8y_Restart operation to the device’s own c8y_SupportedOperations fragment. Then the Device details page will enable a Restart button within its context menu.

Restart operation

Upon clicking the Restart button in the Device Management application an operation as follows is sent:

{
  "c8y_Restart": {}
}
Field Data type Mandatory Details
c8y_Restart object Yes Restart marker fragment, that designates this operation as a restart operation

The device is expected to perform the following actions:

  1. Set the operation status to EXECUTING
  2. Perform the requested restart
  3. Set the operation status to SUCCESSFUL

SmartREST example

Cumulocity IoT provides the 510 static response template:

  1. Device receives command via 510 static response template
    510,DeviceSerial
  2. Device sets operation status to EXECUTING
    501,c8y_Restart
  3. Device confirms successful execution by setting operation status to SUCCESSFUL
    503,c8y_Restart

Hardware information

Devices may announce their underlying hardware information to Cumulocity IoT using the c8y_Hardware fragment in the device’s own managed object.

PUT /inventory/managedObjects/<deviceId>
{
   "c8y_Hardware": {
       "serialNumber": "1234567890",
       "model": "myModel",
       "revision": "1.2.3"
   }
}
Field Data type Mandatory Details
serialNumber string No The hardware serial number of the device
model string No A text identifier of the hardware model
revision string No A text identifier of the hardware revision

SmartREST example

Upload hardware information using the 110 static template. Usually this can be done once during agent application startup:

110,1234567890,myModel,1.2.3

Device profile

The Device profile tab shows the different parameters of the added device profiles. From a device agent perspective, device profiles are a combination of firmware update, software update, and typed file-based device configuration. Large parts of the agent code to support these capabilities can be reused.

Device profile functionality is enabled when the device announces the c8y_DeviceProfile operation in its c8y_SupportedOperations. The Device profile tab allows users to apply a profile to a device. This creates a c8y_DeviceProfile operation according to the configured profile. If present the firmware, software, and configuration should be handled exactly like their individual operations (c8y_Firmware, c8y_SoftwareUpdate, and typed c8y_DownloadConfigFile). We recommend you to execute a c8y_Profile operation by installing firmware first, software second and configuration third to minimize the potential of later actions overriding earlier ones.

{
   "profileName": "my profile",
   "profileId": "158751",
   "c8y_DeviceProfile": {
       "software": [
           {
               "name": "curl",
               "action": "install",
               "version": "2.3.4",
               "url": "http://my.url.com"
           },
           {
               "name": "cumulocity_agent",
               "action": "install",
               "version": "1.2.3",
               "url": "https://cumulocity.com/agent"
           }
       ],
       "configuration": [
           {
               "name": "ssh_conf",
               "type": "ssh_conf",
               "url": "http://cumulocity.com/conf"
           },
           {
               "name": "agent_conf",
               "type": "agent_conf",
               "url": "https://demos.cumulocity.com/inventory/binaries/156719"
           }
       ],
       "firmware": {
           "name": "device_fw",
           "version": "1.0.1",
           "url": "https://cumulocity.com/fw"
       }
   },
}
Name Type Mandatory Description
profileName string Yes Name of the device profile being applied
profileId string Yes ID reference to the device profile object
c8y_DeviceProfile object Yes Device profile object containing all information necessary for the installation
c8y_DeviceProfile.software array No Array of software objects to install or remove
c8y_DeviceProfile.software.name string Yes Name of the software package
c8y_DeviceProfile.software.action string Yes Action to perform on the package describing if the software should be installed or removed
c8y_DeviceProfile.software.version string Yes Version of the software
c8y_DeviceProfile.software.url string Yes URL where the software binary should be obtained from
c8y_DeviceProfile.configuration array No Array of configuration objects to apply
c8y_DeviceProfile.configuration.name string Yes Name of the configuration
c8y_DeviceProfile.configuration.type string Yes Type of the configuration
c8y_DeviceProfile.configuration.url string Yes URL where the configuration file should be obtained from
c8y_DeviceProfile.firmware object No Firmware object containing target firmware details
c8y_DeviceProfile.firmware.name string Yes Name of the firmware to install
c8y_DeviceProfile.firmware.version string Yes Version of the firmware
c8y_DeviceProfile.firmware.url string Yes URL where the firmware binary should be obtained from

When a device receives a c8y_Profile operation it should announce the target profile in its own managed object first.

PUT /inventory/managedObjects/<deviceId>
{
   "c8y_Profile": {
       "profileName": "my profile",
       "profileId": "158751",
       "profileExecuted": false
   }
}
Name Type Mandatory Description
profileName string Yes Name of the device profile
profileId string Yes The ID reference of the device profile object
profileExecuted Boolean Yes Indicator showing if the profile has been applied fully. Must be false in this context

After completing each of the three subsections the device must announce its current state in its own managed object the same way as described in the individual operations using the fragments c8y_Firmware, c8y_SoftwareList, and c8y_Configuration_<type> respectively. Then the device should update its installed profile state in its managed object by updating the profileExecuted property to true.

PUT /inventory/managedObjects/<deviceId>
{
   "c8y_Profile": {
       "profileName": "my profile",
       "profileId": "158751",
       "profileExecuted": true
   }
}
Name Type Mandatory Description
profileName string Yes Name of the device profile
profileId string Yes The ID reference of the device profile object
profileExecuted Boolean Yes Indicator showing if the profile has been applied fully; must be true in this context

The device is expected to perform the following actions:

  1. Set operation status to EXECUTING
  2. Set the c8y_Profile fragment in the device’s own managed object with profileExecuted = false
  3. Install firmware if included and complete installation by updating the c8y_Firmware fragment in its own managed object
  4. Install software if included and complete installation by updating the c8y_SoftwareList fragment in its own managed object
  5. Install configuration if included and complete installation by updating the c8y_Configuration_<type> fragment for each configuration in its own managed object
  6. Set the c8y_Profile fragment in the device’s own managed object with profileExecuted = true
  7. Set the operation status to SUCCESSFUL

SmartREST example

In addition to the static templates for firmware, software, and configuration provided by Cumulocity IoT there are specific templates available for handling device profiles. The 527 static response template is designed to receive the operation. The 121 static template can be used to set the current state of device profile:

  1. Receive c8y_DeviceProfile operation
527,DeviceSerial,$FW,device_fw,1.0.1,https://cumulocity.com/fw,false,,$SW,curl,2.3.4,http://my.url.com,install,cumulocity_agent,1.2.3,https://cumulocity.com/agent,install,$CONF,http://cumulocity.com/conf,ssh_conf,https://demos.cumulocity.com/inventory/binaries/156719,agent_conf
  1. Set operation status to EXECUTING
    501,c8y_DeviceProfile
  2. Set target profile
    121,false,
  3. Download, install and confirm firmware installation state
    115,device_fw,1.0.1,https://cumulocity.com/fw
  4. Download, install and confirm software installation state
    116,curl,2.3.4,http://my.url.com,cumulocity_agent,1.2.3,https://cumulocity.com/agent
  5. Download, install and confirm configuration installation state for each configuration
    120,ssh_conf,http://cumulocity.com/conf,config,
    120,agent_conf,https://demos.cumulocity.com/inventory/binaries/156719,agent.cfg,
  6. Set the target profile as executed
    121,true,
  7. Set operation status to SUCCESSFUL
    503,c8y_DeviceProfile

Firmware

The Firmware tab displays currently installed firmware of a device and allows users to install a different version. A device can have only one firmware installed at a time. It depends on the device, what a firmware can be in Cumulocity IoT. Typical use cases are: operating system, microcontroller firmware or BIOS.

Firmware can be installed with a full installation or with a patch. Which variant is sent to the device depends on how the firmware was created in the firmware repository.

Installed firmware

A device must announce its current state to the platform first. Then the installed firmware should be entered into the c8y_Firmware fragment into the device’s own managed object. A device must upload its current state to Cumulocity IoT during startup and any time a local change is detected. This includes cases where an update was triggered remotely.

PUT /inventory/managedObjects/<deviceId>
{
   "c8y_Firmware": {
       "name": "ubuntu core",
       "version": "20.04.2",
       "url": "http://test.com"
   }
}
Field DataType Mandatory Details
name string Yes Name of the firmware package
version string Yes A version identifier of the firmware
url string No A URL pointing to the location where the firmware file was obtained from

Similar to software the URL field is optional and may be omitted by devices.

SmartREST example

The 115 static template is available for devices to communicate their currently installed firmware state:

115,ubuntu core,20.04.3,http://test.com

Installing a firmware image

When a user selects a complete firmware image for installation, an operation with a similar c8y_Firmware fragment as found in the device managed object is created. This operation should be considered as the desired state that should be achieved by the device.

{
   "c8y_Firmware": {
       "name": "ubuntu core",
       "version": "20.04.3",
       "url": "http://test.com"
   }
}
Field DataType Mandatory Details
name string Yes Name of the firmware package
version string Yes A version identifier of the firmware
url string Yes A URL pointing to the location where the firmware file should be downloaded from

The device is expected to perform the following actions:

  1. Set operation status to EXECUTING
  2. Install firmware image
  3. Update the installed firmware state in the device’s own managed object
  4. Set operation status to SUCCESSFUL

Updating a devices often changes fundamental system components. This operation should always be considered as a critical operation. The device must ensure that all of its connection parameters to Cumulocity IoT are preserved through the upgrade and that connectivity can be resumed afterwards. We recommend you to make sure that the device uses an A/B firmware switching mechanism with a possibility to roll back if necessary.

SmartREST example

Cumulocity IoT provides the 515 static response template to deal with installing firmware images:

  1. Receive c8y_Firmware (image) operation
    515,DeviceSerial,ubuntu core,20.04.3,http://test.com
  2. Set operation status to EXECUTING
    501,c8y_Firmware
  3. Install firmware image
  4. Update device’s installed firmware state in inventory
    115,ubuntu core,20.04.3,http://test.com
  5. Set operation status to SUCCESSFUL
    503,c8y_Firmware

Installing a firmware patch

In case a user selects a firmware patch to be installed on a device, a c8y_Firmware operation is created. In this case two additional parameters are included to help with installation of a firmware patch. The device agent is responsible for a firmware patch process instead of a regular installation.

{
   "c8y_Firmware": {
       "name": "ubuntu core",
       "version": "20.04.4",
       "url": "http://test.com",
       "dependency": "20.04.3",
       "isPatch": true
   }
}
Field DataType Mandatory Details
name string Yes Name of the firmware
version string Yes A version identifier of the firmware
url string Yes A URL pointing to the location of the firmware file
dependency string Yes Version of the firmware the patch depends on
isPatch Boolean Yes Indicator showing that this firmware package is a patch

The device is expected to perform the following actions:

  1. Set operation status to EXECUTING
  2. Verify if the currently installed firmware version is equal to the dependency version
  3. Install firmware patch
  4. Update the installed firmware state in the device’s own managed object
  5. Set operation status to SUCCESSFUL

SmartREST example

Cumulocity IoT provides the 525 static response template to deal with installing firmware patches. It works very similarly to the 515 template, it just adds the dependency parameter as fifth parameter. The fact that a patch instead of a complete image should be installed is implicit because this template is only triggered for patches.

  1. Receive c8y_Firmware (patch) operation
    525,DeviceSerial,ubuntu core,20.04.3,http://test.com,20.04.3
  2. Set operation status to EXECUTING
    501,c8y_Firmware
  3. Verify if currently installed firmware version and dependency version match
  4. Install firmware image
  5. Update device’s installed firmware state in inventory
    115,ubuntu core,20.04.3,http://test.com
  6. Set operation status to SUCCESSFUL
    503,c8y_Firmware

Identity

The Identity tab shows all identities associated with the device. If no identities are available the tab is not shown. Identities map from a unique device identifier (for example, IMEI or SN) to the device’s managed object in Cumulocity IoT. This allows the device to find its managed object.

REST

REST

MQTT (SmartREST 2.0)

In the context of MQTT the client ID is used as the device’s external ID. Upon connecting the MQTT client ID is used to automatically associate the connection to a device in the inventory. No additional identity bindings must be created by the device. They are created internally when the 100 and 101 templates are used. All messages to create data are automatically associated with the device context.

Creating a device by a device connected to Cumulocity IoT:

100,createdDeviceName,deviceType

Creating a child device for a device connected to Cumulocity IoT:

101,uniqueChildId,myChildDevice,myChildType

Logs

The Logs tab is used to extract logs from the device. The Logs tab is available if the fragment c8y_LogfileRequest is present in the c8y_SupportedOperations of the device. The device should contain a fragment called c8y_SupportedLogs, which holds an array of the types of logs that it supports. The types of logs will later be referenced when logs are requested.

Setting supported logs

Supported log types are announced by devices using the c8y_SupportedLogs fragment in the device’s own managed object.

PUT /inventory/managedObjects/<deviceId>
{
   "c8y_SupportedLogs": [
      "syslog",
      "dmesg"
   ]
}
Field DataType Mandatory Details
c8y_SupportedLogs array Yes Array of strings of the supported log types

SmartREST example

The 118 static template is available to announce the supported logs of a device:

118,syslog,dmesg

Uploading log files

When users request log files from devices via the Logs tab a c8y_LogfileRequest operation is created.

{
   "c8y_LogfileRequest": {
       "searchText": "kernel",
       "logFile": "syslog",
       "dateTo": "2021-09-22T11:40:27+0200",
       "dateFrom": "2021-09-21T11:40:27+0200",
       "maximumLines": 1000
   }
}
Field DataType Mandatory Details
dateFrom string Yes Start date for log lines
dateTo string Yes End date for log lines
logFile string Yes Type of log for the specific device (c8y_SupportedLogs)
searchText string Yes A text filter to apply to individual log lines
maximumLines string Yes Maximum amount of lines to transfer

When the device has gathered the logs it uploads them to Cumulocity IoT as a file. We recommend you to create an event and upload the log file as a binary attachment of the event. The following is an example of such an event:

POST /event/events
{
   "source": {
       "id": "4801"
   },
   "type": "c8y_Logfile",
   "time": "2021-09-15T15:57:41.311Z",
   "text": "syslog log file"
}
Field DataType Mandatory Details
source string Yes ID of the device
type string Yes Type of the log file
time string Yes Time when the event occurred
text string Yes Event text

If desired the device may also include the c8y_LogfileRequest fragment from the operation or the operation ID into the event. The file is then attached to the event using it’s event ID and event binaries API.

POST /event/events/<eventId>/binaries

Host: https://<TENANT_DOMAIN>
Authorization: <AUTHORIZATION>
Accept: application/json
Content-Type: multipart/form-data;boundary="boundary"

--boundary
Content-Disposition: form-data; name="object"

{ "name": "syslog.txt", "type": "text/plain" }
--boundary
Content-Disposition: form-data; name="file"; filename="syslog.txt"
Content-Type: text/plain

Oct 25 13:28:53 wtp kernel: [  719.554855] sd 6:0:0:0: [sdb] Write Protect is off
Oct 25 13:28:53 wtp kernel: [  719.554864] sd 6:0:0:0: [sdb] Mode Sense: 03 00 00 00
Oct 25 13:28:53 wtp kernel: [  719.555033] sd 6:0:0:0: [sdb] No Caching mode page found
--boundary--

After successful completion of the upload, the device must include a URL to the uploaded file into the c8y_LogfileRequest fragment of the operation. The link must be presented as property “file”. This action can be combined with setting the operation status to SUCCESSFUL.

PUT /devicecontrol/operations/<operationId>
{
   "status": "SUCCESSFUL",
   "c8y_LogfileRequest": {
       "searchText": "kernel",
       "logFile": "syslog",
       "dateTo": "2021-09-22T11:40:27+0200",
       "dateFrom": "2021-09-21T11:40:27+0200",
       "maximumLines": 1000,
       "file": "https://demos.cumulocity.com/event/events/157700/binaries"
   }
}
Field DataType Mandatory Details
status string Yes Operation status
dateFrom string Yes Start date for log lines
dateTo string Yes End date for log lines
logFile string Yes Type of log for the specific device (c8y_SupportedLogs)
searchText string Yes A text filter to apply to individual log lines
maximumLines integer Yes Maximum amount of lines to transfer
file string Yes URL where the log file was uploaded to

The device is expected to perform the following actions:

  1. Set operation status to EXECUTING
  2. Load, filter, and crop the log file as specified in the operation
  3. Create a log file event
  4. Upload the log file as binary attachment to said event
  5. Set the operation status to SUCCESSFUL and include a URL to the uploaded log file

SmartREST example

Cumulocity IoT provides the 522 static response template for receiving c8y_LogfileRequest operations. When the log file is uploaded the device may use the implicit parameter functionality of the 503 static template to set the operation status and provide the file link at the same time:

  1. Receive c8y_LogfileRequest operation
    522,DeviceSerial,syslog,2021-09-21T11:40:27+0200,2021-09-22T11:40:27+0200,ERROR,1000
  2. Set operation status to EXECUTING
    501,c8y_LogfileRequest
  3. Create log file event using REST API
  4. Upload log file as event binary to newly created event using REST API
  5. Set operation status to SUCCESSFUL and supply uploaded file URL
    503,c8y_LogfileRequest,"https://demos.cumulocity.com/event/events/157700/binaries"

Measurements

The Measurements tab creates a single graph per measurement fragment sent by the device. This means all included series will be shown together in one graph. Therefore, any device integrations must be made considering this grouping. Its visibility is controlled by the device’s supported measurements. Cumulocity IoT automatically and dynamically populates the device’s supported measurements based on previously sent measurements. This means the measurements tab effectively appears after the device has sent its first measurement.

SmartREST example

There are several static templates available to create measurements in the 2xx range of message IDs. We provide the 200 static template to create a measurement with a dynamic fragment and series:

200,c8y_Temperature,T,25

While using this template is possible for many use cases, we recommend you to create a custom template for all use cases where dynamically defining fragment and series are not required.

Network

The Network tab displays network information. It is shown if the c8y_Network fragment is present in the device managed object. There are three subsections: WAN, LAN and DHCP. Each of these can be activated by the nested fragments c8y_ WAN, c8y_LAN, and c8y_DHCP respectively.

Network status

Devices may announce their current local network status and configuration to the platform using the c8y_Network fragment in the device’s own managed object.

PUT /inventory/managedObjects/<deviceId>
{
   "c8y_Network": {
       "c8y_LAN": {
           "netmask": "255.255.255.0",
           "ip": "192.168.128.1",
           "name": "br0",
           "enabled": 1,
           "mac": "00:60:64:dd:a5:c3"
       },
       "c8y_WAN": {
           "password": "user-password",
           "simStatus": "SIM OK",
           "authType": "chap",
           "apn": "example.apn.com",
           "username": "test"
       },
       "c8y_DHCP": {
           "dns2": "1.1.1.1",
           "dns1": "8.8.8.8",
           "domainName": "my.domain",
           "addressRange": {
               "start": "192.168.128.100",
               "end": "192.168.128.199"
           },
           "enabled": 1
       }
   }
}
Name Type Mandatory Description
c8y_LAN object No Optional nested object containing local network information
c8y_LAN.netmask string No Subnet mask configured for the network interface
c8y_LAN.ip string No IP address configured for the network interface
c8y_LAN.name string No Identifier for the network interface
c8y_LAN.enabled integer No Indicator showing if the interface is enabled or not
c8y_LAN.mac string No MAC address of the network interface
c8y_WAN object No Optional nested object describing mobile internet connectivity interface status
c8y_WAN.password string No SIM connectivity password
c8y_WAN.simStatus string No SIM connection status
c8y_WAN.authType string No Auth type used by the SIM connectivity
c8y_WAN.apn string No APN used for internet access
c8y_WAN.username string No SIM connectivity username
c8y_DHCP object No Optional nested object containing information for DHCP server status
c8y_DHCP.dns1 string No First configured DNS server
c8y_DHCP.dns2 string No Second configured DNS server
c8y_DHCP.domainName string No Domain name
c8y_DHCP.addressRange.start string No Start of address range assigned to DHCP clients
c8y_DHCP.addressRange.end string No End of address range assigned to DHCP clients
c8y_DHCP.enabled integer No Indicator showing if the DHCP server is enabled or not

Setting network configuration

If the device contains the c8y_Network operation in its c8y_SupportedOperations users may also update a device’s network configuration in the Network tab. The changed configuration is sent as c8y_Network operation with a very similar fragment as also present in the device managed object. The c8y_Network fragment within this operation may contain one or more of its nested fragments.

{
   "c8y_Network": {
       "c8y_LAN": {
           "netmask": "255.255.255.0",
           "ip": "192.168.128.1",
           "enabled": 1
       },
       "c8y_WAN": {
           "password": "user-password",
           "authType": "chap",
           "apn": "example.apn.com",
           "username": "ee"
       },
       "c8y_DHCP": {
           "dns2": "1.1.1.1",
           "dns1": "8.8.8.8",
           "domainName": "my.domain",
           "addressRange": {
               "start": "192.168.128.100",
               "end": "192.168.128.199"
           },
           "enabled": 1
       }
   }
}
Name Type Mandatory Description
c8y_LAN object No Optional nested object containing local network information
c8y_LAN.netmask string Yes Subnet mask configured for the network interface
c8y_LAN.ip string Yes IP address configured for the network interface
c8y_LAN.enabled integer Yes Indicator showing if the interface is enabled or not
c8y_WAN object No Optional nested object describing mobile internet connectivity interface status
c8y_WAN.password string Yes SIM connectivity password
c8y_WAN.authType string Yes Auth type used by the SIM connectivity
c8y_WAN.apn string Yes APN used for internet access
c8y_WAN.username string Yes SIM connectivity username
c8y_DHCP object No Optional nested object containing information for DHCP server status
c8y_DHCP.dns1 string No First configured DNS server
c8y_DHCP.dns2 string No Second configured DNS server
c8y_DHCP.domainName string No Domain name
c8y_DHCP.addressRange.start string No Start of address range assigned to DHCP clients
c8y_DHCP.addressRange.end string No End of address range assigned to DHCP clients
c8y_DHCP.enabled integer No Indicator showing if the DHCP server is enabled or not

The device is expected to perform the following actions:

  1. Set operation status to EXECUTING
  2. Apply WAN, LAN, and DHCP configuration
  3. Set new network configuration status the device managed object
  4. Set operation status to SUCCESSFUL

Changes to the network configuration potentially impact the device’s ability to connect to the Cumulocity IoT platform. We recommend you to implement a connection test with the new settings. If the test fails the device should rollback the settings to their previous state and set the operation status to FAILED.

SmartREST example

There are no static templates available for populating the network fragment or receiving network operations. A custom template can be used instead:

10,100,PUT,INVENTORY,false,c8y_Network.c8y_LAN.name,STRING,,c8y_Network.c8y_LAN.ip,STRING,,c8y_Network.c8y_LAN.netmask,STRING,,c8y_Network.c8y_LAN.mac,STRING,,c8y_Network.c8y_LAN.enabled,STRING,,c8y_Network.c8y_WAN.simStatus,STRING,,c8y_Network.c8y_WAN.apn,STRING,,c8y_Network.c8y_WAN.username,STRING,,c8y_Network.c8y_WAN.password,STRING,,c8y_Network.c8y_WAN.authType,STRING,,c8y_Network.c8y_DHCP.addressRange.start,STRING,,c8y_Network.c8y_DHCP.addressRange.end,STRING,,c8y_Network.c8y_DHCP.domainName,STRING,,c8y_Network.c8y_DHCP.dns1,STRING,,c8y_Network.c8y_DHCP.dns2,STRING,,c8y_Network.c8y_DHCP.enabled,STRING,
11,200,,c8y_Network.c8y_WAN,c8y_Network.c8y_WAN.apn,c8y_Network.c8y_WAN.username,c8y_Network.c8y_WAN.password,c8y_Network.c8y_WAN.authType
11,201,,c8y_Network.c8y_LAN,c8y_Network.c8y_LAN.ip,c8y_Network.c8y_LAN.netmask,c8y_Network.c8y_LAN.enabled
11,202,,c8y_Network.c8y_DHCP,c8y_Network.c8y_DHCP.addressRange.start,c8y_Network.c8y_DHCP.addressRange.end,c8y_Network.c8y_DHCP.domainName,c8y_Network.c8y_DHCP.dns1,c8y_Network.c8y_DHCP.dns2,c8y_Network.c8y_DHCP.enabled

The example custom template provides the 100 template for the device to upload its current network configuration completely. At device agent startup and each time a change is detected this template should be used to synchronize the information in the cloud with the local truth.

The example template also provides three response templates to receive the three different nested fragments as operations. Each response template may be handled separately.

WAN

  1. Receive WAN configuration operation
    200,example.apn.com,user,secret,chap
  2. Set operation status to EXECUTING
    501,c8y_Network
  3. Apply WAN configuration
  4. Update device’s network configuration in inventory
    100,br0,192.168.128.1,255.255.255.0,00:60:64:dd:a5:c3,1,SIM OK,example.apn.com,user,secret,chap,192.168.128.100,192.168.128.199,my.domain,8.8.8.8,1.1.1.1,1
  5. Set operation status to SUCCESSFUL
    503,c8y_Network

LAN

  1. Receive LAN configuration operation
    201,192.168.128.2,255.255.255.0,1
  2. Set operation status to EXECUTING
    501,c8y_Network
  3. Apply LAN configuration
  4. Update device’s network configuration in inventory
    100,br0,192.168.128.2,255.255.255.0,00:60:64:dd:a5:c3,1,SIM OK,example.apn.com,user,secret,chap,192.168.128.100,192.168.128.199,my.domain,8.8.8.8,1.1.1.1,1
  5. Set operation status to SUCCESSFUL
    503,c8y_Network

DHCP

  1. Receive DHCP configuration operation
    202,192.168.128.150,192.168.128.199,my.other.domain,1.1.1.1,8.8.8.8,1
  2. Set operation status to EXECUTING
    501,c8y_Network
  3. Apply DHCP configuration
  4. Update device’s network configuration in inventory
    100,br0,192.168.128.1,255.255.255.0,00:60:64:dd:a5:c3,1,SIM OK,example.apn.com,user,secret,chap,192.168.128.150,192.168.128.199,my.other.domain,1.1.1.1,8.8.8.8,1
  5. Set operation status to SUCCESSFUL
    503,c8y_Network

Remote access

The Remote access tab is used to configure and access devices for remote control through remote control protocols.

The Remote access tab is available if the following criteria are met:

For more information, see Cloud Remote Access > Using Cloud Remote Access.

Remote access connect

When a user selects a remote access endpoint and clicks the Connect button a c8y_RemoteAccessConnect operation is created.

{
   "c8y_RemoteAccessConnect": {
     "hostname": "10.0.0.67",
     "port": 5900,
     "connectionKey": "eb5e9d13-1caa-486b-bdda-130ca0d87df8"
   }
}
Field DataType Mandatory Details
connectionKey string Yes Shared secret to authenticate the connection request from device side
hostname string Yes Endpoint on local network to connect to
port integer Yes Port to be used on the local network endpoint

With this operation the device must open a WebSocket connection to the microservice endpoint using the connection key for authentication (wss://<c8y host>/service/remoteaccess/device/<connectionKey>) and a local socket to the specified hostname and port. Then it must establish bidirectional forwarding of data between the WebSocket and the local socket.

Cumulocity IoT currently supports VNC, SSH, and Telnet. The device agent should be implemented independently of the remote access protocol used. The operation intentionally does not transfer the protocol. The agent must be capable of forward arbitrary data between both its established sockets.

The device is expected to perform the following actions:

  1. Set operation status to EXECUTING
  2. Establish WebSocket connection to remote access microservice
  3. Establish local socket connection to the specified host and port
  4. Establish bidirectional forwarding between WebSocket and local socket
  5. Set operation status to SUCCESSFUL

The operation is set to SUCCESSFUL after the connection is established. Disconnecting happens silently. Even if the connection was not terminated gracefully by any of the involved components, the operation status must stay in SUCCESSFUL. Whenever one of the connections is terminated (WebSocket or TCP) the device agent should consider the session as ended and should also terminate both connections.

SmartREST example

The 530 static response template is available for receiving c8y_RemoteAccessConnect operations:

  1. Receive c8y_RemoteAccessConnect operation
    530,DeviceSerial,10.0.0.67,22,eb5e9d13-1caa-486b-bdda-130ca0d87df8
  2. Device sets operation status to EXECUTING
    501,c8y_RemoteAccessConnect
  3. Establish WebSocket connection using HTTP
  4. Establish local socket connection
  5. Device sets operation status to SUCCESSFUL
    503,c8y_RemoteAccessConnect

Shell

The Shell tab allows to send arbitrary device-specific commands to the device. It is shown if the c8y_Command operation is present in the device’s c8y_SupportedOperations.

Send a command to a device

You may enter an arbitrary string into the command text. The format and its interpretation is up to the device integration. Click the Execute button to create a c8y_Command operation.

{
   "c8y_Command": {
       "text": "get sw.version; get hw.version"
   }
}
Field DataType Mandatory Details
c8y_Command.text string Yes The command text to be executed by the device

After completing the execution, the device must provide a return string for the command in addition to setting the operation status to SUCCESSFUL. The result is provided as string property nested within the c8y_Command fragment in the operation.

PUT /devicecontrol/operations/<operationId>
{
   "status": "SUCCESSFUL",
   "c8y_Command": {
       "text": "get sw.version; get hw.version",
       "result": "1.2.3; 9.8.7"
   }
}
Field DataType Mandatory Details
status string Yes Operation status indicating if the operation was completed as intended
c8y_Command object Yes c8y_Command object received via the pending operation at the beginning
c8y_Command.text string Yes The command that was executed by the device
c8y_Command.result string Yes Execution result after running the command

The device is expected to perform the following actions:

  1. Set operation status to EXECUTING
  2. Execute the command and obtain the return value
  3. Set the operation status to SUCCESSFUL and include the return value in it

SmartREST example

For SmartREST connected devices the 511 static response template is available for receiving c8y_Command operations. Additionally, the implicit parameter functionality of the 503 static template can be used to supply the return value:

  1. Receive c8y_Command operation
    511,DeviceSerial,"get sw.version; get hw.version"
  2. Set operation status to EXECUTING
    501,c8y_Command
  3. Set operation status to SUCCESSFUL and supply return value
    503,c8y_Command,"1.2.3; 9.8.7"

Software

The Software tab allows you to install and uninstall a set of software files for a device. The files can be located using an URL or they can be hosted in the Cumulocity IoT Software Repository. Device agents are fully responsible for their local installation, management, and uninstall procedures and any kind of error handling during the operation.

The Device details page shows a Software tab for devices that announce c8y_SoftwareList and/or c8y_SoftwareUpdate in their c8y_SupportedOperations fragment in their device managed objects. It also shows a Services tab for devices that have at least one software service running. The service can have measurements, alarms and events assigned.

Installed software

There are two ways in which a device managed object may represent its installed software packages. It may list them in c8y_SoftwareList fragment or as the child additions. The latter approach also requires the device to have c8y_SupportedSoftwareTypes fragment. Let’s call the first approach legacy and the second advanced.

A software package, represented as the list entry or as a child addition, must contain following properties:

Field Mandatory Details
name Yes The name of the software
version Yes A version identifier of the software
url No A URL pointing to the location where the software file was obtained from
softwareType No An arbitrary string for organizing software artifacts

The name and the version are used to identify the package. Already mentioned c8y_SupportedSoftwareTypes fragment restricts possible software types that can be installed on the device.

Legacy Software Management

A device may update its software list by updating its managed object c8y_SoftwareList fragment.

PUT /inventory/managedObjects/<deviceId>
{
  "c8y_SoftwareList": [
    {
      "name": "software_a",
      "version": "3.0.0",
      "url": "http://example.com/software_a",
      "softwareType": "type A"
    },
    {
      "name": "software_b",
      "version": "2.0.0",
      "url": "http://example.com/software_b",
      "softwareType": "type B"
    }
  ]
}

Devices should upload the complete list of installed software during startup. Additionally the list should be updated any time a local change is triggered or detected. This includes cases where a change was requested through Cumulocity IoT UI.

SmartREST example

Cumulocity IoT provides the static SmartREST template 116 for devices to upload their installed software. It takes a dynamic length list of triples per software package as parameters. Each triple is interpreted as the name, version, and URL property of an individual package:

116,software_a,3.0.0,http://example.com/software_a,software_b,2.0.0,http://example.com/software_b

Changing installed software

Within the Software tab users can select software to install, to update, and to uninstall for a device. After confirming, the desired software configuration is sent to the device as an operation. The operation format depends on the device’s c8y_SupportedOperations fragment.

Software list

If the device only supports the c8y_SoftwareList operation and the c8y_SupportedOperations fragment does not contain c8y_SoftwareUpdate, a c8y_SoftwareList operation is sent to the device. This operation contains a very similar c8y_SoftwareList fragment to the one that is already present in the device’s own managed object. The c8y_SoftwareList operation always contains the entire list of software that should be installed on the device. Exactly the packages in the list should be installed. Any installed packages not contained in the list should be removed.

{
  "c8y_SoftwareList": [
    {
      "name": "software_a",
      "version": "4.0.0",
      "url": "http://example.com/software_a"
    },
    {
      "name": "software_b",
      "version": "3.0.0",
      "url": "http://example.com/software_b"
    }
  ]
}
Field DataType Mandatory Details
name string Yes Name of the software
version string Yes A version identifier of the software
url string Yes A URL pointing to the location where the software file should be downloaded from

The device is expected to perform the following actions:

  1. Set operation status to EXECUTING
  2. Uninstall software that should be uninstalled
  3. Install software that should be installed
  4. Update the software list in the device’s own managed object
  5. Set operation status to SUCCESSFUL

If the desired state cannot be achieved for any reason the operation should be concluded with status FAILED.

SmartREST example

The 516 static response template is available for dealing with software list operations. It works very similarly to the 116 template used for updating the device’s own managed object:

  1. Receive c8y_SoftwareList operation
    516,DeviceSerial,software_a,4.0.0,http://example.com/software_a,software_b,3.0.0,http://example.com/software_b
  2. Set operation status to EXECUTING
    501,c8y_SoftwareList
  3. Uninstall and install software
  4. Update device’s software list in inventory
    116,software_a,4.0.0,http://example.com/software_a,software_b,3.0.0,http://example.com/software_b
  5. Set operation status to SUCCESSFUL
    503,c8y_SoftwareList
Software update

If a device supports the c8y_SoftwareUpdate operation in its c8y_SupportedOperations fragment the ** Software** tab will create c8y_SoftwareUpdate operations for the device. Conceptually the software update is very similar to the software list. A desired state of software is sent to the device in form of a list of packages. The difference is that the c8y_SoftwareUpdate should be considered as a partial list. Each list element contains an additional instruction whether the package should be installed or uninstalled. Any package not listed in the software update list should not be touched.

{
  "c8y_SoftwareUpdate": [
    {
      "name": "software_a",
      "version": "4.0.0",
      "url": "http://example.com/software_a",
      "action": "install"
    },
    {
      "name": "software_b",
      "version": "3.0.0",
      "url": "http://example.com/software_b",
      "action": "delete"
    }
  ]
}
Field DataType Mandatory Details
name string Yes Name of the software
version string Yes A version identifier of the software
url string Yes A URL pointing to the location where the software file should be downloaded from
action string Yes Action to be executed from the device on the software (possible values: “install” or “delete”)

The device is expected to perform the following actions:

  1. Set operation status to EXECUTING
  2. Iterate through the list of packages contained in the operation and perform the respective action for each one
  3. Update the software list in the device’s own managed object
  4. Set operation status to SUCCESSFUL

SmartREST example

The 528 static response template is available for dealing with software update operations:

  1. Receive c8y_SoftwareUpdate operation
    528,DeviceSerial,software_a,4.0.0,http://example.com/software_a,install,software_b,3.0.0,http://example.com/software_b,delete
  2. Set operation status to EXECUTING
    501,c8y_SoftwareUpdate
  3. Uninstall and install software
  4. Update device’s software list in inventory
    116,software_a,3.0.0,http://example.com/software_a
  5. Set operation status to SUCCESSFUL
    503,c8y_SoftwareUpdate

Advanced Software Management

In this approach software packages became separate entities and are represented as the device managed object child additions. To facilitate the management of them, the Advanced Software Management default microservice was introduced.

Devices may indicate their support for Advanced Software Management by including the c8y_SoftwareUpdate operation in their c8y_SupportedOperations fragment and additionally listing their supported software types in the c8y_SupportedSoftwareTypes fragment.

{
  "c8y_SupportedOperations": [
    "c8y_SoftwareUpdate"
  ],
  "c8y_SupportedSoftwareTypes": [
    "type_a",
    "type_b"
  ]
}

An example managed object for the software package:

{
  "type": "c8y_InstalledSoftware",
  "name": "Software Name",
  "id": "123",
  "softwareType": "yum",
  "version": "1.0",
  "url": "www.example.com",
  "owner": "service_advanced-software-mgmt"
}

Notice that the owner field is required and must be set to service_advanced-software-mgmt for the microservice to detect the software package.

Querying, adding and removing software packages can be done with the microservice REST endpoints or using SmartREST static templates.

Querying the software packages:

GET /service/advanced-software-mgmt/software?deviceId=<deviceId>
{
  "softwareList": [
    {
      "name": "software_a",
      "version": "3.0.0",
      "url": "http://example.com/software_a",
      "softwareType": "type A"
    },
    {
      "name": "software_b",
      "version": "2.0.0",
      "url": "http://example.com/software_b",
      "softwareType": "type B"
    }
  ],
  "statistics": {
    "currentPage": 1,
    "pageSize": 5
  },
  "self": ...,
  "next": ...
}
Query paramater Mandatory Details
deviceId Yes ID of the device
name No Filter parameter for the software name
version No Filter parameter for the software version
type No Filter parameter for the software type
pageSize No The number of items on the page of the paginated result, between 1 and 2000
currentPage No The current page of the paginated result
withTotalPages No When set to true, the returned result will contain the total number of the pages in the statistics object

Setting software packages

Advanced Software Management allows devices to set their installed software, similarly to legacy software management. In this case any software communicated to the platform before is overwritten entirely with then new packages.

POST /service/advanced-software-mgmt/software?deviceId=<deviceId>
[
  {
    "name": "software_a",
    "version": "3.0.0",
    "url": "http://example.com/software_a",
    "softwareType": "type A"
  },
  {
    "name": "software_b",
    "version": "2.0.0",
    "url": "http://example.com/software_b",
    "softwareType": "type B"
  }
]
SmartREST example

Devices may also use the SmartREST static template 140 instead. It takes a list of software packages of dynamic length, where each package is represented by its name, version, software type and URL:

140,software_a,3.0.0,"type A",http://example.com/software_a,software_b,2.0.0,"type B",http://example.com/software_b

Adding software packages

With Advanced Software Management devices may also append packages to their installed software without having to announce the entire list.

PUT /service/advanced-software-mgmt/software?deviceId=<deviceId>
[
  {
    "name": "software_a",
    "version": "3.0.0",
    "url": "http://example.com/software_a",
    "softwareType": "type A"
  },
  {
    "name": "software_b",
    "version": "2.0.0",
    "url": "http://example.com/software_b",
    "softwareType": "type B"
  }
]
SmartREST example

Devices also use the SmartREST static template 141 instead. Similarly to 140, it takes a list of software packages of dynamic

141,software_a,3.0.0,"type A",http://example.com/software_a,software_b,2.0.0,"type B",http://example.com/software_b

Removing software

In order to complete partial updates of installed software Advanced Software Management offers an interface to remove individual packages from a device’s installed software.

DELETE /service/advanced-software-mgmt/software?deviceId=<deviceId>
[
  {
    "name": "software_a",
    "version": "3.0.0"
  },
  {
    "name": "software_b",
    "version": "2.0.0"
  }
]
SmartREST example

Devices may also use the SmartREST static template 142 instead. It takes a list of software packages of dynamic length, where each package is represented by its name and version, as URL and software type are not used to identify a package:

142,software_a,3.0.0,software_b,2.0.0

Changing installed software

Similarly, in the Advanced Software Management approach updating software packages requires sending to the device one of the operations: c8y_SoftwareUpdate or c8y_SoftwareList, depending on which are specified in c8y_SupportedOperations fragment. The only difference is that now software type property is required for software packages.

Software update

The c8y_SoftwareUpdate operation contains also partial list of software packages, each with an instruction whether it should be installed or uninstalled. This is very similar to legacy software management, however an additional parameter indicating the software type of each package is also included.

{
  "c8y_SoftwareUpdate": [
    {
      "name": "software_a",
      "version": "4.0.0",
      "url": "http://example.com/software_a",
      "softwareType": "type A",
      "action": "install"
    },
    {
      "name": "software_b",
      "version": "3.0.0",
      "url": "http://example.com/software_b",
      "softwareType": "type B",
      "action": "delete"
    }
  ]
}
Field DataType Mandatory Details
name string Yes Name of the software
version string Yes A version identifier of the software
url string Yes A URL pointing to the location where the software file should be downloaded from
softwareType string Yes An arbitrary string for organizing software artifacts
action string Yes Action to be executed from the device on the software (possible values: “install” or “delete”)

The device is expected to perform the following actions:

  1. Set operation status to EXECUTING
  2. Iterate through the list of packages contained in the operation and perform the respective action for each one
  3. Update the software list in the device’s own managed object
  4. Set operation status to SUCCESSFUL

SmartREST example

The 529 static response template is available for dealing with software update operations for devices that support Advanced Software Management:

  1. Receive c8y_SoftwareUpdate operation
    529,DeviceSerial,software_a,4.0.0,"type A",http://example.com/software_a,install,software_b,3.0.0,"type B",http://example.com/software_b,delete
  2. Set operation status to EXECUTING
    501,c8y_SoftwareUpdate
  3. Uninstall and install software
  4. Remove from the inventory uninstalled software packages
    142,software_b,3.0.0
  5. Add to the inventory installed software packages
    141,software_a,4.0.0,"type A",http://example.com/software_a
  6. Set operation status to SUCCESSFUL
    503,c8y_SoftwareUpdate

Services

The Cumulocity IoT UI allows you to monitor software services running on a device. The services are represented in Cumulocity IoT domain model as the device managed object child additions with c8y_Service type.

The Device details page shows a Services tab for devices that have at least one software service. A service can have measurements, alarms and events assigned.

Query, update, add and remove services using Cumulocity IoT REST API for manipulating managed objects.

REST API examples

Announcing a service to the platform

Using Inventory REST API:

POST /inventory/managedObjects/<deviceId>/childAdditions

Content-Type: "application/vnd.com.nsn.cumulocity.managedObject+json"
{
  "name": "MongoDB",
  "type": "c8y_Service",
  "serviceType": "systemd",
  "status": "up"
}
Field Mandatory Details
name Yes Name of the service
type Yes Type of the managed object, must always be ‘c8y_Service’
serviceType Yes An arbitrary string for organizing services
status Yes ‘up’, ‘down’, ‘unknown’ or any custom service status

Or using SmartREST static template 102. The second parameter - the unique ID does not reference the internal numeric ID but a string based external ID which is defined by the device not by the platform. We recommend prefixing the unique ID with a device specific prefix to avoid clashes with other devices running the same service:

102,myDevice_MongoDb,systemd,MongoDb,up

Updating the status of a service

Using Inventory REST API:

POST /inventory/managedObjects/<serviceId>

Content-Type: "application/vnd.com.nsn.cumulocity.managedObject+json"
{
  "status": "down"
}
Field Mandatory Details
status Yes ‘up’, ‘down’, ‘unknown’ or any arbitrary string specifying the service status

Or using SmartREST static template 104 (remember to target the service in the MQTT topic using its unique ID):

104,down

Sending service data

Measurement REST API:

POST /device/<serviceId>/measurements

Content-Type: "application/vnd.com.nsn.cumulocity.measurement+json"
{
  "source": {
    "id": "123"
  },
  "time": "2020-03-19T12:03:27.845Z",
  "type": "c8y_Memory",
  "c8y_Memory": {
    "allocated": {
      "unit": "MB",
      "value": 100
    }
  }
}

Or using SmartREST static template 200 sent to topic s/us/<serviceUniqueId>:

200,c8y_Memory,allocated,100,MB

Similarly to measurements, alarms and events associated with the service can also be sent.

Tracking

The Tracking tab allows the device’s path to be visualized. To achieve this the device must periodically send tracking events and update its position.

Tracking position history

A device may upload its current or past positions as location updated events with the c8y_Position fragment. This is useful for tracking devices on a route or generally tracing the location history of devices.

POST /event/events
{
    "c8y_Position": {
    	"alt": 67,
      "lng": 6.95173,
      "lat": 51.151977
    },
    "time":"2013-06-22T17:03:14.000+02:00",
    "source": {
    	"id": "10300"
     },
    "type": "c8y_LocationUpdate",
    "text": "LocUpdate"
}
Field DataType Mandatory Details
c8y_Position object Yes Holds geographical location properties
c8y_Position.alt number No Optional altitude of the device position in meters
c8y_Position.lng number Yes Longitude of the device position in degrees
c8y_Position.lat number Yes Latitude of the device position in degrees
time string Yes The time the position was measured
source object Yes ID of the source device
type string Yes Must always be c8y_LocationUpdate to designate this event as location update event
text string Yes Description of the event. This parameter is required because it is a required for events in general. There are no further semantics applied to the text in the context of tracking devices.

SmartREST example

Cumulocity IoT provides the 401 static template to send location update events using SmartREST:

401,51.151977,6.95173,67,2013-06-22T17:03:14.000+02:00

Setting the current position

The current device position is represented using the c8y_Position fragment in the device’s own managed object.

PUT /inventory/managedObjects/<deviceId>
{
    "c8y_Position": {
    	"alt": 67,
      "lng": 6.95173,
      "lat": 51.151977
    }
}
Field DataType Mandatory Details
alt number No Optional altitude of the device position in meters
lng number Yes Longitude of the device position in degrees
lat number Yes Latitude of the device position in degrees

SmartREST example

Devices may update their current position using the 112 static template:

112,51.151977,6.95173,67,

In Cumulocity IoT tracking over time is done using events and the current position is represented as fragment in the device’s own managed object (see above for details). In practice devices usually determine their current position in an interval and upload the coordinates as they are measured. In this case the current position and the position at that time are the same and can be uploaded at the same time using 402 static template.

402,51.151977,6.95173,67,,