Working with Cumulocity IoT Edge

IoT platform

Cumulocity IoT Edge comes with three built-in applications - Device Management, Cockpit and Application.

Since Cumulocity IoT Edge is based on the same software as the cloud-based Cumulocity IoT Core version, the above applications are the same in both versions, with minor restrictions.

Below find an overview on the functionalities of these applications in Cumulocity IoT Edge.

For general information on functionalities and features of the GUI refer to GUI functionalities and features.

For information on how to change the user settings of your account refer to User settings.

Device Management

The Device Management application provides functionalities for managing and monitoring devices and enables you to control and troubleshoot devices remotely.

The following functionalities are available in Cumulocity IoT Edge and described in detail in these sections:

SECTION CONTENT
Connecting devices How to register one or more devices manually and how to bulk-register devices in order to connect devices to your account.
Viewing devices What is displayed in the device list and how to sort devices by searching for devices and filtering devices.
Grouping devices Why and how to group devices into top-level groups, subgroups and smart groups.
Device details Detailed description of the various kind of information available for various types of devices.
Monitoring and controlling devices How to monitor the connection quality and service status of devices, how to handle alarms from devices, how to remote control and how to troubleshoot devices.
Managing device types How to process data from various device types by using device protocols.
Managing device data How to retrieve and manage firmware and software for devices and how to handle configuration snapshots.
Using SmartREST templates How to work with SmartREST templates, a collection of request and response templates used to convert CSV data and Cumulocity Rest API calls.

Cockpit

The Cockpit application provides you with options to manage and monitor Internet of Things (IoT) assets and data from a business perspective.

The following functionalities are available in Cumulocity IoT Edge and described in detail in these sections:

Section Content
Managing assets Organize assets in hierarchies by creating groups and assigning devices.
Visualizing data using the Data Explorer Interactively explore, compare and visualize IoT data.
Describes how to access and use the data explorer, add data points to the data explorer, customize data point properties, modify the visualization, store the data explorer as widget, and export the data.
Working with dashboards Create your own analytics and monitor pages by adding and arranging widgets. Share dashboards among all devices of the same type.
Widgets collection Use various types of widgets from the Widgets collection that comes with Cumulocity and configure them according your needs.
Working with alarms Monitor problems of your assets using severities and workflows. Since working with alarms in the Cockpit application is actually the same as working with alarms in Device Management, refer to Working with alarms in Device Management.
Managing reports Handle reports based on dashboard layouts, create reports for exporting data in CSV or excel format and schedule the export.
Using the Data Point Library Manage default settings ("profiles") of your devices and apply them automatically using the Data Point Library.
Working with Smart Rules Create and manage business rules to work on incoming data in realtime and to perform actions based on this data.
Smart Rules collection Use pre-defined global Smart Rules to configure rules for geofencing, thresholds or alarm escalation and notifications (SMS/email/voice). Describes each SmartRule and its configurable parameters in detail.

Administration

The Administration application enables account administrators to manage their users, roles, tenants and applications and lets them configure a number of settings for their account.

The following functionalities are available in Cumulocity IoT Edge and described in detail in these sections:

SECTION CONTENT
Home Screen Providing information on your capacity usage and subscribed applications.
Managing Users How to create users, edit, disable or delete them.
Managing Permissions How to create and edit global roles and inventory roles, how to assign them to users, and how to grant application access.
Managing own applications How to manage and configure own applications in your Cumulocity account.
Changing settings How to change account settings like application settings or password policy settings and how to manage the properties library.
Managing data retention How to manage and configure retention rules for your data and how to manage stored files in the file repository.

Connecting devices

Cumulocity uses REST and MQTT as protocols for external communication. Both protocols may be used to interface devices with Cumulocity. For details refer to the sections on Device integration using REST and Device integration using MQTT in the Device SDK guide.

Additionally, Cumulocity IoT Edge offers Cloud Fieldbus functionality to collect data from fieldbus devices and remotely manage them. To do so, various protocols are provided, e.g. Modbus and OPC/UA. For details on how to integrate devices using Modbus and OPC/UA, refer to Optional Services > Cloud Fieldbus in the User guide.

Connecting a Modbus device

Modbus is a serial communications protocol originally published by Modicon and used to establish master-slave/client-server communication between devices.

Before you can connect a Modbus device you first have to configure the Modbus agent. This only has to be done once as a preparation step and is not required for every Modbus device.

Configuring the Modbus agent

Check if the Modbus agent is running in Edge (running on port 6670):

$ systemctl status cumulocity-agent

Once the agent is started navigate to the log file or execute the following command to monitor the log:

tailf /var/log/cumulocity-agent.log

Copy the cumulocity-agent device ID which you can find in /var/log/cumulocity-agent.log, e.g. "C0F64C7B90A14C4BB22AB526928F09A9”. This ID will be used for the registration process.

Registering the agent

Next, register the agent in the Device management application using the device ID copied from the log file.

Follow the description in Device Management > Connecting devices in the User guide to register the agent.

In the Device Management application, click “All devices” in the navigator and find the Modbus agent in the device list.

For further information on connecting and managing Modbus devices, refer to Optional services > Cloud Fieldbus in the User guide.

Example: Connecting an OPCUA device

To connect an OPC/UA device in Edge, follow the steps below.

Preparation

Check if the OPC/UA agent is running in Edge (running on port 6670):

$ sudo systemctl status opcua-agent-server

Check if the platform.url in /etc/opcua/opcua-agent-gateway.properties is pointing to the correct URL, which is http://localhost.

Registering the device

Next, you need to register a device in the Device management application with the same device ID as the gateway.identifier in /etc/opcua/opcua-agent-gateway.properties, e.g. “opcua”.

Follow the description in Device Management > Connecting devices in the User guide to register a device.

In the Device Management application, click “All devices” in the navigator and find the opcua device in the device list.

For further information on managing and configuring OPCUA devices, refer to Optional services > Cloud Fieldbus in the User guide.

Connecting to the Cloud

Cumulocity IoT Edge provides the option to upload Edge data to a Cumulocity Cloud account selectively (note that you first need to create a Cloud account).

You can share the following data:

  • devices (and more generically, managed objects)
  • events
  • alarms
  • measurements
  • operations

Navigate to "Data connectors" if you would like to send data to the Cloud account.

Navigate to "Data subscriptions" in your cloud account to receive the data from Edge.

Data broker menus

In the same way, you can push operations from a Cumulocity Cloud account to Edge devices.

For details on sending and receiving data in Cumulocity refer to Using the Data Broker in the User guide.

Realtime analytics using Apama

Introduction

You can add your own real-time analytics to Cumulocity IoT Edge using the Apama Event Processing Language.

Apama is a complete CEP platform. It contains a complex event processing engine and a comprehensive set of tools to develop, integrate, and deploy event-driven applications.

With Apama you can

  • monitor rapidly moving channels of events from multiple sources
  • detect and analyze events and event patterns of interest
  • respond to them in real time

For further information refer to the Apama guide or see the topic Developing Apama Applications in EPL in the Apama documentation for full details.

Uploading a custom Apama CEP rule

In Cumulocity, users can configure their own custom rules bases on their business needs. These custom rule files can be uploaded to the platform which in turn is injected as a monitor in Apama.

The following example shows how to upload a custom mon file to Cumulocity.

  1. First create a custom mon file, as shown in our example for measurements. This sample custom rule creates an alarm for every measurement of type “c8y_SpeedMeasurement” where the “speed” value goes beyond 600.
    using com.apama.cumulocity.Measurement;
    using com.apama.cumulocity.Event;
    using com.apama.cumulocity.Alarm;

    monitor SampleMonitor {

    action onload {        
        monitor.subscribe(Measurement.CHANNEL);
        on all Measurement() as measurement {

            Event newEvent := new Event;
            newEvent.source := measurement.source;
            newEvent.type := "Event in Edge 9.0.x";
            newEvent.time := currentTime;
            newEvent.text := "test custom smart rule using apama CEP - in Edge 9.0.x";
            newEvent.params["First_String"] := "Execute the plan discussed";
            newEvent.params["Second_String"] := "Some kmat Random key-value param";
            send newEvent to "CumulocityIoT";

            if measurement.measurements.getOrDefault("c8y_SpeedMeasurement").getOrDefault("speed").value > 600.0 {
                send Alarm("", "My_Alarm_MAJOR_Version_1", measurement.source, currentTime, 
                            " Test in Edge 9.0.x MAJOR Alarm", "ACTIVE", "MAJOR", 
                            1, new dictionary<string, any>) to Alarm.CHANNEL;
            } else {
                send Alarm("", "My_KMAT_Alarm_Minor_Version_1", measurement.source, currentTime, 
                            "Test in Edge 9.0.x Alarm MINOR", "ACTIVE", "MINOR", 
                            1, new dictionary<string, any>) to Alarm.CHANNEL;
            }

        }
    }

    }
  1. In the Administration application, open the Own Applications page from the navigator. Click “Add application and in the upcoming window click Upload custom Apama rule.

  2. Upload the Apama monitor file (.mon) previously created. After successful upload your rule will be deployed as a custom Apama application.

  3. In the Own Applications page, you can now open your custom Apama application with type “Apama CEP rule”.

Monitoring alarms and events

In the Cockpit application, select the device sending measurements in the Groups menu in the navigator and switch to its Alarms tab (since the custom rule written was such that it creates alarms).

In the Device Management application, click All devices in the navigator. Select the device from the device list and switch to the Events tab, to see the events sent by Apama as per the custom CEP rule.