Optional services

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

Cloud Fieldbus

With Cumulocity IoT Cloud Fieldbus you can collect data from fieldbus devices and remotely manage them. This section describes how to

Cloud Fieldbus is supported out of the box by several devices. For information on supported devices, refer to the Cumulocity IoT Device Partner Portal which allows to filter for all devices which offer full functional support with Cloud Fieldbus.

Info: To support Cloud Fieldbus with your terminal, please contact the Software AG Support.

Connecting fieldbus devices

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

Connecting Modbus/RTU devices

To connect a Modbus/RTU device, follow these steps:

  1. Physically wire the Modbus/RTU device through RS-485 or RS-232 to the terminal.
  2. Assign 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 Modbus 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 Serial communication section to match the settings on the bus, if needed.
  6. Change the transmit rate and the polling rate according to your requirements. The transmit rate is the frequency where measurements are sent to Cumulocity IoT. The polling rate is the frequency at which the Modbus devices are polled for changes.
  7. Click Save to save your settings.

Add Modbus device

To add child devices

  1. To start the communication between the terminal and the Modbus/RTU device, click Add RTU device.
  2. Enter a name for the device and select the device protocol from the dropdown field. See Configuring fieldbus device protocols for information on how to add a new device protocol. Set the Modbus address of the connected device.
  3. Click Add. Cumulocity IoT 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 list 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, follow these steps:

  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 transmit rate is the frequency at which measurements are sent to Cumulocity IoT. The polling rate is the frequency at which the Modbus devices are polled for changes.
  6. Click Save to save your settings.

Add Modbus device

To add child devices

  1. To start the communication between the terminal and the Modbus/TCP device, click Add TCP device.
  2. Enter a name for the device and select the device protocol from the dropdown field. See Configuring fieldbus device types for information on how to add a new device protocol. Set the Modbus address and the IP address of the connected device.
  3. Click Add.

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

Info: It is assumed that all Modbus/TCP communication uses the standard Modbus/TCP port 502. On the NTC-6200 and NTC 220 series, the port to be used can be configured through the variable “service.cumulocity.modbus.port” via the device shell or the local web user interface of the device.

Connecting CAN devices

To connect a CAN device, follow these steps:

  1. Physically wire the CAN device 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 IoT.
  6. Click Save to save your settings.

Add CAN device

To add child devices

  1. To start the communication between the terminal and the CAN device, click Add CAN device.
  2. Enter a name for the device and select a device protocol from the dropdown field. See Configuring fieldbus device types for information on how to add a new device protocol.
  3. Click Add.

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

Connecting Profibus devices

Connecting Profibus devices slightly differs from the regular plug & play approach of Cloud Fieldbus. The gateway device acts as a slave on the Profibus so it can easily be integrated into an 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 its configured Profibus slave address.

To connect a Profibus device, follow these steps:

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

Add device

To add child devices

  1. To start the communication between the gateway and the Profibus device, click Add Profibus device.
  2. Enter a name for the new device.
  3. Select the device protocol from the dropdown field. See Configuring fieldbus device types for information on how to add a new device protocol.
  4. Click Add to confirm and notify the gateway.

Now a child device will be created containing the data configured in the selected device protocol.

Cumulocity IoT 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 IoT, you can:

Collecting measurements

If the device protocol 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 which is exactly the same as collected previously may not be sent again.

Fieldbus measurements

Monitoring alarms

If the device protocol 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

Monitoring the device status

The status of devices can be monitored in realtime 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.

Monitoring the 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 to 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 protocol. The “Fieldbus device” widget updates automatically as soon as there is new data available. You do not need to click Reload.

Use the Fieldbus Device Widget

Registers and coils that can be changed are represented by active widgets. 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 the device 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. In the upcoming dialog box, basic device properties or fieldbus properties (i.e. status coils and registers) can be chosen. 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 widget accepts SVG files which use AngularJS directives, for example ng-if, ng-show, ng-style, ng-repeat, ng-click, for dynamic data presentation. Data from devices (like latest measurements and other properties) are provided via placeholders. There are also predefined helper functions which can be used.

For creating SVG files, it is recommended to use https://boxy-svg.com/. It is an easy to use, quality Chrome extension.

Placeholders

For a placeholder to be recognized by the SCADA widget, it must occur at least once in double curly braces with no other expression, for example {{placeholderName}} (in a comment, attribute’s value, or element’s content - see example). Once annotated, the placeholder can be used within other expressions, for example {{placeholderName * 3.1415}}, ng-class="{ active: placeholderName > 100 }" or ng-if="placeholderName === 'VALUE'".

Predefined functions

The following predefined functions are available for use in expressions:

Example
svg
<?xml version="1.0" encoding="utf-8"?>
<svg width="600px" height="600px" viewBox="0 0 600 600" xmlns="http://www.w3.org/2000/svg">
  <!-- Annotate placeholders in comments: -->
  <!-- {{batteryValue}} -->
  <!-- {{alarmsStatus}} -->

  <style>
    .critical {
      fill: red;
    }
  </style>

  <!-- or in an attribute: -->
  <text data-placeholder="{{batteryValue}}"
    class="text"
    x="50"
    y="200"
    width="200">
    <!-- pass placeholder's value to a predefined function to get alarms status CSS class: -->
    <tspan ng-class="getActiveAlarmsStatusClass(alarmsStatus)" style="font-size: 45pt;">
      <!-- or in an element's content: -->
      {{batteryValue}}

      <!-- a placeholder can be also a part of expression, e.g.: -->
      {{batteryValue * 100}} %
    </tspan>
  </text>
</svg>

Configuring fieldbus device protocols

New fieldbus device protocols can be created in the Device protocols page which is opened from the Device types menu in the navigator.

  1. Click Add device protocol in the top menu bar.
  2. Select the protocol of your device from the list.
  3. Enter a name for it and an optional description.
  4. Click Create to create the protocol.

Add device protocol

The device protocol will be added to the device protocol list.

Device protocol list

Next, you can configure the device protocol, following the descriptions for the respective protocol type below.

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

Configuring Modbus device protocols

To add a coil definition (discrete outputs)

Click Add Coil in the Coils (discrete output) section, to add a coil definition.

  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. In the Value selection section, enter the number of the coil in the Modbus device.
  4. In the Functionalities section, you may select the following actions:

    • Show status - To show the current value in the UI, e.g. in the “Fieldbus device” widget. In this case, you can enter the text that the UI should show for unset and set coils.
    • Update status - To enable to update the current value from the UI, e.g. in the “Fieldbus device” widget.
    • Raise alarm - To raise an alarm 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.
    • Send event - To send an event each time the value changes. If selected, you may specify the type of event and the text in the event.
  5. Click Save to save your configuration.

Add coil

To add a discrete inputs definition

The same settings can be specified for discrete inputs. However, it is not possible to update the status of a discrete input.

To add a register definition

Click Add holding register under Holding registers or Add input register under Input registers to add a register definition.

  1. In the General section, specify a name for the register and a display category to structure your data in widgets.
  2. In the Value selection section, enter the number of the register in the Modbus device. If the Modbus device used implements the standard Modbus specification, the number of the register is 1. 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”.
  3. In the Normalization section, specify how the raw value should be transformed before storing it in the platform. To scale the integer value read from the Modbus device, you can enter a Multiplier, a Divisor and a number of decimal places in the Right Shift field. 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 IoT. 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 IoT. If you use a divisor of ten and no decimal places, the terminal may send 23 to Cumulocity IoT (depending on its implementation). In the Unit field, indicate the unit of the data, for example, “C” for temperature values.
  4. In the Options section, select the following options:

    • Signed - If the register value should be interpreted as signed number.
    • Enumeration type - 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.
    • Little endian - If the register value should be interpreted in little-endian format based on 8-bit values.
  5. In the Functionalities section, you may select the following actions:

    • Show status - To show the current value in the UI, e.g. in the “Fieldbus device” widget.
    • Update status - To enable to update the current value from the UI, e.g. in 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.
    • Send measurement - To collect the values of the register regularly 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.
    • Raise alarm - To raise an alarm 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.
    • Send event - To send an event each time the value of the register changes. If selected, you may specify the type of event and the text in the event.
  6. Click Save to save the register.

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 the device protocol.

Configuring CAN bus device protocols

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

Configuring Profibus device protocols

Profibus device protocols can be configured in the following way:

  1. In the Registers section, click Add register to add one or more register definitions as described exemplarily for Modbus devices in To add a register definition above.
  2. 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.
  3. Finally, click Save to save your settings.

Configuring CANopen device protocols

CANopen device protocols can be configured in the following way:

In the CANopen device type field, specify the device type as a hex number.

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

Click Add variable to configure a new variable.

New variable

To configure a variable
  1. In the General section, specify a name for the variable and a display category. Display categories are used to group variables into sections in the visualization.
  2. In the Value selection section, specify from where the value should be extracted:

    • 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 - Type of the variable (e.g. boolean, unsigned).
    • Access type - Access type, e.g. read-only, write-only.
  3. Depending on the selected access type, the following functionalities may be specified:

    • Show status - To enable to show the current value in the UI, e.g. in the “Fieldbus device” widget.
    • Update status - To enable to update the current value from the UI, e.g. in the “Fieldbus device” widget. If selected, two additional fields Minimum and Maximum are displayed. Using these fields, you can constrain numerical values entered in the widget.
    • Send measurement - To create a measurement whenever the value is changed. If selected, you may specify a Measurement type and Measurement series.
    • Raise alarm - To raise an alarm if a given mask matches with the value of the variable ((value & mask) == mask). Additionally, you may specify the type of the alarm raised, its text and its severity.
    • Send event - To send an event each time the value of the register changes. If selected, you may specify the type of event and the text in the event.
  4. In the Normalization section, specify a unit to define how the raw value should be transformed before storing it in the platform.

  5. Click Save to save the variable.

The variable will be listed in the Variables section of the device protocol. All variables are grouped by the given display category, i.e. variables with the same category are grouped together.

category view

After completing your configuration, click Save to save the device protocol configuration.

Importing a CANopen device protocol

See Exporting and importing device protocols for general information on how to import a device protocol.

After importing the EDS file, all variables defined in the file are listed in the Variables section of the CANopen device protocol.

The user can then enrich the imported variable configurations manually, for example by adding the missing display category.

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:

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

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 protocols

To manage device protocols more conveniently, you can export them to a file. The file can be re-imported to set up other Cumulocity IoT accounts easily or to restore the protocols from a backup. The import functionality also supports importing ready-made device protocols provided by device manufacturers.

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

A file with the device protocol definition will be downloaded, named “<device type>.json”.

Export device type

  1. To import a device protocol, click Import in the top menu bar.
  2. In the resulting dialog box, either select a pre-defined protocol or upload a file with a previously exported device protocol.
  3. You may enter a new name for the device protocol.
  4. Click Import to import the protocol.

Import device type

Cumulocity IoT Sensor App

Overview

The Cumulocity IoT Sensor App is a smartphone application which sends sensor measurements to the Cumulocity IoT platform. With the app it is also possible to connect a Texas Instruments (TI) Sensor Tag device over bluetooth and send the measurements to the Cumulocity IoT platform. Commands can also be sent from the Cumulocity IoT platform to the smartphone.

Info: The TI Sensor Tag is a low energy wireless device manufactured by Texas Instruments © http://www.ti.com/.

The Sensor App requires a smartphone with Android version 5.0 (or higher) or iOS version 11.0 (or higher).

Installing the Sensor App

To install the Sensor App on your smartphone, open the Cockpit application in Cumulocity IoT, expand the right drawer and click Add smartphone from the quick links.

Quick Links

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

Install App

Scanning the QR code with your smartphone will take you to the App Store where you can install the app.

Info: Alternatively, you can open the Apple App Store or Google Play Store from your smartphone, search for Cumulocity IoT Sensor App and install the app.

Registering the Sensor App in Cumulocity IoT

The easiest way to register your smartphone as a new device in Cumulocity IoT is by scanning the QR code in step 2 of the Add Smartphone wizard. This feature is only available for Android smartphones.

If you are not able to scan the code or if are using an iOS smartphone, you can connect via username and password.

Registering using a QR code

In Cumulocity IoT click Next in the Add Smartphone wizard to display step 2 with the second QR code which registers the smartphone in Cumulocity IoT.

Register phone QR

Your smartphone will be added to the devices list in the Device Management application, which can be accessed by navigating to All devices in the Devices menu in the navigator.

All devices

Moreover it will be added to the group Phones (which will be created if not available yet). You will find the group in the Group menu in the navigator. This feature is only available in case of QR code registration.

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.

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 with username and password
  1. On the start screen of the Cumulocity IoT Sensor App, press Connect to Cumulocity, to connect your device to Cumulocity IoT.
  2. In the Account details page of the Cumulocity IoT Sensor App, provide the Cumulocity IoT tenant and instance. These can be seen in the Cumulocity IoT URL from the browser address bar. For example the screenshot below shows the tenant and instance for a URL “mytenant.us.cumulocity.com”. Press Connect.

    Account details

  3. Press Login with Software AG Cloud or enter your username and password and press Login.

    Account details

    Info: The option Login with Software AG Cloud is only available for subscriptions made via the Software AG Cloud portal.

  4. Next, go to Cumulocity IoT.

Your smartphone will be registered and added to the devices list in the Device Management application, which can be accessed by navigating to All devices in the Devices menu in the navigator.

All devices

For further information about registering a device on the platform manually, refer to Connecting devices in the Device Management section.

Viewing sensor data

Press View sensors to view the data from sensors on your smartphone.

The sensor data (i.e. gyroscope, location, acceleration, magnetic field and barometer data), will be shown on the smartphone.

Info: On an iOS smartphone you can view sensor data without being connected to Cumulocity IoT. Only when your phone is connected to Cumulocity IoT the sensor data is being sent to the platform.

Sending sensor data to Cumulocity IoT

The measurements from the sensors of your smartphone will automatically start being sent to your Cumulocity IoT tenant when your smartphone is connected to the platform.

The data points will be displayed in the Phones group on the dashboard of your smartphone device.

map in cockpit

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

The Sensor App sends measurements to Cumulocity IoT every 2 seconds by default. This interval can be changed in the app.

Connecting TI Sensor Tag to the Sensor App

The Cumulocity IoT Sensor App connects to both TI Sensor Tag version 1.20 and 1.30 via bluetooth.

On an Android smartphone

Use the Scan devices button in the Sensor App to connect a Sensor Tag.

Scan devices button

On an iOS smartphone

Press the Add Tag button in the Sensor App to connect a Sensor Tag.

Add Tag

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 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 Sensor App’s screen:

Sensor Tag Card

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

Sensor Tag Info

In your Cumulocity IoT 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 Remove on its card.

Device control

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

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

Create a dashboard for your smartphone device as described in Creating a dashboard in the Cockpit section.

Add the Messaging widget to the dashboard, for details see Widgets collection.

To send a message from Cumulocity IoT, 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 Message

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.

Cloud Remote Access

The Cumulocity IoT Cloud Remote Access microservice allows you to remotely access operating panels and other devices via a web browser.

When to use Cloud Remote Access

To provide the best level of control, remote devices should be represented as devices in the Device Management of Cumulocity IoT, with the corresponding reporting, remote control and real-time functionality.

In some cases however, it is not possible or not economic to implement every aspect of a machine or remote device in a Cumulocity IoT agent. For example, it might be a legacy device that does not have APIs for accessing certain parts of the functionality, or it may have many very low-level configuration parameters that would be very involved to map to Cumulocity IoT.

In this case, you can use Cloud Remote Access to securely manage remote devices. The benefit is that you manage the device in the same way as if you had it physically close to you.

Important: Be aware that using Cloud Remote Access includes administrative intervention:

  • Often, devices have no detailed permission management, so you give a user very fundamental access to the device.
  • When using Cumulocity IoT to remotely operate machinery, make sure that all remote operations follow the safety standards.

Supported protocols and gateways

The following protocols are supported:

The following gateways are supported:

How Cloud Remote Access works

Cloud Remote Access is a secure way to directly access remote devices through a web browser.

VNC

The following protocols are supported:

Cloud Remote Access works as in the illustration below. The remotely controlled device runs a VNC, SSH or Telnet 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 IoT. 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

VNC1b

The connection to remote devices is securely encrypted through TLS technology. Additionally, passwords are encrypted in your Cumulocity IoT 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:

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

Device list

When you open the gateway you will find the Remote access tab in its tab list.

Remote access tab

In the Remote Access tab, you can configure devices for remote control, so-called “endpoints”, and connect to remote devices.

Connections can be established to the gateway itself (localhost) or to any device in the local area network reachable by the device.

Info: If the prerequisites are met and you do not see the Remote access tab in the tab list of your gateway, please contact sales@cumulocity.com.
Info: If you are a gateway manufacturer and would like to support Cloud Remote Access on your gateway, please contact us via empower.softwareag.com.

Configuring endpoints

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

Endpoints

To configure new remote devices, click Add endpoint. Follow the descriptions below for configuring the various types 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 remote 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

Important: Be aware, that Telnet is considered to be an insecure protocol lacking built-in security measures. For network communication in a production environment we highly recommend to use the SSH protocol instead.

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:

Info: The public key needs to be installed on the remote 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:

The following algorithms are supported when adding new keys:

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

Auto-saving host key

A host key is a public key of the server which is generated when an SSH server is installed. It is used to verify the identity of the server.

By enabling the auto-saving host key functionality you will no longer need to enter the host key after each connection. Instead, the host key can be automatically saved after the first successfully established connection to a remote access endpoint.

In order to enable the auto-save host key functionality, navigate to the Remote access page under the Settings menu in the Administration application. Activate the checkbox and then click Save.

Save host key

Connecting to endpoints

To connect to configured endpoints, choose an endpoint in the Remote access tab and click Connect.

Connect Endpoint

The connection to the configured remote device is established and the VNC, SSH or Telnet screen is shared in the client area.

Telnet connection

To terminate the connection, click Disconnect.

Audit logs

Audit logs are available for each gateway 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 gateway device.

Display Audit logs

Compatibility and limitations

VNC protocol

The following versions of the VNC protocol are currently supported:

The functionality has been tested on the following VNC servers:

The following operating systems/browsers are currently supported:

Operating system Browser Touch Swipe Keyboard Pointer
Windows 10 Edge 38 Yes Yes Yes Minor
Windows 10 Internet Explorer 11.5.6.7 Yes Yes Yes Minor
Windows 10 Firefox 51 Yes Yes Yes Yes
Ubuntu 16.04 Chrome 56 Minor Yes Yes Yes
Ubuntu 16.04 Firefox 51 Minor Yes Yes Yes
MacOS Safari Yes Yes Yes Yes
iOS 10.2.1 Safari Yes Minor No n/a
Android 6.0.1 Chrome Yes Minor No n/a
Android 6.0.1 Stock browser 5.0 Yes Minor No n/a

Telnet protocol

The following limitations apply to Cloud Remote Access for Telnet:

Area Scrolling Reflow on width change Bitmap fonts Vector fonts Mouse tracking Application keypad Tabs Split screen
Console Yes No Yes Yes Yes Yes ? Yes
xterm Yes No Yes Yes Yes Yes No No

SSH protocol

For Cloud Remote Access for SSH the same limitations as mentioned for Telnet apply (see above). Also the following additional limitations are known:

Troubleshooting

Endpoints cannot be set up

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.

Connection fails

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

Unsupported protocol version

In case of Real VNC, if you get an error message stating that you are using an unsupported protocol version (e.g. 005.00x), try the following workaround:

  1. Open VNC.
  2. Navigate to Options.
  3. Select the Export tab.
  4. Search for “ProtocolVersion”.
  5. Enter “3.8” as protocol version.x

Connectivity

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

Cumulocity IoT integrates with the SIM connectivity management platform Jasper. For the SIM connectivity management platforms Comarch and Ericsson, Cumulocity IoT provides an experimental implementation. For more details, please contact our support team.

The following features are supported by these providers:

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

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

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

Jasper architecture

The following sections describe:

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

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

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

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

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

Jasper user management

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

Configuring the connectivity for the SIM provider in Cumulocity IoT

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

  1. Use a Cumulocity IoT administrator user to log into the Cumulocity IoT platform.
  2. Switch to the Administration application.
  3. Click Connectivity in the Settings menu of the navigator. If the menu item is not displayed, make sure that your user has ADMIN permission for Connectivity. If the menu item is still not available, contact support to make the Connectivity agent available in your tenant.
  4. Switch to the SIM provider settings tab.
  5. Select a provider from the drop-down list.
  6. Enter the credentials (URL, key (in case of Jasper), username and password) for the respective SIM provider account. If you do not have any credentials, ask your administrator.
  7. Click Save to save your settings.

Jasper settings

The Connectivity agent is now set up.

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

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

Connectivity permission settings

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

If the ICCID is not shown automatically check the following:

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

Connectivity tab

In the Connectivity tab you will find the following sections:

Connectivity tab

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

The Status section lists summary information for the SIM card.

Status section

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

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

At the bottom you will find usage information for the current month, 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.

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

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

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

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

Checking connectivity

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

In the Connectivity tab, check if

Data connectivity can be analyzed in various places:

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

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

IMPACT

This document describes

IMPACT Integration

Cumulocity IoT offers an integration with the Nokia IMPACT Data Collector which is designed to collect data from heterogeneous devices. Integrating Cumulocity IOT with IMPACT, enables you to make use of existing Cumulocity IoT 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 IoT 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 IoT 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 IoT 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 IoT. Cumulocity IoT’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 IoT.
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 IoT as disabled.

IMPACT device protocols

To process data from IMPACT devices, Cumulocity IoT 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.

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

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

    New Impact protocol2
  5. Click Create to create the new device protocol.

The device protocol will open in a new page.

Impact temperature

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

Impact resources

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:

Impact functionalities

Send measurements

Turn on Send measurements to specify a measurement.

Create alarm

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

Send event

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

Custom Actions

Turn on Custom Actions to map device data into Cumulocity IoT using custom data processing actions. For specialized integration use cases, it is required to perform customized data processing on device data. Examples are resources of non-standard data type that contain proprietary, binary data, CBOR, XML or alike.

The set of custom actions is provided by decoder microservices available in the particular tenant. A decoder microservice is an ordinary Cumulocity IoT microservice that implements a simple decoder interface. The IMPACT microservice calls these microservices for decoding data in a customer-specific way. We provide examples how to write such a decoder microservices in our public Bitbucket repository.

Auto observe

Enabling Auto observe for a resource means, that each time the device with this particular resource appears, Cumulocity IoT 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.

Impact sensor value

LoRa Actility

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

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

Cumulocity IoT 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 and application EUI

Before using LoRa devices with Cumulocity IoT, you need to configure your ThingPark account details in the Administration application. In order to create new credentials or replace existing ones, go to the Administration application and select Connectivity in the Settings menu 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:

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 provider 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 Replace credentials.

Enter your profile ID, username, password and application EUI (for details on profile ID and application EUI see Creating new account credentials.

Replace credentials

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

Creating device protocols

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

During the device registration, you can associate this device protocol. The received uplink callbacks for this device with a hexadecimal payload will then be mapped to the ones you have configured in your device protocol. If a device protocol 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.

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

In order to create a device protocol, navigate to the Device Management application and select Device protocols in the Device types menu in the navigator. You can either import an existing device protocol or create a new one.

Importing a predefined device protocol

In the Device protocols page, click Import.

Select the predefined device type, for example “LoRaWAN Demonstrator” or upload from a file. Click Import.

Import device protocol

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

Creating a new device protocol

In the Device protocols page, click New device protocol in the top menu bar. The following window will open:

Create new LoRa protocol

Select LoRa as the device protocol type, provide a name for it and click Create.

Under Message types, specify the message types. LoRa devices can send messages of different types with different encodings per type.

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

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

LoRa protocol payload

Click Add value to create the value configuration.

LoRa protocol add value

In the upcoming window, configure the relevant values as shown in this example.

LoRa protocol add new value

LoRa protocol add new value

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

Under Message type, configure the Message ID according to your device message specification and map it to the Cumulocity IoT 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 protocol 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

LoRa bits

Under General, specify a name for the value and the category under which it will be displayed 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

LoRa bits

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:

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

Info: “Little endian” support to decode the payload has been added.

Under Options, select on of the following options, if required:

Under Functionalities, specify how this device protocol should behave:

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

Click OK to add the values to your device protocol.

Value configurations of created device protocol

After clicking Save, your device protocol 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 the battery level changes.

Battery level changes example

Battery level changes example

Example with nested structure

The following image shows an example of a nested structure for a device protocol reporting the current position of a GPS device. The display category 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

To register a LoRa device, navigate to the Device Management application and click Registration in the Devices menu in the navigator. Click Register device.

In the upcoming window, click Custom device registration and select LoRa:

Register devices

Cumulocity IoT 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, refer to the LoRa device registration with ABP section.

In the next window fill in the required information:

Register devices

Click Next to submit the device registration request and create the device.

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.

The provision status is shown under Device data in the Info tab of the device.

Device data

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

LoRa device registration process

A device is created based on the above workflow.

First it is checked, if the device already exists. If no device exists with the same device EUI in the ThingPark account, the device is first provisioned on the ThingPark platform and then created on the Cumulocity IoT platform with a link to the device in the ThingPark platform. If the device exists in the ThingPark account, a validation will be applied to compare these devices based on application EUI (for OTAA activation) and device profile. If the validation is successful, the device is created only in Cumulocity IoT with a link to the device in the ThingPark platform. If the validation fails, a failure message will be shown (see troubleshooting section for device registration) and the device is not created in Cumulocity IoT.

LoRa device registration with Activation by Personalization (ABP)

Activating the device by personalization is not recommended and not fully supported in Cumulocity IoT LoRa device registration.

However, if you would like to create a device with this activation type in Cumulocity IoT and use the LoRa features - such as sending operations to a device, deprovisioning a device and setting LoRa device protocol 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 IoT using the 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 created with general device registration

The general device registration for LoRa devices is no longer supported.

Existing LoRa devices that have been created in Cumulocity IoT with the general device registration process have limitations. For those devices, it is not possible to send operations to the device, deprovision the device and set the LoRa device protocol 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 IoT, but the device will be deleted in ThingPark.

To deprovision a device, navigate to the respective device in the Device Management application under All devices. Click More in the top right and select Deprovision device.

Deprovision device

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

To provision the device again, the device should be deleted and re-registered using LoRa device registration.

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, navigate to the device you want to send an operation to in the Device Management application under All devices. Switch to the Shell tab.

In the following screenshot you can find some examples of a device protocol’s predefined commands and their format.

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

The status of the operation is set to SUCCESSFUL when the operation has successfully been sent to the ThingPark platform. The status of the operation is set to FAILED when a problem occurred with the validation of the command or after the operation has been sent to the Thingpark platform.

ThingPark API availability monitoring

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

ThingPark API monitoring alarm

Troubleshooting

Connectivity

Authorization to the provider´s platform failed

This warning message shows up if a provided profile ID, username or password is invalid.

Account credentials

To resolve this, provide correct credentials and try again.

Device registration

Access to device denied

This warning message shows up when there already exists a provisioned device in ThingPark with the same device EUI used for device registration and the validation comparing those devices based on application EUI (for OTAA activation) and device profile has failed.

Device registration failure for comparison validation

To resolve this, provide the correct application EUI from Connectivity application and device profile and try again.

No LoRa provider settings found

This warning message shows up when there are no credentials set up for the ThingPark account.

Device registration failure without credentials

To resolve this, refer to Configure ThingPark credentials.

Getting device profiles from provider failed

This warning message shows up when the tenant’s access token to Thingpark becomes invalid. Invalidation of the token might happen when the same ThingPark credentials are used for another tenant.

Device registration failure with invalidated token

This issue can be solved by reconfiguring the ThingPark credentials to renew the access token. Refer to configure ThingPark credentials for reconfiguration of the credentials.

No device protocols configured

This warning message shows up when no LoRa device protocol exists to be used for device registration.

No device protocol given for LoRa

To resolve this, configure at least one device protocol in the Device database.

No connectivity plans with free slots available

This warning message shows up when the connectivity plan in ThingPark has reached the limit for the device count.

No free slots by device registration

To resolve this, either contact ThingPark on the device quota limits for your connectivity plans or remove unused devices from ThingPark and retry registering the device in Cumulocity IoT.

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.

Info: You can connect any device supporting LWM2M 1.0 to Cumulocity IoT without programming. We expect the device and its capabilities (e.g. firmware update) to be compliant to the LWM2M specification. The device must support the UDP binding of the LWM2M standard.

Our LWM2M solution allows any LWM2M object to be easily interfaced with the platform. For the sake of convenience, we provide out-of-the-box integration for the following LWM2M objects:

To make use of these integrations, upload the corresponding DDF XML to your tenant. For arbitrary protocols, you can configure how LWM2M devices are mapped to Cumulocity IoT 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 the LWM2M feature. However, this field is still mandatory. For LWM2M-only devices, it is okay to use "dummy" credentials here.
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 IoT 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 IoT 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 “NO_SEC”.

The table below reflects the full set of possible fields that can be added:

Field Type Description Mandatory
endpoint id String The name of the LWM2M client endpoint. Yes
lwm2m server url String The URL of the LWM2M server to be sent to the devices during bootstrap. If you are using the Cumulocity IoT 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 IoT 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. Default is "0". 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 IoT 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.

CSV example 2.1

In this CSV example, the security mode value is “PSK”. With “PSK” enabled, additional mandatory fields must be filled. All fields, available to “PSK”, can be observed in the table below:

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

Add new protocol

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

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

Upload DDF file

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.

Create alarm

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

Send Event

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

Custom Actions

Turn on Custom Actions to map LWM2M data into Cumulocity IoT using custom data processing actions. For specialized integration use cases, it is required to perform customized data processing on LWM2M data. One example are LWM2M resources of the OPAQUE data type that contain proprietary, binary data, CBOR, XML or alike.

Custom actions

Cumulocity IoT LWM2M allows the set of custom actions to be extended using decoder microservices. A decoder microservice is an ordinary Cumulocity IoT microservice that implements a simple decoder interface. The LWM2M agent calls this microservice for decoding data in a customer-specific way. We are providing an according example how to write such a decoder microservice in our public Bitbucket repository.

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:

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 Update. In order to perform the operation, 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.

View History 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 33001…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 /<objectID>/<instanceID>/<resourceID> Reads a resource path
observe /<objectID>/<instanceID>/<resourceID> Enables the observe functionality
execute /<objectID>/<instanceID>/<resourceID> Executes a resource on the device
cancelobservation /<objectID>/<instanceID>/<resourceID> Cancels the observation functionality from the desired resource
delete /<objectID>/<instanceID>[/<resourceID>] Deletes a given object/instance/resource
discover /<objectID>/<instanceID>/<resourceID> Shows all resources of the given object
create /<objectID> [JSON] Creates a new object. The JSON argument is optional
writeattr /<objectID>/<instanceID>/<resourceID> {pmin=<sec>}{&pmax=<sec>}{&greater=<num>}{&less=<num>}{&step=<num>}{&cancel} Writes additional attributes to the object. Typically used for conditional observes
fwupdate /<Firmware name>/<firmware version>/<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:

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

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:

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.

OPC UA

The OPC UA device gateway is a stand-alone Java program that communicates with OPC UA server(s) and the Cumulocity IoT platform. It stores data into the Cumulocity IoT database via REST. Additionally, C8Y commands are executed to perform various operations on the OPC UA servers.

The gateway has to be registered as Cumulocity IoT device in a specific tenant and the opcua-device-gateway must run in the users’ environment.

Important: In order to use OPC UA, you must be subscribed to the “opcua-mgmt-service” microservice. If the “opcua-mgmt-service” microservice is not available in your tenant, contact SAG support.

To download the gateway navigate to Cumulocity resources.

The gateway requires Java 8 in order to run.

Gateway configuration and registration

YAML file and spring profiles are used for the configuration of the gateway. A default configuration file is embedded in the gateway JAR file, so you only need to set the properties which are different from the default.

Important: When editing the YAML file, make sure to provide valid indentations.

To run the gateway locally, the default settings should be overridden in a customized profile. To use the customized profile, create a YAML file which must follow the naming convention:

application-<<Profile_name>>.yaml

For example, to connect to a tenant, first a profile named application-myTenant.yaml will be created. The following properties will be added to the file:

C8Y:
    baseUrl: https://<<yourTenant>>.cumulocity.com
gateway:
    bootstrap:
        tenantId: <<yourTenantId>>
    identifier: Gateway_Device
    name: My Gateway
    db:
# The gateway uses the local database to store platform credentials and local cache. This parameter shows the location in which the local data should be stored.
        baseDir: C:/Users/<<userName>>/.opcua/data

Info: Windows OS is used for the example.

Depending on your OS, the file must be saved to one of the following directories:

Windows OS
    /C:/opcua/
Linux OS
    /etc/opcua/
    /etc/opcua/data
Mac OS
    /opt/opcua/
    /opt/opcua/data

The number of profiles you may have is not limited. To use a specific profile on runtime, the “-Dspring.profiles.active” JVM argument has to be passed when running the gateway JAR file. For example, let’s use the previously created profile. Start a terminal and use the following command:

java -Dspring.profiles.active=default,myTenant -jar opcua-device-gateway-<<version>>.jar

The command above will start a gateway with the default profile and it will override the default properties with the properties defined in the “myTenant” profile. The list of profiles has to be provided as an ordered, comma-separated list. The default profile always needs to be the first profile in the list.

Optional: To specify your own configuration, Spring arguments can be used in your terminal to run the gateway JAR file. Multiple locations have to be comma-separated. The configuration locations should be either YAML files or directories. In case of directories, they must end with “/”. For example:

java -jar opcua-device-gateway-<<version>>.jar --spring.config.location=file:<<location>>/.opcua/conf/application-myTenant.yaml,file:<<location>>/.opcua/conf/

If both arguments “–spring.config.location” and “-Dspring.profiles.active” are provided, the configuration locations should be directories instead of files. Otherwise, the profile-specific variants will not be considered.

Additional customizations

Info: If no additional customizations are required, you can skip this section.

The following properties can be manually configured in the YAML file:

# Name of the application - this should not change
name: opcua-device-gateway
# Platform location and configuration
C8Y:
  baseUrl: http://localhost
  forceInitialHost: true

gateway:
# Gateway version - this is filled automatically during the build process - do not change this property
  version: ${project.version}
# The following two properties will be set to the name of the user that is running the gateway unless it's overridden manually
  identifier: mygateway
  name: mygateway
  db:
# The gateway uses the local database to store platform credentials and local cache. This parameter shows the location in which the local data should be stored.
    baseDir: ${user.home}/.opcua/data

# Credentials for device bootstrap - enter tenant that gateway should register to.
  bootstrap:
# ID of the tenant to which the device will be registered.
    tenantId: management
    username: devicebootstrap
    password: <devicebootstrap user password>
# On start, the gateway will wait <delay> milliseconds before connecting to the platform and searching for a      device.
    delay: 5000
# If true then gateway will drop stored device credentials and fetch them from platform
    force: false

# Scheduled tasks and thread pools configuration. Unless required, modifying these properties is not recommended.
  scheduler:
    threadpool:
      size: 10
  executor:
    threadpool:
      coreSize: 5
      maxSize: 20
# mappings execution thread pool configuration. Unless required, modifying these properties is not recommended.
  mappingExecution:
    http:
      connectionRequestTimeout: 3000
      connectionTimeout: 3000
      socketTimeout: 5000
    refreshInterval: 60000
    threadpool:
      size: 200
  cyclicRead:
    threadpool:
      size: 30
  subscription:
    reportingRate: 100
    maxKeepAliveCount: 200
# Should be at least 3 times greater than maxKeepAliveCount
    lifetimeCount: 600
# Repositories thread pool configuration. Unless required, modifying these properties is not recommended.

  repositories:
    flushInterval: 10000
    eventsThreadpool: 30
    alarmsThreadpool: 30
    measurementsThreadpool: 60
# Platform connection configuration. Unless required, modifying these properties is not recommended.

  platform:
    connectionPool:
      max: 250
      perHost: 150
# Monitoring interval - how often in milliseconds gateway sends monitoring data to Cumulocity IoT.     
  monitoring:
    # This parameter describes how often in milliseconds the gateway sends monitoring data to Cumulocity IoT.
    interval: 10000
# Time after which the gateway will publish a snapshot of values for the UI to the server.
  valueMap:
    lifeTime: 30

# How often (in milliseconds) gateway checks for changes in configured servers.
  childrenAddedOrRemoveCheck:
    interval: 30000

# Interval in milliseconds after which the gateway will read pending operations from the platform.
  shortPolling:
    enabled: true
    fixedDelay: 15000

# Time in days for which the certificate is valid.
  applicationIdentity:
    validityTime: 3650

Logging

Custom logging configuration can be set during startup by passing the “-Dlogging.config” jvm argument. For more info on how to set up custom logging settings, refer to the “Logback” documentation.

Running the Gateway

The gateway can run with either default or custom settings. To run the gateway run one of the commands below:

For example, using the profile from the previous section we are going to register the gateway. First, open the terminal and navigate to the location of the gateway.jar file. Next, enter the following command:

java -Dspring.profiles.active=default,myTenant -jar opcua-device-gateway-<<version>>.jar

Adjusting gateway memory settings

In certain scenarios it is required to adjust the memory settings of the gateway application. Examples for such scenarios are the integration of servers with very large address spaces or obtaining large amounts of data from servers using high sampling rates.

You can adjust the memory settings of the gateway like with any other Java program. Typically, it is sufficient to increase the initial heap size and the maximum heap size of the gateway process.

Important Please adjust the memory settings according to the physical memory available on the gateway host. The maximum heap size must be set in a way that it doesn’t consume more RAM than physically available to the gateway. Otherwise, the virtual memory management of the host operating system might start paging, resulting in reduced gateway performance.

Register the gateway as a Cumulocity IoT device

Navigate to the Registration page and click Register device > General device registration. Enter the Identifier name (in our example it is “Gateway_Device”) and then click Next.

Click Accept to complete the registration.

Device Registration

Connecting the gateway to the server

Next, establish a connection between the gateway and the OPC UA server.

  1. In the OPC UA server tab of the respective gateway, click Add server.
    Add new server
  2. Use the Server connection toggle, to enable or disable the server connection.
  3. Enter the Server URL which is used to establish a connection between the server and the gateway.
  4. Enter the Timeout value in seconds. The timeout value is calculated for each request. If the timeout value is exceeded the request will be unsuccessful.
  5. Enter the Status check interval in seconds. The platform constantly checks whether there is incoming data. If the status check interval value is exceeded an alarm is created. The status check interval value has to be greater than the monitoring value of the gateway.
  6. Select the Security mode and Security policy depending on the server configuration. For more info, see the section below.
  7. Select the desired authentication method. For more info, see the section below.
  8. Click Save.

Info: Once a connection is established, the servers will be located in the Child devices tab. In there, the servers will contain additional data such as access to the address space.

Security modes

The security mode settings tell the gateway how it should secure the connection between itself and the OPC UA server. When a mode other than NONE is selected, the gateway will auto-generate a self-signed application instance certificate and will use it to connect to the server. Possible security mode options are:

Info: The security modes have nothing to do with authorization or authentication! The security mode tells the gateway how the connection should be secured and whether the connection should be encrypted or not.

Authentication

The authentication setting is used to authenticate and authorize the server user. It tells the gateway how to create a user identity and how to send it to the OPC UA server when establishing a connection. The following authentication methods can be selected:

The keystore can be create via the following Java keytool command:

keytool -genkey -keyalg RSA -alias opcuauser -keystore keystore.jks -storepass passw0rd_a -validity 3600 -keysize 2048

terminal

The keystore can then be verified by using a tool like KeystoreExplorer.

Keystore explorer

Keystore explorer2

The keystore can then be uploaded as binary in Cumulocity IoT and it can be used in the server configuration.

Opcua Keystore

Gateway device details

In this section, only OPC UA specific information related to the tabs in the device details page will be explained. For more info on all tabs, see Device Management > Device Details in the User guide.

Gateway device details

Child devices

All server connections are listed as child devices even if the servers are disconnected. To stop a server connection, either delete the server child device or disable/remove the connection from the OPC UA server tab.

Gateway child devices

Measurements

The Measurements tab provides visualization of data in the form of charts. In total the gateway contains the following six charts:

Charts Description
Connected servers Provides the number of connected and disconnected servers.
Gateway active threads Shows the number of active threads for the alarm/measurements/event flushes and for the executor. You can also see whether the threadpool size limit is not sufficient, based on the threadpool configurations in the gateway. If the maximum threadpool size is reached then any new activities which require a new thread will be blocked until a thread is available.
Gateway cyclic reads Number of active cyclic reads done by the gateway. Cyclic reads are actively reading from the OPC UA server within an interval based on the configuration of the device protocol.
Gateway memory Represents the “free”,”max” and “allocated” memory values of the gateway.
Gateway repository queues Before a thread is flushed it is first added to the queue. This chart shows how many threads are currently in the queue.
Server response time Shows the response time of each currently connected server.

Gateway measurements tab

Alarms

The Alarms tab shows all alarms raised either in the gateway or in the servers. In total there are three alarms which can be raised:

Gateway alarms tab

Events

The Events tab shows all events related to the gateway-server connection. Additionally, you can see when the gateway has started and when it ends.

Gateway events tab

Address space

The Address space tab shows the attributes and references of the address space node of the servers. The filter searches through the whole hierarchy to find “nodeId”, “browserName” or “displayName” of an attribute. In case of multiple “ancestorNodeIds”, you can click on the desired node to be redirected.

The address space is automatically scanned when a connection between the gateway and the server is established. The duration of the scan depends on the size of the address space. The address space information is stored locally once it is scanned and then used by this applying process. If the address space information is not yet available, e.g. the address space has not been scanned, another scan will be triggered without synchronizing data into Cumulocity IoT. Performing another address space operation will update the address space information.

Gateway events tab

Device protocols

Adding a new device protocol

  1. Click New device protocol in the top menu bar and select OPC UA as device protocol type.
  2. In the resulting dialog box, enter a name and an optional description for the device protocol.
  3. Optionally, a reference server can be selected. Selecting a reference server allows you to create device protocols based on the OPC UA model stored on an OPC UA server. This greatly simplifies the mapping process, as device protocols can be created based on OPC UA browse paths being actually present on the server.
  4. Click Create.
    Add new device protocol

    Info: Selecting a reference server will require you to select a reference node.

Once the device protocol is created, various configuration settings such as variables, data reporting and constraints can be applied. Initially, the device protocol will be inactive. When active, the gateway will scan the address space of all servers and will automatically apply the device protocol to all nodes which match the criteria. When the device protocol is configured, click Save.

Adding a new variable

  1. Click Add variable under the Variables section.
  2. Enter the path and the name of the variable.
  3. Choose either the default or the custom data reporting. The default option uses the data reporting mechanism used in the device protocol. The custom option will let you configure a data reporting mechanism only for the current variable.
  4. Additionally, different functionalities such as sending measurements, creating alarms, sending events and custom actions for each variable can be selected.
  5. Click Save to save your settings.

The gateway has a scheduling job and after the variables are saved, the gateway will check whether the variables exist under the subtree of the node. Afterwards, for each node a child device of the server is created. The child devices will contain data based on the configuration of the device protocol. The node child devices will also be listed in the All devices page.

Info: If no reference server was selected during the device protocol creation, the path should be given with a namespace URI representation. In the OPC UA server the index value can be taken from the namespace array. An example namespace URI representation for browse path “5:Counter1” would be: http://www.prosysopc.com/OPCUA/SimulationNodes:Counter1. Node id equal to “ns=5;s=Simulation” will have the following namespace representation ‘nsu=http://www.prosysopc.com/OPCUA/SimulationNodes;s=Simulation. In both examples the server’s namespace array, the 5th element has the value of “http://www.prosysopc.com/OPCUA/SimulationNodes”.

OPC UA device protocol

The functionalities that can be enabled are the following:

Send measurement

Turn on Send measurement to specify a measurement.

Specify the following parameters:

Create alarm

Turn on Create alarm if you want to create an alarm out of the resource.

Specify the following parameters (all mandatory):

Send Event

Turn on Send event to send an event each time you receive a resource value.

Specify the following parameters:

Custom Actions

Custom actions are HTTP POST requests which the gateway will send to a defined custom URL. You can define custom headers and body template with the following placeholders available:

Below there is an example of a full device protocol that configures a custom action:

{
   "name": "My device protocol for HttpPost",
   "referencedServerId": "{serverId}",
   "referencedRootNodeId": "ns=2;s=HelloWorld/Dynamic",
   "enabled": true,
   "subscriptionType" : {
     "type": "Subscription",
     "subscriptionParameters": {
       "samplingRate": 1000
     }
   },
   "applyConstraints": {
     "matchesNodeIds": [
       "ns=2;s=HelloWorld/Dynamic1"
     ]
   },
   "mappings": [
       {
           "browsePath": [
               "2:Double"
           ],
           "customAction": {
               "type": "HttpPost",
               "endpoint": "http://my.endpoint.local",
               "bodyTemplate": "{\"text\": \"I am coming from Http POST, value: ${value} \", \"type\": \"HttpPostMO\"}",
               "headers": {
                   "Authorization": "Basic MYAUTHCREDENTIALS==",
                   "Content-Type": "application/json"
               }
           }
       }
   ]
}

Data reporting

There are three data reporting mechanisms which can be applied to read all mapped browse paths:

OPC UA device protocol

Important: Very low interval rates (e.g. 50 ms) for cyclic read and subscription types will result in huge amounts of data being created.

Applying constraints

Specifying auto-apply constraints allows you to limit the scope in which the device protocols are applied, for example by specifying a set of possible servers or node IDs. If no constraints are set, device protocols are applied at any fitting location on the OPC UA server.

The following constraints can be applied:

OPC UA device protocol

Operations

Cumulocity IoT operations is the interface that is used to tell the gateway what to do and how to do it. This section describes all operations that are currently supported by the gateway.

Scanning the address space

This operation triggers importing address space for a specific OPC-UA server. The server’s ID is passed as a device ID. The gateway will scan the entire address space of the server and persist a twinned representation of the address space in the Cumulocity IoT platform.

POST /devicecontrol/operations/

	{
	"deviceId": "<server-device-Id>",
	"c8y_ua_command_ScanAddressSpace": {
	        “skipSync”: false
	    },
	"description": "Import address space from root node"
	}

The twinned address space information is persisted in the Cumulocity IoT inventory. It is internally used to support address space browsing and to define device protocols. Hence this operation is always triggered if a new server is added to the platform.

Once the device gateway knows the address space, it uses it to handle different logics, for example applying device protocols to nodes. So if you already have the address space scanned once and stored in Cumulocity IoT, you might want the device gateway to learn one more time about server’s address space without synchronizing data into Cumulocity IoT. To achieve that, provide “skipSync”: true.

Info: We do not recommend to directly work with the persisted address space data structures in the Cumulocity IoT inventory, as these might change in the future. Use the endpoints of the management service to interact with the OPC UA address space.

Reading the value of a node/nodes

This operation reads the value attribute of specific node or list of nodes.

POST /devicecontrol/operations/

	{
	  "deviceId" : "<server-device-Id>",
	  "c8y_ua_command_ReadValue": {
		"nodes": ["NODE_ID"],
	     “timestampsToReturn”: “Neither”   
	  },
	  "description":"read value"
	}

Other possible values for timestampsToReturn: “Source”, “Server” or “Both”.

The result of this operation will contain output in the following format:

{
	"results": {
		"ns=2;s=MyLevel": {
			"13": {
				"value": {
					"value": 77.0
				},
				"statusCode": 0,
				"sourcePicoseconds": 0,
				"serverPicoseconds": 0
			}
		}
	}
}

Reading all attributes of a node

This operation returns all attributes of specific node.

{
	"deviceId": "<server-device-Id>",
	"c8y_ua_command_ReadNodeAttributes": {
		"node": "ns=2;s=MyEnumObject"
	},
	"description": "Read node attributes"
}

The result may differ depending on the node type.

{
	"Value": {
		"value": 1
	},
	"DataType": "ns=2;s=MyEnumType",
	"ValueRank": -1,
	"AccessLevel": 3,
	"UserAccessLevel": 3,
	"MinimumSamplingInterval": -1.0,
	"Historizing": false,
	"DisplayName": "MyEnumObject",
	"WriteMask": 0,
	"UserWriteMask": 0
}

Reading an attribute

This operation supports to read one or more attributes of one or more nodes. This includes support of the range parameter to read a single element or a range of elements when the attribute value is an array.

{
    "deviceId": "<server-device-Id>",
    "c8y_ua_command_ReadAttribute": {
   	  "nodes": ["ns=3;s=FloatArray"],
   	  "attribute":"13"
    }
    "description": "Read attribute from ns=3;s=FloatArray",
}

The result may differ depending on the node type.

{
	"results": {
		"ns=3;s=FloatArray": {
			"13": {
				"value": {
					"value": [1.0, 2.0, 3.0, 4.0, 5.0]
				},
				"statusCode": 0,
				"sourceTimestamp": 1566572540173,
				"sourcePicoseconds": 0,
				"serverTimestamp": 1566573849897,
				"serverPicoseconds": 0
			}
		}
	}
}

The index ranges given below are according to the OPC UA specifications and will be transformed to NumericRange.

The syntax is as following:

    NumericRange: <dimension> [',' <dimension>]
    <dimension>: <index> [':' <index>]
{
    "description": "Read attribute from ns=3;s=FloatArray",
    "deviceId": "<server-device-Id>",
    "c8y_ua_command_ReadAttribute": {
   	  "nodes": ["ns=3;s=FloatArray"],
   	  "attribute":"13",
   	  "ranges":"0:1"
    }
}

The result may differ depending on the node type.

{
    "results": {
   	 "ns=3;s=FloatArray": {
   		 "13": {
   			 "value": {
   				 "value": [1.0, 2.0]
   			 },
   			 "statusCode": 0,
   			 "sourceTimestamp": 1566572540173,
   			 "sourcePicoseconds": 0,
   			 "serverTimestamp": 1566574513935,
   			 "serverPicoseconds": 0
   		 }
   	 }
    }
}

Historic read

This operation reads history values and applies the mappings except of alarm mappings.

{
    "deviceId": "<server-device-Id>",    
    "c8y_ua_command_HistoricReadOperation": {
   	 "nodeId": "ns=2;s=MyLevel",
       "processMappings": true,
   	 "dateFrom": "2019-06-13T10:43:00+02:00",
   	 "dateTo": "2019-06-13T10:52:00+02:00",
   	 "tagType": "TAG"
    },
    "description": "Historic read"
}

Historic data binary upload

his operation reads historic values and only saves those values to a file which can be retrieved using the binary API.

{
    "deviceId": "<server-device-Id>",
    "c8y_ua_command_HistoricDataUploadOperation": {
   	 "nodeId": "ns=2;s=MyLevel",
   	 "dateFrom": "2019-01-03T09:53:00+02:00",
   	 "dateTo": "2019-06-13T18:53:00+02:00",
   	 "chunkSize": 1,
   	 "compress": true
    },
    "description": "Upload history data"
}

The binary file representations, which can be queried using binary API, are created with the type “c8y_ua_HistoricData” and an operationId with the value of the operation with which it has been generated.

Write value

This operation writes values to the node/nodes.

{
	"deviceId": "<server-device-Id>",
	"c8y_ua_command_WriteValue": {
		"values": {
			"ns=3;s=LocalizedText": {
				"value": "This is a localized text"
			},
			"ns=3;s=Double": {
				"value": "3.14159"
			}
		}
	},
	"description": "Write values to different nodes"
}

Write attribute

This operation is similar to the previous one, but instead of writing to the value attribute, this operation writes attributes’ values to any writable attributes. The following example writes two different attributes to two different nodes.

{
	"deviceId": "<server-device-Id>",
	"c8y_ua_command_WriteAttribute": {
		"values": {
			"ns=3;s=LocalizedText": {
				"attribute": "13",
				"value": "This is a localized text"
			},
			"ns=3;s=Double": {
				"attribute": "13",
				"value": "3.14159"
			}
		}
	},
	"description": "Write attributes’ values to different attributes of different nodes"
}

Optionally, it is possible to write a value range when the attribute value is an array.

{
	"deviceId": "<server-device-Id>",
	"c8y_ua_command_WriteAttribute": {
		"values": {
			"ns=3;s=FloatArray": {
				"attribute": "13",
				"ranges": "0:1",
				"value": "2.0,4.0"
			}
		}
	},
	"description": "Write attribute value to array attribute"
}

Get method description

This operation reads the description of a method node.

{
	"deviceId": "<server-device-Id>",
	"c8y_ua_command_GetMethodDescriptionOperation": {
		"nodeId": "ns=2;s=MyMethod"
	},
	"description": "get method description"
}

The result describes a method, it’s parent object, input and output arguments.

{
	"nodeId": "ns=2;s=MyMethod",
	"name": "MyMethod",
	"parentNodeId": "ns=2;s=MyDevice",
	"parentName": "MyDevice",
	"inputArguments": [{
			"name": "Operation",
			"description": "The operation to perform on parameter: valid functions are sin, cos, tan, pow",
			"dataType": "String",
			"dataTypeId": "i=12"
		},
		{
			"name": "Parameter",
			"description": "The parameter for operation",
			"dataType": "Double",
			"dataTypeId": "i=11"
		}
	],
	"outputArguments": [{
		"name": "Result",
		"description": "The result of 'operation(parameter)'",
		"dataType": "Double",
		"dataTypeId": "i=11"
	}]
}

Get method

This operation calls the method on the OPC UA server. It requires complete input arguments with an additional “value” fragment.

{
	"deviceId": "<server-device-Id>",
	"c8y_ua_command_CallMethodOperation": {
		"request": {
			"nodeId": "ns=2;s=MyMethod",
			"arguments": [{
					"name": "Operation",
					"description": "The operation to perform on parameter: valid functions are sin, cos, tan, pow",
					"dataType": "String",
					"dataTypeId": "i=12",
					"value": "pow"
				},
				{
					"name": "Parameter",
					"description": "The parameter for operation",
					"dataType": "Double",
					"dataTypeId": "i=11",
					"value": "5"
				}
			]
		}
	},
	"description": "call method"
}

The result contains all output arguments with values set by the OPC UA server. Power of 5 is 25:

{
	"statusCode": 0,
	"result": [{
		"name": "Result",
		"description": "The result of 'operation(parameter)'",
		"dataType": "Double",
		"dataTypeId": "i=11",
		"value": "25.0"
	}]
}

Troubleshooting

Permission denied error when running the gateway JAR file on a Linux OS

Permission denied

If the following error appears, add a baseDir property to the YAML file. For example:

db:
  baseDir: ${user.home}/.opcua/profile/data

Unknown host exception when running the gateway JAR

This error appears if the provided baseUrl property in the YAML file is incorrect.

Failed to load property source from location when running the gateway JAR

The following error appears if the indentation of the properties in the YAML file is incorrect.

Failed to load

java.net.BindException: Address already in use

Address in use

If this error appears, a Java process is running in the background. To fix this issue, the process must be stopped/killed.

Sigfox

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

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

Cumulocity IoT Sigfox integration

The following sections describe how to:

Moreover, check out the Troubleshooting section in case of any issues.

Info: To be able to use the Sigfox agent, your tenant needs to be subscribed to the application sigfox-agent. 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 IoT, you need to have an “Associated user” which is added to the Cumulocity IoT group in Sigfox Cloud and has the following profiles:

Important: Without the profiles described below, the required Sigfox API access can not be set up.

Step 1

If you already have an associated user make sure it has the profiles mentioned below and proceed to step 2.

The group name is not constrained. “Cumulocity” is used as a sample group name throughout the remaining steps.

First, enter into your Sigfox Cloud account and create a new user. Add the user to the group and select the “Customer [R]” 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:

API access page

Step 3

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

The following information has to be provided:

Info: The group name in the screenshot below is only an example. It does not necessarily have to be “Cumulocity”.

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, click Replace credentials and add your new credentials.

Creating device protocols

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

During the device registration, you can associate this device protocol. The received uplink callbacks for this device with a hexadecimal payload will then be mapped to the ones you have configured in your device protocol.

If a device protocol 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.

To create device protocols, select Device protocols in the Device types menu in the navigator of the Device Management application. You can either import an existing device protocol or create a new one.

Importing a device protocol

In the Device protocols page, click Import.

Select the desired predefined device type or upload it from a file. When ready, click Import again.

Creating a new device protocol

In the Device protocols page, click New device protocol and select Sigfox from the options list.

New Sigfox protocol

Provide a name for the device protocol an and optional description, and click Create.

Under Message types, specify the message types. 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).

In the Source field, select the way the message type is encoded:

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. In the Number of bits field, indicate how long this information is. For example, start bit = “0” and number of bits = “8”.

Sigfox protocol

Configuring values

Click Add value to create the value configuration.

Sigfox protocol add value

In the following window, configure the relevant values as shown in this example.

LoRa protocol add new value

LoRa protocol add new value

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

Under Message type, configure the Message ID according to your device message specification. 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 protocol 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

LoRa bits

Under General, specify a name for the value and the category under which it will be displayed in the values list.

Under Value selection, specify 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

LoRa bits

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

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

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

Under Options, select on of the following options, if required:

Under Functionalities, specify how this device protocol should behave:

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

Click OK to add the values to your device protocol.

Value configurations of created device protocol

Click Save to create the device protocol.

Example with single property

The following images show an example for a message which sends a measurement when the battery level value changes.

Battery level changes example

Battery level changes example

Example with nested structure

The following images show an example of a nested structure for a device protocol, reporting the current position of a GPS device. The device protocol 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

To register a Sigfox device, navigate to the Registration page in the Devices menu in the Device Management application and click Register devices. In the upcoming window, select Custom device registration and then Sigfox.

Register devices

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

In the next window, fill in the required information:

Info: The term “Device type” is used both by Sigfox and Cumulocity IoT, but with different meaning. In Sigfox, a device type specifies how to route data from devices. In Cumulocity IoT, 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 previously 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 the “Shell”. In the Device Management application, navigate to the device you want to send an operation to in the All devices page. 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.

Troubleshooting

No contracts available

No contracts available error

In order to resolve this error, please contact support.sigfox.com to create a contract for your Sigfox account.

Sigfox callbacks in backend.sigfox.com are not created correctly

Callback information

The information for the callback setup is retrieved by a microservice.

To verify whether your setup is correct, execute the following REST API request:

```http
GET {{url}}/tenant/currentTenant
```

Info: The request above is simply an example API request that could be used. For more info on REST API requests, refer to the Tenants in the Reference guide.

Issues with alarm provisioning

!Failed operation

If the “transfer operation failed” alarm is triggered, the device is already provisioned in the Sigfox platform and changing the device type in the Sigfox platform failed. In order to fix this issue, you have to manually change the device type in the Sigfox platform to the intended one.

Provisioned status is set to false

!False provision

In case of this alarm, you can see that the Provisioned status is set to “false” which means that no data is coming from the Sigfox platform. In the alarm message there is more information regarding the error. In this case the PAC code given during registration was invalid.

Info: If the provisioning process has been completed, but has failed, information is returned as an alarm with the reason of the failure provided.

The Provisioned status is set to true when the device provisioning process is completed and success information is received from the Sigfox platform. Additionally, it is set to true when uplink messages are retrieved from the device.

Info: The status is updated asynchronously which means that sometimes you might have to wait a bit until it is set to true.

Callback creation failed

Callback creation failed

This alarm is created when one or more callback creation requests have failed in the Sigfox platform. You can view the alarm either in the Alarms page or in the Home page.

In order to fix this issue, navigate to the Sigfox platform web interface and check the device type with the id mentioned in the alarm.

Device Type Id in the alarm

In this case navigate to the following address: https://backend.sigfox.com/devicetype/5cd3d97ee833d9746698b27d/callbacks

If the mentioned callbacks cannot be located in the Sigfox platform, you must create them manually. All of the required information needed for the creation of the callbacks is already given in the alarm description. In the case of the above alarm, the following callback is listed first:

In order to manually create the callback, the following properties must be filled:

Info: The Authorization header displayed in the alarm does not show the user credentials.

Non-mentioned properties from the alarm are:

These properties will be set to false.

SNMP

Overview

Simple Network Management protocol (SNMP) is an application layer protocol, used widely in network management for monitoring network devices.

There are two components that help SNMP-enabled devices to connect to the Cumulocity IoT platform:

  1. The Mibparser microservice helps in converting a Managed Information Base (MIB) file to a JSON representation which is then used to create a device protocol.
  2. The SNMP agent is a device-side agent that helps SNMP-enabled devices to connect to the Cumulocity IoT platform and translates messages from a SNMP-specific format to a Cumulocity IoT model before forwarding them to the Cumulocity IoT platform.

Info: The SNMP agent and the Mibparser microservice code is open source. The code can be found in the Cumulocity IoT examples repository at https://bitbucket.org/m2m/cumulocity-examples/src/develop/snmp/.

The following image provides a general overview of the SNMP-enabled device integration with Cumulocity IoT:

Cumulocity IoT SNMP Integration

SNMP agent

Introduction

The SNMP agent is a stand-alone Java program that communicates with SNMP-enabled device(s) and the Cumulocity IoT platform. It receives SNMP data from the devices, converts the data to Cumulocity IoT-based objects based on the device protocol mapping, persists the data locally, and forwards the data to Cumulocity IoT. The agent has to be registered in Cumulocity IoT before serving the device request.

Info: If you are using one of the Software AG managed public cloud instances, you need to ensure that your tenant is subscribed to the Mibparser microservice.

To add the Mibparser microservice to the Cumulocity IoT platform,

Installation

Prerequisites
Java version Java Runtime Environment 8 or newer version.
Heap memory The agent Java application can run on as little as 200MB of heap space.
However, based on the number of devices and the load, this needs to be adjusted.
Disk space The Cumulocity IoT representation of the SNMP message will be persisted before forwarding to the platform.
Based on the load, sufficient disk space should be available to store the objects.
Hardware and OS Linux environment, can run on laptops or industrial PCs.
To install the agent
  1. Download the latest SNMP agent RPM:

    wget -nv http://resources.cumulocity.com/examples/snmp/snmp-agent-gateway-<ga-version>-1.noarch.rpm
    

    The <ga-version> needs to be provided in the format 1005.7.0, 1006.0.0, and so on. A sample command would look like this:

    wget -nv http://resources.cumulocity.com/examples/snmp/snmp-agent-gateway-1006.0.0-1.noarch.rpm
    
  2. Verify the signature of the RPM package:

    rpm --checksig snmp-agent-gateway-<ga-version>.rpm
    
  3. Install the SNMP agent RPM package:

    sudo rpm -ivh snmp-agent-gateway-<ga-version>.rpm
    
  4. Check the installed RPM package:

    rpm -q snmp-agent-gateway
    
  5. Configure the agent:

    • Create a .snmp folder in the user home directory:

      mkdir -p $HOME/.snmp
      
    • Copy the snmp properties file into the .snmp folder:

          cp /etc/snmp-agent-gateway/snmp-agent-gateway.properties $HOME/.snmp
      
    • Change the properties according to the Cumulocity IoT environment (e.g. gateway.identifier, Cumulocity IoT bootstrap details, SNMP Community target).

  6. Start the service:

    systemctl start snmp-agent-gateway
    
  7. Check if the service started properly by checking the status:

    systemctl status snmp-agent-gateway
    
  8. Make sure that the agent process is running without any issues. To do so, check the agent log file:

    $HOME/.snmp/log/snmp-agent-gateway-server.log
    

Info: The agent uses the following location as persistent storage:

    $HOME/.snmp/{gateway.identifier}/chronicle

Upgrading a GA version

Info:: This upgrade procedure is only for GA releases. If you have installed any previous release prior to GA release, follow the migration procedure described below.

  1. Make sure that the load to the SNMP agent is zero. This can be done by gracefully disconnecting all SNMP devices from the SNMP agent or redirect the traffic to a different endpoint.
  2. If there are pending messages in the SNMP agent to be sent to the platform, wait for the processing to complete.
  3. Once the message processing is complete, stop the agent process:

    systemctl stop snmp-agent-gateway
    
  4. Upgrade the SNMP agent RPM package:

    rpm -Uvh snmp-agent-gateway-<new-ga-version>.rpm
    
  5. Start the service:

    systemctl start snmp-agent-gateway
    
  6. Check if the service started properly by checking the status:

    systemctl status snmp-agent-gateway
    
  7. Make sure that the agent process is running without any issues. To do so, check the agent log file:

    $HOME/.snmp/log/snmp-agent-gateway-server.log
    

Migration

The SNMP agent has undergone a major revamp in-terms of persistence storage mechanism, robustness, performance improvements etc. between version 10.4.x and 10.5.x. If the current running version of SNMP is 10.4.x or earlier then follow the steps below to migrate to a GA version.

Info:: The migration is equivalent to a fresh installation, as the GA release uses a different persistent store compared to earlier releases. This requires a down time for installation and configuration.

  1. Make sure that load to the SNMP agent is zero. This can be done by gracefully disconnecting all SNMP devices from the SNMP agent or redirect the traffic to a different endpoint.
  2. If there are pending messages in the SNMP agent to be sent to the platform, wait for the processing to complete.
  3. Once the message processing is complete, stop the agent process.
  4. Take a backup of the $HOME/.snmp folder, the configuration file in /etc/snmp (if present) and the agent JAR file (if a JAR file is used for starting the agent).
  5. If the SNMP agent was installed as RPM package, uninstall it:

    rpm -e <snmp-package-name>
    
  6. Delete the contents inside $HOME/.snmp/ and /etc/snmp folder (if present).

  7. Delete the snmp-agent device in Cumulocity IoT which was registered as part of the installation and all its child SNMP devices. This can be done from the user interface or by using REST endpoints.

  8. Follow the installation procedure described above, to install/move to GA version.

Info: SNMP device protocol/s can be retained (unless there are no changes in the SNMP device configuration).

Registering the agent

Before any SNMP device can connect to the Cumulocity IoT platform, first the SNMP agent needs to be registered in the platform.

To register the agent from the UI

  1. In the Device Management application, click Registration in the Devices menu in the navigator.
  2. Click Register device and then select General device registration.
  3. In the resulting dialog box, enter the device ID. The device ID corresponds to the gateway.identifier value mentioned in the snmp-agent-gateway.properties file.
  4. Click Next to proceed with the device registration and then click Complete.The device will be shown in the Device registration page with the status WAITING FOR CONNECTION.
  5. If the agent process is started and the device ID is correct you will see an Accept button. If the agent is not started, start the agent application. Click Accept to complete the registration process.

After successful registration, the agent device will be added to the device list in the All devices page, with device ID as name.

Device list

To register the agent via REST API

Step-1: Create a new device request:

POST /devicecontrol/newDeviceRequests
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.newDeviceRequest+json
{
    "id": "snmp-agent" // should be the same as "gateway.identifier" value from the snmp-agent-gateway.properties file.
}

Step-2: Accept the new device request:

PUT /devicecontrol/newDeviceRequests/snmp-test
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.newDeviceRequest+json
{
    "status": "ACCEPTED"
}

Creating a device protocol

SNMP device protocols can either be created manually or by importing a MIB file shared by the device manufacturer. This device protocol will later be used when adding the SNMP device to the platform.

To create a device protocol from the UI

  1. Create a ZIP file which contains the top-level MIB file along with dependent MIB files and an index file named mib-index which contains the name of the top level MIB file.
    Subscribed applications
  2. In the Device Management application, click Device protocols in the Device types menu in the navigator.
  3. In the top menu bar of the Device protocols page, click Import.
  4. Select the MIB ZIP file from the dropdown list or upload the file from your file system.
  5. In the Name field, enter a name for the device protocol.
  6. Click Import.

On successful import, the newly added device protocol will be listed in the device protocols list.

Device protocol - SNMP

To create a device protocol via REST API

Step-1: Upload the MIB file and note down the JSON response:

POST /service/mibparser/mib/uploadzip
Authorization: Basic ...
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary8WCDTr2uRkbroQ11

------WebKitFormBoundary8WCDTr2uRkbroQ11
Content-Disposition: form-data; name="file"; filename="APPN-TRAP-MIB_02.zip"
Content-Type: application/zip
------WebKitFormBoundary8WCDTr2uRkbroQ11--

Step-2: Use the JSON response and create a device protocol managed object:

POST /inventory/managedObjects
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.managedobject+json;
{
    "name": "snmp-device-protocol",
    "fieldbusType": "snmp",
    "type": "c8y_ModbusDeviceType",
    "fieldbusVersion": 4,
    "c8y_IsDeviceType": {},
    "c8y_Global": {},
    "c8y_Registers": [
        <<This is the response of the above POST call>>
    ]
}

To create a device protocol manually

Device protocols can also be created manually. To do so, you need to know the OIDs supported by the device. This method is suitable for small number of OIDs supported by the device or for testing purposes.

  1. In the Device Management application, click Device protocols in the Device types menu in the navigator.
  2. In the top menu bar of the Device protocols page, click Add device protocol.
  3. Select SNMP as device protocol.
  4. Enter the name and a description for the device protocol.
  5. Click Create. On successful creation, the new device protocol will be added to the device protocols list.
  6. Open the newly created device protocol.
  7. Click Add component.
  8. Provide OID details and device protocol mapping for the OID.
  9. Click Save to save your settings.

Device protocol - SNMP

Creating device protocol mapping

The device protocol mapping helps the agent to know how to deal with incoming data from the SNMP-enabled devices. It basically allows users to configure an OID with a corresponding Cumulocity IoT object such as an alarm, event or measurement. This information is later used by the agent to convert incoming data (say TRAP) to corresponding Cumulocity IoT object/s that are defined in the mapping.

To create mapping from the UI

  1. In the Device Management application, click Device protocols in the Device types menu in the navigator.
  2. Open the desired device protocol (e.g. snmp-device-protocol). It shows a list of components representing the OIDs.

    Device protocol details

  3. Click the menu icon at the right of the component and click Edit to configure the mapping for the component.

  4. Under Functionalities, switch the toggle button to turn on the mapping for the required Cumulocity IoT model (Send measurement, Raise alarm and/or Send event). Fill in the values for the respective fields and click Save.

    Edit components details

  5. Click Save in the Device protocol page to finally save the changes.

To create mapping via REST API

PUT /inventory/managedObjects/{{device.protocol.id}}
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json
{
   "id":"18849",
   "name":"snmp-device-protocol",
   "owner":"snmp-test",
   "description":"snmp-device-protocol",
   "fieldbusType":"snmp",
   "type":"c8y_ModbusDeviceType",
   "fieldbusVersion":4,
   "c8y_Coils": [],
   "c8y_Global": {},
   "c8y_IsDeviceType": {},
   "c8y_Registers": [
    {
        "id": "22555518094562443"
        "name": "CPU",
        "number": null,
        "multiplier": 1,
        "divisor": 1,
        "offset": 0,
        "decimalPlaces": 0,
        "startBit": 0,
        "noBits": 16,
        "unit": "",
        "signed": false,
        "input": false,
        "category": "cpu",
        "description": "CPU",
        "oid": "1.3.6.1.2.1.34.4.0.2",
        "measurementMapping": {
            "type": "c8y_CPU",
            "series": "T",
            "sendMeasurementTemplate": 301
        }
    }
   ]
}

Adding SNMP devices

SNMP-enabled devices can be added manually or through the autodiscovery method.

Autodiscovery

The autodiscovery functionality allows to scan SNMP-enabled devices in the network for a given IP range. Identified devices will automatically be added as a child to the agent device in the platform. This functionality is helpful when you need to add a large number of devices to the agent. Instead of adding all devices manually, you can use the autodiscovery functionality. The IP range field accepts multiple IP ranges separated by comma, for example “10.23.52.51-10.23.52.54,192.168.0.1-192.168.0.5”. It also supports the IPv6 IP address format.

There are two supported ways of discovering devices.

Both ways of device discovery can be controlled from the user interface.

Autodiscovery

To start autodiscovery from the UI
  1. In the Device Management application, click All devices in the Devices menu in the navigator.
  2. In the devices list, click on the SNMP agent device and open the SNMP tab of the device.
  3. Enter the IP range and click Save.
  4. Once the changes are saved, the Start autodiscovery button gets enabled.
  5. Click Start autodiscovery. The operation being started can be monitored in the Control tab.

If a new SNMP-enabled device is identified, it will be added to the devices list. Alternatively, added SNMP devices can be seen in the Child devices tab.

If you want to run autodiscovery after every interval, enter the interval in the Scheduled interval field and click Save. When the agent refreshes the configuration data, the scheduled autodiscovery will automatically be started. You don´t need to click Start autodiscovery in case of scheduled autodiscovery.

Autodiscovery SNMP device list

For the newly found SNMP device, the default device name will be mentioned as Device-<device-ip-address>, the IP address will be <device-ip-address> and the default port number is 161. All other details will be empty and have to be entered manually.

An alarm will be generated

To start autodiscovery via REST API

The following REST call will trigger autodiscovery once:

POST /devicecontrol/operations
Authorization: Basic ...
Content-Type: application/json
{
    "deviceId": "{{agent.device.id}}",
    "description": "Autodiscovery request",
    "c8y_SnmpAutoDiscovery": {
        "ipRange": "10.23.52.51-10.23.52.54"
    }
}

The following REST call schedules autodiscovery for the given interval:

PUT /inventory/managedObjects/{{agent.device.id}}
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json
{
    "id": "{{agent.device.id}}",
    "c8y_SNMPGateway": {
        "ipRange": "10.23.52.51-10.23.52.54",
        "autoDiscoveryInterval": 10,     // Scheduling interval in minutes
        "maxFieldbusVersion": 4,
        "transmitRate": 0,
        "pollingRate": 0
    }
}

Adding SNMP devices manually

To add a SNMP device manually from the UI
  1. In the Device Management application, click All devices in the Devices menu in the navigator.
  2. In the devices list, click on the SNMP agent device and open the SNMP tab of the device.

    SNMP tab
  3. In the SNMP devices section, click Add SNMP device.
  4. Provide the SNMP device details:
    Field Description
    Name Provide a meaningful name to identify the device.
    Device type Select the device protocol relevant for the device being added. The device protocol contains the OID and the mapping of the OID to the Cumulocity IoT’s model such as alarm/event/measurement.
    IP address IP address of the device.
    Port Port to be used during device polling.
    SNMP version Select one of the 3 SNMP versions (v1, v2c and v3) supported by the SNMP agent:
    For v1 and v2c, the community target is configurable at the agent side (snmp-agent-gateway.properties).
    For v3, various additional parameters have to be provided under Device authentication details:
    - User name: Provide a valid user name for the device which will be used to authenticate the TRAPs coming from the device.
    - Engine ID: The engine ID must be unique for each device and cannot be edited once saved. The length of the engine ID must have of a minimum of 5 and a maximum of 32 characters.
    - Security Level: There are three types of security levels supported by SNMP v3 (NOAUTH_NOPRIV, AUTH_NOPRIV, AUTH_PRIV). Depending on the security level selected, you need to provide authentication and/or privacy details.
  5. Click Add to add the device.

The SNMP device will be listed in the devices list and in the Child devices tab.

To add a SNMP device via REST API

Step-1: Create a device in the platform:

For a SNMP device with SNMP v1 or v2c

POST /inventory/managedObjects
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json
{
   "name":"snmp-device-0",
   "type":"snmp-device-protocol",
   "owner":"{{tenant.user}}"
   "c8y_SNMPDevice":{
      "ipAddress":"192.168.0.1",
      "port":"161",
      "version":0,              // 0 for v1, 1 for v2c and 3 for v3
      "auth":{},
      "type":"/inventory/managedObjects/{{device.protocol.id}}"
   }
}

After posting the above request you will get a response similar to the one below. Note down the SNMP device ID (snmp.device.id).

{
   "id": "18955",
   "owner": "{{tenant.user}}",
   "name": "snmp-device-0",
   "type": "snmp-device-protocol",
   "c8y_SNMPDevice": {
        "port": "161",
        "auth": {},
        "ipAddress": "127.0.0.1",
        "type": "/inventory/managedObjects/{{device.protocol.id}}",
        "version": 0
    }
   ...
}

For SNMP v3, additional authentication and privacy details have to be provided:

POST /inventory/managedObjects
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json
{
    "name": "snmp-device-3",
    "type": "snmp-device-protocol",
    "owner": "{{tenant.user}}",
    "c8y_SNMPDevice": {
        "ipAddress": "192.168.0.1",
        "port": "161",
        "version": 3,
        "auth": {
            "username": "my-user",
            "engineId": "12:23:4B:3F",
            "securityLevel": 3,
            "authProtocol": 2,
            "authPassword": "***",
            "privProtocol": 1,
            "privPassword": "****",
        },
        "type": "/inventory/managedObjects/{{device.protocol.id}}"
    }
}

Security level and protocols can have the following values:

securityLevel

“securityLevel”: 1 //NOAUTH_NOPRIV
“securityLevel”: 2 //AUTH_NOPRIV
“securityLevel”: 3 //AUTH_PRIV

authProtocol

“authProtocol”: 1 // MD5
“authProtocol”: 2 // SHA

privProtocol

“privProtocol”: 1 // DES
“privProtocol”: 2 // AES128
“privProtocol”: 3 // AES192
“privProtocol”: 4 // AES256

Step-2: Add the SNMP device as a child device under the agent:

POST /inventory/managedObjects/{{agent.device.id}}/childDevices
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.managedObjectReference+json
{
    "managedObject": {
        "id": "{{snmp.device.id}}"
    }
}

To update the SNMP device details, use the following REST API:

PUT /inventory/managedObjects/{{snmp.device.id}}
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json
{
    "name": "snmp-device-1",
    "type": "snmp-device-protocol",
    "owner": "{{tenant.user}}",
    "c8y_SNMPDevice": {
        "ipAddress": "192.168.0.1",
        "port": "161",
        "version": 2,
        "auth": {},
        "type": "/inventory/managedObjects/{{device.protocol.id}}"
    }
}

To delete the SNMP device, use the following REST API:

DELETE /inventory/managedObjects/{{snmp.device.id}}
Authorization: Basic ...

TRAP processing

A TRAP is an urgent message sent from the SNMP device to the agent. The SNMP device must send the TRAPs to the agent at the port number defined in snmp.trapListener.port in the agent configuration file (default port number is 6671). For this, the SNMP device needs to be configured with the agent connectivity details.

For SNMP v1 and v2c, the community target has to be the same in the agent and in the SNMP device. At the agent side, this is configured in snmp-agent-gateway.properties and this should match with the SNMP device. In case of SNMP v3, the authentication and privacy details need to be configured before the SNMP device can send the TRAP to agent.

A TRAP contains a PDU object which is configured with an OID and a value. If this OID is configured with a mapping in the device protocol assigned to the SNMP device in the platform, corresponding Cumulocity IoT object/s such as alarm/event/measurement will be created in the platform based on the configured mapping.

Info:: If a TRAP is received by the agent from a device which is not registered, the agent raises a major alarm that a TRAP has been received from an unknown device, showing its IP address. The alarm can be viewed in the Alarms tab of the agent device.

Device polling

The SNMP agent provides the capability to poll for SNMP device data by the OID. In the device protocol that is configured for the SNMP device, if any of the OIDs have measurement mapping enabled, these OIDs will be polled for the data. If an OID does not contain measurement mapping it will be skipped from polling.

To enable polling from the UI

  1. In the Device Management application, click All devices in the Devices menu in the navigator.
  2. In the devices list, click on the SNMP agent device and open the SNMP tab of the device.
  3. In the SNMP communication section, provide the polling interval in the field Polling rate. For example: If the value is set to “5”, the agent polls the SNMP devices OID(s) data every 5 seconds. To stop the polling, set the polling interval to 0 or an empty value.
  4. Click Save.
    SNMP Device polling

The data received via polling is mapped to the Cumulocity IoT model based on the mapping defined. As the OIDs contain measurement mapping, the measurements can be viewed in the Measurements tab of the SNMP device.

SNMP device measurement graph

To enable polling via REST API

The following REST call schedules the polling with a given time period:

PUT /inventory/managedObjects/{{agent.device.id}}
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json
{
    "id": "{{agent.device.id}}",
    "c8y_SNMPGateway": {
        "maxFieldbusVersion": 4,
        "ipRange": "",
        "autoDiscoveryInterval": null,
        "pollingRate": 5,    // Polling rate in seconds
        "transmitRate": 10,
    }
}

Transmit rate is the interval at which the data from the agent is sent to the platform. For example: If the transmit rate is 5 seconds, the data will be queued up at the agent side and sent to the platform after every 5 seconds. In case of measurements, if the number of measurements is more than 1, the measurements will be grouped and sent to the platform in batches. In case of a large number of measurements in the queue, the maximum batch size will limit to 200 measurements in a single request (default is 200, but configurable in snmp-agent-gateway.properties). If the transmit rate is set to zero, the data will be sent to the platform as and when they are created.

Uninstallation

To uninstall the agent completely, follow these steps:

  1. Make sure that the load to the SNMP agent is zero. This can be done by gracefully disconnecting all SNMP devices from the SNMP agent or redirect the traffic to a different endpoint.
  2. If there are any messages to be processed, wait for it to complete. If you do not care about the pending messages to be processed, continue.
  3. Stop the agent process:

    systemctl stop snmp-agent-gateway
    
  4. Take a backup of the following folders (if required):

    $HOME/.snmp
    /etc/snmp-agent-gateway
    
  5. Uninstall the SNMP agent RPM package:

    rpm -e snmp-agent-gateway
    
  6. Delete the following folders:

    $HOME/.snmp
    /etc/snmp-agent-gateway
    /usr/lib/snmp-agent-gateway
    /var/log/snmp-agent-gateway
    

Troubleshooting

If there are any issues while starting the service

Check the status of the service:

systemctl status snmp-agent.service
If there are any issues during the execution

The agent has extensive logging to inform the user about the situation and in many cases it will also provide the action that the user can take in case of an error situation. All information is logged into a file and the log file is located at: $HOME/.snmp/log/snmp-agent-gateway-server.log.

How can I find the old logs?

The latest log can be found in $HOME/.snmp/log/snmp-agent-gateway-server.log. However, the agent uses logback and log files are rotated based on a rolling policy. The default rolling policy is FileAndTime based and the max file size is set to 50MB. The old log files are also present in the same directory as the current running log: $HOME/.snmp/log/snmp-agent-gateway-server-%d.%i.log.

How can I change the log configuration of the agent process?

Edit the following startup file and change the “arguments” attribute and add the new log configuration file path. Restart the service for the changes to take effect.

vi /usr/lib/snmp-agent-gateway/start
--logging.config=/etc/snmp-agent-gateway/snmp-agent-gateway-logging.xml
How can I change the memory configuration of the agent Java process?

Edit the following startup file and change the heap memory settings (-Xms128m -Xmx384m) to the desired value. Restart the service for the changes to take effect.

/usr/lib/snmp-agent-gateway/start
How can I change the default agent configurations?

In the installation procedure, many of the agent configurations are defaulted to some value. These default values are set based on testing, common usage assumptions and ease of installation. However, you can change the default value to a value suitable for your environment and usage. To do so, uncomment the property and change the value of the property in $HOME/.snmp/snmp-agent-gateway.properties. On saving the changes, restart the agent service for the changes to take effect.

Which Cumulocity IoT services does the agent use?

The agent makes use of c8y core APIs (most notably inventory, identity, device control, alarm/measurement/event) of the platform.

What are the ports used by the agent?

Exposed Network Interfaces (listening ports) The table below lists the default values for all inbound listening ports. All ports are configurable in the agent settings config file.

Default Port Protocol Remarks Note
6671 UDP/TCP SNMP TRAP listener port This is the default port number on which
SNMP devices connect and sends TRAP.
The value can be changed in the property file.

Tenant SLA Monitoring

Overview

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

Info: The Tenant SLA Monitoring service is only available to the main Management Tenant.

In detail, it offers the following features:

By using Tenant SLA Monitoring, service providers can instantly check

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.

Sla-monitoring subscribe

For details on application subscription, refer to Enterprise Tenant > Managing tenants > 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:

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:

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.

webMethods.io Integration

webMethods.io Integration is Software AG’s cloud based integration solution. It enables you to automate tasks by connecting cloud applications and services (such as Marketo, Salesforce, Evernote, and Gmail) without writing any code.

The complete webMethods.io Integration documentation is available at https://docs.webmethods.io/.

Getting started

Info: If your tenant has been created outside of SAG Cloud you will not benefit from the user experience described below. You can still use webMethods.io to integrate Cumulocity IoT with other applications, but you cannot use the app switcher and single sign-on login.

To subscribe to webMethods.io Integration, perform the following steps:

  1. Log into the Cumulocity IoT platform as part of Software AG Cloud.

  2. In the application switcher, select webMethods.io Integration.

webMethods.io App Switcher Integration

Info: If the icon is unavailable you might not be subscribed to webMethods.io Integration. Subscribe to it by opening the application switcher and clicking MyCloud. This will take you to the Software AG Cloud portal where you can subscribe for a free trial.

webMethods.io App Switcher My Cloud

Examples

Integrations in webmethods.io are called “workflows”. A workflow is a connection between two or more web apps or services. It’s like a set of steps required to perform a task.

The example workflow below is triggered by an alarm in Cumulocity IoT and creates a ticket in Zendesk and sends an SMS message.

webMethods.io Example Workflow

WebMethods.io also provides pre-configured workflows which are called “recipes”.

webMethods.io Example Recipe

More examples and technical guides can be found on the Software AG TECHcommunity website https://techcommunity.softwareag.com/ in the Tips, Tricks and Code section.