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.

Connecting Devices

Device registration page

In the Device registration page all devices which currently are in the registration process are displayed either in a list or in a grid.

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 so that the credentials are sent to the device.
• Accepted - The user has allowed the credentials to be send to the device.Devices can be connected to your Cumulocity account in different ways.

To register devices

To register devices, you may choose one of the following options:

• General device registration - to manually connect one or more devices
• Bulk device registration - to register larger amounts of devices in one step

If you are subscribed to the required applications you will see a third option Custom device registration for registering devices of specific types, e.g. LoRa or Sigfox, see the documentation for these services in Optional services.

To connect a device manually

Info: Depending on the type of device you want to connect, not all steps of the following process may be relevant.

1. Click Registration in the Devices menu of the navigator and then click Register device.

2. In the resulting Register devices dialog box, select General device registration.

   

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

Info: In case of any issues, consult the documentation applicable for your device type in the Devices guide or look up the manual of your device.

To bulk-register devices

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

1. Click Registration in the Devices menu of the navigator and then click Register device.

2. In the resulting Register devices dialog box select Bulk device registration.

   

3. Click Select file to upload and select the CSV file you want to upload by browsing for it on your computer.

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

Simple registration

The CSV file contains two columns: ID;PATH, where ID is the device identifier, e.g. 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 this example.

		ID;Credentials;PATH;ICCID;NAME;TYPE
		006064ce800a;LF2PWJoLG1Fz;Sample_Düsseldorf;+491555555;Sample_Device1;c8y_Device
		006064ce8077;OowoGKAbiNJs;Sample_Düsseldorf;+491555555;Sample_Device2;c8y_Device		

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

• User name - the user name for accessing Cumulocity 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 password to access Cumulocity, 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 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 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 Bulk device credentials in the Reference guide.

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

Viewing devices

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

A detailed device list will be displayed.

Device information

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

The devices list displays up to 100 rows. If a list contains more than 100 devices, click Load more at the bottom of the list to display the next 100 entries.

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.

The device will be permanently deleted from the platform.

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

To search for devices

Cumulocity includes a full-text search for devices.

Click the Search button at the top right and enter a search term into the textbox. Cumulocity returns all devices containing this term in any property (name, model, any fragment…)

Our example shows a search for “Ublox C027”.

Info: Unlike filtering, the use of wildcards in a search is not supported.

For details on the search functionality, refer to Getting Started > GUI functionalities and features.

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. Just click the filter icon next to the name of the column you want to set a filter for.

In the Filter options dialog box, specify your filter options.

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 + Or 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 (e.g. 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).

In the Filter options dialog box, click Ascending or Descending if you want the devices to be sorted in a specific order. Finally, click Apply to carry out the filtering.

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

Click Clear filters at the left of the top menu bar if you want to clear all filters and view all devices.

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

Grouping devices

Devices can be arbitrarily 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 distinguishes between top-level groups and subgroups:

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

Viewing groups

To display a list of all groups in the account, click Groups in the navigator.

For each group, the name and the number of children is displayed.

Click a group to view its details.

Info Tab

In the Info tab, the following information is provided:

Sub-assets

In the Sub-assets tab you see a list of all devices assigned to the group. For each device, the name and the number of children is displayed.

See also To add a group and To assign a device to a group.

Bulk operations

In the Bulk operations tab, bulk operations created for the group can be managed. With bulk operations you can at once execute operations for each device within one group. For details, refer to Bulk operations.

To create a new group

1. Click the Plus button at the right of the top bar and then click New group.
2. In the resulting dialog box, enter a unique group name to identify your group.
3. In the search field, enter the search criteria for the devices you might want to add to your group (e.g. “ublox”). A list of devices that match your search criteria will be displayed.
4. Checkmark the devices you want to add from the list.
5. Click Create group with # device(s) to finally create your new group.

The new group will be added to the groups list.

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

From the Groups page, you can also create a new group by clicking Add group in the top menu bar. In the resulting dialog box, enter a name for the group and click Add group.

To edit a group

1. In the navigator, click a group to open it.
2. In the Info tab, click Edit. This allows you to edit the name of the group and to assign user permissions for the group. For further information on permissions, see the Administration Guide.

To delete a group

Click the menu icon in a device entry and then click Delete.

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 Sub-assets tab.
2. Click Assign devices at the right of the top menu bar. In the resulting dialog box search for the devices you might want to add to your group (e.g. “ublox”). A list of devices that match your search criteria will be displayed.
3. Checkmark the devices you want to add from the list.
4. Click Assign # device(s) to assign the selected devices.

The devices will be assigned to the selected group.

From the device perspective

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

The device will be assigned to the selected group.

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

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

To unassign a device

Click the menu icon in a device entry and then click Unassign.

To delete a device

Click the menu icon in a device entry and then click Delete.

The device will be permanently deleted.

To view the device details

Click the menu icon in a device entry and then click Device management.

The device details for the specific device stored under All devices in the Device Management application will open.

Restructuring groups and devices

You can easily restructure groups, sub-groups and devices by a drag and 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. They have a temporary character because the group members can change constantly. Smart groups do not have fixed member listings. They have fixed criteria instead. 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.

Note that smart groups are only available in the Device Management application and not visible in the Cockpit application.

Smart groups can be created from the device list.

To create a smart group

1. To open the device list, click All devices in the navigator.
2. Filter the devices in the list to select the desired devices. Refer to Filtering 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.

In the Sub-asset tab you can adjust your selection and modify the filter settings.

To delete a smart group

To delete a smart group, click the menu icon and then click Delete.

Important: Deleting a smart group is irreversible.

Device details

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

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

The device details are divided into tabs. The number of tabs is dynamic and depends on the available information, i.e. tabs are only displayed if the kind of information is available for the particular device.

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, Service monitoring, Identity (also see the tab list below).

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

Info: Several individual tabs, which you do not find listed here, may be described in a different context in another section of the Cumulocity documentation. Use the Search function to switch to the relevant sections. A detailed description on the Modbus tab, for example, can be found in Optional services > Cloud fieldbus.

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.

Info

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

The information is provided on the following cards:

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.

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 motion measurement including graphs for acceleration in the three dimensions, and a chart with modem statistics in the form of signal strength and bit error rate.

If a chart contains graphs with different units, one Y-axis is rendered per unit. In the example above, motion measurements consist of three parameters with unit “meter per square second”, so only one axis is rendered. Modem statistics consist of signal strength in decibel milliwatts and bit error rate in percent, so one axis is rendered for each graph.

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 has to send measurements in a specified fragment format.

“fragment_name” : { “serie_name” : { “value” : … “unit” : … } }

Example:

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

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

Alarms

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

Configuration

The Configuration tab allows you to configure the parameters and initial settings of your device in a text format.

To add or edit a configuration

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

Alternatively, you can work with configuration snapshots, see Configuration snapshots.

Control

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

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.

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

To configure WAN parameters

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

To configure LAN parameters

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

Info: Name and Mac address fields are not configurable.

To configure DHCP parameters

1. Enter the address range in which the connection can be established.
2. Enter the DNS.
3. Enter the DNS 2.
4. Enter the domain name.
5. Click Save changes to save your settings.

Info: If the LAN configuration is disabled, the DHCP configuration is automatically disabled as well.

Software

The Software tab allows you to manage and update the firmware of a device and the software installed on a device.

To install firmware/software

Select a firmware from the dropdown list, which contains all firmware available in the Firmware repository, and click Install.

Similarly, to install a software on the device, select a software package from the dropdown list, which contains all software available in the Software repository, and click Install.

Installing software and firmware usually includes a restart of the device. To monitor the progress of an installation, visit the Control tab.

To remove firmware/software

To remove a firmware/software object from a device, hover over a particular firmware/software entry and click the delete icon.

Events

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

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.

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

Service monitoring

In addition to connection monitoring, Cumulocity offers a separate service monitoring for machines, see Service monitoring for more information.

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 if the device is online.

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

Click View history at the right of the top menu bar to switch to the Control tab which displays a list of the previously executed commands. For details, refer to Monitoring and controlling devices > Working with operations.

For your convenience, Cumulocity provides several frequently used commands for some devices. Click <_Get predefined commands at the right of the top menu bar 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, or Execute, to execute the command straight away. You may also add new commands here for re-use.

Tracking

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

Note that the Tracking tab only shows up when a device contains c8y_Position property.

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

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, you can configure device-side geo-fencing and motion detection.

Info: When this feature is activated and the device is compatible, Cell ID information can be used to determine the position of the device. Currently, the services from Combain and Google are supported. The user can see the tracks based on both data, or filter out GPS based data or Cell ID-based data.

Identity

Cumulocity 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 need to 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.

Monitoring and controlling devices

Locating devices

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

Push connections

The bottom arrow represents the push connection (from Cumulocity 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

Push connection means the connection from Cumulocity to /devicecontrol/notifications API, not to real-time API.

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

Maintenance mode

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

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

To monitor the connection of a particular device

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

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

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

In the Required interval field you can specify an interval. This parameter defines how often you expect to hear from the device. If, for example, you set the required interval to 60, you expect the device at least to communicate once in an hour with Cumulocity. 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.

Service monitoring

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

Service monitoring 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. 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 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 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 displays service availability at the level of individual devices and across all devices.

To view the service monitoring of a particular device

Click the Service monitoring tab in the details of a particular device to check the service monitoring of this device.

To view the service monitoring across all devices

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

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

Working with alarms

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

To view alarms

Cumulocity 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 includes four different alarm types:

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

By clicking one of the buttons at the top, the corresponding section will be hidden. Click it again to show the section 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 the Administration application.
• 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.

To view operations

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.

Operations can be in one of the following four states:

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.
• History of Changes: Providing information on the past changes of the operation.

By clicking one of the state buttons at the top, the corresponding operations will be hidden. Click it again to show the operations again.

Click Realtime at the right of the top menu bar to see operations coming in from the devices in realtime.

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

To create and execute operations

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

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

To execute bulk operations

For easier handling of devices, Cumulocity offers bulk operations. With bulk operations you can at once execute operations for each device within one group.

To execute bulk operations for a group, follow these steps:

1. Select a device and open the Control tab.
2. Create an operation.
3. Hover over the operation you want to execute.
4. Click the menu icon and then click Execute for whole group.

The operation will be executed for all devices in the group.

In order to view the status and progress of your operations, simply select the desired group and click the Bulk operations tab.

To edit bulk operations

1. Hover over the bulk operation you want to edit, click the menu icon and then click Edit operation schedule.
2. In the resulting dialog box you may change the Start date and Delay values.
3. To change operation details, click Show operation details.
4. Click Reschedule to apply your changes.

The changes will be applied to the bulk operation accordingly.

To delete bulk operations

Hover over the bulk operation you want to delete, click the menu icon, and then click Cancel operation.

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 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 the Filter button to apply the filter. Click the Clear button to clear the filter again.

Managing device types

To process data from various device types, Cumulocity uses so-called “device protocols” which are stored in a device database.

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

In the Device database 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 (e.g. Modbus, CANOpen, LoRa, IMPACT)
• the device type name
• the number of resources for the device (at the right)

To add a device protocol

1. Click New 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 Optional services.

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

To remove a device protocol

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

The device protocol will be removed 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

Managing device firmware and software

In the firmware and in the software repository, Cumulocity offers to collect reference firmware and software for devices respectively.

Info: The descriptions below refer to firmware but also apply to device software.

Click Firmware repository in the Management menu in the navigator.

The available firmware objects will be displayed, presented as cards in a grid.

Click Details on a specific object to “turn around” its card and display details.

In addition to the object name and version, you will here find the name of the file containing the firmware.

Moreover, several action buttons are provided which are explained below.

To add a firmware object

1. In the Firmware repository page, click Add firmware at the right of the top menu bar.
   
   
2. In the resulting dialog box, enter a name for the firmware and its version.
3. Specify the file for the firmware by either uploading it from the file system, specifying a URL from where the firmware can be obtained or choosing a file previously added in the Administration application.
4. Click Save.

The firmware object will be added to the firmware list.

Similarly, you can add a new software object to the Software repository.

To update a firmware/software object

1. Click Details on a specific object to “turn around” its card and display details.
2. Update the name or description, or specify a new file for the firmware by either uploading it from the file system or choosing a file.
3. Click Save.

The object will be updated.

To download a firmware/software object

1. Click Details on a specific object to “turn around” its card and display details.
2. Click the download icon.

The object will be downloaded to your file system.

To install firmware/software on a device

1. Click All devices in the Devices menu in the navigator and select a device from the device list.
2. Open the Software tab for the device and click Install firmware, see also the description of the Software tab in Device details.

Info: To store other types of binaries in Cumulocity, switch to the Administration application.

To install firmware/software on multiple devices

Cumulocity offers the option to execute firmware or software updates for multiple devices at once. To do so, follow these steps:

1. Execute the software update in a single device to test that the new version really works.
2. Navigate to operation and select Execute for the whole group.
3. Fill in the fields to schedule the bulk operation and click Create.

The operation status can be viewed in the Bulk operations tab of the selected group, see Bulk operations.

To delete a firmware/software object

Click the menu icon at the top right of a firmware/software card and click Delete firmware (or Delete software).

The object will be deleted from the list.

Configuration repository

Cumulocity 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 configurations are listed. Each entry shows the configuration name, the device from which it has been uploaded and the upload timestamp.

Click a configuration in the list to open it. You may modify the settings here and apply them by clicking Save. Refer to the section below for details on the fields.

To add a snapshot configuration from a file

1. Click Add configuration snapshot at the right of the top menu bar.
2. In the resulting dialog box, enter a unique name and an optional description for the configuration.
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. Specify the configuration snapshot file by either uploading it from the file system, specifying a URL from where the firmware can be obtained or choosing a file.
5. Click Add configuration snapshot.

The snapshot will be added to the configuration repository.

To retrieve a current snapshot from a device

In addition to adding configurations from a file you can also add configurations by retrieving them from a device.

In order to retrieve a current configuration snapshot from a device, follow these steps:

1. Navigate to the desired device and open its Configuration tab.
2. Under Configuration snapshot, click Get new snapshot from device at the top right.

The retrieved snapshot can be found in the Configuration repository, under Management menu in the navigator.

To apply a configuration snapshot to a device

1. Navigate to the desired device and open its Configuration tab.
2. Under Configuration snapshot, select a configuration from the dropdown field.
3. Click Put new snapshot to device to apply the selected snapshot to the device.

To apply a snapshot configuration from one device to another

1. Navigate to the device which has your desired configuration and open the Configuration tab.
2. Under Configuration snapshot, click Get new snapshot from device at the top right.
3. Navigate to the other device and open its Configuration tab.
4. Under Configuration snapshot, select the new configuration from the dropdown field and click Put new snapshot to device.

Info: When you apply a snapshot configuration from one device to another, the configuration may contain data which is device-specific.

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

Configuration repository

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

For details on configuration management also refer to Device management library > Configuration management in the Reference guide.

In the Configuration repository page which you open from the Management menu in the navigator, all available configurations are listed. Each entry shows the configuration name, the device from which it has been uploaded and the upload timestamp.

Click a configuration in the list to open it. You may modify the settings here and apply them by clicking Save. Refer to the section below for details on the fields.

To add a snapshot configuration from a file

1. Click Add configuration snapshot at the right of the top menu bar.

2. In the resulting dialog box, enter a unique name and optional description for the configuration.

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. Under Configuration snapshot file click one of the available options to select the file:

   • Upload - to upload a file from your file system
   • External URL - to provide an external URL
   • Choose file - to select a file from a list

5. Click Add configuration snapshot to save your settings.

The snapshot will be added to the configuration repository.

To retrieve a current snapshot from a device

In addition to adding configurations from a file you can also add configurations by retrieving them from a device.

1. Navigate to the desired device and open its Configuration tab.
2. Under Configuration snapshot, click Get new snapshot from device at the top right.

The retrieved snapshot will be added to the configuration repository.

To apply a configuration snapshot to a device

1. Navigate to the desired device and open its Configuration tab.
2. Under Configuration snapshot, select a configuration from the dropdown field.
3. Click Put new snapshot to device to apply the selected snapshot to the device.

To apply a snapshot configuration from one device to another

1. Navigate to the device which has the desired configuration and open the Configuration tab.
2. Under Configuration snapshot, click Get new snapshot from device at the top right.
3. Navigate to the other device and open its Configuration tab.
4. Under Configuration snapshot, select the new configuration from the dropdown field and click Put new snapshot to device.

Info: When you apply a snapshot configuration from one device to another, the configuration may contain data which is device-specific.

SmartREST templates

Introduction

SmartREST templates are a collection of request and response templates used to convert CSV data and Cumulocity 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 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. For further information on static templates, refer to the Device SDK guide.

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 at the right of the top menu bar.
2. In the resulting dialog box, choose 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 New 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:

   Field	Description
   Response ID	Unique integer that will be used as a response identifier.
   Name	Name for the response. Mandatory.
   Base Pattern	Base pattern for the response.
   Condition	Condition value of the response.
   Pattern	At least one pattern is required. Click Add pattern and enter a pattern value.

   

3. Click Save.

The response will be added to the SmartREST template.

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 simulator all aspects of IoT devices can be simulated, 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 artificial devices that have 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 (e.g. 23.0 degrees). Many predefined message templates are provided, e.g. 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 New 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 on the right changes according to the type of instruction selected on 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, i.e. if the simulator itself does not work correctly. See Working with alarms for information on alarms.