Device management

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.

Home dashboard

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

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.

The following information is shown for each device:

• Device name specified in the registration process
• Status of the device (see below)
• Creation date
• Tenant from which the device was registered

The devices may have one of the following status:

• Waiting for connection - The device has been registered but no device with the specified ID has tried to connect.
• Pending acceptance - There is communication from a device with the specified ID, but the user doing the registration must still explicitly accept it so that the credentials are sent to the device.
• Accepted - The user has allowed the credentials to be send to the device.
• Blocked - The device registration has been blocked due to the exceeded limit of failed attempts.

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:

• Single device registration - to manually connect one device or several devices one by one.
• Bulk device registration - to register larger amounts of devices in one step.

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

Single device registration

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

To connect a device manually

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.

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

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

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.

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

• IGNORED - Even if a device requires secure registration, Cumulocity IoT will ignore that requirement.
• OPTIONAL - If a device requires secure registration, Cumulocity IoT will request an additional security token from the user.
• REQUIRED - All devices connected to Cumulocity IoT must use a security token during registration.

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"
}

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:

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.

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.

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.

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:

• Simple registration
• Full registration

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:

• Username - the username for accessing Cumulocity IoT must have the format <tenant>/device_<id>, where <tenant> refers to the tenant from which the CSV file is imported and <id> refers to the respective value in the CSV file.
• Password - the unique password for each device to access Cumulocity IoT equals the value “Credentials” in the CSV file.
• Device in managed object representation - fields TYPE, NAME, ICCID, IDTYPE, PATH, SHELL in the CSV file.

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.

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.

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 information

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

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

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.

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:

• In case of date fields (for example Registration date), you specify a date range to filter for.
• In the Status column you can filter for various criteria representing the send, push or maintenance status of the device.
• In the Alarm column the filtering options you may select correspond to the alarm types (critical, major, minor, warning, no alarms).
• For custom columns, select Only rows where value is defined to filter based on whether the fragment exists, or specify one or more filter terms the entry must match.

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.

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:

• Top-level groups are shown in the Group menu in the navigator at top-level.
• Subgroups can be used to further subdivide top-level groups.

Viewing groups

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

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

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.

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.

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.

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.

To delete a smart group

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

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.

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:

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.

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:

• Text-based configurations
• Binary-based configuration snapshots

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.

Control

The Control tab lists the operations being sent to a device. See Working with operations for detailed information on 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.

The information is provided on the following cards:

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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:

• Online (data was sent within the required interval)- indicated by a green arrow
• Offline (data was not sent within the required interval) - indicated by a red arrow
• Unknown or not monitored (no interval configured) - indicated by a grey arrow

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.

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:

• Online (connection established)- indicated by a green arrow
• Offline (connection not established) - indicated by a red arrow
• Not monitored - indicated by a grey arrow

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.

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.

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

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

• that the machine continues to stay in service during the connection outage, if this was the status before it lost connection.
• that the machine continues to stay out of service, if this was the status before it lost connection.

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.

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:

• To check the alarms for all devices, click Alarms in the Overview menu in the navigator.
• To check the alarms of a particular device, switch to the Alarm tab in the details of this device.

By default,

• only unresolved alarms are shown. If you turn on Show cleared alarms at the right of the top menu bar, you will see the entire alarm history.
• alarms are shown as coming in from the devices in real time. Click Realtime in the top menu bar to disable real-time updates.

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

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.

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:

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

• Status: Providing further information on the alarm status and showing the type of the alarm. The type info is used for duplicating alarms and for configuring the priority of alarms in Administration > Managing business rules > Alarm mapping.
• Change Log: Providing the server time when the alarm was created, which may differ from the device time.

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:

• To view the operations for all devices, click Device control in the Overview menu in the navigator.
• To view the operations of a particular device, switch to the Control tab in the details of this device.

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

• Single operations execute on a single device, see To view single operations.
• Bulk operations comprise of the same single operation executed on a set of devices, see To view bulk operations.

To view single operations

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

Single operations can have one of the following four statuses:

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

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

• Details: Providing information on the operation name and status. In case of status = FAILED the reason for the failure is provided. In case the single operation is part of a bulk operation, you can see the bulk operation details.
• History of Changes: Providing information on the past changes of 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.

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.

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 have an operation type and status.

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

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:

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

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

• Details: Providing information on the start date, delay, status and result of the bulk operation. The result lists the number of successful, failed and pending operations. If the bulk operation is a retry attempt for failed operations, there will be an additional row that shows the index of the bulk operation it was retried from. Click the index to scroll to that bulk operation. If a description was added when the bulk operation has been created, there will be an additional row that shows this description.
• Operation: Providing information on the operation in the form of a JSON object.
• Operations: Only present for executing or completed bulk operations. Providing information on the status and the device of single operations entailed in the bulk operation. Can be filtered by status. You may also either retry all failed operations by clicking Retry failed operations at the top right of the Operations section or retry single operations by hovering over them and then clicking the Retry operation button that appears right next to it. Also see To retry failed operations.
• History of Changes: In a second tab, providing information on the past changes of 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:

• Use the bulk operation wizard
• Schedule a single operation as 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:

• Configuration update
  • Select a configuration from the list. The list can be filtered by configuration type or by configuration name. Click Next.
  • Check the preview of the selected configuration. Click Next.
• Firmware update
  • Select a firmware from the list. The list can be filtered by firmware name. Click Next.
  • Expand a version and select a patch. Click Next.
• Software update
  • Expand a software from the list and select a version, then also choose to install/update or remove the software from the dropdown list. The list of available software can be filtered by device type, by software type or by software name. Click Next. If you selected software for multiple device types, a warning dialogue appears and informs you that some operations may fail due to unsupported software, and ask for confirmation.
  • Confirm the selection and click Next.
• Apply device profile
  • Select a device profile from the list. The list can be filtered by device type or by profile name. Click Next.
  • Confirm the selection and click Next.

4. 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.
5. 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:

• To view the events for all devices, click Events in the Overview menu in the navigator.
• To view the events of a particular device, switch to the Events tab in the details of this device.

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:

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.

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

Alarms

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

Events

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

Measurements

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

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.

The device protocol list shows the following information:

• the device protocol type (for example Modbus, CANOpen, LoRa)
• the device type name
• the number of resources for the device (at the right)

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:

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

   

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.

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.

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.

Applying device profiles to devices

Device profiles can be assigned to:

• Individual devices
• Multiple devices through bulk operations

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

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.

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.

Click Trusted certificates in the Management menu in the navigator.

All certificates owned by the tenant will be displayed.

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.

To add a certificate

Before adding a new trusted certificate, make sure that:

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

To add a certificate perform these steps:

1. Click Add trusted certificate at the right of the top menu bar.
2. In the resulting dialog box, provide the following information:

3. Click Add Certificate to validate and save the certificate.

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.

For each template, the following information is provided:

• Template name
• Template ID
• Number of send messages
• Number of responses

There are two ways to add a SmartRest template:

• Import an already existing template
• Create a new 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.

   

   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:

3. 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:

• Setting up a simulated device or a network of simulated devices.
• Specifying the operations which a device can process.
• Creating work instructions based on predefined message templates or user-defined templates and scheduling work steps.
• Creating up to ten devices of a defined type.
• Generating messages for measurements, alarms, events and inventory.
• Viewing simulation problems as alarms.

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.

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.

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.

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.

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.

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:

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.

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.

The following sections describe:

• How to set up your Jasper Control Center account (examplarily).
• How to configure the connectivity for the SIM provider in your Cumulocity IoT tenant.
• How to link SIMs and mobile devices.
• Which information is shown in the Connectivity tab.
• How to manage connectivity from the Device management application.

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.

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.

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.

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:

• Your user does not have permissions for Connectivity.
• The device is not linked to a SIM card.
• The device is linked to a SIM card, but the card is not managed by the respective SIM provider account.

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.

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:

• Determine the ICCID of the SIM card. It is printed on the SIM card and is visible in Control Center.
• Enter the ICCID in the Info tab, then click Save.
• Click Reload in the top menu bar to make the Connectivity tab appear.

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:

• Status
• SMS
• Sessions
• Audit logs

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:

• When the message was sent or received.
• Where it was sent from and where it was sent to.
• The delivery status of the message:
  • For messages to the device: “Pending”, if it was not yet received by the device, or “Delivered”, if it was received by the device.
  • For messages from the device: “Received”, if it was received by the SIM provider, or “Canceled”, if it was not yet received by the SIM provider.
• What the direction of the message is: MT (“Mobile terminated”), if it went to the device, or MO (“Mobile originated”) if it came from the device.

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:

• the SIM is activated. If the SIM card is not activated, you can activate it selecting “ACTIVE” from the “SIM status” drop-down menu. It may take a while until the SIM card is activated in the network. There may be a reset of the device needed to make it dial up to the network again.

• The device is connected to the network. If the device is not connected to the network, this may have several reasons:

  • The device is in a location without mobile network coverage. If the device reports network quality parameters, you can navigate to the Measurements tab of the device and verify the last reported signal strength and error rate parameters.
  • There is a network or hardware problem (antenna, modem). For the Jasper Control Center, for example, click the cogwheel icon on the top right and select SIM details, then open the Jasper Control Center diagnostics tool. If the device is not attempting to connect to the network, it may be broken.
  • The device is in a data session. If the device is not in a data session, this may, again, have several reasons:
  • The APN settings are incorrectly configured in the device.
  • The SIM card is over traffic limit.
  • Data roaming is disabled on the device and the device is not in the SIM card’s home network.
  • Data roaming for the particular network is not included in the SIM card’s plan.
  • The SIM configuration was changed.

Data connectivity can be analyzed in various places:

• If the device reports its network configuration, navigate to the Network tab and verify, potentially edit, APN settings.
• If the device supports shell, navigate to the Shell tab and verify, potentially edit, APN settings and roaming configuration.
• Check the Sessions section on the Connectivity tab to see if the device has been communicating earlier and how much traffic it used.
• Check the Audit logs section on the Connectivity tab to see if there were any recent changes to the SIM card.
• Finally, click the cogwheel on the top right and select SIM details to navigate to the SIM configuration in Jasper Control Center.

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

• The device may have lost its credentials, for example, due to a factory reset or full loss of power. In this case, you can re-register the device.
• There may be a configuration or software problem with the device, which must be analyzed in a device-specific way.