Managing device data

The Device Management application provides features that support you in efficiently managing your devices. They are accessible through the Management menu in the navigator:

Management menu

Managing firmware

In the firmware repository, Cumulocity IoT offers to collect reference firmware for devices.

Only one firmware package version can be applied per device.

To view firmware

Click Firmware repository in the Management menu in the navigator.

The available firmware objects will be displayed as a list.

Firmware list

Each entry shows the firmware name, the device type it is applicable for (if set), and a label indicating if and how many versions are available for a particular firmware. At the left in the top menu bar, you can filter the repository entries by name, description or device type. For details on the filtering functionality, see Search and filter functionality.

When clicking on an entry, the details for this firmware are displayed along with all available versions and patches.

Firmware details

At the top, the firmware name, a description, and optional device type filter(s) are shown. If a filter is set, the firmware will show up for installation only for devices of that type. If no filter is set, it will be available for all devices.

The list of versions and patches shows the version name and the name of the firmware binary. Moreover, the list indicates if a firmware version has patches, which can be viewed by expanding the version entry. The versions and patches are ordered by their creation time (descending).

To add a new firmware or firmware version

  1. In the Firmware repository page, click Add firmware at the right of the top menu bar.
  2. In the resulting dialog box,
    • to add a new firmware, enter a name for the firmware (and confirm it by clicking Create new in the resulting window), add a description and its version (all required).
    • to add a new version, select the firmware for which you want to add a new version from the dropdown list in the Firmware field and enter a version.
  3. Optionally, you can define the device type filter when adding a new firmware.
  4. Either upload a binary from the file system or specify a URL from where the firmware can be downloaded.
  5. Click Save.

Add firmware

The firmware object will be added to the firmware list or the firmware version will be added to the firmware details and the version label will be updated accordingly.

If you click Add firmware from within the details of a specific firmware, the dialog box looks slightly different as the firmware is already selected. Enter the new version number and upload a binary or provide a file path.

To add a new firmware patch

  1. In the Firmware repository page, click Add firmware patch at the right of the top menu bar.
  2. In the resulting dialog box, select the firmware, for which you want to add a patch, from the dropdown list in the Firmware field.
  3. in the Version field, select the version, for which you want to add a patch.
  4. In the Patch field, enter a name for the patch.
  5. Either upload a binary from the file system or specify a URL from where the firmware can be downloaded.
  6. Click Save.

As with adding versions, if you click Add firmware patch from within the details of a specific firmware, the dialog box looks slightly different as the firmware is already selected.

The firmware patch will be added to the version details within the firmware details.

To edit a firmware

  1. Click the menu icon at the right of a specific firmware entry and in the context menu click Edit.
  2. Update the name, description or device type filter by clicking the edit icon next to it. Make the desired changes and click Save.

The firmware will be updated accordingly.

To delete a firmware

Click the menu icon at the right of a specific firmware entry and in the context menu click Delete.

The object will be deleted from the firmware repository.

To delete a firmware version or patch

In the details of a specific firmware, hover over the version or patch entry you want to delete and click the delete icon. The firmware version or patch will be deleted from the firmware details.

To manage firmware on a device

In the Firmware tab of a device you can manage the installed firmware for the device.

Info
The Firmware tab shows up for a device if the device supports c8y_Firmware operations.

Click All devices in the Devices menu in the navigator, select the desired device from the device list and open its Firmware tab.

The Firmware tab shows the current firmware installed on the device.

Firmware tab

Additionally, it shows the operation status for the last operation (one of SUCCESSFUL, PENDING, EXECUTING, FAILED). Clicking on the operation will show you the operation details.

To install/replace firmware on a device
  1. In the Firmware tab, click Install firmware (or Replace firmware if there is already firmware installed on the device).
  2. Select a firmware and the desired version from the list, which contains all firmware available for the particular device type (or the ones that have no device type) in the firmware repository.
  3. Click Install.

The install operation to be executed by the device will be created. The firmware installation is completed as soon as the device has executed the operation.

Click on the operation to view its details. The status of the last operation is also shown on the Firmware tab.

To install/update firmware on multiple devices

Cumulocity IoT offers the option to execute firmware updates for multiple devices at once.

  1. Execute the firmware operation (install or replace) on a single device to test that the new version works.
  2. Navigate to the operation in the Control tab and in the context menu select Schedule as bulk operation.
  3. Fill in the fields to schedule the bulk operation and click Create. For details on bulk operations, see Monitoring and controlling devices.

The status of the bulk operation is shown in the Bulk operations tab under Device control.

Moreover, the operation details are shown in the Control tab of the selected devices.

Managing software

In the software repository, Cumulocity IoT offers to collect reference software for devices. Multiple software packages can be installed on a device.

To view software

Click Software repository in the Management menu in the navigator.

The available software objects will be displayed as a list.

Software list

Each entry shows the software name, the device type it is applicable for (if set), the software type (if set), and a badge indicating if and how many versions are available for a particular software. The values in every column except for the Versions column can be filtered and sorted by clicking the filter and sort icons in the column header.

When clicking on an entry, the details for this software are displayed along with all available versions.

Software details

At the top, the software name, a description, an optional device type filter(s), and a software type are shown. If a device type filter is set, the software will show up for installation only for devices of that type. If no filter is set, it will be available for all devices. The software type will make the software installable only on devices that specifically support the particular software type.

Info
The Software type field suggests you a list of types already used in your software repository. Before you consider defining a new software type (the field accepts new values directly) check if the type you need has already been defined before for another software by looking at the suggestions in the dropdown. This will help you keep software types consistent within your organization. If you use, for example, container images you may look for container or image, or try to search for more specific types like docker, lxc, and so on. This may prevent you from scattering your software types and using different names for effectively the same software type.

The list of versions shows the version name and the name of the software binary. The versions are ordered by their creation time (descending).

To add a new software or software version

  1. In the Software repository page, click Add software at the right of the top menu bar.
  2. In the resulting dialog box,
    • to add a new software, enter a name for the software (and confirm it by clicking Create new in the resulting window), a description, and its version (all required).
    • to add a new version, select the software for which you want to add a new version from the dropdown list in the Software field and enter a version.
  3. Optionally, you can define the device type filter when adding a new software.
  4. Define the software type. It will make the software installable only on devices that have declared to support the particular software type.
  5. Either upload a binary from the file system or specify a URL from where the software can be downloaded.
  6. Click Add software.

Add software

The software object will be added to the software list or the software version will be added to the software details and the version count label will be updated accordingly.

If you click Add software from within the details of a specific software, the dialog box looks slightly different as the software is already selected. Enter the new version number and upload a binary or provide a file path.

To edit a software

  1. Click the edit icon at the right of a specific software item.
  2. Update the name, description, device type filter or software type by hovering over the edit icon next to it. Make the desired changes and click Save.

The software will be updated accordingly.

To delete a software

Click the delete icon at the right of a specific software item and in the context menu click Delete.

The software and all its versions will be deleted from the software repository.

To delete a software version

In the details of a specific software, hover over the version entry you want to delete and click the delete icon . The software version will be deleted from the software details.

If the last version of a software is deleted, the software is entirely removed from the repository.

To manage software on a device

In the Software tab of a device you can manage the software for the particular device.

Info
The Software tab shows up for a device if the device supports one of the following operations: c8y_SoftwareUpdate, c8y_SoftwareList, c8y_Software.

Click All devices in the Devices menu in the navigator, select the desired device from the device list and open its Software tab.

The Software tab shows a list of all available software installed on the device. If a given software has a type, it will be displayed next to its name. You can search for a particular software by its name or filter the list by software type.

Software tab

Additionally, it shows the operation status for the last operation (one of SUCCESSFUL, PENDING, EXECUTING, FAILED). Clicking on the operation will show you the operation details.

To install software on a device

  1. In the Software tab, click Install software.

    Info
    The Install software dialog will only display software items which match the device type or have no device type specified. Additionally, if the device has any c8y_SupportedSoftwareTypes declared the dialog will only display the software items matching the supported software types.
  2. Select one or multiple software items by selecting the respective version from the list which contains all software items for the particular device type available in the software repository.
    For devices supporting advanced software management features, already installed software items cannot be pre-filtered from the list of available software items. Thus, after a particular software version has been selected, a check is done if the selected software is already installed on the device. If this is the case, a warning next to the selected version indicates that this software version is already present on the device.
    You can remove the already installed software item under Software changes or leave it and apply it as part of the changes. It is up to the device agent to decide how to handle such an update.

  3. Click Install.

  4. Under Software changes at the right, review your planned changes and confirm the software update operation by clicking Apply changes.

The install operation to be executed by the device will be created. The software installation is completed as soon as the device has executed the operation.

Click on the operation to view its details. The status of the last operation is also shown on the Software tab.

To update software on a device

Hover over the software item which you want to update and click Update. Select a version from the list and click Update again.

The software will be updated with the selected version.

To delete software from a device

Hover over the software item which you want to delete and click the delete icon.

To install software on multiple devices

Cumulocity IoT offers the option to execute software updates for multiple devices at once.

  1. Execute the software operation (install or update) on a single device to test that the new version works.
  2. Navigate to the operation in the Control tab and in the context menu select Schedule as bulk operation.
  3. Fill in the fields to schedule the bulk operation and click Create. For details on bulk operations, see Monitoring and controlling devices.

The status and details of the bulk operation are shown in the Bulk operations tab under Device control.

Moreover, the operation details are shown in the Control tab of the selected devices.

Managing configurations

Cumulocity IoT allows to retrieve configuration data and store and manage it in a configuration repository. The configuration data contains the parameters and the initial settings of your device.

Configuration snapshots help you, for example, to apply the same configuration to multiple devices as described below.

Click Configuration repository in the the Management menu in the navigator. In the Configuration repository page, all available configuration snapshots are listed. Each entry shows the configuration name, the description of the configuration, the device type, and the configuration type.

Configuration Repository

To add a configuration snapshot

  1. Click Add configuration snapshot at the right of the top menu bar.
  2. In the resulting dialog box, enter a unique name.
  3. In the Device type field, enter a device type. The device type can be found in the Info tab of the target device.
  4. Optionally enter a description for the configuration.
  5. Enter the configuration type, for example “ssh”.
  6. Specify the configuration snapshot file by either uploading it from the file system, specifying a URL from where the configuration snapshot can be obtained or choosing a file.
  7. Click Add configuration.

The configuration snapshot will be added to the configuration repository.

To edit a configuration snapshot

To edit a configuration snapshot, click on the menu icon at the right of the row and then click Edit.

For details on the fields, see To add a configuration snapshot.

Configuration Repository

Click Update configuration to save your changes.

To delete a configuration snapshot

To delete a configuration snapshot, click on the menu icon at the right of the row and then click Delete.

The configuration snapshot will be deleted from the configuration snapshot repository.

To retrieve and apply a configuration snapshot

Managing configurations, that is requesting a configuration from a device and sending a configuration to a device, can be done in multiple ways. Depending on user permissions and device settings, you can work with text based, typed file-based or legacy file-based configuration. Refer to Configuration for more detailed and technical information.

To retrieve and apply a configuration snapshot to a device which supports typed file-based configuration

We recommend you to use typed file-based configuration. With typed file-based configuration, devices can manage multiple configurations at the same time. You can upload or retrieve different configurations for different types. Using this approach is more versatile because the configurations are handled as events rather than as files, which is more efficient.

  1. Navigate to the desired device in Devices > All devices and open its Configuration tab.
  2. Under Device-supported configurations, select the desired configuration type and click Get snapshot from device at the right.

Once retrieved, you can save or download the snapshot in the Preview section. The snapshot will be added to the Configuration repository, accessible from the Management menu in the navigator.

Retrieve Configuration Snapshot

Info
Clicking Get snapshot from device creates a new operation. If the operation is in status PENDING or EXECUTING, it is not possible to trigger another configuration request for the configuration type. Navigate to the Control tab of a device to cancel the operation or view the history of operation changes.

To apply a configuration snapshot to a device which supports multiple configuration types:

  1. Navigate to the desired device and open its Configuration tab.
  2. Under Device-supported configurations, select the desired configuration type.
  3. Under Available supported configurations, select a configuration file.
  4. Click Send configuration to device at the right to apply the selected snapshot to the device.

Apply new snapshot to a device

Info
Under Available supported configurations, only configuration files with a matching configuration type property or without a configuration type defined are displayed. Also, configuration files are filtered based on the device type (ones that match the device type or have no device type specified).

To retrieve and apply a configuration snapshot to a device which supports legacy file-based configuration

Devices managing configuration as files can do so in a basic form using legacy file-based configuration. Legacy file-based configuration only allows a single configuration to be set per a device.

Retrieve Configuration Snapshot

To retrieve and apply a configuration snapshot to a device which supports text-based configuration

The most basic form of configuration is text-based configuration. A text command can be sent or received from a device. We recommend you to use text-based configuration for short human readable configuration files only.

Send Text Configuration

Managing trusted certificates

Cumulocity IoT allows devices to connect via MQTT protocol using a X.509 certificate for authentication. To do so, a certificate must be trusted by Cumulocity IoT. A certificate is trusted when it is added to the trusted certificates and is in activated state.

Info
This section describes how to manage trusted certificates. For information on connecting devices using certificates refer to Device certificates.

Click Trusted certificates in the Management menu in the navigator.

All certificates owned by the tenant will be displayed.

Trusted certificates List

The Status column indicates if the certificate is enabled or disabled. At any given time a tenant can have any number of enabled or disabled certificates. Expand a certificate by clicking the arrow icon at the right to view more details.

The information in the table at the right side is extracted from the provided certificate. The content is read-only and cannot be changed.

Trusted certificate details

To add a certificate

Before adding a new trusted certificate, make sure that:

  • It is a X.509 certificate in PEM format.
  • It is in version 3.
  • It contains BasicConstraints:[CA:true].
  • It has not already been uploaded to Cumulocity IoT.
  • It is still valid (not expired).

To add a certificate perform these steps:

  1. Click Add trusted certificate at the right of the top menu bar.
  2. In the resulting dialog box, provide the following information:
Field Description
Certificate name User-provided name for the certificate. This name is not used by Cumulocity IoT and can serve as a description of the certificate.
Certificate File containing the certificate in PEM format. Add the file by dropping it into this field or browsing for it in your file system.
Auto registration If selected, new devices which use a certificate signed by the authority owning this trusted certificate will automatically be registered. The option does not support devices using the LWM2M protocol.
Enabled/ Disabled When disabled, devices which use a certificate signed by the authority owning this certificate, will not be able to connect.
  1. Click Add Certificate to validate and save the certificate.
Info
For performance reasons, you shouldn’t add the certificates of each device you want to connect, but only add the root certificate or one of the intermediate certificates from the chain which has been used to sign certificates used by devices.

To edit a trusted certificate

In the detail view of a certificate you may change the parameters on the left, that is, the certificate name, and the settings for the auto registration and enabled/disabled option.

For details on the fields, see the description on adding certificates above.

To delete a trusted certificate

To permanently delete a certificate from the trusted certificates list, click the delete icon at the right of the respective entry and in the context menu click Delete. The certificate will be permanently deleted.

Managing trusted certificate settings

Cumulocity IoT allows administrators to fine-tune various certificate configurations. Currently, Certificate Revocation List (CRL) is supported.

Info
This section targets at advanced users for granular control over certificate attributes like CRL, OCSP, Certificate Policy and PKI. If you are unfamiliar with these terms it’s advisable to leave the defaults. Bad configuration might result in changes which cannot be reversed.

CRL settings

In general, Certificate Revocation List (CRL) contains a list of serial numbers of revoked certificates. These are issued by Certificate Authorities (CAs) periodically and published through an endpoint called CRL Distribution Point (CDP). Revocation reasons and dates are included in the CRL.

In Cumulocity IoT terms, if there is a breach at device certificates signed by a trust anchor, users can inform the platform about the revoked certificates in two ways:

  1. Online revocation : To perform online revocation checks, the device administrator is expected to upload a trusted CA which maintains the CRLs with the list of revoked certificate serial numbers and should provide this information in its CDP attribute.
  2. Offline revocation : The trusted CA doesn’t maintain the revocation details of the certificates, in which case, the platform users can manually upload the serial numbers of the revoked certificates.

Note that both online and offline CRL checks are by default unchecked.

Important
Certificate revocation is an irreversible process. So, offline entries once made cannot be removed.

To enable online revocation

CRl Details

  1. Click CRL check in the upper right corner of the screen.
  2. Enable the Online option.

To enable offline revocation

CRl Details

  1. Click CRL check in the upper right corner to enable the offline revocation of the screen.

  2. Check the Offline checkbox.

  3. To add revoked certificate serial numbers manually, enter the serial number and date in the Revoked certificates list panel.

    Click Down to add new entries in the format below:

    Field Description Example
    Serial number Must be a hexadecimal value. 0b8a5b9dd501a88775399b9a048811a3
    Date (optional) Date format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'. 2024-01-17T10:48:51.000Z
    1. Click Save to confirm your entries.
Info
If the date field is empty, then the current date is used. Future dates are not allowed.

Offline CRL bulk upload

Info
Revoked certificate serial numbers can be added in bulk. Each file can hold at maximum 5000 revocation entries. If the date is in the future then the CRL entry is skipped. In case of a duplicate, the latest one (last one uploaded) is used.

To bulk upload, follow these steps:

  1. Download the CSV template from the Revoked certificates list panel.
  2. Fill in all revoked certificate serial numbers and revocation dates.
  3. Upload the filled CSV file using file upload.

To download or view the offline CRL file

In the Revoked certificates list panel, click Download CRL file.

Managing device credentials

The Device credentials page lists all credentials that have been generated for your connected devices. Each device that has been registered shows up here with the naming convention “device_<id>”.

Device credentials

To manage permissions for a device

  1. Click the arrow in the Global roles column of a device to open a list with available global roles.
  2. Assign or remove permissions for an individual device by selecting/deselecting roles.
  3. Click Apply.

The roles for the device will be updated accordingly.

To edit device credentials

  1. Click the menu icon at the right of a device credentials entry and then click Edit to open the device details.

  2. In the details page, you may disable/enable a device by clicking the Active toggle, change the password for a device, or assign or remove permissions by selecting/deselecting roles in the Global roles list.

    Device credentials details

  3. Click Save.

The device credentials will be updated accordingly.

To disable device credentials

Click the menu icon at the right of a device credentials entry and then click Disable.

The device credentials will be temporarily disabled.

To delete device credentials

Click the menu icon at the right of a device credentials entry and then click Delete.

The device credentials will be permanently deleted.

Deleting device credentials might be required if you have carried out a factory reset on a device. In this case, the device will often loose its assigned credentials. Delete it and continue with the normal registration process to re-register the device.

Managing device profiles

Device profiles represent a combination of a firmware version, one or multiple software packages, and one or multiple configuration files which can be deployed on a device. Based on device profiles, users can deploy a specific target configuration on devices by using bulk operations.

To view device profiles

Click Device profiles in the Management menu in the navigator to access the Device profiles page, which lists all available device profiles.

Device profiles list

Each device profile entry shows the profile name and the selected device type(s), if any.

Click a device profile name to view its details.

The Name and device type section shows the name of the profile and optionally selected device types.

The sections below list the firmware version, software packages, and configuration files for this particular device profile.

Device profile details

To add a device profile

Click Add device profile at the right of the top menu bar, to add a new device profile.

In the Add device profile window, provide a name for the profile and optionally enter one or more device types. If a device type is provided, the device profile can only be assigned to devices of the specified type. If left empty, it will be available for all device types.

To add items to a device profile

In the device profile details, you can add firmware versions, software packages, and configuration files.

Click Add firmware to add a firmware version to the profile. Select a firmware and a version from the list and click Save to add the selection to the profile. If a device type has been defined for the profile, only those firmware versions can be selected that match the device type. Only one firmware version can be added to a profile.

For details on firmware, see Managing firmware.

Click Add software to add a software package to the profile. Select a software and a software version from the list and click Save to add the selection to the profile. If a device type has been defined for the profile, only those software versions can be selected that match the device type. You can add multiple software packages to a profile.

For details on software, see Managing software.

Click Add configuration to add a configuration file to the profile. Select a configuration file from the list and click Save to add the selection to the profile. You can add multiple configuration files to a profile.

For details on configuration snapshots, see Managing configurations.

To update device profiles

To update a device profile click the menu icon at the right of the respective device profile entry and then click Edit.

You may edit the name and the device types by clicking the edit icon next to the respective fields. Make the desired changes and click Save to save your edits.

Moreover, you can delete firmware, software or configuration items or add new ones.

To delete an item, hover over it and click the delete icon.

See To add items to a device profile for details on how to add firmware, software or configuration items.

Note that in case of firmware, only one item is allowed in a profile at a time.

To duplicate device profiles

To duplicate a device profile, click the menu icon at the right of the respective device profile entry and then click Duplicate.

Duplicating a profile creates another instance of the profile with the same content. Per default, the original profile name is extended with “Copy of”. You may give the profile a more appropriate name by clicking the edit icon next to the name field and editing it.

To delete device profiles

To delete a device profile, click the menu icon at the right of the respective device profile entry and then click Delete.

Info
Deleting a profile deletes the entry from the device profile repository. It has no affect towards the devices that currently use the profile.

To apply device profiles to devices

Device profiles can be assigned to:

The Device profile tab of a particular device shows the details of the currently installed profile on a device.

Currently installed profile

Info
The Device profile tab shows up for a device if the device supports c8y_DeviceProfile operations.

To apply device profiles to a single device

Device profiles can be applied to individual devices in the Device Profile tab of the particular device.

  1. In the Device profile tab, select a device profile from the dropdown list. Only profiles that match the device type (if specified) or have no device type specified are displayed.
  2. Click Assign device profile to start the update operation.

To apply device profiles to multiple devices

Device profiles can be applied to multiple devices by using bulk operations.

  1. Click Device control in the Overview menu to navigate to the Device control page. In the Device control page, a new bulk operation can be created to apply a device profile.
  2. In the Bulk operations tab, click New bulk operation at the right of the top menu bar and in the resulting dialog select Apply device profile.
  3. Follow the steps described in To add a bulk operation to schedule a bulk operation which applies a device profile.

The devices will install the firmware, software, and configurations items of the profile and report back the status of the operation. After applying the profile, the device objects in the platform are updated accordingly with the new profile information.

Info
When creating bulk operations, it is possible to use filters, and by this create bulk operations only for those devices where a profile has not been applied yet.