Optional services

In addition to the standard and built-in applications that come with Cumulocity, various additional applications are provided which you may subscribe to, i.e. integrated agents for several device types.

Android Cloud Sensor App

Overview

This document describes the Android Cloud Sensor App. This App sends the sensor measurements from a Texas Instruments (TI) Sensor Tag and an Android smartphone to Cumulocity to be securely processed and managed. Additionally, both devices can be remote-controlled by Cumulocity. The TI Sensor Tag is a low energy wireless device manufactured by Texas Instruments © http://www.ti.com/.

Installing the Android Cloud Sensor App

To use the Android Cloud Sensor App you need a smartphone with Android version 5.0 (Lollipop) or higher. To determine the Android version installed on your smartphone, refer to http://www.wikihow.com/Check-What-Android-Version-You-Have.

To install the Android Cloud Sensor App from Google Play, open the Cockpit application in your Cumulocity IoT Sensor tenant and click Add smartphone from the quick links on the Welcome screen.

Quick Links

This will start a wizard showing the QR code for downloading the Android Cloud Sensor App.

Install App

Scan this QR code with any scanning application on your smartphone. You will be navigated to Google Play for the installation of the Android Cloud Sensor App.

Registering the Cloud Sensor App to your IoT Sensor tenant

To register your smartphone as a new device in your tenant you have two options:

  • Option 1: Scan a QR code with encrypted registration credentials (fastest way)
  • Option 2: Use Web-based registration

Info: Just in case you need to re-register your smartphone, and you change from option 1 to option 2 (or vice versa), you must delete the smartphone object in Device Management.

The QR code registration process (option 1) uses credentials derived from the username and password of the user who is currently logged into the IoT Sensor tenant. Unique device credentials are used in the web-based registration process (option 2).

Registering using a QR code with credentials

Click Next in the Cockpit wizard to see the QR code with credentials to register the Cloud Sensor App to your Cumulocity IoT Sensor tenant.

Register phone QR

Your smartphone will be added to the devices list in the Device Management application, available from All devices in the Devices menu in the navigator.

All devices

Moreover it will be added to the group “Smartphones” (which will be created if not available yet). You can easily navigate to the group in the Cockpit application by clicking Go to phones.

Info: Until you scan the registration credentials QR code, the button will remain in the pending state showing the message “Waiting...”. Scanning the QR code will complete the registration process.

Waiting text

Important: The registration credentials are encrypted. However, we highly recommend to use specific demo user accounts on your tenant for large public presentations. Do not use this method for production tenants or for tenants containing sensitive data.

Registering using web-based registration

To register your smartphone manually, follow these steps:

  1. Press the Web-based Registration button on the Cloud Sensor App Welcome screen.
    Action bar
  2. Select the instance on which your IoT Sensor Demo tenant is hosted, e.g. cumulocity.com.
    Select Instance
  3. Press the Register device button to start registration. A device ID will be displayed which needs to be entered during device registration on the Cumulocity IoT Sensor tenant.
    Get device Id
  4. In your Cumulocity tenant in the Device Management application, click Registration in the Devices menu and enter the device ID.
    Register device
  5. Click Accept.
    Accept device

Your smartphone will be added to the devices list in the Device Management application, available from All devices in the Devices menu in the navigator.

All devices

Moreover it will be added to the group “Smartphones” (which will be created if not available yet). You can easily navigate to the group in the Cockpit application by clicking Go to phones.

For further information about registering a device at the platform manually, refer to Device Management > Connecting devices.

Sending sensor data to Cumulocity

Once your Cloud Sensor App is registered either by a QR code or manually, the device name will be provided which identifies your smartphone in the platform.

You need to accept several permission requests allowing for accessing data on your device (e.g. network information and GPS data) to let the smartphone transfer network and GPS data to the cloud. This requests only show up once.

access media manage calls media read location

You may edit the device name or leave it at the default value for your smartphone model.

edit name

A new device record with the model name and the device name used in the platform will appear on the screen of the Cloud Sensor App.

The measurements from the sensors of your smartphone will automatically start being sent to your Cumulocity tenant. You can view the data from sensors by pressing the View sensors button.

phone sensors gps sensor acceleration sensor

The data points will also be displayed on the graphs in the dashboard of your smartphone in the Cockpit application.

map in cockpit

A 3D rotation widget on this dashboard will depict the data from a gyroscope sensor on your smartphone if present.

rotation widget

To save battery power, the Cloud Sensor App sends measurements to Cumulocity only when the data change is significant, or every 20 minutes by default. This interval can be changed in the Device Management application.

Switch to the Device Management application and select your smartphone from the device list, available through All devices in the Devices menu in the navigator.

select from list

Switch to the Configuration tab and specify the interval in milliseconds.

configuration interval

Connecting TI Sensor Tag to the Cloud Sensor App

The Cloud Sensor App connects to both TI Sensor Tag version 1.20 and 1.30 via Bluetooth. Use the “Scan devices” button in the Cloud Sensor App to connect a Sensor Tag.

Scan devices button

All Sensor Tags which are discoverable are displayed. To make a Sensor Tag discoverable, press the red button next to it. The Sensor Tag will start blinking to show that it is ready to connect. It should immediately appear in the list of visible Bluetooth devices in the Cloud Sensor App.

Connect Sensor Tag

Press Connect next to the Sensor Tag of your choice. The Bluetooth connection between the Sensor Tag and your smartphone will be established. Once the Sensor Tag is paired with your smartphone, you will see it as a record on the Cloud Sensor App’s screen:

Sensor Tag Card

Observing information and sensor data from the TI Sensor Tag is possible by pressing the View sensors button on its card.

Sensor Tag Info Sensor Tag Key Not Pressed Sensor Tag Key Pressed

In your Cumulocity tenant, the data points for the Sensor Tag will be displayed on the graphs in the dashboard of your smartphone and as measurements in the Device Management application.

Sensor tag data points

To detach the Sensor Tag from your smartphone, press the Remove button on its card.

Device control

The Cloud Sensor App can receive real-time control commands from Cumulocity.

The Messaging widget can be used to send text notifications to the smartphone. The vibration relay control can be used to turn on/off the vibration motor.

For example, to send a message from Cumulocity, enter a text into the Messaging widget and click Send.

message widget

The message will appear as a pop-up on the screen of your smartphone.

Hello World Messsage

If the vibration switch is turned on, the smartphone will start vibrating until the switch is turned off again.

Info: The smartphone must remain connected to the platform to receive these commands.

To learn more about dashboard widgets, refer to Cockpit > Working with dashboards.

Cloud Fieldbus

Cloud Fieldbus is a Cumulocity application with the ability to collect data from fieldbus devices and remotely manage them. This section describes how to

It is supported out of the box by the following terminals:

OPC UA support is implemented in Java and runs on any system running JRE7 (Java Runtime Environment 7) or newer.

If you want to support Cloud Fieldbus with your terminal, please contact info@cumulocity.com for more information.

Connecting Fieldbus devices

For the following instructions, we assume you have a Cloud Fieldbus terminal available and it is registered as a device in your Cumulocity tenant. To register a terminal with Cumulocity, follow the instructions provided with the terminal.

Connecting Modbus/RTU devices

To connect a Modbus/RTU device:

  1. Physically wire the Modbus/RTU device through RS/485 or RS/232 to the terminal.
  2. Give the device a unique Modbus address according to the instructions provided with the Modbus device (e.g. by setting a jumper on the device).
  3. Check the serial communication settings of the device according to the instructions provided with the device (i.e. baud rates and communication protocol). These have to match with all devices on the bus.
  4. In the Device Management application, click All devices in the Devices menu in the navigator. In the device list, select the terminal and switch to the Modbus tab.
  5. Change the communication settings shown in the section Serial communication to match the settings on the bus, if needed.
  6. Change the transmit rate and the polling rate according to your requirements. The polling rate is the frequency at which the Modbus devices are polled for changes. The transmit rate is the frequency where measurements are sent to Cumulocity.
  7. Click Save changes if you made changes.
    Add Modbus device
  8. To start communication between the terminal and the Modbus device, click Add new device.
  9. Enter a name for the device and select the type of the device from the drop-down field. To add new device types, see Configuring Fieldbus device types below. Set the Modbus address of the connected device.
  10. Click Add. Cumulocity will now send a notification to the Modbus terminal that a new device is ready to be managed. This may take a few seconds.

After completion, a new child device has been added to the terminal and can now be managed. You can click on the name of the device in the table to navigate to the device. If you have not yet added Modbus devices to the terminal, you may have to reload your browser window to make the Child Devices tab visible.

Connecting Modbus/TCP devices

To connect a Modbus/TCP device:

  1. Make sure that the Modbus/TCP device is connected to the terminal, i.e. directly through an Ethernet cable or through a switch. If you are using a Modbus gateway, configure the gateway in a way it can communicate with the Modbus devices behind the gateway.
  2. Check the network settings of the device using the instructions provided with the device.
  3. In the Device Management application, click All devices in the Devices menu in the navigator. In the device list, select the terminal and switch to the Network tab. Verify that the LAN settings of the terminal match the settings of the device so that TCP communication can be established.
  4. Switch to the Modbus tab.
  5. Change the transmit rate and the polling rate according to your requirements. The polling rate is the frequency at which the Modbus devices are polled for changes. The transmit rate is the frequency at which measurements are sent to Cumulocity.
  6. Click Save changes if you made changes.

Adding child devices

  1. To start communication between the terminal and the Modbus device, click Add new device.
  2. Enter a name for the device and select the type of the device from the dropdown field. To add new device types, see Configuring Fieldbus device types below. Set the Modbus address and the IP address of the connected device.
  3. Click Add.

Cumulocity will now send a notification to the Modbus terminal that a new device is ready to be managed. This may take a few seconds.

Add Modbus device

We assume that all Modbus/TCP communication uses the standard Modbus/TCP port 502. On the NTC-6200, the port to be used can be configured through the variable "service.cumulocity.plugin.lua__modbus.port" using, for example, Device Shell or the local web user interface of the device.

Connecting CAN devices

To connect a CAN device:

  1. Physically wire the CAN device through to the terminal.
  2. Check the serial communication baud rate of the device according to the instructions provided with the device. These have to match all devices on the bus.
  3. In the Device Management application, click All devices in the Devices menu in the navigator. In the device list, select the terminal and switch to the CAN bus tab.
  4. Change the baud rate setting shown in the section CAN bus communication to match the settings on the bus, if needed.
  5. Change the transmit rate according to your requirements. The transmit rate is the frequency where measurements are sent to Cumulocity.
  6. Click Save changes if you made changes.

Adding child devices

  1. To start communication between the terminal and the CAN device, click Add CAN device.
  2. Enter a name for the device and select the type of the device from the dropdown field. To add new device types, see Configuring Fieldbus device types below.
  3. Click Add.

Cumulocity will now send a notification to the Fieldbus terminal that a new device is ready to be managed. This may take a few seconds.

After completion, a new child device has been added to the terminal and can now be managed. You can click on the name of the device in the table to navigate to the device. If you have not yet added Fieldbus devices to the terminal, you may have to reload your browser window to make the "Child Devices" tab visible.

Add CAN device

Connecting OPC UA servers

To connect an OPC UA server to Cumulocity, you need a gateway or industrial PC running the Cumulocity OPC UA agent.

  1. Make sure that the OPC UA server is connected to the gateway or PC, i.e. directly through an Ethernet cable or through a switch.
  2. Check the network settings of the gateway and make sure that the OPC UA server is reachable from the gateway.
  3. In the Device Management application, click All devices in the Devices menu in the navigator. In the device list, select the gateway and switch to the OPCUA tab.
  4. In the URL field, enter the URL of the OPC UA server as seen from the gateway.
  5. Set the username and password to access the OPC UA server.
  6. Change the transmit rate and the polling rate according to your requirements. The transmit rate is the frequency at which measurements are sent to Cumulocity. The polling rate is the frequency at which the OPC UA server polls for changes. Note that not all OPC UA servers support setting a polling rate. In such cases, the OPC UA server sends data usually whenever it changes.
  7. Click Save changes if you made changes.

Adding child devices

  1. To start communication between the gateway and the OPC UA server, click Add OPCUA device. An OPC UA server may host many devices as part of its object model.
  2. Enter a name for the OPC UA device.
  3. Enter the absolute Browse path of the OPC UA device. The browse path of the device is configured on the OPC UA server and represents the "root" of the OPC UA device in the OPC UA server object model.
  4. Select the type of the child device from the drop-down box. To add new device types, see Configuring Fieldbus device types below.
  5. Click Add.

Cumulocity will now send a notification to the OPC UA agent that a new device is ready to be managed. This may take a few seconds.

After completion, a new child device has been added to the gateway and can now be managed. You can click on the name of the device in the table to navigate to the device.

Add OPCUA device

Connecting Profibus devices

Connecting Profibus differs slightly from the regular Plug & Play approach of Cloud Fieldbus. The gateway device acts as slave on the Profibus so it can easily be integrated into existing infrastructure. This means that Profibus data must be actively sent to the gateway though. Typically this is done by programming a PLC to actively send information to the gateway via it’s configured Profibus slave address.

  1. Physically wire the Profibus device to the terminal.
  2. In the Device Management application, click All devices in the Devices menu in the navigator. In the device list, select the terminal and switch to the "Profibus" tab.

    Profibus settings

  3. The baud rate is automatically detected by the gateway and is just being displayed here.
  4. Change the transmit rate according to your requirements. The transmit rate is the interval at which measurements are sent to Cumulocity.
  5. Set the slave address of the terminal.
  6. Configure your Profibus Master device to communicate to that slave address. To do so, refer to the gateway manual (e.g. SmartBox DP).
  7. Click Save to update the gateway with the new settings.

Adding child devices

  1. To start communication between the gateway and the Profibus device, click Add Profibus device.
  2. Enter a name for the new device.
  3. Select the type of the child device from the drop-down box. To add new device types, see Configuring Fieldbus device types below.
  4. Click Add to confirm and notify the gateway.

Add device

Now A child device will be created containing the data configured in the selected device type.

Cumulocity will notify the gateway to send data for the newly created child device.

Managing Fieldbus devices

Once connected, you can now manage your device. Switch to the Child devices tab of a device to list the connected Fieldbus devices and navigate to a Fieldbus device. Depending on the capabilities of the device and its configuration in Cumulocity, you can:

Collecting measurements

If the device type of the Fieldbus device is configured to collect measurements, these will be visible in the Measurements tab. They will also be available for usage in the Data Explorer and in Dashboard widgets.

Data is collected according to the interval specified in the "transmit rate" property of the terminal as described above. To optimize the data traffic, data that is exactly the same as collected previously may not be sent again.

Fieldbus measurements

Monitoring alarms

If the device type of the Fieldbus device is configured to send alarms, these will be visible in the Alarms tab and usable in widgets. To determine the alarm status, the Fieldbus devices are monitored for changes according to the "polling rate" setting of the terminal. If a particular coil or register is non-zero, an alarm will be raised. If the value goes back to zero, the alarm will be cleared.

Fieldbus alarms

Logging events

Similar to alarms, changes in Fieldbus devices can be monitored and logged as events. Each time, the value of the monitored coil or register changes, an event is created. You can see the events in the "Events" tab of the device or use them in widgets. You can inspect the new value of the monitored coil or register by clicking on the event and unfolding the event details.

Fieldbus events

Monitor a device status

The status of devices can be monitored in real time using dashboard widgets in the Cockpit application. Navigate to the Cockpit application, create a dashboard or report, and add widgets as described in the Cockpit section in the User guide. The Cloud Fieldbus has two new widgets: The "Fieldbus Device" widget and the "SCADA" widget.

Monitoring device status using the Fieldbus Device widget

The Fieldbus Device widget provides you with a tabular display of the status of a device. The status of the device can also be modified through the widget.

To use the Fieldbus Device widget, follow these steps:

  1. Select a dashboard and click Add widget in the top menu bar.
  2. Select the Fieldbus Device Widget and edit the title of the widget.
  3. Choose the device that should be shown in the widget in the Target assets or devices section.
  4. Select the coils and registers that should be shown on the widget.

Adding the Fieldbus Device Widget

In the widget, the selected coils and registers are grouped into display categories as configured in the device type. The Fieldbus Device Widget updates automatically as soon as there is new data available. You do not need to click on reload.

Use the Fieldbus Device Widget

Registers and coils that can be changed are represented by active widgets. For example, in the screenshot above, the "Master switch" coil and the "Mode" register are editable. If you click a switch, an operation to change the corresponding coil or register is sent to the terminal. Similar, if you change a value and click Set, an operation is created. The terminal will then carry out the configuration change on the device, as requested through the operation. While the operation is being processed, a progress indicator is shown.

Monitoring status using the SCADA widget

The SCADA widget provides you with a graphic representation of the status of a device.

To use the SCADA widget, follow these steps:

  1. Select a dashboard and click Add widget in the top menu bar.
  2. Select the SCADA widget and edit the title of the widget.
  3. Choose the device that should be shown in the widget in the Target assets or devices section.
  4. Upload an SVG file with the graphic representation of the device. SVG files are vector graphics that have to be specifically prepared with placeholders for the status information. See Preparing SVG files for the SCADA widget below.
  5. Assign placeholders to devices. Note that multiple devices can be taken as source.
  6. You now need to assign each placeholder to a property of the device. Hover over each placeholder and select Assign device property or Assign fieldbus property. A dialog box comes up, in which you can choose basic device properties or fieldbus properties (i.e. status coils and registers). Select the desired property and click Select.
  7. After assigning all placeholders, a preview of the widget with the current values of the properties is shown. Click Save to place the widget on the dashboard.

Adding the SCADA Widget

Preparing SVG files for the SCADA widget

The SCADA widgets inspect uploaded SVG files for placeholders. These placeholders are replaced by actual values from devices. Placeholders have a specific syntax and can be used anywhere in the SVG file. To add a placeholder, enter the name of the placeholder in double curly braces using your design application or a text editor.

When creating svg files, we recommend you to use "https://boxy-svg.com/". It is easy to use, quality chrome extension.

<text class="text" xt-anchor="middle" x="100" y="236.982125" width="200" ...>
    {{batteryValue}}
</text>

Configuring Fieldbus device types

New Fieldbus device types can be set up in the Device database page which you open from the Device Types menu in the navigator.

Click New in the top menu bar. In the Device type field, select the protocol of your device and enter a name for it.

Now you can start adding coils and register definitions to the device type, depending on the selected protocol (see the descriptions below).

Device Database

Configuring Modbus data

Adding a coil definition

Click Add at the top right of the Coils (discrete inputs) section, to add a coil definition. This will open a dialog to specify the coil. Enter the following information:

  1. Enter the name of the coil as being displayed in the user interface.
  2. Optionally, enter the display category to structure your data in widgets.
  3. Enter the number of the coil in the Modbus device.
  4. Select the Show status checkbox if you want to show the coil's current value in the Fieldbus Device Widget. In this case, you can enter the text that the Fieldbus Device Widget should show for unset and set coils.
  5. Select the Update status checkbox if you want to be able to edit the coil from the Fieldbus Device Widget.
  6. Select the Raise alarm checkbox if an alarm should be raised when the coil is set in the device. In this case, you can specify the type of the alarm that is raised, its text and its severity. Note that there can only be one alarm active of a particular type for a particular device.
  7. Select the Send event checkbox if an event should be generated each time the value of the coil changes. If Send event is selected, you can specify the type of event and the text in the event.
  8. Click OK to finish editing the coil.

Add coil

The same functions are available for discrete inputs. However, it is not possible to update the status of a discrete input.

Adding a register definition

Click Add at the top right of the Holding registers section, to add a register definition. This opens a dialog to enter the details of the register definition:

  1. Enter the name of the register being displayed in the user interface.
  2. Optionally, enter the display category to structure your data in widgets.
  3. Enter the number of the register in the Modbus device. You can indicate a subset of bits to be used from a register by providing a start bit and a number of bits. This allows you to split a physical Modbus register into a set of "logical registers".
  4. To scale the integer value read from the Modbus device, you can enter a multiplier, a divisor and a number of decimal places. The register value is first multiplied by the "multiplier", then divided by the "divisor" and then shifted by the number of decimal places. Note, that the terminal may use integer arithmetic to calculate values sent to Cumulocity. For example, if you use a divisor of one and one decimal place, a value of 231 read from the terminal will be sent as 23.1 to Cumulocity. If you use a divisor of ten and no decimal places, the terminal may send 23 to Cumulocity (depending on its implementation).
  5. Indicate the unit of the data, for example, "C" for temperature values.
  6. Select the Signed checkbox if the register value should be interpreted as signed number.
  7. Select the Enumeration type checkbox if the register value should be interpreted as enumeration of discrete values. If Enumeration type is selected, you can click Add value to add mappings from a discrete value to a text to be shown for this value in the widget. Click Remove value to remove the mapping.
  8. Select the Show status checkbox if you want to show the current value of the register in the Fieldbus Device Widget.
  9. Select the Update status checkbox if you want to be able to edit the register from the Fieldbus Device Widget. If Update status is selected, two additional fields Minimum and Maximum appear. Using these fields, you can constrain numerical values entered in the widget.
  10. Select the Send measurement checkbox if you want the values of the register to be regularly collected according to the transmit interval (see above). In this case, add a measurement type and a series to be used. For each measurement type, a chart is created in the Measurements tab. For each series, a graph is created in the chart. The unit is used for labelling the measurement in the chart and in the Fieldbus Device Widget.
  11. Select the Raise alarm checkbox if an alarm should be raised when the register is not zero in the device measurement. In this case, you can specify the type of the alarm raised, its text and its severity. Note, that there can only be one alarm active of a particular type for a particular device.
  12. Select the Send event checkbox if an event should be generated each time the value of the register changes. If Send event is selected, you can specify the type of event and the text in the event.
  13. Click OK to save your settings.

Add register

In the Options section, select the checkbox Use server time to create the time stamps for data on the server instead of on the terminal. If you need to support buffering of data on the terminal, leave this checkbox clear.

Finally, click Save to save your settings.

If you edit a device type that is currently in use, you may need to

  • restart the terminals that use the device type,
  • reconfigure dashboards and widgets that use the device type.

Configuring CAN bus data

CAN device types can be configured in a very similar way as Modbus device types. For more information, see Configuring Modbus data above. The differences are:

  • Holding registers are used to describe the different pieces of data inside CAN messages.
  • Enter the CAN message ID of the specific message the data should be extracted from. Use a hexadecimal number for the message ID.
  • Conversion of values is extended by an offset parameter. This will be added or substracted from the register value, depending on its sign. The offset calculation is done after applying multiplier and divisor, and before performing decimal shifting.

Add CAN register

Configuring OPC UA data

OPC UA device types can be configured in a very similar way as Modbus device types. For more information, see Configuring Modbus data above.

The main difference is how data is addressed. OPC UA servers provide a hierarchical object model of connected nodes. The nodes are addressed by the browse path from the root of the object model to the respective node.

To simplify configuration, the browse path is split into two parts in Cloud Fieldbus:

  • From the root to the OPC UA device (configured above).
  • From the OPC UA device to a node with data of that device.

When you click Add, enter the second part of the path into the ** field as shown in the image below. Note that the OPC UA agent currently only supports nodes of type "Variable". The description of the paths should be either provided with your OPC UA server or with your devices.

Add OPCUA register

Configuring Profibus data

To configure a Profibus device type, select "Profibus" as device type from the dropdown list and enter a name for it.

In the Register section, click Add at the right to add one or more register definitions as described exemplarily for Modbus devices in Adding a register definition above.

In the Options section, select the checkbox Use server time to create the time stamps for data on the server instead of on the terminal. If you need to support buffering of data on the terminal, leave this checkbox clear.

Finally, click Save to save your settings.

If you edit a device type that is currently in use, you may need to

  • restart the terminals that use the device type,
  • reconfigure dashboards and widgets that use the device type.

Configuring CANopen data

There are two ways to create a new device type. Either manually from scratch via the “New” operation or via import of an EDS file for the corresponding device.

Manually creating a new device type from scratch

Navigate to the Device database page and click New. The following window will open:

New device type

Select “CANopen” as fieldbus type and enter a name for your device type. Specific to CANopen is the CANopen device type field which accepts a hex number.

In the Variables section, you determine the CANopen variables. Variables inside the “Object Dictionary”(OD) of the CANopen device can be accessed later by adding the variables to the device type definition. Via the Add button at the right of the Variables section, new variables can be configured.

New variable

The following fields can be observed:

  • Name: The name of the variable.
  • Display category: This field is used to group variables into sections in the visualization.
  • Index: Index of the variable in the OD of the device.
  • Sub-index: Sub-Index of the variable in the OD of the device.
  • Data type: The type of the variable (e.g. boolean, unsigned).
  • Access type: E.g. read only, write only, etc.
  • Unit: Logical unit of the variable.
  • Show status: Defines how the variable is shown in the inventory.
  • Update status: Defines how the variable is updated in Cumulocity.
  • Send measurement: Create a measurement when the value of the variable is changed.
  • Raise alarm: Create an alarm if a given mask matches with the value of the variable ((value & mask) == mask). Therefore, it is possible to raise alarms on single bits of e.g. an Unsigned8 variable, like the Error-Register.
  • Raise event: Create an event, whenever the value of the variable is changed.

After adding variables to the new device type, they are listed in the Variables section of the device type. All variables are grouped by the given display category, i.e. variables with same category are grouped together.

category view

After completing your configuration, click Save to save your settings. The device type can be used now to add CANopen devices to the platform. The device type can be updated after creation.

Importing a device type

To import a new device type, see the Exporting and importing device types section.

After importing the EDS file, all variables defined in the file are listed in the Variables section of the device type. The user can then enrich the imported variable configurations by opening the configuration dialog for each variable (e.g. the missing display category can be set or mappings can be defined).

Configuring CANopen device data

To configure CANopen device data navigate to the desired device and switch to the CANopen tab.

In the CANopen communication section, the following parameters can be configured:

  • Baud rate: This field must match with the used baud rate in the CANopen network.
  • Polling rate: The rate at which the agent sends requests to the CANopen devices. to determine changes in variables.
  • Transmit rate: The transfer rate, i.e. the rate at which the terminal sends regular measurements to Cumulocity.

In the CANopen section, up to 127 CANopen devices can be added to the gateway as child devices by giving the following parameters:

  • Name: The name of the device used for visualization.
  • Device type: The device type of the CANopen device. The user can select from a list of all CANopen device types which are stored in the device database.
  • Node ID: The CANopen node ID of the device. It is used for addressing the device inside the CANopen network.

The device type and node ID need to match with the real CANopen device, otherwise setting up the communication is not possible or wrong values will be transmitted.

Exporting and importing device types

To manage device types more conveniently, you can export device types to a file once they are edited in the user interface. The file can be re-imported to set up other Cumulocity accounts easily or to restore the types from a backup. The import functionality also supports importing ready-made device types provided by device manufacturers.

To export a device type, hover over the device type that you would like to export and click Export. Your browser will download a file named "<device type>.json" with the device type definition.

Export device type

To import a device type, click Import in the top menu bar. This will open a dialog that lets you choose between importing a ready-made device type and uploading a previously exported device type. You can change the name of the device type during import using the New device type name field.

Import device type

Cloud Remote Access

Introduction

Cumulocity Cloud Remote Access implements Virtual Network Computing (VNC) to remotely access operating panels and other devices via a web browser.

VNC

Cloud Remote Access works as in the illustration below. Starting from the remote-controlled device: The device runs a VNC server and is connected to a gateway compatible with Cloud Remote Access. This gateway must be registered as a device within the Device Management application in Cumulocity. More information about registering devices and instructions can be found in Device Management > Device Registration in the User guide.

VNC2

With Cloud Remote Access users can

  • view status visualizations and track updates of remote devices immediately as if the user were at the device location,
  • connect to remote devices easily as complex VPN setups are not required,
  • establish connection via Telnet or SSH to the gateway itself or to any device in the local area network.

VNC1b

The connection to remote devices is securely encrypted through TLS technology. Additionally, passwords are encrypted in your Cumulocity account, so that you do not need to manage them elsewhere.

Using Cloud Remote Access

Cloud Remote Access is available in the Device Management application.

To use Cloud Remote Access, the following prerequisites have to be met:

  • a Cloud Remote Access compatible gateway connected to your Cumulocity account;
  • a device with a VNC server that is connected to the gateway and reachable from the gateway;
  • Cloud Remote Access included into your subscription plan.

Click All devices and select the desired gateway from the device list.

router device

When you open the device you will find the Remote access tab in the tab list of the device.

In the Remote Access tab you will find a list of devices for remote control, so-called "endpoints".

Info: If the prerequisites are met and you do not see the Remote access tab in the tab list of your gateway contact sales@cumulocity.com.

Adding new endpoints

The "endpoint" is the IP address and port of the VNC, SSH or Telnet server running on the device. The IP address and port need to be reachable from the gateway.

Endpoints

To configure remote devices, click Add endpoint. Follow the descriptions below for configuring the various kind of endpoints.

Info: To be able to configure an endpoint, you need "Admin" permission for "Remote access" and "Device control". To read data, a “Read” permission is sufficient. For more information on permissions, refer to Administration > Managing permissions in the User guide.

Adding remote access endpoints via VNC

To configure a remote access endpoint via VNC, enter a description for the remote access endpoint, the IP address and port, and the password of the VNC server. Click Save to add the endpoint to the list.

Remote access endpoint

Once the connection is established, a new browser tab will open displaying the front screen or operating panel of the device you are connected to. The top bar of the screen will show “starting VNC handshake” when the process is starting.

Adding remote access endpoints via Telnet

Enter the name of the endpoint. Select the Telnet protocol from the dropdown menu. Enter the IP address and the port. When ready, click Save.

Remote access Telnet endpoint

Adding remote access endpoints via SSH

To configure a remote access endpoint via SSH, enter the name of the endpoint, select the "SSH" protocol from the dropdown list, and enter the IP address and the port. There are two Sign-in methods to be selected:

  • Username and password: If this method is selected, it is mandatory to enter username and password.

    SSH username and password sign in

  • Public/private keys: Automatically generate public and private keys or simply paste pre-generated keys. The keys can also be uploaded from a file.

    SSH public/private keys sign in

Info: The public key needs to be installed on the device as authorized_key.

Optionally, you can also add a host key to ensure connection to the correct device. This key can also be uploaded from a file.

Click Save to save your settings.

The following formats are supported when adding new keys:

  • OpenSSHv1
  • OpenSSHv2
  • PEM
  • SSH2

The following algorithms are supported when adding new keys:

  • RSA
  • DSA
  • ECDSA
  • ED25519

Editing or removing endpoints

To edit or remove an endpoint, click the menu icon at the right of a row and select Edit or Remove from the context menu.

Edit endpoints

Connecting to endpoints

To connect to configured endpoints, choose an endpoint in the Remote access tab and click Connect. The connection will be set up.

Connect Endpoint

To terminate the connection, click Disconnect.

Displaying the audit logs

Audit logs are displayed for each device.

For each connection the Cloud Remote Access microservice creates an operation in scope of the current user. The operation then will be updated by the device to reflect the current status. Finally the operation will be in state SUCCESSFUL or FAILED.

The audit logs can be found in the Control tab of the device.

Display Audit logs

Troubleshooting

If you cannot set up new endpoints, check if you have sufficient permissions.

To set up new endpoints, you need "Admin" permission for "Device control" to be able to register a device and “Admin” permission for "Remote access" to be able to add an endpoint.

To establish a connection to a remote operating panel, a “Read” permission for "Remote access" is sufficient.

For more information on permissions, refer to Administration > Managing permissions in the User guide.

The VNC connection via a gateway to a remote VNC server can fail because of network problems. In this case you need to contact your network administrator.

The functionality has been tested on the following VNC servers:

  • Real VNC Connect 6.0.2
  • TightVNC 1.3.9
  • TigerVNC 1.7.0
  • EfonVNC 4.2

IMPACT Agent

This document describes

IMPACT Integration

Cumulocity offers an integration with the Nokia IMPACT Data Collector which is designed to collect data from heterogeneous devices. Integrating Cumulocity with IMPACT, enables you to make use of existing Cumulocity features like connectivity monitoring, data visualization or real-time analytics with IMPACT devices.

Info: Currently only the integration of LWM2M devices has been tested.

The IMPACT agent in Cumulocity registers itself at the Nokia IMPACT platform. Similarly, it subscribes to events such as devices coming online or reporting data at IMPACT.

The following illustration provides an overview on the Cumulocity IMPACT integration.

IMPACT integration

Info: Your subscription needs to include the IMPACT feature. If you do not see the functionality described in this document, please contact the Cumulocity support.

To be able to communicate with a device through IMPACT the device must be registered in IMPACT. How to register a device in IMPACT is not in the scope of this document.

Device lifecycle integration

IMPACT devices do not need to be registered again in Cumulocity. Cumulocity’s device lifecycle integration automatically handles the following events:

Event type Description Actions triggered in IMPACT agent
Registration A new device has been registered at IMPACT. Create device in Cumulocity.
Obtain list of resources provided by device (either from request or by querying device).
Subscribe to all resources that are mapped as “Auto-Observe” in the corresponding object mapping.
Deregistration A device has been deleted in IMPACT. At IMPACT, unsubscribe from all resources for this device.
Expiration A device registration in IMPACT has expired. Mark device in Cumulocity as disabled.

IMPACT device protocols

To process data from IMPACT devices, Cumulocity uses device protocols. Through device protocols you can observe your resources and perform other actions like creating alarms.

Device protocols are accessible through the Devices types menu in the Device Management application. For details on the general usage see Device protocols.

Device protocols

How to add an IMPACT device protocol

To add a new IMPACT device protocol follow these steps:

  1. In the Device Management application, navigate to the Device protocol page, accessible from the Device types menu in the navigator.
  2. Click Add device protocol in the top menu bar.
  3. In the upcoming window select IMPACT as device protocol type.

    Add protocol
  4. In the next dialog, enter a unique ID, a name and an optional description for the device protocol.

    Add protocol
  5. Click Create to create the new device protocol.

The device protocol will open in a new page.

Protocol page

In the Device protocol page you will see the description at the top left and the ID, the creation date and date of the last update at the top right.

Below a list of resources configured for the device will be listed (which is empty when creating a new protocol), showing the ID, name and potentially configured functionalities for each resource.

Example: Resource list for the device protocol "Temperature Measurement":

Protocol page

How to add a resource to a device

Click Add resource at the bottom of the resource list to add a new resource to your device.

For each resource you may specify the following parameters:

Field Description Required
ID The ID of the resource. Must be unique within one protocol object. Mandatory
Name Name for the resource. Mandatory
Type The parameter type. May be one of BOOLEAN, STRING, INTEGER or FLOAT. Mandatory
Unit The parameter unit, e.g. Celsius, meter. Optional
Instance Type The instance type for the parameter. May be one of "Single" or "Multiple". The default value is "Single". Optional
Description A more detailed description of the resource. Optional

Optionally, you may turn on several functionalities for the resource:

Functionalities

Send measurements

Turn on Send measurements to specify a measurement.

  • In the Type field, enter the type of the measurement, for example “c8y_AccelerationMeasurement”.
  • Series are any fragments in measurements that contain a “value” property. In the Series field you can enter for example “c8y_AccelerationMeasurement.acceleration”.
  • The Unit field specifies the unit of the given measurement, for example “m/s” for velocity.

Create alarm

Turn on Create alarm if you want to create an alarm out of the resource. Specify the following parameters (all mandatory):

  • In the Severity field, select a severity for the alarm. May be one of CRITICAL, MAJOR, MINOR, WARNING.
  • The Type field is a text field which is used for duplicating alarms and for configuring the priority of alarms in the Administration application.
  • In the Status field, select an alarm status. may be one of ACTIVE, ACKNOWLEDGED, CLEARED.
  • In the Text field, provide a textual description for the alarm.

Send event

Turn on Send event to send an event each time a certain condition has been triggered. Specify the following parameters:

  • In the Type field, enter the type of the event, for example "com_cumulocity_model_DoorSensorEvent".
  • In the Text field, enter the text which will be sent, for example "Door sensor was triggered".

Auto observe

Enabling Auto observe for a resource means, that each time the device with this particular resource appears, Cumulocity will automatically receive all values. It is not necessary, to subscribe to it manually.

Info: At least one functionality must be set to enable Auto observe.

Finally, click Save to create the resource. The resource will be added to the resource list.

In the resources list you can see if functionalities have been turned on for a resource. Active functionalities are indicated by the related icons. In the example below, Send measurements and Auto observe are turned on.

Functionalities

Jasper Control Center

The Jasper Control Center Add-On to Cumulocity provides you with a holistic view of mobile device connectivity. This Add-On works from within the Cumulocity Device Management Application. While Cumulocity itself communicates directly with devices and shows connectivity information as reported by the device, the Jasper Control Center Add-On complements this with a view of connectivity.

Jasper architecture

If you have a Jasper Control Center account with your network provider, you can link that account to your Cumulocity tenant. With this combination you can:

  • Check the status of the SIM card in the device and activate or deactivate it.
  • Check the online status of the device as reported by the network.
  • View usage of data traffic, text messages and voice calls.
  • View the history of data sessions and any changes to the SIM card or tariffs.
  • Invoke the Control Center diagnostics tools.
  • Communicate with the device through text messages, for example, to set APN parameters.

The following sections describe:

Cumulocity accesses your Jasper Control Center account using a dedicated user that you need to create in the Control Center and configure it in Cumulocity. This user is used for all access from Cumulocity to Jasper Control Center, so the permissions of the user have influence on functionalities available in Cumulocity.

Besides the user, you also need a so-called API license key 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.

We recommend creating a dedicated user in Jasper Control Center:

  • As an admin user, navigate to "Admin" and "Users".
  • Click the "Create New" button.
  • Enter the user name and further details of the user.
  • If you want to be able to activate and deactivate SIM cards from Cumulocity, or to send SMS from Cumulocity, use the role "ACCOUNTUSER". Otherwise, use the role "ACCOUNTREADONLY".
  • Click "Ok" to create a user, then enter your password. Then click "Ok" again. (Note: You need to enter your admin password, not the password that the new user will get.)

Jasper user management

The user is now created but does not have a password yet. Follow the instructions emailed to you by Control Center to set a password. Now link your Jasper Control Center account to Cumulocity:

  • Use a Cumulocity administrator user to log in to the Cumulocity Administration application.
  • Click on the "Connectivity" menu. If the menu does not show, please make sure that your user has the "admin" permission for option management. If the menu still does not show, contact support to make the Jasper Control Center add-on available in your tenant.
  • Enter key, URL, username and password, then click "Save".

Jasper settings

The Add-On is now set up.

Now change to the Device Management application and navigate to a device that is connected through a SIM card managed by Jasper Control Center. You should see a tab "Connectivity". If this tab is not shown,

  • Your user does not have permissions on "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 Jasper Control Center account.

To assign permissions, navigate to the administration application and select "Read" or "Admin" permissions on "Connectivity" as shown below.

Connectivity permission settings

Jasper Control Center identifies SIM cards through their ICCID ("integrated circuit card identifier"). In most cases, devices will report the ICCID of their SIM card automatically to Cumulocity. If the ICCID is not shown:

  • 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 the "Reload" button of the browser to make the "Connectivity" tab appear.

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

Browsing the "Connectivity" tab

Now navigate to the "Connectivity" tab. It shows several sections of information:

  • Status.
  • SMS.
  • Sessions.
  • Audit log.

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

The "Status" section lists summary information for the SIM card, as visible in the screenshot below. 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 left side of the section 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.

The right side of the section shows usage information for the current month, i.e., from the first of the month till today. Hovering over the tooltip shows the covered time period, including the usage during the past month.

Status section

The "SMS" section shows the text messages sent to the device and received from the device, including

  • 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 Control Center, or "Cancelled", if it was not yet received by Control Center.
  • 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".

SMS section

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.

Sessions section

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

Audit logs section

This tab does not update in real-time. To show current data, click the "Reload" link at the top.

Managing connectivity

If you suspect that a device is not correctly reporting to Cumulocity, or it is not receiving commands, you can verify the connectivity status of the device using the "Connectivity" tab. Check if

  • The SIM is activated. If the SIM card is not activated, you can activate it selecting "Activated" from the 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). Select the cogwheel icon on the top right and click "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.

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

Finally, if the device is still not reporting to Cumulocity, 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 has to be analyzed in a device-specific way.

LoRa Actility

Cumulocity can interface with LoRa devices through Actility's ThingPark Wireless. You can:

  • Provision and deprovision LoRa devices easily using the Cumulocity Device Management. No interaction in the ThingPark user interface is required.
  • Decode upstream payload packets using a web-based user interface.
  • Debug and postprocess raw device data through Cumulocity events.
  • Send downstream data to the device using Cumulocity operations.
  • Make use of existing Cumulocity features with LoRa devices, for example: connectivity monitoring, device management, data visualization with dashboards, real-time analytics and more.

The following illustration gives an overview of the Cumulocity LoRa Actility integration.

Cumulocity LoRa Actility integration

The following sections describe how to:

Note that your subscription needs to include this feature. If you do not see the functionality described in this document, please contact support.

Configuring ThingPark account credentials

Before using LoRa devices with Cumulocity, you need to configure your ThingPark account details in the Cumulocity Administration application. In order to create new credentials or replace existing ones, go to the Administration application and select "Connectivity" in "Settings" in the navigator.

Creating new account credentials

If you go to "Connectivity" for the first time, you will be asked to provide credentials and application EUI which is used for LoRa device provisioning.

Enter the following information:

  • profile ID: This depends on your ThingPark account and environment. If you are using, for example, the Dev1 ThingPark environment your profile ID will be "dev1-api". Multiple tenants can have the same profile id.
  • username: your ThingPark user name
  • password: your ThingPark password
  • application EUI: This is a global application ID in the IEEE EUI64 address space that uniquely identifies the application provider of the device. It is a 16 character (8 byte) long hexadecimal number. There can be only one application EUI for a tenant but multiple tenant can have the same application EUI.

Do not use the same ThingPark login (username and password) for other tenants. The profile ID, username and password are used to retrieve an access token to send further requests to the ThingPark platform. It is possible to renew the access token by replacing the account credentials.

Setting device credentials

Click "Save". If everything is okay, there will be a message "Credentials successfully saved".

Replacing account credentials

In order to replace your credentials, click the "Replace credentials" button.

Enter your profile ID, username, password and application EUI. For an explanation of the terms "profile ID" and "application EUI", refer to section Creating new account credentials above.

Account credentials

Click "Save". Your old credentials will now be replaced with the new ones.

Creating device types

To process data from LoRa devices, Cumulocity needs to understand the payload format of the devices. Mapping a payload data to Cumulocity data can be done by creating a LoRa device type. During the device registration, you can associate this device type and afterwards the received uplink callbacks for this device with a hexadecimal payload will be mapped to the ones you have configured in your device type. If a device type has been changed after being associated to a device, the reflection of the change can take up to 10 minutes because of the refresh mechanism of the Actility Server Side Agent.

Note that device protocol mapping only supports decoding for fixed byte positions based on the message type.

In order to create device types, go to the Device Management application and select "Device database" in the "Device types" menu in the navigator. You can either import an existing device type or create a new one.

Importing a predefined device type

In the Device database window, click the "Import" button.

Select the predefined device type, for example "LoRaWAN Demonstrator". Click "Import".

Import a predefined device type

Alternatively you may also load the device type from a file and import it.

Creating a new device type

In the device database window, click the "New" button. The following window will open:

Create new device type

Select "LoRa" as the device type and name your device type.

In the next UI section you determine the message type. LoRa devices can send messages of different types with different encodings per type. Depending on the device, the type can be determined by looking either at the FPort parameter of a message (Source: FPort) or at the subset of the message payload itself (Source: Payload).

Select the way the message type is encoded in the "Source" dropdown box:

  • FPort: if the message type can be determined by looking at the FPort parameter of a message
  • Payload: if the message type can be determined by looking at the subset of the message payload itself

In the following example payload structure, the first byte indicates the message type source (as highlighted).

Example payload: message type source

In the user interface you can enter this type of message type source information as follows: Indicate in the "Start bit" field where the message type information starts in the payload and how long this information is in the "Number of bits" field, for example start bit = "0" and number of bits = "8".

Message type payload

Click the "Add" button to create the value configuration.

Device type: new

A window similar to the following one will open. Configure the relevant values as shown in this example.

Value configuration: new

The value configuration maps the value in the payload of a message type to the Cumulocity data.

Configure the "Message ID" according to your device message specification and map it to the Cumulocity data. The message ID is the numeric value identifying the message type. It will be matched with the message ID found in the source specified on the device type main page (i.e. Payload or FPort). The message ID needs to be entered in decimal numbers (not hex).

In this example payload structure the message ID is "1".

Example payload: message type source

Value configuration: message type

Fill in the general fields for your new value in order to categorize it in the "Values" list. The associated "Name" for this value will be displayed under the "Display category" given.

Under "Value selection" define from where the value should be extracted. In order to do so, indicate where the value information starts in the "Start bit" field and how long this information is in the "Number of bits" field.

In this example the "Channel 1 Type" information starts in byte 2 (i.e. start bit = "16") and is 1 byte long (i.e. number of bits = "8").

Example payload: value selection

Value selection

The hexadecimal value is converted to a decimal number and afterwards a "value normalisation" is applied.

Under "Value normalisation" define how the raw value should be transformed before being stored in the platform and enter the appropriate values for:

  • Multiplier: This value is multiplied with the value extracted from the "Value selection". It can be decimal, negative and positive. By default it is set to 1.
  • Offset: This value defines the offset that is added or subtracted. It can be decimal, negative and positive. By default it is set to 0.
  • Unit (optional): A unit can be defined which is saved together with the value (e.g. temperature unit "C" for degree Celsius).

For detailed information on how to decode the payload, refer to the documentation of the device.

Note: "Little endian" support to decode the payload has been added.

Select the options, if required: "Signed" (if the value is a signed number) or "Packed decimal" (if the value is BCD encoded).

In the functionalities, define how this device type should behave:

  • Send measurement: creates a measurement with the decoded value
  • Raise alarm: creates an alarm if the value is not equal to zero
  • Send event: creates an event with the decoded value
  • Update managed object: updates a fragment in a managed object with the decoded value

You can also have a nested structure with several values within a measurement, event or managed object fragment. In case of a measurement all the properties of the same type will be merged to create a nested structure. In case of an event or a managed object all the properties with the same fragment are merged to create a nested structure. (Also refer to the example of a nested structure for a "Position" device type below.)

After clicking "OK", the values are added to your device type.

Value configurations of created device type

After clicking "Save", your device type is created with the values you defined.

Example with single property

The following picture shows an example for a message which sends a measurement when this value (the battery level) changes.

Value configuration in detail: measurement

Example with nested structure

The following picture shows an example of a nested structure for a device type reporting the current position of a GPS device. The device type is named "Position" and contains values for longitude and latitude.

The "Message ID" should be the same for all the values. Enter the rest of the parameters according to the instructions above. Enter "c8y_Position" in the "Managed object fragment" field and create a new value for each: longitude and latitude.

Value creation: Longitude-nested

Value creation: Latitude-nested

This will be the result:

Value configuration in detail: nested structure

Registering LoRa devices

In order to register a LoRa device, go to the Device Management application and click "Device Registration" in the Quick links. Click "Register device". The following window opens:

Register devices

Click "LoRa".

Cumulocity fully supports the LoRa device provisioning with Over-the-Air Activation (OTAA) which is the preferred and most secure way to connect with the LoRa network. If Activation by Personalization (ABP) is required to be used, please see the LoRa device registration with ABP section.

In the next window fill in the required information:

  • Device profile: Select the appropriate device profile from the drop-down list.
  • Device type: Select the appropriate device type from the drop-down list.
  • Device EUI: This is the unique identifier for the device. It is a 16 character (8 byte) long hexadecimal number. You can find it on the device itself.
  • Application key: This is an AES-128 application key specific for the device that is assigned to the device by the application owner and is responsible to encrypt. The application key is a 32 character (16 byte) long hexadecimal number. JOIN communication. You can find this key on the device itself.
  • Connectivity plan: Select the appropriate connectivity plan from the drop-down list.

The following picture shows an example for device registration.

Register devices

After clicking "Next" the device registration request will be submitted and the device will be created.

You can verify that the device is really connected by checking that events are actually coming in. You can do so by clicking on a device and opening the "Events" tab. All events related to this device are listed here.

For more information on viewing and managing your connected devices, also refer to Device Management.

LoRa device registration process

LoRa device registration with Activation by Personalization (ABP)

Activating the device by personalization is not suggested and not fully supported in Cumulocity LoRa device registration. However, if you would like to create a device with this activation type in Cumulocity and use the LoRa features such as sending operations to a device, deprovisioning a device and setting LoRa device type with custom device protocol configuration, you must first provision the device in the ThingPark platform. Moreover you have to create "AS Routing Profile" for Cumulocity using destination "http://actility-server.cumulocity.com" as a "Third Party AS (HTTP)" and assign it to your devices manually. Afterwards, you can register this device using LoRa device registration. In this case, the application key field in the LoRa device registration is invalid.

Limitations for LoRa devices which were not created using LoRa device registration

The general device registration for LoRa devices is no longer supported. The existing LoRa devices that were already created in Cumulocity with the general device registration process have limitations. For those devices, it is not possible to send operations to device, deprovision device and set LoRa device type with custom device protocol configuration. It is recommended to delete and re-register these devices using LoRa device registration to fully use the LoRa feature.

Deprovisioning LoRa devices

You can deprovision a LoRa device in the ThingPark platform. This means that the device will no longer be connected to the network. Its history data will still be available in Cumulocity, but the device will be deleted in ThingPark.

To deprovision a device, go to the Device Management application and navigate to the device you want to deprovision. Click the cogwheel and select "Deprovision device".

Device deprovisioning

After confirming the deprovisioning, the device will be deprovisioned in ThingPark.

Sending operations

If a LoRa device supports receiving hexadecimal commands, you can send them using shell operations. Notice that these commands are not serial monitor commands. In order to send an operation, go to the Device Management application and navigate to the device you want to send an operation to. Click the "Shell" tab.

In the following screenshot you can find some examples of a specific device type's predefined commands and their format. Predefined commands

Enter the shell command or view/edit the predefined command in the ">_Command" field.

If you enter the command without defining a port, it will be sent to the default target port (i. e. 1) of the device. If you enter the command and define a port (format "command:port"), it will be sent to the specified target port instead of the default port.

Port configuration

Click "Execute". The operation will be sent to the device. The timing depends on Actility ThingPark.

ThingPark Api availability monitoring

The ThingPark Api is monitored and if the ThingPark Api is not reachable, an alarm is created to notify all the subscribed tenants that are using this feature. The alarm is cleared right after the ThingPark Api is reachable again.

ThingPark Api monitoring alarm

LightweightM2M

Lightweight M2M (LWM2M) is a traffic and resource-optimized protocol to remotely manage IoT devices. The protocol is standardized by the Open Mobile Alliance. For more information, see http://openmobilealliance.org/iot/lightweight-m2m-lwm2m.

You can connect any device supporting LWM2M to Cumulocity without programming. Instead, you configure how LWM2M devices are mapped to Cumulocity using device protocols.

Device protocols

Registering LWM2M devices

To connect LWM2M devices, you need to upload a CSV file with registration data. This data is required to enable LWM2M communication. The CSV holds all information for factory bootstrap and client-initiated bootstrap. In the factory bootstrap mode, the LWM2M client has been configured with the necessary bootstrap information prior to the deployment of the device. The client initiated bootstrap mode requires a LWM2M bootstrap-server account pre-loaded in the LWM2M client. Below, you can see two CSV examples:

CSV example 1

In the first CSV example you can see the following fields:

Field Description
ID Unique ID of the device. For example, the ID could be an IMEI, serial number, etc.
IDTYPE The type of the device.
CREDENTIALS The content of this field is not used by LWM2M.
NAME The name of the device. In this case the name of the device is the same as the device ID.
TYPE This field needs to have the value "c8y_lwm2m”.
SHELL To enable “Shell”, the value of this field must be “1”. If you want to disable “Shell” the value must be “0”. For more info about the shell commands, see Shell commands.
com_cumulocity_model_Agent This field needs to have the value "1".
endpoint id Indicates the LWM2M client’s “Endpoint ID” in order to allow the LwM2M bootstrap to provision the bootstrap information for the LWM2M client.
lwm2m server url The URL the server is using for bootstrap. The LWM2M bootstrap server is used to provision the LWM2M client with the information required to contact the LWM2M servers. If you are using the Cumulocity service the hostname of the LWM2M server is "lwm2m.cumulocity.com". The bootstrap server port is "5683" and the LWM2M port is "5783". Note, that these values can be different for other services.
securityMode In this example the value of the security mode is “NO_SEC” which means that there is no security. It is highly recommended to always protect the LWM2M protocol. However, there are scenarios in which the LWM2M protocol is deployed in environments where the lower layer security mechanisms are provided. Currently Cumulocity supports only “NO_SEC” and “PSK”. With “PSK”, the client and server have a common secret symmetric cryptography. In the next example you will see how the CSV file should look when the security mode value is “PSK”.

CSV example 2.1 CSV example 2.2

In this CSV example, the security mode value is “PSK”, hence additional fields are required. The table below reflects the full set of possible fields.

Field Type Description Mandatory
lwm2m psk_key String For security mode PSK: The key used by the device for LWM2M in PSK mode. Will be delivered to the device during bootstrap. Mandatory for PSK. Should not be set for NO_SEC
lwm2m psk_id String For security mode PSK: The ID used by the device for LWM2M in PSK mode. Will be delivered to the device during bootstrap. Mostly the same as the endpoint name. Mandatory for PSK. Should not be set for NO_SEC
endpoint id String The name of the LWM2M endpoint. Yes
bootstrap psk_id String For security mode PSK: The ID used by the device for bootstrapping in PSK mode. Yes for PSK
bootstrap psk_key String For security mode PSK: The key used by the device for bootstrapping in PSK mode. Yes for PSK
lwm2m server url String The URL of the LWM2M server to be sent to the devices during bootstrap. If you are using the Cumulocity service the hostname of the LWM2M server is "lwm2m.cumulocity.com". The bootstrap server port is "5683" and the LWM2M port is "5783". Note, that these values can be different for other services. Yes, for LWM2M bootstrap
securityMode String, “NO_SEC” or “PSK The LWM2M security mode to be used. Possible values are PSK and NO_SEC. Yes
serverPublicKey String The public key of the server. Optional
generateBootstrapServerConfig Boolean Toggles if Cumulocity generates a server config for the LWM2M bootstrap server and writes that back during bootstrap. Default is false. Optional
securityInstanceOffset Integer The first instance to be used during bootstrap to which entries are written. "0" is default. If set e.g. to "3", the first instance will be three. Optional
bootstrapShortServerId Integer The short server ID to be used for the bootstrap server. Default is "0". Optional
lwm2mShortServerId Integer The short server ID to be used for LWM2M server. Default is "1". Optional
registrationLifetime Integer The registration lifetime that is sent to the device during bootstrap. Overrides global agent configuration. Optional
defaultMinimumPeriod Integer The default minimum period to configure during bootstrap. See LWM2M Spec for explanation. Optional
defaultMaximumPeriod Integer The default max period to configure during bootstrap. See LWM2M Spec for explanation. Optional
bindingMode String The LWM2M binding mode to be reported to the device. Supported are “UQ” (default, queuing) and “U” (unqueued). Note, that Cumulocity will always queue operations. Optional
notificationIfDisabled (true/false) Boolean See LWM2M spec. Default: Not configured. Optional, defaults to Leshan default behavior
disableTimeout (true/false) Boolean See LWM2M spec. Default: Not configured. Optional, defaults to Leshan default behavior
external-c8y_BootstrapPskId String The ID being used to find a device during bootstrap. Optional

Info: Firmware updates are also supported. For more information, see Device Management > Managing device data in the User guide.

After creation, the bootstrap parameters can be viewed and changed in the LWM2M bootstrap parameters tab in the Device details page, see LWM2M bootstrap parameters.

LWM2M device protocols

To process data from LWM2M devices, Cumulocity uses device protocols. Device protocols are accessible through the Devices Types menu in the Device Management application. For details on the general usage, see Device Management > Managing device types.

Creating LWM2M device protocols

Once you have registered a device with the proper CSV file, you can manage LWM2M device protocols. Each piece of information available by the LWM2M client is a resource. The resources are further logically organized into objects. The LWM2M client can have any number of resources, each of which belongs to an object. In the device protocols you can observe your resources. Furthermore, you can choose whether to create measurements, events or alarms out of those resources.

To add a new LWM2M device protocol follow these steps:

  1. In the Device Management application, move to the Device protocol page.
  2. Click Add device protocol in the top menu bar.
  3. In the upcoming dialog select LWM2M as device protocol type.

    Protocol type

  4. Next, upload an appropriate DDF or XML file. DDF or XML files describe the data provided by your device. They are typically provided by the manufacturer or by standards bodies such as IPSO. There are also 3 "special" device protocols (DDF files) for standard OMA objects: 6 (location tracking), 5 (firmware update) and 3 (device information). If these files are not uploaded, then neither location tracking nor firmware updates will work. By default, the LWM2M agent adds mappings to these objects and knows how to "handle" their information without any additional configuration. The XML schema used by LWM2M can be found here.
    If the DDF files for the default mappings are uploaded in the management tenant, all subscribed user tenants will inherit this behavior.

    Upload DDF

  5. In the next dialog, you can see the name and description of the protocol. Click Continue to create the new device protocol.

    Protocol name

The device protocol will open in a new page.

Example protocol

In the device protocol page, you will see the description at the top left and the ID, the creation date and date of the last update at the top right.

Below, a list of resources configured for the device will be listed (which is empty when creating a new protocol), showing the ID, name and potentially configured functionalities for each resource.

Info: LWM2M protocol resources cannot be edited.

Example: In the following screenshot you can see an example device protocol. This object should be used with a temperature sensor to report a temperature measurement. It also provides resources for minimum/maximum measured values and the minimum/maximum range that can be measured by the temperature sensor. An example measurement unit is “degrees Celsius”.

Example protocol2

Adding additional functionalities to a resource

The functionalities that you may enable are the following:

Resource functionalities

Send measurement

Turn on Send measurement to specify a measurement.

  • Enter the type of the measurement. For example, “c8y_AccelerationMeasurement”.
  • Series are any fragments in measurements that contain a “value” property. For example, in the series field you can enter: “c8y_AccelerationMeasurement.acceleration”
  • The “Unit” field specifies the unit of the given measurement. For example, “m/s” for velocity.

Create alarm

Turn on Create alarm if you want to create an alarm out of the resource. Specify the following parameters (all mandatory):

  • Severity - one of CRITICAL, MAJOR, MINOR, WARNING
  • Type
  • Status - one of ACTIVE, ACKNOWLEDGED, CLEARED
  • Text

Send Event

Turn on Send event to send an event each time you receive a resource value. Specify the following parameters:

  • Enter the type of the event. For example, "com_cumulocity_model_DoorSensorEvent".
  • Enter the text which will be sent. For example, "Door sensor was triggered".

Custom Actions

Adding a custom action to a mapping invokes custom specific mapping actions, for example custom decoders for opaque data. The dialog allows you to select a custom action from a dropdown box.

Custom actions

Auto observe

If Auto-Observe is turned on for a resource, the LWM2M server observes a specific resource for changes.

Info: At least one functionality must be set to enable "Auto observe".

Resource

LWM2M device details

Info: In the Device management application, you can view all details of a device. The following details are specific to LWM2M devices. For information on general details refer to Device details in the Device management section.

Objects

In the Objects tab of a LWM2M device, you can view all objects, resources and instances of the device. Additionally, you can create new operations, see all currently pending operations and view the history of all previous operations.

Objects view

Info: In order to see resources in the Objects tab, the resources first have to be added in the Device Protocols page.

The following operations may be available in each instance:

  • Read Object: Reads all instances for the selected object and lists all available resources for each instance.

    Read Objects

  • Read Instance: Reads the current instance of the given object and lists all available resources.

    Read Instance

  • Create Instance: Creates a new instance for the selected object.
  • Delete Instance: Deletes the selected instance.

Info: Some instances do not have all of the listed operations.

Some object cards show additional operations which can be performed. These operations become available after reading the object/instance, for example, device Reboot or Reset error code. In order to perform these operations, click Execute.

Execute operation

More information can be acquired for each resource by hovering over the tooltip icon.

Tooltip

Additional information on recent operations can be viewed by clicking the operations button located on the right side of an instance card. The button is only visible if any operation has been performed. The number of unread operations can be seen on the top right of the button. In the example below there is only one.

Recent operations Recent operations 2

To view the history of all operations, simply click View history. Note, that you will be redirected to the Control tab.

Control tab

Audit Configuration

In the Audit configuration page you can audit the current device by comparing it to a selected reference device. It is also possible to sync properties to the values of the referenced device.

Click Audit configuration in the right of the top menu bar to navigate to the Audit configuration page.

Audit configuration

To sync properties, select the desired reference device from the dropdown list. Check the properties that you wish to sync and click Sync selected properties.

Info: The numbers in the green circles represent the number of properties in the instance which have the same value in both devices. Respectively, the numbers in the red circles represent the number of properties which have different values compared to the values of the referenced device. If an instance is expanded, you can select only specific properties which can be synced.

Sync properties

LWM2M bootstrap parameters

In the LWM2M bootstrap parameters tab, bootstrap parameters of the current device can be viewed and changed. To modify a parameter, enter the desired value in a field of your choice and click Save.

Bootstrap customization

Important: Currently only the "NO_SEC" and "PSK" security modes are supported.

For further information on the fields in the LWM2M bootstrap parameters tab, see Registering LWM2M devices.

Handling LWM2M shell commands

In the Shell tab of a device, LWM2M shell commands can be performed. Each command has a different functionality. Find all available placeholders (e.g. “objectID”, “instanceID”) and commands with their respective descriptions below:

Placeholder Description
objectID The ID of the object.
instanceID The ID of the instance. Some objects can have multiple instances. For example, “3300” is a temperature sensor object. Each device can have up to 10 sensors. In this case the instance ID would be 3300/1...10 depending on the sensor that you would like to focus.
resourceID The ID of the desired resource. The resources describe the characteristics of each object. All instances of a given object have the same resources, but the value of the resources may be different.
Firmware version The current version of the firmware.
Firmware url The URL from which the new version of the firmware will be downloaded.

In the next table you will see all available commands and a brief description of their functionality.

Command Description
read /// Reads a resource path
observe /// Enables the observe functionality
execute /// Executes a resource on the device
cancelobservation /// Cancels the observation functionality from the desired resource
delete //[/] Deletes a given object/instance/resource
discover /// Shows all resources of the given object
create / [JSON] Creates a new object. The JSON argument is optional
writeattr /// {pmin=}{&pmax=}{&greater=}{&less=}{&step=}{&cancel} Writes additional attributes to the object. Typically used for conditional observes
fwupdate ///<firmware_ur>/l Updates the firmware of the agent

Adding validation rules to resources

Validation rules are used to verify that the data a user enters in a resource meets the constraints you specify before the user can save the resource.

Validation rules can only be added to resources which have “write” permissions. Resources which can have validation rules are marked by the following icon:

Validation rule icon

When hovering over the icon, you can see whether there are defined validation rules.

Add a new validation rule by clicking on the desired resource and then click Add validation rule.

Add validation rule

Validation rules can have the following types:

  • Date: Simply enter a date and choose your desired rule.
  • Number: Only values of “Integer” or “Float” type are allowed depending on the resource.
  • ObjectLink: Reference to another object using the format “/Object/Instance/Resource”.
  • Regex: Add a string which describes the validation pattern. For example, “.*dd” means that the string must end with “dd”.
  • String: Enter a string value which can be either “True” or “False".

After selecting a type, the following rules can be chosen:

  • Greater than
  • Lower than
  • Equals
  • Equals not
  • Greater or equals than
  • Lower or equals than

Info: Not all rules are available to each type.

To delete a rule, simply click on the delete icon:

Remove lwm2m rule

Click Save to save your settings.

Complex rulesets

In order to enable more complex conditions, multiple validation rules can be defined for a resource:

  • Multiple rules can be defined in a validation rule group. A user input is only valid if each of the rules in the validation rule group is satisfied (logical AND).
  • It is possible to declare multiple validation rule groups. If multiple validation rule groups are declared, user input is valid if any of the validation rule groups is satisfied (logical OR).

The screenshot above provides an example for the use of validation rule groups: User input is valid if the given string does not match “test” (equals not). It is also valid if it ends with “asd” and it matches the contents of the LWM2M resource /3/0/15.

Complex rulesets are based on Boolean Disjunctive Normal Form, which allows arbitrary complex rules to be defined.

Sigfox

Cumulocity can interface with Sigfox devices through the Sigfox Cloud. You can:

  • Provision Sigfox devices easily using the Cumulocity Device Management.
  • Decode upstream payload packets using a web-based user interface.
  • Debug and postprocess raw device data through Cumulocity events.
  • Send downstream data to the device using Cumulocity operations.
  • Make use of existing Cumulocity features with Sigfox devices, for example: connectivity monitoring, device management, data visualization with dashboards, real-time analytics and more.

The following illustration grants you a quick overview of the Cumulocity Sigfox integration:

Cumulocity Sigfox integration

The following sections describe how to:

Info: To be able to use the Sigfox agent, your tenant needs to be subscribed to the following applications: sigfox-agent, feature-fieldbus4. In case of any issues, please contact support.

Managing the connectivity settings

Before you register a device, you need to configure Sigfox Cloud credentials in the “Connectivity” page in the Administration application. You have to set up these Sigfox Cloud credentials in Sigfox.

Before you create API access to Cumulocity, you need to have an “Associated user” which is added to the Cumulocity group in Sigfox Cloud and has the following profiles:

  • Customer [W]
  • Device Manager [W]

Info: Without the following profiles, the required Sigfox API access can not be set up.

Step 1 is only relevant, if you do not have an associated user yet. If you do, skip to Step 2.

Step 1

First enter into your Sigfox Cloud account and create a new user. Add the user to the “Cumulocity” group and select the “Customer [W]” and “Device Manager [W]” profiles.

New user

Step 2

After creating an “Associated User” with the proper group and profiles navigate to the “Groups” page. In the “API Access” tab create a new entry and add the following profiles:

  • Customer [R]
  • Device Manager [R]
  • Device Manager [W]

API access page

Step 3

After the API access entry has been created, you can connect your Sigfox Cloud account to Cumulocity via the “Connectivity” page in the Administration application. Navigate to the “Connectivity” page and then go to the “Sigfox provider settings” tab.

The following information has to be provided:

  • Login: The login token is located in the API access entry in the Sigfox Cloud.
  • Password: The password token is located in the API access entry in the Sigfox Cloud next to “Password”.
  • Parent Group ID: This ID is written in your URL when you are logged into your Sigfox account and you have selected the “Cumulocity” group. For example, “https://backend.Sigfox.com/group/**9823ruj29j9d2j9828hd8**/info”.

API access page

API access page

Click Save credentials to save your settings. If everything is correct, a message "Credentials successfully saved" will be displayed.

If you wish to overwrite your previous credentials, simply click Replace credentials and add your new credentials.

Creating device types

To process data from Sigfox devices, Cumulocity needs to understand the payload format of the devices. Mapping payload data to Cumulocity data can be done by creating a Sigfox device type.

During the device registration, you can associate this device type and afterwards the received uplink callbacks for this device with a hexadecimal payload will be mapped to the ones you have configured in your device type. If a device type has been changed after being associated to a device, the reflection of the change can take up to 10 minutes because of the refresh mechanism of the Sigfox microservice.

Info: Device protocol mapping only supports decoding for fixed byte positions based on the message type.

In order to create device types, go to the Device Management application and select "Device database" in the "Device types" menu in the navigator. You can either import an existing device type or create a new one.

Importing a device type

In the Device database window, click Import.

Upload the device type from a file and click Import again.

Creating a new device type

In the device database window, click New. The following window will open:

Create new device type

Select "Sigfox" as the device type and provide a name for your device type.

In the following window you determine the message type. Sigfox devices can send messages of different types with different encodings per type. Depending on the device, the type can be determined by looking either at the FPort parameter of a message (Source: FPort) or at the subset of the message payload itself (Source: Payload).

Select the way the message type is encoded in the "Source" list:

  • Payload: if the message type can be determined by looking at the subset of the message payload itself

In the following sample payload structure, the first byte indicates the message type source (as highlighted).

Example payload: message type source

In the user interface you can enter this type of message type source information as follows: In the "Start bit" field, indicate where the message type information starts in the payload and in the"Number of bits" field indicate how long this information is, for example start bit = "0" and number of bits = "8".

Message type payload

Click Add to create the value configuration.

Device type: new

A window similar to the following one will open. Configure the relevant values as shown in this example.

Value configuration: new

The value configuration maps the value in the payload of a message type to the Cumulocity data.

Configure the "Message ID" according to your device message specification and map it to the Cumulocity data. The message ID is the numeric value identifying the message type. It will be matched with the message ID found in the source specified on the device type main page (i.e. Payload or FPort). The message ID needs to be entered in decimal numbers (not hex).

In this sample payload structure the message ID is "1".

Example payload: message type source

Value configuration: message type

Fill in the general fields for your new value in order to categorize it in the "Values" list. The associated "Name" for this value will be displayed under the "Display category" given.

Under "Value selection" define from where the value should be extracted. In the “"Start bit" field, indicate where the value information starts and in the "Number of bits" field, indicate the length of the information.

In this example the "Channel 1 Type" information starts in byte 2 (i.e. start bit = "16") and is 1 byte long (i.e. number of bits = "8").

Example payload: value selection

Value selection

The hexadecimal value is converted to a decimal number and afterwards a "value normalization" is applied.

Under "Value normalization" define how the raw value should be transformed before being stored in the platform and enter the appropriate values for:

  • Multiplier: This value is multiplied with the value extracted from the "Value selection". It can be decimal, negative or positive. By default it is set to 1.
  • Offset: This value defines the offset that is added or subtracted. It can be decimal, negative or positive. By default it is set to 0.
  • Unit (optional): A unit can be defined which is saved together with the value (e.g. temperature unit "C" for degree Celsius).

For detailed information on how to decode the payload, refer to the documentation of the device.

Select the options, if required: "Signed" (if the value is a signed number) or "Packed decimal" (if the value is BCD encoded).

In the functionalities, define how this device type should behave:

  • Send measurement: creates a measurement with the decoded value
  • Raise alarm: creates an alarm if the value is not equal to zero
  • Send event: creates an event with the decoded value
  • Update managed object: updates a fragment in a managed object with the decoded value

You can also have a nested structure with several values within a measurement, event or managed object fragment. In case of a measurement all the properties of the same type will be merged to create a nested structure. In case of an event or a managed object all the properties with the same fragment are merged to create a nested structure. (Also refer to the example of a nested structure for a "Position" device type below.)

After clicking "OK", the values are added to your device type.

Value configurations of created device type

After clicking "Save", your device type is created with the values you defined.

Example with single property

The following image shows an example for a message which sends a measurement when this value (the battery level) changes.

Value configuration in detail: measurement

Example with nested structure

The following image shows an example of a nested structure for a device type, reporting the current position of a GPS device. The device type is named "Position" and contains values for longitude and latitude.

The "Message ID" should be the same for all the values. Enter the rest of the parameters according to the instructions above. Enter "c8y_Position" in the "Managed object fragment" field and create a new value for each: longitude and latitude.

Value creation: Longitude-nested

Value creation: Latitude-nested

This will be the result:

Value configuration in detail: nested structure

Registering Sigfox devices

In order to register a Sigfox device, go to the “Registration” page in the “Device Management” application and click “Register Devices”.

Register devices

In the upcoming window, click Sigfox.

Info: If Sigfox is not one of the available options, your tenant is not subscribed to the relevant applications, see info at the top.

In the next window, fill in the required information:

ID: Unique device ID. The value must be a hexadecimal number. PAC: Porting authorization code for your device. The value must be a hexadecimal number. Contract: Choose your desired contract. Device Type: Select your desired device type from the drop-down list. Product Certificate Key: This key can be located in “https://partners.sigfox.com/”. Navigate to your device and copy the certificate key.

Info: The term "Device type" is used both by Sigfox and Cumulocity, but with different meaning. In Sigfox, a device type specifies how to route data from devices. In Cumulocity, a device type describes the data that is sent by devices of a particular type.

Register devices1

After clicking Next the device registration request will be submitted and the device will be created.

You can verify that the device is really connected by checking that events are actually coming in. You can do so by clicking on a device and opening its "Events" tab. All events related to this device are listed here.

For more information on viewing and managing your connected devices, also refer to Device Management.

Updating devices registered with the general device registration

If devices have been registered via the general device registration the following URLs have to be manually changed in the Sigfox cloud:

Info: General device registration for Sigfox devices is no longer supported.

Sending operations

If the device supports sending hexadecimal commands, you can send commands from “Shell”. Go to the Device Management application and navigate to the device you want to send an operation to. Switch to the "Shell" tab.

Info: Operations do not go to “Executing” state immediately. They go to “Executing” state when the device is expecting the downlink message. Afterwards, the pending operation which is created first goes to executing state.

Tenant SLA Monitoring

Overview

The Tenant SLA Monitoring service lets service providers monitor the availability and response time of tenants and sub-tenants.

In detail, it offers the following features:

  • monitoring of the availability for each tenant
  • information on the current availability status of tenants (yes/no)
  • information on the tenants availability in percentage
    • during the last day
    • during the last week
    • during the last month

By using Tenant SLA Monitoring, service providers can instantly check

  • if any tenant is currently down,
  • if all tenants are fully functional,
  • the current response time for each tenant,
  • the current status of a specific tenant,
  • the availability KPIs (key performance indicators) of all tenants in the last day/week/month.

Info: The tenant SLA monitoring service is only available to the management tenant.

Use the the Device Management application to visualize Tenant SLA Monitoring data.

Using Tenant SLA Monitoring

Prerequisites

The management tenant needs to be subscribed to the application “Tenant-sla-monitoring” to see any monitoring results.

Tenant Monitoring application

For details on application subscription, refer to Administration > Managing Tenants > Subscribing to applications in the User guide.

How the service works

Every 5 minutes, the Tenant SLA Monitoring service probes for the response time of each tenant, and all its sub-tenants (if not disabled), and stores the results.

To be able to do so, the service automatically subscribes to all sub-tenants of a subscribed tenant, to get its credentials and gain access to its API.

Moreover, for each subscribed tenant (i.e. management tenant), a source in the Device Management application is created in which the monitoring results, including those of the sub-tenants, are stored as measurements.

Viewing measurements

To view the measurements showing the monitoring results, open the management tenant´s source (device) in All devices in the Device Management application and switch to the Measurements tab.

Tenant Monitoring measurements

In the API Response Time diagram, you see the response time of the tenants in milliseconds.

Additionally, you will find diagrams showing the average availability values for the tenants for the following periods:

  • Api Availability Day Average - 24 hours
  • Api Availability Week Average - 7 days
  • Api Availability Month Average - 30 days

These average values are calculated by summing up the timespan of all timeout and response time alarms (e.g. created if data is missing, see below) for the specific time period and divide it by the total timespan.

Tenant Monitoring Day Average

For further details on measurements refer to Device Management > Device details > Measurements in the User guide.

Creating alarms

The Tenant SLA Monitoring service will create alarms in case of the following scenarios:

  • Unavailability of a tenant - Whenever a tenant is not reachable, the service will not store any measurement but will leave gaps in the measurement series. When the tenant becomes available again, the service will search for the last measurement stored for the tenant and create an alarm for the calculated time of unavailability.
  • High response times - If the required response time is not met (defaults to 300ms). This alarm will be active until the response time drops below the defined limit again.
  • Time spans which have not been monitored

These alarms are used to calculate the availability of the system in percentage, shown as measurements (see above).

To view recent alarms, switch to the “Alarms” tabs of the management tenant´s source.

Zapier Integration

Overview

The Zapier service in Cumulocity helps you to bring real-life data from your assets into ERP, CRM and other enterprise IT services. It also enables you to remote control your assets from these services. The Zapier service effectively connects more than 350 IT services with the Internet of Things. Use this service, for example, to

  • send machine maintenance alerts into your CRM system,
  • send sales information from vending machines into your ERP system,
  • bring life data into spreadsheets for analysis,
  • create forms to support manual maintenance of master data for your assets,
  • improve customer service by automating standard interactions such as machine resets from your help desk tools.

This section describes how to implement these and many other use cases by combining Cumulocity with Zapier. It will show all available triggers and actions the Cumulocity Zapier app offers and describe how you can connect them with other services.

All the examples in this section require a Zapier account, which you can obtain for free at https://zapier.com.

Access Cumulocity App in Zapier

If you want to get access to the App and try it out please contact us at support.

How the service works

The Zapier service connects Cumulocity in two ways to enterprise IT services:

  • You can send data from the sensor network and from Cumulocity to these IT services.
  • You can send data from the IT services to Cumulocity and the sensor network.

From the Internet of Things to enterprise IT services

To send data to enterprise IT services, you need to set up a CEL statement in Cumulocity (or use one of your existing Smart Rules) and a Zap in Zapier, as shown below.

Triggers

New SmartRule Event

The New SmartRule Event trigger enables you to add additional actions when your Smart Rule is executed (e.g. a threshold rule creates a threshold alarm). Make sure that you have created and activated a Smart Rule in Cumulocity before using this feature.

Info: Note that when using Zapier in Cumulocity the processing of global Smart Rules is limited to Smart Rules from the Global Smart Rules page in the navigator.

After choosing this trigger and selecting your Cumulocity account, you can specify your SmartRule.

Cumulocity account

Input Description
SmartRule type The type of the Smart Rule you want to trigger on.
Statement The statement in the Smart Rule you want to trigger on. Some Smart Rules support multiple trigger statements.
SmartRule The Smart Rule from your Cumulocity account you want to trigger on. If none is displayed you don't have a Smart Rule of that type created.

All inputs are provided as a dropdown list.

In the test step in Zapier, we will provide you with an example of how Zapier will receive the data.

New CEL Event

The New CEL Event trigger provides a more generic way to forward any statement of any of your CEL modules to Zapier. Before using this feature you need to deploy your module in Cumulocity.

After choosing this trigger and selecting your Cumulocity account, you can specify your CEL module.

Cumulocity account

Input Description
Module name The name of your CEL module in Cumulocity.
Statement name The statement in the CEL module you want to trigger on.
Is Channel? Whether you want to listen to a statement or a channel.

In the test step in Zapier, we will provide you with an example of how Zapier will receive the data. However, the structure purely depends on how your statement in the CEL looks like. Therefore some of the fields in our example might not exist in your CEL statement.

For further information, refer to our example for this trigger.

From enterprise IT services to the Internet of Things

The Zapier service provides a number of Zapier actions to send data to Cumulocity and to the device managed by Cumulocity. The currently supported actions are:

  • New device
  • Update inventory
  • Create operation

Actions

New device

New device registers a new device so that you can connect it directly. Pass the same device ID (IMEI, serial number) as you would normally use in the Device registration dialog.

Device Registration

Update Inventory

Update inventory enables you to create and update assets in the Cumulocity inventory. The following parameters can be defined:

Input Description
ID A technical identifier for the asset
Name A readable name for the asset
Fragment The fragment type that is created or updated
Data The fragment's data as a list of keys and values
Is a device? A flag that marks the asset as a device. The device will show up in All devices.

Assets migrate into the inventory using the following process:

1 The ID is interpreted as asset ID and the Zapier service checks if there is an existing asset with the given asset ID. 2 The ID is interpreted as a Cumulocity global ID and the Zapier service checks for an asset with that global ID. 3 The name is used to find an asset with an exactly matching name.

If any of the three steps succeeds, the retrieved asset is updated. If there are no matches, a new asset is created.

Inventory

Create operation

Trigger device restarts sends a restart operation to a device.

Input Description
ID A technical identifier for a device
Name A readable name for a device
Description The description of the operation
Fragment The fragment which is added to the operation
Data The fragment's data as a list of keys and values

The device is identified with the same three-step mechanism as described above under "Update inventory".

Operation

Configuring your Cumulocity account in Zapier

Each trigger and action requires to add valid Cumulocity credentials. If you create your first Zap with a Cumulocity connection, you need to connect a new account. You will be processed to the following dialog where you enter your Cumulocity credentials.

Cumulocity account

Examples

For detailed information on setting up Zaps, refer to https://zapier.com/help/. Note that the Zapier plans have limitations on the volume of data that can be transferred. Sending data outside of your plan may deactivate your Zap temporarily.

Store CEL data in a Google spreadsheet

In the first example, we connect Cumulocity to Google Spreadsheet and transfer live measurements from your account into the spreadsheet. You can use the measurements for ad-hoc analysis, for example, to compare the performance of different devices. The example consists of four steps.

To run the example, you need a Google account besides your Zapier account. If you do not have a Google account yet, visit https://google.com and create an account. We also assume that you have the default simulated devices running in your account.

Open the Cumulocity Administration application, click Event Processing in the Business rules menu in the navigator and select New Module. Enter "zapier" as the name for the new module. In the Examples drop-down field, select "Send simulator temperature to Zapier". Click Save. Your screen should look like the screenshot below.

Sample CEL statement

The above statement selects all new temperature measurements in your account and formats them for the Zapier service. The output of the statement is printed in realtime next to the statement. If you have the default simulator configuration running, it should start showing values. For more information on the statements, refer to Real-time processing in the Concepts Guide.

You must create a spreadsheet for holding the data coming from Cumulocity. Go to https://docs.google.com and switch to Google Sheets. Open a new blank spreadsheet and provide a name for it. In the spreadsheet, create a header row and a row with sample data as illustrated in the screenshot below. The header row and the sample data will be used by Zapier to simplify the setup of your "Zap", your new system integration.

Sample spreadsheet

More information on using spreadsheets with Zapier can be found at https://zapier.com/support/questions/2301/using-zapier-with-google-docs/.

To setup your Zap, follow these steps:

  1. Choose "Cumulocity" as Trigger app.
  2. Select New CEL event.
  3. Connect your Cumulocity account in Zapier (or select it if you previously connected it).
  4. Enter "zapier" as Module name and "simulatortemperature" as Statement.
  5. Choose "Google Sheets" as Action app on the right side.
  6. Select Create Spreadsheet Row.
  7. Connect your Google account in Zapier (or select it if you previously connected it).
  8. Select your spreadsheet and worksheet from the dropdown fields.

After processing these steps, your screen should look like the following:

Example 1

Activate the Zap in Zapier and open the spreadsheet to watch data from the simulator flowing in.

Result

Register a device from a spreadsheet

In this example, we assume that you maintain a spreadsheet to keep track of your devices, their IMEIs, their SIM cards and their deployment location -- a "poor man's asset management". Whenever new devices have entered this spreadsheet, it should be automatically entered into Cumulocity's device registration. You can then switch on the device and pair it with your account.

As a first step, prepare a spreadsheet similar to the one below in the screenshot. The column "IMEI" provides the identifier of the device in registration.

Device spreadsheet

To setup your Zap, follow these steps:

  1. Choose "Google Sheets" as Trigger app.
  2. Select New Spreadsheet Row.
  3. Connect your Google account in Zapier (or select it if you previously connected it).
  4. Select your spreadsheet and worksheet from the dropdown fields.
  5. Choose "Cumulocity" as Action app on the right side.
  6. Select New Device.
  7. Connect your Cumulocity account in Zapier (or select it if you previously connected it).
  8. Select the IMEI column from the fields list to use it in the "Device ID" input.

After processing these steps, your screen should look like the following:

Example 2

Test the Zap and turn it on. Enter a new device into your spreadsheet.

Enter device

After a while, the device ID appears in the Device registration dialog of Cumulocity.

Device registered

Info: It may take up to 15 minutes until Zapier picks up the change in the spreadsheet.

Now you can play with this setup. For example, you could introduce a workflow column indicating the state of the device (ordered, in stock, rolling out, in production) and only register the device when it is being rolled out.

Use a form to enter customers into the inventory

In this example, we update the Cumulocity inventory using a Wufoo form.

To run the example, you need a Wufoo account.

Open the Wufoo form builder and create a form for your inventory entry. For this example, we want to create customer contacts in the inventory. Save the form.

Wufoo form

To setup your Zap, follow these steps:

  • Choose "Wufoo" as Trigger app.
  • Select New Entry.
  • Connect your Wufoo account in Zapier (or select it if you previously connected it).
  • Select your form from the dropdown field.
  • Choose "Cumulocity" as Action app on the right side.
  • Select Update Inventory.
  • Connect your Cumulocity account in Zapier (or select it if you previously connected it).
  • Fill the data fields from the Wufoo form into the Update Inventory inputs (e.g. like in the screenshot below).

In this case, we are creating a new entry for each customer entered into Wufoo. The Wufoo entry ID can be used as asset ID in Cumulocity. As name, we use the first and last name of the contact. "Data" contains a list of key/value pairs that you can use for the remaining form data. These key/value pairs are stored in a Cumulocity fragment "c8y_Contact". You can set "Is a device?" to true to see the entered data in the Device Management application (even though your contact isn't exactly a device).

Wufoo Zap

After processing these steps, your screen should look like the following:

Example 3

Extensions

Zapier offers a built-in action to send pure REST requests called "Webhooks". You can to use this action to send any data to our documented APIs directly.

Still have ideas for features in the Cumulocity app? Mail us.