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.

Info: Currently, only the Modbus and OPC/UA protocols are supported.

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 connect a Modbus device

How to check/change the agent state

Use the following command to check if the agent is running in Cumulocity IoT Edge (running on port 6670):

$ systemctl status cumulocity-agent

If the agent is not running, start it with the following command:

$ systemctl start cumulocity-agent

The Modbus agent is pre-registered in the post-installation phase. In the Device Management application, click All devices in the navigator and find the Modbus agent (called “linux-agent”) in the device list.

How to connect Modbus devices

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.

Important: The OPC UA agent is in beta state and not supported.

Preparation

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

$ sudo systemctl status opcua-agent-server

If the agent is not running, start it with the following command:

$ sudo systemctl start 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

Remote Device Management

The Cumulocity tenant allows you to remotely manage your Edge device by registering the Edge device in the tenant account. To do so, you must first configure the Cumulocity tenant account in the Edge agent and then register your Edge device in the tenant account.

To configure the tenant account in your Edge device, run the post-installation script and select Option 7 - Configure Edge Agent. For more information, see Configuring the Edge server.

The Cumulocity tenant uses the SSH protocol to access the remote Edge device through a web browser.

Registering the Edge device with the Cumulocity tenant

Before performing these steps, ensure that you have provided the URL for the Cumulocity tenant in the post-installation procedure.

  1. Log in to your Cumulocity tenant.
  2. Go to Device Management.
  3. Click Registration in the Devices menu and then click Register device.
  4. Select General device registration.

    General device registration

  5. In the Device ID field, enter the Edge device ID. The Edge device ID is available at /usr/edge/properties/edge-agent/device-id in your Edge device.

  6. Click Next.

  7. Click Complete to register your Edge device.
    After successful registration, the Edge device appears in the Device registration page with the status Waiting for connection.
    Turn on the Edge device and wait for the connection to be established. Once the device is connected, the device status changes to Pending acceptance.

  8. Click Accept to confirm the connection. The status of the device changes to Accepted.

Accessing the Edge device from the Cumulocity tenant

The Cumulocity Cloud Remote Access microservice allows you to remotely access the Edge device through a web browser. The remote Edge device is represented as a device in the Device Management application of Cumulocity. For more information about remote access, see Cloud Remote Access.

Info: Currently, only the SSH protocol is supported.

Data exchange using Data Broker

Cumulocity IoT Edge provides the option to upload Edge data to a Cumulocity tenant account selectively. Note that you must first create a Cumulocity tenant account.

You can share the following data:

Go to Data Broker > Data connectors if you would like to send data to the tenant account.

Go to Data Broker > Data subscriptions in your tenant account to receive the data from Edge.

Data broker menus

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

For details about sending and receiving data in Cumulocity, see Enterprise Tenant > Using the Data Broker.