Overview

The following sections will walk you through all functionalities of the Device management application in detail. For your convenience find an overview on the content of this document below.

SECTION CONTENT
Connecting devices How to register one or more devices manually and how to bulk-register devices in order to connect devices to your account.
Viewing devices What is displayed in the device list and how to sort devices by filtering devices.
Grouping devices Why and how to group devices into top-level groups, subgroups and smart groups.
Device details Detailed description of the various kind of information available for various types of devices.
Monitoring and controlling devices How to monitor the connection quality and availability status of devices, how to handle alarms from devices, how to remote control and how to troubleshoot devices.
Monitoring device services Description of the different kinds of data available for the purpose of device service monitoring.
Managing device types How to process data from various device types by using device protocols.
Managing device data How to manage firmware and software for devices, configuration snapshots, device credentials, trusted certificates and device profiles.
SmartREST templates How to work with SmartREST templates, a collection of request and response templates used to convert CSV data and Cumulocity IoT Rest API calls.
Working with simulators How to model devices with the simulator in order to have the same level of functionality as connected hardware devices.

Home dashboard

The Home screen of the Device management application is a dashboard which shows data for the tenant.

Home dashboard

The data shown on the Home dashboard is shared by all users of the tenant. By default, the Home dashboard includes recent alarms and quick links. The Home dashboard can be edited and designed individually according to your needs. You can add, remove or change widgets which are displayed here.

For details on editing a dashboard, refer to Cockpit > Working with dashboards. The Device management application dashboard works just like the Cockpit dashboard.

To reset the Home dashboard to its default, click Restore dashboard at the right of the top menu bar.

Connecting Devices

Device registration

In the Device registration page all devices which are currently in the registration process are displayed.

Device registration page

The following information is shown for each device:

The devices may have one of the following status:

Info
If a device registration is blocked, you will need to delete it first and then create it again.

Devices can be connected to your Cumulocity IoT account in different ways.

To register devices

To register devices, you can select one of the following options:

Microservice developers can also use the Extensible device registration and implement a custom registration form that blends seamlessly into the UI.

Info
The following descriptions apply to the general device registration processes. If you subscribe to specific protocol integrations, you will see additional protocol-specific options (for example, for LWM2M or OPC UA). A full list of supported protocols can be found in the Protocol integration guide. It also contains descriptions for the protocol specific registration processes.

Single device registration

Cumulocity IoT offers single device registration to connect devices manually one by one.

To connect a device manually

Info
Depending on the type of device you want to connect, not all steps of the following process may be relevant.
  1. Click Registration in the Devices menu of the navigator.
  2. In the Device registration page, click Register device at the right of the top bar and from the dropdown menu select Single registration > General. The Register devices dialog box will be displayed.
  3. In the Device ID field, enter a unique ID for the device. To determine the ID, consult the device documentation. In case of mobile devices the ID usually is the IMEI (International Mobile Equipment Identity) often found on the back of the device.
  4. Optionally, select a group to assign your device to after registration, see also Grouping devices.
  5. Click Add device to register one more device. Again, enter the device ID and optionally select a group. This way, you can add multiple devices in one step.
  6. Click Next to register your device(s).
Info
In an Enterprise tenant, the Management tenant may also directly select a tenant to which the device will be added from here. Note that since the Management tenant does not have access to the subtenant’s inventory you can either register devices to a tenant OR to a group, not both.

General device registration

After successful registration the device(s) will be listed in the Device registration page with the status “Waiting for connection”.

Turn on the device(s) and wait for the connection to be established.

Once a device is connected, its status will change to “Pending acceptance”.

Info
The Pending acceptance screen might differ depending on the security token policy.

Click Accept to confirm the connection. The status of the device will change to “Accepted”.

Info
In case of any issues, consult the documentation applicable for your device type in the Cumulocity IoT Device Partner Portal or look up the manual of your device.

Security token policy for device registration

Configure the security token policy to reduce the risk of devices which are not yet registered being taken over by threat actors, for example, by guessing their serial numbers.

Info
The feature requires READ permission for “Option management”. If the permission is missing, the security token policy defaults to OPTIONAL.

Cumulocity IoT supports the following values for the security token policy:

The policy can be configured by setting the following tenant option with one of the values listed above, for example:

{
  "category": "device-registration",
  "key": "security-token.policy",
  "value": "IGNORED"
}
Info
The Pending acceptance screen might differ depending on the security token policy.
Ignored security token policy

With a value of IGNORED for the security token policy, a device connected to Cumulocity IoT can be accepted without any token validation:

Accepting devices registrations under ignored security token policy

Optional security token policy

The list of device registrations is presented in the image below. Note that the input for security token is displayed for all devices.

Accepting devices registrations under optional security token policy

Registration without using a security token

When a device connected to Cumulocity IoT doesn’t use a security token, the registration can proceed without providing any value in the security token input.

If a security token is provided for a device which is connected insecurely, it will be accepted and the token will be ignored.

Registration using a security token

When a device connected to Cumulocity IoT does use a security token, the registration can be completed only if the user provides a token matching the one sent by the device on establishing the connection.

Providing a token for device registration request in optional security token policy

In the case of providing an incorrect token, an error message will be displayed informing about a mismatch between the value used by the device and the value provided via the user interface.

After a certain amount of failed attempts, the registration will reach the blocked state, indicated by a corresponding error message. The blocked registration must be removed before the next attempt to connect the device.

Limited usage of “Accept all” feature

The accept all feature is supported for devices connected to Cumulocity IoT without the usage of a security token.

For any device which uses a security token, the accept all feature is not available and will display a warning message. The details of the warning message provide the list of devices which could not be accepted automatically.

Such devices must be accepted manually by providing the correct Security token value and clicking Accept.

Required security token policy

In this mode any device connected to Cumulocity IoT must use a security token on establishing the connection and the user must enter the same token when accepting the device.

The procedure of accepting devices is the same as described in Optional security token policy.

While in this mode, any devices connecting to Cumulocity IoT without a security token will be blocked and it won’t be possible to complete their registration.

Bulk device registration

To connect larger amounts of devices, Cumulocity IoT offers the option to bulk-register devices, that means, to register larger amounts of devices by uploading a CSV file.

Info
There is no restriction on the number of devices that you can bulk-register but the more devices you add the slower the creation and operation gets.
To bulk-register devices
  1. Click Registration in the Devices menu of the navigator.

  2. In the Device registration page, click Register device at the right of the top bar and from the dropdown menu select Bulk registration > General. The Bulk device registration dialog box will be displayed.

  3. Click the Plus button to select or drag-and-drop the CSV file you want to upload.

Depending on the format of the uploaded CSV file, one of the following registration types will be processed:

Info
Bulk registration creates an elementary representation of the device. Then, the device needs to update it to a full representation with its own status.

A separator is automatically obtained from the CSV file. Valid separator values are: \t (tabulation mark), ; (semicolon) and , (comma).

Simple registration

The CSV file contains two columns: ID;PATH, where ID is the device identifier, for example, serial number, and PATH is a slash-separated list of group names (path to the group where the device should be assigned to after registration).

ID;PATH
Device1;Group A
Device2;Group A/Group B			

After the file is uploaded, all required new groups will be created, new registrations will be created with status “Waiting for connection”, and the normal registration process needs to be continued (see above).

Full registration

The CSV files must contain at least the IDs as device identifier and the credentials of the devices.

In addition to these columns the file can also contain other columns like ICCID, NAME, TYPE as shown in the following example:

ID;CREDENTIALS;TYPE;NAME;ICCID;IDTYPE;PATH;SHELL;AUTH_TYPE
006064ce800a;LF2PWJoLG1Fz;c8y_Device;Sample_Device1;+491555555;c8y_Serial;bulk group/subgroup1;1;BASIC
006064ce8077;OowoGKAbiNJs;c8y_Device;Sample_Device2;+491555555;c8y_Serial;bulk group/subgroup2;1;BASIC

To connect the devices, they are pre-registered with the relevant information. More specific, each device will be configured as follows:

After the data is imported, you will get feedback on the number of devices that were pre-registered as well as on any potential errors that may have occurred.

For your convenience, we provide CSV template files for both bulk registration types (simple/full) which you can download from the registration wizard to view or copy the structure.

Info
If the device with the given identifier already exists, it will be updated with the data from the CSV file.
To import CSV data in Microsoft Excel
  1. In Microsoft Excel, switch to the Data tab.
  2. In the Data tab, select From Text in the top menu bar.
  3. Select the CSV file you want to import by browsing for it (in this case the template file that you have downloaded from the Cumulocity IoT platform).
  4. In Step 1 of the Text Import Wizard, leave the default settings and click Next.
  5. In Step 2 of the Text Import Wizard, select Semicolon as delimiter and click Finish.

For further information on the file format and accepted CSV variants, also refer to Create a bulk device credentials request in the Cumulocity IoT OpenAPI Specification.

Info
In an Enterprise tenant you may also register devices across multiple tenants by adding a Tenant column to the spreadsheet and importing the CSV file from the Management tenant.

Viewing devices

To view all devices connected to your account, click All devices in the Devices menu in the navigator.

A detailed device list will be displayed.

Device list

Device information

For each device, the device list shows the following information provided in columns:

Column Description
Status An icon representing the connection status. For details, see Connection monitoring.
Name Unique name of the device.
Model Model type of the device. Not always displayed, depends on browser width.
Serial Number Serial number of the device. Not always displayed, depends on browser width.
Group Group the device is assigned to, if any.
Registration Date Date when the device was registered to your account.
System ID System ID of the device.
IMEI IMEI of the device.
Alarms The alarm status of the device, showing number and type of alarms currently unresolved for the device. Only includes alarms for the parent device. See Working with alarms for further information on working with alarms.

For users with global roles the devices list displays the items in a paginated manner. You can select the number of items per page and directly jump to any page. Users with inventory roles see up to 50 items initially. If there are more than 50 devices available more devices are loaded as you scroll down the list.

Configuring columns

The columns shown in the device list may be configured to your needs.

To show/hide standard columns

  1. In the table header, click Configure columns.
  2. In the resulting dropdown, select/clear the checkboxes for all columns as required.

The device list will reflect your changes and only show the selected columns.

To add custom columns

Moreover, you can add custom columns to show additional device properties.

  1. In the Configure columns dropdown, click Add custom column.
    Configure columns
  2. In the Header field, enter a header for the new custom column.
  3. In the Fragment path field, enter the property of the device to be shown. Nested properties will be accepted. However, for nested properties its only possible to select Cumulocity IoT standard fragments like c8y_Mobile.mcc.
  4. Switch the Add another column after saving this one toggle to active to create another custom column right after saving the current one without leaving the dialog.
  5. Click Save.

The new column will be added and displayed in the device list.

Info
While standard columns can only be shown/hidden as required, custom columns may be deleted permanently.

To delete a device from the list

  1. Hover over the row of the device you want to delete.
  2. Click the delete icon at the right of the row.
  3. Confirm the device removal. Optionally, select whether to delete child devices of the device or to delete the associated device owner. Note that it is not possible to select both options.

The device will be permanently deleted from the platform.

Important
Deleting a device means to remove the device from the Cumulocity IoT database including all its generated data. Alternatively, you can arrange all retired devices in one group, see Grouping devices). This ensures that all reports remain correct. To prevent alarms from being raised for the retired devices, disable connection monitoring. Deleting a device does not delete the data of its child devices.

To filter devices

The device list offers a filtering functionality to filter devices in the list for specific criteria.

Filtering is available on every column. Click the filter icon next to the name of the column you want to set a filter for.

Specify your filter options in the dropdown list.

Most columns represent text fields. You can filter these columns by simply entering an arbitrary text into the textbox as in the search field. Click + Add next to add another textbox if you want to filter for more than one term.

Apart from filtering for text there are several other options:

Finally, click Apply to carry out the filtering.

The devices list will now only display devices matching the filtering options.

Sorting is available on every column. Click the sort icon in the respective column header once to sort the entries in ascending order and twice to sort the entries in descending order. Click the sort icon once more to remove sorting for this column.

Click Clear filters in the table header if you want to clear all filters and view all devices.

Info
If you select to sort a text field, for example, device name, in ascending or descending order, keep in mind that the resulting alphabetical sorting is based on ASCII/UTF: A < B < … < Z < … < a < b … < z. Names starting with lower case letters will be sorted below all names with uppercase letters or vice versa.

Grouping devices

Devices can be grouped according to a particular use case. A device can be located in multiple groups and groups themselves can again be part of multiple groups.

Cumulocity IoT distinguishes between top-level groups and subgroups:

Viewing groups

Click Groups in the navigator to see all groups in a list format.

Groups list

For each group, various information is provided, for example the type and name. Click Configure columns at the right, to add or remove columns and customize the view to your preference. See also Viewing devices > Configuring columns.

To filter the groups for certain criteria, hover over the column headers and click the respective filter icon.

See also Viewing devices > Filtering devices.

Note that this function only creates a temporary filter. For permanent filters, you can use the smart groups function.

Click a group to view its details.

Subassets

Subassets page

At the top of the Subassets page, the name and the description of the group is displayed (editable), followed by the information when the group was created and last updated.

Below, all assets assigned to the group are listed. For each asset, various information is displayed, for example the type and name. As with the top-level groups list, you can add or remove columns and customize the list to your preference, or you can apply filters to filter the list for certain criteria.

Morover, you can assign devices, see To assign a device to a group.

To add a group

  1. Click Add group at the right of the top menu bar.
  2. In the resulting dialog box, enter a unique group name and an optional description and click Next.
  3. In the list, select the devices you want to add. You may apply filters to reduce the number of displayed devices.
  4. Click Create to create the new group.

The new group will be added to the groups list.

Info
A group can be created with “0” devices in it.

To add a new group as a child of an existing group, navigate to its Subassets page and click Add Group in the top menu bar.

To edit a group

  1. In the navigator, click a group to open it.
  2. In the Subassets page, you can edit the name and description of the group.

For further information on permissions, see Managing permissions in the Administration section.

To delete a group

Hover over the respective entry you want to delete and click the delete icon at the right.

Managing devices in groups

To assign devices to a group

You can assign devices to groups in several ways.

From the group perspective

You can quickly assign devices to groups by using the drag and drop functionality in the navigator, see Restructuring groups and devices.

Moreover, you can assign devices performing the following steps:

  1. In the navigator, select a group from the Group menu and then open the Subassets page.
  2. Click Assign devices at the right of the top menu bar.
  3. In the list, select the devices you want to add. You may apply filters to reduce the number of displayed devices.
  4. Click Assign to assign the selected devices.

Assign devices

The devices will be assigned to the selected group and shown as subassets in the Subassets page.

From the device perspective

  1. Select a device from the device list and open it.
  2. In the Info tab, scroll down to the Groups assignment card. From the dropdown field, select the group you want to assign the device to. You can also directly enter a group name here or you can enter just parts of a name to filter the list for it and only show the matching group names.
  3. Click Assign.

The device will be assigned to the selected group.

If you search for a group by its name which does not exist yet, a New button will appear so that you can create a new group with this name from here and assign the device to that group.

Info
In order to create a new group, the user must have the permissions ROLE_INVENTORY_CREATE and ROLE_INVENTORY_ADMIN.

To unassign a device

Hover over the respective device you want to unassign and click the unassign icon at the right.

Unassigning a device does not delete the device, subdevices or any associated data. The device is only removed from this group.

To delete a device

Hover over the respective device you want to delete and click the delete icon at the right.

The device will be permanently deleted.

To view the device details

To display the details of a particular device, click its name.

The device details for the device will be displayed.

Restructuring groups and devices

You can easily restructure groups, subgroups and devices by a drag & drop functionality.

To move a group

  1. In the navigator, select a group which you want to move to another group.
  2. Drag and drop it to the desired group.
  3. In the resulting dialog box, confirm the operation.

To move or add a device

  1. In the navigator, select the group or device which you want to move or add to another group.
  2. Drag and drop it to the desired group.
  3. In the resulting dialog box, select if you want to move or add the device.

Using smart groups

Smart groups are groups dynamically constructed based on filtering criteria. This type of group can be used, for example, for bulk upgrades of devices of a certain type to a new software or firmware version.

Info
Smart groups are only available in the Device management application and not visible in the Cockpit application.

Smart groups can be created from the device list.

To create a smart group

  1. To open the device list, click All devices in the navigator.
  2. Filter the devices in the list to select the desired devices. See Viewing devices > To filter devices for details on filtering.
  3. Click Create smart group at the right of the top menu bar.
  4. Enter a name for the group and click Create.

The new group will appear as a top-level group in the Groups menu of the navigator. Smart groups can be distinguished by a small cogwheel in the folder icon.

Below the smart group name and description you can see the filter criteria which have been applied on building the smart group. You can edit the filter settings here and adjust your selection.

Smart groups

To delete a smart group

Hover over the respective entry you want to delete and click the delete icon at the right.

Important
Deleting a smart group is irreversible.

Device details

For each device, detailed information is available. The kind of information actually provided for a device depends on the device type, device usage and the configuration of your user interface.

To view detailed information on the device, click a device in the device list.

Device info

The device details are divided into tabs. The number of tabs is dynamic and depends on the available information, that means, tabs are only displayed if the kind of information is available for the particular device. For a detailed description of the operations and fragments related to each device detail tab see the Device management library in the Reference guide.

Initially the Info tab is shown, which offers general information on a device and is available for each device.

Each device at least shows the following tabs: Info, Alarms, Control, Events, Availability, Identity (also see the tab list below).

The following tabs are the most common ones, each described in detail in a separate section:

Tab Description
Actility LoRa Provides details for devices connected via Actility LoRa. For details, see Actility LoRa.
Alarms Provides information on the alarms for a device. See Working with alarms. Available for each device.
Availability Allows the availability monitoring of machines. For details, see Availability. Available for each device.
Child Devices Lists devices being connected to the current device.
Configuration Allows manual configuration of device parameters and settings entered in a text format. For details, see Managing configurations for binary configuration.
Connectivity Provides SIM management functionality. For details, see Connectivity.
Control Displays operations being sent to a device. Also refer to Working with operations. Available for each device.
Device profile Shows the details of the currently installed profile on a device.
Events Displays events related to a device, helpful for low-level troubleshooting. Also refer to Troubleshooting devices. Available for each device.
Fieldbus Provides details for fieldbus devices. For details, see Cloud Fieldbus.
Firmware Manages firmware of a device. See Managing firmware on a device.
Identity Displays identities recorded for a particular device. Available for each device.
Info Provides general information on a device. Available for each device.
LWM2M Provides details for devices connected via LightweightM2M. For details, see LightweightM2M.
Location Shows the location of a device, if available.
Logs Allows requesting log information for a device.
Loriot LoRa Provides details for devices connected via Loriot LoRa. For details, see Loriot LoRa for more details.
Measurements Provides a default visualization of numeric data provided by the device in the form of charts.
Network Displays network information for a device.
OPC UA server Provides details for devices connected via an OPC UA server. For details, see OPC UA.
Services Provides an overview of the services running on a device.
Shell Enables you to interact with remote devices via a command prompt.
Sigfox Provides details for devices connected via Sigfox. For details, see Sigfox for more details.
SNMP Provides details for devices connected via SNMP. For details, see SNMP.
Software Manages software installed on a device. For details, see Managing software on a device.
Tracking Shows the movement of a device, if available.
Info
Several individual tabs, which you do not find listed here, may be described in a different context in another section of the Cumulocity IoT documentation. Use the Search function to switch to the relevant sections. A detailed description on the Modbus tab, for example, can be found in Cloud fieldbus in the Protocol integration guide.

Below the name, a list of breadcrumbs is displayed. If the device is part of an asset hierarchy (such as a group), you can use the breadcrumbs to easily navigate up that hierarchy. Since devices can be part of multiple hierarchies, several rows of breadcrumbs may be shown.

Depending of the type and usage of a device, further actions are provided in an action menu when clicking More… at the right of the top menu bar.

More menu

Details on these additional menu items are provided where required.

Alarms

The Alarms tab provides information on the alarms of a device. See Working with alarms for detailed information on alarms.

Availability

The Availability tab offers availability monitoring for machines, see Monitoring and controlling devices > Availability for more information.

Child devices

The Child devices tab shows a list of devices connected to the currently displayed device. For example, if you look at a gateway, the tab lists all machines connected to the gateway.

For details provided in the child device list, see Viewing devices.

Configuration

The Configuration tab allows you to configure the parameters and initial settings of your device. Depending on the device, possible configurations are:

For more details on managing binary-based configuration snapshots, see Managing device data > Managing configurations.

To request the current text-based configuration snapshot

  1. Navigate to the Configuration tab.
  2. Select one of the device-supported configurations in the list.
  3. Click Get snapshot from device.

To add or edit a text-based configuration snapshot

  1. In the Configuration tab, you can manually add or edit the device configuration in the text field.
  2. Click Send configuration to device to save your edits.

Text-based configuration

Info
If a device supports both text-based and binary-based configuration the Configuration tab shows a subtab for each configuration type.

Control

The Control tab lists the operations being sent to a device. See Working with operations for detailed information on operations.

Operations

Device profile

See Applying device profiles to devices for more information on how to apply device profiles to a device.

Events

The Events tab displays events related to a device. This enables low-level troubleshooting of a device. See Troubleshooting devices for detailed information.

Firmware

See Managing firmware on a device for more information on how to manage and update the firmware on a device.

Identity

Cumulocity IoT can associate devices and assets with multiple external identities. For example, devices can often be identified by the IMEI of their modem, by a micro-controller serial number or by an asset tag. The Identity tab lists all the identities recorded for a particular device.

This is useful, for example, when you have non-functional hardware and must replace the hardware without losing the data that was recorded. Just connect the new hardware to your account and modify the identity entry of the old hardware, to contain the identity of the new hardware.

Info

The Info tab summarizes management-relevant device information in a dashboard.

Device Info

The information is provided on the following cards:

Card Description
Notes Provides optional notes to inform about current activities. Notes usually may only be edited by an administrator. To add or edit a note, click Edit, enter your note or your modifications in the text box and save your edits by clicking the green checkmark at the right of the text box.
Device status Displays connection-relevant information, as described in detail in Connection monitoring.
Device and communication Shows a data point graph displaying real-time data on particular measurements. Drag the x-axis to move the data point time measurement. To zoom in select a time period, double click to zoom out of the graph. For details on data point graphs, refer to Using the data explorer in the Cockpit documentation.
The following measurements may be shown here:
Data points: c8y_Battery.level, c8y_SignalStrength.rssi, c8y_MemoryMeasurement.Used, c8y_CPUMeasurement.Workload, c8y_NetworkStatistics.Upload, c8y_SignalStrength.RCSP, c8y_SignalStrength.ber, c8y_SignalStrength.ECN0, c8y_NetworkStatistics.Download, c8y_MemoryMeasurement.Total
Alarms: c8y_UnavailabilityAlarm
Events: c8y_LocationUpdate
Device data Displays general information on the device (ID, name, type, owner, last update). The fields Name and Type can be edited. Below the general device information, the card shows status information for active alarms, availability and connection (not editable). Moreover, various device-specific information like hardware and firmware is displayed here (editable).
Active, critical alarms Shows the active critical alarms for the device.
Groups assignment Displays the groups the device belongs to. Moreover you can add the device to groups here or unassign it from groups, see Grouping devices.
Location Shows the location of a device on a map as reported by the device or as manually set, see Location.

Location

The Location tab by default shows the location of a device on a map and as coordinates, as reported by the device. For devices that do not report a location you may manually set the location. Simply place the “pin” in the correct place of the displayed map.

Location tab

The Location tab also shows when a device contains c8y_Position property. When you send a new c8y_Position event, you can set the same c8y_Position fragment on the device and it will automatically mark its position on the map.

Logs

In the Logs tab you can manage log information from devices.

To request log information

  1. In the Logs tab, click Request log file at the right of the top menu bar.
  2. In the resulting dialog box, specify a date and time range for the log information.
  3. Select the type of log from the dropdown field. The supported logs listed are usually device-specific.
  4. Optionally, specify a text filter. For example, if you enter “Users”, only lines including the term “Users” will appear in the returned log information.
  5. Specify the maximum number of lines to be returned (counted from the end). The default value is 1000.
  6. Click Request log file.

The log information will be requested from the device.

Logs tab

Requesting a log from a device may take some time.

After the log has been transferred from the device to Cumulocity IoT, it will be listed in the Logs tab. The row in the list shows the requested log time range.

Click on the entry in the list to show the entire log information.

To download a log

Hover over a row and click the download icon, to download the log excerpt to your file system.

To delete a log

Hover over a row and click the delete icon, to delete the log information.

Measurements

The Measurements tab provides a default visualization of numeric data provided by the device in the form of charts. Charts are grouped into types of measurements, which can contain multiple graphs or “series”.

The screenshot below, for example, shows a chart for temperature measurement with two different series.

Measurements

If a chart contains measurements with different series, one Y-axis is rendered per series. In the example above, temperature data is recorded from two sensors namely “sensors-1” and “sensor-2” having the same unit as °C. Here measurements from different sensors are categorized as separate “Series” data. The measurements from the respective sensors are stored using separate series names (same as the sensor names) and hence, two axes are rendered here. Only one Y-axis is rendered if the measurements belong to the same series.

To see detailed information about the measured values, hover over the chart. A tooltip will be displayed with detailed information on the measurement next to your cursor (the tooltip will “snap” to the closest measurement).

Info
We recommend you to have max. 20 series per measurement for optimal performance and readability of a single graph in Device management (the graph displays all available series). If you need to display only a few series from the measurement, we advise you to use Data explorer in Cockpit where you can select series to be shown in the graph.

Time range and aggregation

By default, charts show the raw data of the last hour. To change the time range on the X-axis, open the “Last hour” dropdown menu at the top right and select a time range.

If you increase the time range, the value in the Aggregation field will automatically switch to “hourly” or “daily”. The chart now shows ranges instead of individual raw data points. For “hourly”, the chart will show a range of the minimum and maximum value measured in one hour. For “daily”, the chart will show the minimum and maximum value measured over one day. Likewise, the tooltips will now show ranges of values instead of individual values.

This enables you to get an efficient overview over larger time periods. A graph will only show 5.000 data points per graph maximum to avoid overloading your desktop browser. If you select a fine focus resulting in more than 5.000 data points, a warning message will be shown: “Truncated data. Change aggregation or select shorter date range.”

Clicking Realtime will enable real-time user interface updates of the graphs as new data flows into the system from the connected devices.

You can influence the graphical display and axes limits by setting up so-called “KPIs”, see the Administration Guide.

Measurement format

In order to see measurement graphs, the device must send measurements in a specified fragment format.

"fragment_name" : {
	"series_name" : {
		"value" : ...
		"unit" : ...
	}
}

Example:

"c8y_SpeedMeasurement": {
      "Speed": { "value": 1234, "unit": "km/h" }
}

"Fragment_name" and "series_name" can be replaced by different valid JSON property names, but no whitespaces and special characters like [ ],* are allowed. The structure must be exactly as above, two-level deep JSON object.

Network

In the Network tab, mobile network (WAN) and local area network (LAN) parameters can be viewed and configured.

Network tab

The WAN parameters in the user interface correspond to the first profile stored in the router. These parameter can be configured remotely or via SMS.

Info
For SMS configuration, the router needs to be configured to accept SMS commands.

To configure WAN parameters

  1. Enter the Access Point Name (APN).
  2. Enter the username and the password of your account in the platform to which you wish to establish a connection.
  3. Select the authentication type.
  4. Click Save to save your settings.

To configure LAN parameters

To configure LAN parameters, simply enter IP address and Subnet mask.

Info
Name and Mac address fields are not configurable.

To configure DHCP parameters

  1. Enter the address range in which the connection can be established.
  2. Enter the DNS.
  3. Enter the DNS 2.
  4. Enter the domain name.
  5. Click Save to save your settings.
Info
If the LAN configuration is disabled, the DHCP configuration is automatically disabled as well.

Services

The Services tab provides a list of all services running on a device with their status, name, type and date of the last update. Every column allows services to be filtered and/or sorted by the respective value displayed.

Services overview

The platform defines three status options for services: Up, Down and Unknown. These predefined statuses have their own graphical representation and can be selected directly from the Status filter. Other status options are also allowed and can be freely defined, see Service module in the Web SDK documentation resources. They all share the same icon and must be entered manually in the Status filter. A tooltip on the status icon displays their actual value.

Shell

The device shell enables you to interactively work with remote devices. Many industrial devices support some form of command language, like AT commands for modems, CSV-style commands for many tracking devices or elaborate scripting mechanisms such as Tixi TiXML. In the shell, you can send commands in the respective language of the device and interactively view the results of the commands.

The Shell tab presents a command prompt to enter commands.

In the command prompt you can enter arbitrary command text. To send the command text to the device, click Execute. This button only is activated once the command is written in the text area.

Device shell

Important
When using Cumulocity IoT to remotely operate machinery, make sure that all remote operations follow the safety standards and do not cause any harm.

For your convenience, Cumulocity IoT provides several frequently used commands for some devices. Click Predefined commands above the command prompt area to open a window containing a list of available pre-defined commands. Select the command of your choice and click Use, to copy the command to the command prompt. You may also add new commands here for re-use.

Software

See Managing software on a device for more information on how to manage and update the software installed on a device.

Tracking

Devices can record the history of their movements in Cumulocity IoT. This movements may be viewed in the Tracking tab.

Info
The Tracking tab only shows up when a device contains c8y_Position property.

In the dropdown list at the top right you can select a time period (or specify one by selecting “Custom- from the list) and visualize the movements of the device during this period. Movements are shown as red lines in the map.

Tracking tab

Next to the map, the individual recordings with their time are listed (“location update events”). When you click a recording, a “pin” on the map will show the location at the time of the recording.

Depending on the type of device and the integration into Cumulocity IoT, you can configure device-side geo-fencing and motion detection.

Monitoring and controlling devices

Locating devices

Cumulocity IoT provides the option to view all devices in your account on a map.

Click Map in the Devices menu in the navigator to display a map showing all devices in real time.

Devices are represented as “pins”. Click a pin to see the name of the respective device. Click the device name to switch to its device details.

Device map

Connection monitoring

In the Device management application you can monitor the connections to your devices.

This can be done at the level of individual devices (see below) or across multiple devices in a list.

To monitor the connection for multiple devices

Open a device list to monitor the connections for multiple devices.

The connection status is represented by arrows in the Status column in the device list.

Connection Status

Send connections

The top arrow represents the send connection (traffic from the device to Cumulocity IoT). The status for the send connections may be one of:

Hovering over the arrow displays the timestamp of the last request from the device to the server.

When a device is detected to be offline (stops sending data within required interval and top arrow changes to red color), an unavailability alarm is created for the device: “No data received from device within required interval”.

Send connections are updated when something is sent from the device, such as alarms, events, measurements or if a blank update is sent to the device itself. For details see Device management library > Device availability > Availability monitoring in the Reference guide.

Info
Empty PUT requests to the managed object of the device will also update a send connection. Such requests are the recommended way of implementing a heartbeat service that monitors the server status.

Push connections

The bottom arrow represents the push connection (from Cumulocity IoT to the device). The status for the push connections may be one of:

A push connection is an active HTTPS long poll connection to the /notification/operations API endpoint or an active MQTT connection to the MQTT endpoint of Cumulocity IoT. It is always green if the device is connected, even without data.

Info
Connection monitoring is not real time. This means that the displayed connection status will not change immediately after switching off a device. Depending on the used protocol for push connection monitoring this can take a couple of minutes.

Maintenance mode

Moreover, the device may be in “Maintenance” mode, indicated by the tool icon in the Status column. This is a special connection status indicating that the device is currently being maintained and cannot be monitored. While a device is being maintained, no alarms for that device are raised.

You can turn the maintenance mode on or off for a device through a toggle in the Connection monitoring card in its Info tab, see below.

To monitor the connection of a particular device

Navigate to the Info tab of a particular device to monitor the connections of this device. Under Device status, the connection status for the device is displayed.

Device Status

Below the send connection and push connection status, the time of the last communication is displayed.

Info
“Last communication” and “Last updated” are two entirely different time stamps. “Last communication” indicates when a device has last sent data. “Last updated” indicates when the inventory entry of the device was last updated. This update may have originated from the device, from the web user interface or from another application.

In the Required interval field you can specify an interval. This parameter defines how often you expect to hear from the device. If, for example, you set the required interval to 60, you expect the device at least to communicate once in an hour with Cumulocity IoT. The interval is either set by the device itself, based on the device’s knowledge how often it will try to send data, or it is set manually by you.

If an interval is set, you will find the Maintenance toggle below it.

With the Maintenance toggle you can turn the maintenance mode for the device on or off which is immediately reflected in the connection status.

Availability

Cumulocity IoT distinguishes between connection monitoring and availability. Connection monitoring, as described in the previous section, only indicates if the device is communicating with Cumulocity IoT, it does not automatically indicate if it is functional or not.

Availability indicates if a device is in service. For example, a vending machine is in service if it is ready to sell goods. A vending machine can sell goods using cash money without a connection to Cumulocity IoT. From the perspective of a merchant, it is in service. Similar, if you switch off the power on a gateway, the devices behind the gateway can still continue to work.

Cumulocity IoT considers a device to be in service while there is no critical, unresolved alarm present for the machine. This is displayed as a share of time such an alarm was present. If a machine didn’t have any critical alarms whatsoever during a time period, it was 100% in service. If half of the time there was some critical, unresolved alarm, the machine was 50% in service.

While a machine is offline, Cumulocity IoT assumes by default

There may be exceptions from this rule. If your vending machines rely exclusively on cashless payment, losing the connection to the network means that your machine is out of service and stops selling. In this case, unavailability alarms must be set in the Administration application which have CRITICAL severity instead of MAJOR severity.

Cumulocity IoT displays service availability at the level of individual devices and across all devices.

To view the availability of a particular device

Click the Availability tab in the details of a particular device to check the availability of this device.

To view the availability across all devices

Click Availability in the Device menu in the navigator to display the overall service across all devices.

Availability

The Availability page shows the availability of devices for the last 24 hours, last 7 days and last 30 days in percentage.

Working with alarms

Devices can raise alarms to indicate that there is a problem requiring an intervention.

To view alarms

Cumulocity IoT displays alarms at the level of individual devices and across all devices:

Alarms page

By default,

Alarms are classified according to their severity. Cumulocity IoT includes four different alarm types:

Severity Description
CRITICAL The device is out of service and should be fixed immediately.
MAJOR The device has a problem that should be fixed.
MINOR The device has a problem that may be fixed.
WARNING There is a warning.

The Alarm tab is split into four sections corresponding to these alarm types.

In the top menu bar, buttons are provided to filter for severity. By clicking a button, the corresponding section will be hidden. Click it once more to make it visible again.

Info
The number provided on the buttons in the top menu bar refers to the number of active alarms for the given severity, as opposed to the counter provided as red circle next to an active alarm, which shows the number of times this same alarm has occurred (see also the table below).

Within each section, the alarms are sorted by their occurrence, displaying the most recent alarm first.

In each row, the following information for an alarm is provided:

Info Description
Severity One of CRITICAL, MAJOR, MINOR, WARNING (see above).
Count (provided as number in a red circle) The number of times this alarm was sent by the device. Only one alarm of a particular type can be active for a certain device. If another alarm of the same type is sent by the device, the number is increased by 1.
Description An arbitrary text describing the alarm.
Status The status of the alarm. An alarm can be:
Active: When it was raised and nobody is so far working on the alarm.
Acknowledged: When someone changed the status to "Acknowledged" to indicate that someone is working on the alarm.
Cleared: When either someone manually set the status to "clear" or when the device detected by itself that the problem has gone.
Last occurrence Timestamp of the last occurrence of the alarm (device time).
Device The name of the device. Clicking the name leads you to the detailed view of the device.

Click the arrow on the right of a row to expand it and display further details on the alarm.

To change the status of an alarm

To change the status of an alarm, hover over it and click the button for the desired status or click the menu icon and select the desired status. It is also possible to change the status of all alarms to “clear” at once. Click Clear all in the top menu bar, to clear all alarms of the selected severities.

Working with operations

Operations are used to remotely control devices.

You can view operations at the level of individual devices and across all devices:

There are two types of operations in Device control, each represented by a tab:

To view single operations

See the list of single operations in the Single operations tab.

Single operations list

Single operations can have one of the following four statuses:

Status Description
PENDING The operation has just been created and is waiting for the device to pick it up.
EXECUTING The operation has been picked up by the device and is being executed.
SUCCESSFUL The operation has been successfully executed by the device.
FAILED The operation could not be executed by the device.

In each row, the following information for an operation is provided:

Info Description
Status One of PENDING, EXECUTING, SUCCESSFUL, FAILED (see above).
Name Name of the operation.
Device The name of the device. Clicking the name leads you to the detailed view of the device.

Clicking a row expands it and displays further details on the operation.

To filter the list of single operations by status, click one of the status buttons in the top menu bar. Click All to clear the filter.

Click Realtime at the right of the top menu bar to see operations coming in from the devices in realtime. Click Reload to update the list once manually.

Info
Single operations are listed in descending time order. Operations are executed strictly according to this order.

To add and execute a single operation

Single operations can be created either from bulk operations or via the different types of operations that the device supports: managing firmware, software, configurations and more.

When you create a bulk operation, the single operations entailed in the bulk operation are also added to the list of single operations.

Operations for a specific device can also be created and executed in the Shell tab of the device, see Device details > Shell.

Important
When using Cumulocity IoT to remotely operate machinery, make sure that all remote operations follow the safety standards and do not cause any harm.

To cancel pending single operations

You can cancel particular pending single operations or all pending single operations at once.

To cancel a particular pending single operation, click the menu icon at the right of the respective single operation entry and select Cancel operation.

To cancel all pending operations at once, click More… at the right of the top menu bar and select Cancel all pending operations. Alternatively, filter the list of single operations to show only single operations with status PENDING, then click Cancel all at the right of the top menu bar.

To create a smart rule from a single operation

Click the menu icon at the right of the single operation that you want to create a smart rule for, and select Create smart rule.

See Cockpit > Smart rules > To create a smart rule for further steps.

To view bulk operations

See the list of bulk operations in the Bulk operations tab.

Bulk operations list

Bulk operations have an operation type and status.

You can add bulk operations of the following operation types with the bulk operation wizard:

Operation type Description
Configuration update The bulk operation updates the configuration of the selected devices.
Firmware update The bulk operation updates the firmware on the selected devices.
Software update The bulk operation updates the software on the selected devices.
Apply device profile The bulk operation applies a device profile on the selected devices.

Bulk operations can have other operation types as well, for example when you schedule a single operation as bulk operation and the single operation has a different operation type.

Bulk operations can have one of the following statuses:

Status Description
SCHEDULED The bulk operation has been created and is on hold until the scheduled time.
EXECUTING The bulk operation is being executed.
CANCELED The bulk operation was created but canceled before the scheduled time.
COMPLETED WITH FAILURES The bulk operation completed with failures for some devices.
COMPLETED SUCCESSFULLY The bulk operation has been successfully executed on all devices.

In each row, the following information for a bulk operation is provided:

Info Description
Status One of SCHEDULED, EXECUTING, CANCELED, COMPLETED WITH FAILURES, COMPLETED SUCCESSFULLY (see above).
Name Name of the operation.
Progress bar Only for executing and completed bulk operations. Shows the operation’s progress in percent.
Start and finish dates Only for executing and completed bulk operations. For executing bulk operations, the finish date is an approximation based on the bulk operation settings.
Refresh button Only for executing bulk operations. Updates the progress bar.

Clicking the arrow button at the right in a row expands the row and displays further details on the bulk operation.

To filter the list of bulk operations by operation type, click the dropdown list in the top menu bar and select a set of operation types, then click Apply. To clear the filter, select All in the dropdown list and click Apply once more.

To filter the list of bulk operations by status, click one of the status buttons in the top menu bar. Click All to clear the filter.

To filter the list of bulk operations by date, select a date in both the Date from and Date to datepickers, then click Apply right next to it. To clear the filter, click Clear right next to it.

To clear both filters, click Reset filters at the bottom of the list (only visible if filters are applied).

To add a bulk operation

There are two ways of creating a bulk operation:

To add a a bulk operation using the wizard

Follow these steps:

  1. In the Bulk operations tab, click New bulk operation at the right of the top menu bar.
  2. In the resulting dialog, select an operation type.
  3. The resulting wizard has four steps. The first two steps differ depending on the operation type:
  1. Select target devices by applying filters to the paginated list of all devices. You can filter by status, name, type, model, group, registration date and alarms. You may apply multiple filters. To apply a filter, click the column header, make your filter option choices in the context menu and click Apply. The group filter also allows filtering by subgroups. To select a subgroup, if there are any, click the arrow button at the right of a group and select the desired subgroups from the dropdown. You can clear all filters by clicking Clear filters above the list. For the operation types “configuration update”, “software update” and “apply device profile”, the list is already filtered by the according device type. Click Next.
  2. Enter a new title or use the preset title. Optionally enter a description. Select a start date and a delay. The delay may either be in seconds or milliseconds and is the time spent between each single operation of the bulk operation. Click Schedule bulk operation to create the bulk operation.

To schedule a single operation as bulk operation

You can schedule a single operation as a bulk operation either from the Single operations tab or from a Control tab of a particular device. Follow these steps:

  1. Click the menu icon at the right of the single operation that you want to schedule as a bulk operation and then click Schedule as bulk operation.
  2. The resulting wizard is similar to the new bulk operation wizard described in To add a bulk operation using the wizard. However, there are just two steps because the operation type is inferred from the operation that is scheduled as a bulk operation. See the description of the full wizard and follow it.

To edit the schedule of bulk operations

You may only edit the schedule of bulk operations with status = SCHEDULED.

  1. Click the menu icon to the right of the bulk operation that you want to edit, and then click Edit schedule.
  2. In the resulting dialog box you may change the Start date and Delay values.
  3. Click Reschedule to apply your changes.

The changes are applied to the bulk operation accordingly.

To cancel bulk operations

You may only cancel bulk operations with status = SCHEDULED or EXECUTING. If it is executing, you may only cancel the operation until all of its single operations are created. This way, you can cancel the creation of the remaining single operations.

Click the menu icon to the right of the bulk operation that you want to cancel, then click Cancel bulk operation.

To retry failed operations

You may retry the failed operations of a bulk operation that is either executing or completed with failures.

To do so, expand the desired bulk operation, then click Retry failed operations under Operations to create a new bulk operation with all failed operations. To retry a single operation, hover over the operation and click Retry operation. This will create a new single operation.

For a bulk operation that completed with failures, you may also click the menu icon to the right of the operation, then click Retry failed operations.

To manually set failed bulk operations to successful

You may manually set a failed bulk operation to the status SUCCESSFUL.

To do so, click the menu icon to the right of the bulk operation, then click Set operation to successful.

This may be useful if the operation is generally a success, but contains operation failures on devices that are not too important. These failures would otherwise still leave the bulk operation in status FAILED.

Troubleshooting devices

Troubleshooting devices at a more detailed level can be done with the help of events. Events are low-level messages sent by devices that are usually used for application-specific processing. For example, a vending device sends its real-time sales in the form of events.

To view events

Cumulocity IoT displays events at the level of individual devices and across all devices:

Events

Per default, events are shown as coming in from the devices in real time. To disable real-time updates, click Realtime at the right of the top menu bar.

For each event, the following information is provided:

Info Description
Timestamp Timestamp when the event has been executed.
Name Name of the event.
Device The name of the device sending the event. Clicking the name leads you to the detailed view of the device.

In the event list, the latest entry is displayed on top.

Clicking a row expands it and displays further details on the event (as type and position of the device).

Since devices may send large amounts of event data, you can filter the data to be displayed by date.

Select a start date and an end date from the fields in the top menu bar and click Apply to apply the filter. Click Clear to clear the filter again.

Monitoring device services

The Device management application lets you monitor the data that your devices send about the services they are running.

The Services tab on the device details view provides an overview of the services running on a given device and acts as an entry point to the service details view. There you can see detailed information about measurements, events and alarms sent for every service.

Service details

The following tabs make up the service details view, each described in detail in a separate section:

Tab Description
Alarms Provides information on the alarms for a service. See Working with alarms. Available for each service.
Events Displays events related to a service. Available for each service.
Measurements Provides a default visualization of numeric data of the service in the form of charts.

Alarms

The Alarms tab provides information on the alarms of a service. See Working with alarms for detailed information on alarms.

Info
The service details Alarms tab displays only alarms which have the particular service as a source. It does not display any alarms sourced by the device itself.

Events

The Events tab displays events related to a service. See Troubleshooting devices for detailed information.

Info
The service details Events tab displays only events which have the particular service as a source. It does not display any events sourced by the device itself.

Measurements

The Measurements tab provides a default visualization of numeric data for the service in the form of charts.

Info
The service details Measurements tab displays only measurements which have the particular service as a source. It does not display any measurements sourced by the device itself.

For more information about how to use the Measurements tab see Measurements.

Managing device types

To process data from various device types, Cumulocity IoT uses device protocols which are stored in a database.

Click Device protocols in the Device types menu in the navigator.

In the Device protocols page you will find a list with all device protocols available in your account.

Device protocols

The device protocol list shows the following information:

To add a device protocol

  1. Click Add device protocol in the top menu bar.
  2. Select one of the available device protocol types from the list.
  3. In the resulting dialog box, enter a name and an optional description for the device protocol and click Create.
  4. Enter the configuration for the device protocol. The configuration of the device protocol depends on the protocol type.
    For details on configuring device protocols, follow the documentation of the particular device type you want to create, see Protocol integration guide.
  5. Click Save.

The device protocol will be added to the device database.

To import a device protocol

To add a device protocol from an existing protocol, perform the following steps:

  1. Click Import in the top menu bar.
  2. Either select the device protocol to be imported from a list of predefined protocols or load it from a file by browsing.
  3. Provide a name for the new protocol and click Save.

The device protocol will be added to the device database.

To edit a device protocol

To edit a device protocol, just click on the protocol or click the menu icon at the right of the row and then click Edit.

Details on the fields can be found in the documentation of the particular device type, see Protocol integration guide.

To delete a device protocol

To delete a device protocol, click the menu icon at the right of the row and then click Delete.

The device protocol will be deleted from the device database.

To export a device protocol

To export a device protocol, click the menu icon at the right of the row and then click Export.

The device protocol will be exported to your file system.

Managing device data

Overview

The Device management application provides various features that support you in efficiently managing your devices:

Feature Description
Managing device firmware How to retrieve and manage firmware, firmware versions, and patches in the firmware repository and how to install or update them on devices.
Managing device software How to retrieve and manage software and software versions in the software repository and how to install or update them on devices.
Managing configurations How to retrieve configuration data, store and manage it in a configuration repository as configuration snapshot.
Managing device credentials How to manage all credentials generated for your connected devices.
Managing device profiles How to manage device profiles - a set of firmware, software, and configuration - and apply them to devices.
Managing trusted certificates How to manage trusted certificates.

All features are accessible through the Management menu in the navigator:

Management menu

Managing device firmware

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

Only one firmware package version can be applied per device.

Viewing 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 Getting started > UI functionalities and features > Filtering.

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).

Adding firmwares, firmware versions, or firmware patches

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 pencil icon next to it. Make the desired changes and click Save.

The firmware will be updated accordingly.

Deleting firmwares, firmware versions, or firmware patches

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.

Managing 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 device software

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

Viewing 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 menu icon at the right of a specific software item and in the context menu click Edit.
  2. Update the name, description, device type filter or software type by clicking the pencil icon next to it. Make the desired changes and click Save.

The software will be updated accordingly.

Deleting software items or software versions

To delete a software

Click the menu 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.

Managing 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 Device management library > Configuration in the Reference guide 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 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 device 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 device 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 pencil 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 pencil 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.

Applying 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 Monitoring and controlling devices > Working with operations > 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.

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 integration using MQTT > Device certificates in Device integration.

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:

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.
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 menu icon at the right of the respective entry and in the context menu click Delete. The certificate will be permanently deleted.

SmartREST templates

Introduction

SmartREST templates are a collection of request and response templates used to convert CSV data and Cumulocity IoT Rest API calls. For example, you can use SmartREST templates to easily add devices to the platform instead of manually writing the requests each time.

To ease the device integration, Cumulocity IoT supports static templates that can be used without the need for creating your own templates. These templates focus only on the most commonly used messages for device management.

Open the SmartREST template page from the Device Types menu in the navigator.

template view

For each template, the following information is provided:

There are two ways to add a SmartRest template:

To import an existing SmartREST template

  1. Click Import template at the right of the top menu bar.
  2. In the resulting dialog box, select a file to upload by browsing for it.
  3. Enter a template name and a unique template ID (both mandatory fields).
  4. Click Import to import the template.

To create a new SmartREST template

  1. Click Create template at the right of the top menu bar.
  2. In the resulting dialog box, enter a template name and a unique template ID (both mandatory fields).
  3. Click Continue to proceed adding messages or responses.

To add a message

The message template contains all necessary information to convert the SmartRest request into a corresponding Rest API call which is then sent to the platform.

  1. To add a new message, navigate to the Messages tab in your desired SmartREST template and click Add message.

  2. Complete the following fields:

    Field Description
    Message ID Unique integer that will be used as a message identifier. It must be unique among all message and response templates.
    Name Name for the message. Mandatory.
    Target REST API REST API for the target. Dropdown list. May be one of Measurement, Inventory, Alarm, Event, Operation.
    Method Request method. May be one of POST, PUT, GET, depending on the selected Target REST API.
    Include Responses Select this checkbox if you want to process the results of the request with response templates.
    REST API built-in fields These fields are optional and vary depending on the target REST API selected. In case no value is provided, a device will be able to set it when sending an actual message.
    REST API custom fields Additional fields can be added by clicking Add field. Enter the API key and select the desired data type.

    Add message

    Under Preview you can see a preview of your request message.

  3. Click Save.

The message will be added to the SmartREST template.

To remove a message

To remove a message, open it and click Remove at the bottom.

The message will be removed from the SmartREST template.

To add a response

A response template contains the necessary information to extract data values from a platform REST API call response, which is then sent back to the client in a CSV data format.

  1. To add a new response, navigate to the Response tab in your desired SmartREST template and click Add response.

  2. Complete the following fields:

Field Description
Response ID A unique string that will be used as a response identifier.
Base Pattern Path in a JSON document. The base pattern acts as a prefix to all patterns. You can enter either a base pattern here and add patterns with only the subpath below the base pattern, or leave this field empty and provide patterns with the full path.
Condition Condition value of the response.
Pattern At least one pattern is required. Click Add pattern and enter a pattern value.

Add template with filled out response

  1. Click Save.

The response will be added to the SmartREST template.

For further information see SmartREST 1.0 > Templates > Response templates in the Reference guide.

To remove a response

To remove a response, open it and click Remove at the bottom.

To edit a SmartREST template

Either click the desired template or click the menu icon at the top right of the respective template card and then click Edit.

After editing the template, click Save to save your settings.

To delete a SmartREST template

Click the menu icon at the top right of the respective template card and then click Remove.

To export a SmartREST template

Click the menu icon at the top right of the respective template card and then click Export.

The template will automatically be downloaded to your file system.

To export a SmartREST template as CSV file follow these steps:

  1. Open the template you want to export and select the CSV preview tab.
  2. In the resulting dialog box, specify the preferred options for the field separator, decimal separator and character set.
  3. In the CSV preview tab, which provides additional information on messages and responses, click Copy to clipboard.

The SmartREST template will be exported as CSV file.

Working with simulators

With the Cumulocity IoT simulator all aspects of IoT devices can be simulated, such as:

About simulators

With the simulator you can create devices that simulate the same level of functionality as connected hardware devices.

A simulator uses a playlist to simulate messages that the device sends to the Cumulocity IoT platform. A playlist is a series of instructions that the simulator executes one after the other. When the last instruction is reached, the simulator starts again with the first one.

An instruction can either send a message (measurements, alarms, events and inventory) or wait for a specified time (sleep).

A message is defined by choosing a message template (like sending a temperature) and providing the values for this template (for example 23.0 degrees). Many predefined message templates are provided, for example, for creating a measurement, sending an event, creating and cancelling an alarm. These templates are based on MQTT static templates. Additionally, custom message templates can be defined using the SmartREST template editor.

To view simulators

Click Simulators in the Devices menu in the navigator to open the Simulators page.

Simulator page

All simulators which you can access will be listed here.

To create a simulator

  1. Click Add simulator at the right of the top menu bar.
  2. In the resulting dialog box, select a simulator type from the dropdown list in the Presets field. Select “Empty simulator” to create a simulator from scratch or select one of the sample simulators.
  3. Enter a name for the simulator.
  4. Select the number of instances for this simulator (up to ten).
  5. Click Create.

The simulator will be created and added to the list.

To edit a simulator

  1. Click the menu icon at the top right of a simulator card and then click Edit, or simply click the simulator card.
  2. In the resulting dialog box, make the relevant changes.
  3. Click Save to apply your changes.

To duplicate a simulator

  1. Click the menu icon at the top right of a simulator card and then click Duplicate.
  2. In the resulting dialog box, provide a name for the new simulator.
  3. Click Duplicate.

The new simulator will be added to the list.

To remove a simulator

  1. Click the menu icon at the top right of a simulator card and then click Remove.
  2. In the resulting dialog box, confirm to remove the simulator.
  3. Click Save.

The simulator will be removed from the list.

Instructions

For each simulator, you can create instructions specifying what the simulator is supposed to do. Instructions are single tasks added to a playlist through which the simulator will work.

Instructions can be viewed and edited on the Instructions tab of the simulator.

Add Instructions

Examples

The simulator presets already contain sample instructions. For example, the “Temperature measurement” preset contains instructions for the steps “Create measurement” and “Sleep”, see image above.

The panel at the right changes according to the type of instruction selected at the left.

Fragment

The measurement instruction refers to a fragment. Fragments are used to identify capabilities of a managed object. Find more details about fragments in Sensor Library in the Reference guide.

The “Sleep” instruction requires one value for its duration in seconds.

To add an instruction

  1. Click Add instruction to add a new instruction to the simulator.
  2. In the resulting dialog box, select a message from the dropdown list.
  3. Specify the required parameters, depending on the message type.
  4. Click Save.

The new instruction will be added to the simulator.

To add a sleep

  1. Click Add sleep to add a new instruction to the simulator.
  2. In the resulting dialog box, specify the duration.
  3. Click Save.

The new sleep instruction will be added to the simulator.

To remove an instruction

Hover over the instruction or the sleep you want to remove and click the remove icon.

The instruction will be removed from the simulator.

Supported operations

In the Supported operations tab of a simulator you can find specific operations like configurations or software/firmware updates.

Supported operations

Click the toggle to turn the respective operation on or off.

To add a custom operation

  1. Click Add custom operation to specify a customized operation.
  2. In the resulting dialog box, Enter the custom operation type to be supported by the simulator.
  3. Click Add.

The custom operation will be added to the operation list.

Alarms (simulator)

The Alarm tab of a simulator displays alarms related to the simulator itself, not related to the simulated device, that is, if the simulator itself does not work correctly. See Working with alarms for information on alarms.

Alarms

Connectivity

The Connectivity agent, which works from within the Cumulocity IoT Device management application, provides basic information on mobile devices and additional connectivity details.

The Cumulocity IoT platform integrates with the SIM connectivity platforms Comarch, Ericsson, Jasper and Kite.

The following features are supported by these providers:

Feature Comarch Ericsson Jasper Kite
Check the status of the SIM card in the device x x x x
Check the online status of the device as reported by the network x x x x
Change SIM card status, for example activate or deactivate it x x x x
Disconnect SIM card from current session x
Communicate with the device through text messages, for example, to set APN parameters x x x
View summary usage of data traffic, text messages and voice calls x x x x
View usage details of data traffic, text messages and voice calls x x
View the history of data sessions and any changes to the SIM card or traffic   x

As you can see, Jasper currently is the most feature-rich provider.

Each provider requires either ICCID or MSISDN to be set in the c8y_Mobile fragment of the managed object. This is used to properly map the managed object in Cumulocity IoT to the associated SIM on the respective provider’s platform.

Requires Comarch Ericsson Jasper Kite
ICCID x x x
MSISDN x

The following description is primarily based on Jasper, but the same configuration and usage also applies to the other providers. If there are any differences, they will be stated explicitly.

Jasper architecture

The following sections describe:

Setting up your Jasper Control Center account

The following steps describe how to create a dedicated user in the Jasper Control Center. This user is used for all access from Cumulocity IoT to Jasper Control Center, so the permissions of the user have influence on functionalities available in Cumulocity IoT.

Info
In a similar way, we recommend you to set up a dedicated user for Comarch, Ericsson or Kite to get the credentials required to connect to Cumulocity IoT. Ask your administrator or our product support for further information.

Besides the user, you also need a so-called API license key (only required for Jasper) and API server URL. To determine your API license key and API server URL, use a Control Center administrator user to log in to your Control Center account and click API integration on the Control Center home page. Your API license key and the API server URL are displayed on the top left.

To create a user in Jasper Control Center perform the following steps:

  1. As an admin user, navigate to Admin and Users.
  2. Click Create New.
  3. Enter the username and further details of the user.
  4. If you want to be able to activate and deactivate SIM cards from Cumulocity IoT, or to send SMS from Cumulocity IoT, use the role ACCOUNTUSER. Otherwise, use the role ACCOUNTREADONLY.
  5. Click OK to create the user, then enter your admin password and click OK again.

Jasper user management

The user is now created but does not have a password yet. Follow the instructions emailed to you by Control Center to set a password.

Configuring the connectivity for the SIM provider

Process the following step to configure the connectivity in Cumulocity IoT:

  1. Use a Cumulocity IoT administrator user to log into the Cumulocity IoT platform.
  2. Switch to the Administration application.
  3. Click Connectivity in the Settings menu of the navigator. If the menu item is not displayed, make sure that your user has READ and ADMIN permissions for Connectivity. If the menu item is still not available, please contact product support to make the Connectivity agent available in your tenant.
  4. Switch to the SIM provider settings tab.
  5. Select a provider from the drop-down list.
  6. Enter the credentials for the respective SIM provider account. If you do not have any credentials, ask your administrator.
  7. Set a Cache duration in seconds to determine how long information from the provider is cached. This will prevent timeout issues.
  8. Click Save to save your settings.

Depending on the connectivity provider you choose you must provide parameters specific to the provider. The parameter Cache duration defines how long SIM data returned by the provider is cached before fresh data is requested again, in seconds. This reduces traffic and the number of requests to SIM providers for billing and reliability purposes. A longer cache duration means less traffic to your SIM provider while a shorter duration means that more recent data is displayed.

Jasper settings

Linking SIMs and mobile devices

Switch to the Device management application and navigate to a device that is connected through a SIM card managed by the SIM provider of your choice. The device should have a Connectivity tab. If this tab is not shown, one of the following applies:

To assign permissions, navigate to the Administration application and make sure that your user has a role assigned with READ or ADMIN permission for Connectivity.

Connectivity permission settings

Jasper and Comarch identify SIM cards through their ICCID (Integrated Circuit Card Identifier). Ericsson is using MSISDN (Mobile Station International Subscriber Directory Number) instead. In most cases, devices will report the ICCID and MSISDN of their SIM card automatically to Cumulocity IoT.

If the ICCID is not shown automatically check the following:

Info
Note that it may take a few seconds until the tab appears for the first time on a device, as Cumulocity IoT checks if the particular SIM card is managed by the SIM provider.

The Kite provider requires the following device configuration: ICCID (Integrated Circuit Card Identifier) and MSISDN (Mobile Station International Subscriber Directory Number).

Connectivity tab

In the Connectivity tab you will find the following sections:

Connectivity tab

Info
Some sections may not appear or may be empty. For example, if there have been no SMS sent and you do not have permission to send SMS, you will not see the SMS section.

The Status section lists summary information for the SIM card.

The first row shows if the device is currently running a data session. If it is, the start of the session and the current WAN IP address of the device is displayed.

The second row shows further status information: The ICCID of the SIM card, the activation state of the SIM card and, if set, the fixed IP address assigned to the SIM card. Provided you have ADMIN permission for Connectivity, you can change the activation state by using the drop-down menu.

At the bottom you will find usage information for the current month, that is, from the first of the month till today. Hovering over the tooltip shows the covered time period, including the usage during the past month.

The SMS section shows the text messages sent to the device and received from the device, including the following information:

Provided you have ADMIN permission for Connectivity, you can also send text messages to the device by entering the text and clicking Send SMS.

The Sessions section shows the log of data sessions carried out by the device. It lists when the session started, how long it took and how much data traffic was consumed.

The Audit logs section lists all changes to the SIM card and its tariff. It shows the type of change, old and new values when the change was carried out by whom, and if it was successful.

The Connectivity tab does not update in real-time. To show current data, click the Reload in the top menu bar.

Checking connectivity

If you suspect that a device is not correctly reporting to Cumulocity IoT, or it is not receiving commands, you can verify the connectivity status of the device.

In the Connectivity tab, check the following conditions:

Data connectivity can be analyzed in various places:

Info
The SIM details menu item requires you to have a login for Jasper Control Center. This login is independently provided by your administrator.

If the device is still not reporting to Cumulocity IoT, there may be a configuration or software problem on the device.