Working with Cumulocity IoT Edge

Important: The tenant in the Edge instance is always named as “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.

DataHub Edge is an optional component of Cumulocity IoT Edge, which can be used for storage and analytics over historical data.

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; how to retrieve configuration data and store and manage it in a configuration repository as 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 IoT 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 IoT 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). Describes each smart rule 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 IoT 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 IoT uses REST and MQTT as protocols for external communication. Both protocols may be used to interface devices with Cumulocity IoT . For more information, see 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. For example, Modbus protocol.
OPC UA protocol. OPC UA protocols support through the OPC UA device gateway and OPC UA management service.

For details on how to integrate devices using Modbus and OPC UA protocols, see Cloud Fieldbus and OPC UA in the Protocol integration 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 primary-replica/client-server communication between devices.

Before you connect a Modbus device, ensure that the agent is running.

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

[admin@server ~]$ systemctl status cumulocity-agent

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

[admin@server ~]$ 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 more information on connecting and managing Modbus devices, see Cloud Fieldbus in the Protocol integration guide.

Example: Connecting an OPCUA device

Important: While configuring the OPC UA server, ensure that the server is reachable from the Edge VM. If you are using a hostname, configure DNS accordingly.

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

Preparation

OPC UA Management service

Check if the OPC UA management service is running in Cumulocity IoT Edge (running on port 8083):

[admin@server ~]$ sudo service opcua-mgmt-service status

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

[admin@server ~]$ sudo service opcua-mgmt-service start

OPC UA Device Gateway

Check if the OPC UA device gateway is running in Cumulocity IoT Edge (running on port 1099):

[admin@server ~]$ sudo service opcua-device-gateway status

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

[admin@server ~]$ sudo service opcua-device-gateway start

Registering the device

Next, you need to register a device in the Device Management application with the name opcua-gateway

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 about managing and configuring OPCUA devices, see OPC UA in the Protocol integration guide.

Connecting to the Cloud

Remote Device Management

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

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

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

Registering the Edge device with the Cumulocity IoT tenant

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

Log in to your Cumulocity IoT tenant.
Go to Device Management.
Click Registration in the Devices menu and then click Register device.
Select General device registration.
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 VM.
Click Next.
Click Complete to register your Edge VM.
After successful registration, the Edge VM appears in the Device registration page with the status Waiting for connection.
Turn on the Edge VM and wait for the connection to be established. Once the device is connected, the device status changes to Pending acceptance.
Click Accept to confirm the connection. The status of the device changes to Accepted.

Accessing the Edge device from the Cumulocity IoT tenant

The Cumulocity IoT Cloud Remote Access microservice allows you to remotely access the Edge VM through a web browser. The remote Edge VM is represented as a device in the Device Management application of Cumulocity IoT.

Prerequisites

To use Cloud Remote Access, you need:

“Remote access” permission granted to the tenant user.
The Cloud Remote Access microservice included into your subscription plan.

Supported protocols

The following protocols are supported to connect to the Edge VM through remote access from the Cumulocity IoT tenant:

Remote Desktop (VNC). See Accessing the Edge device remotely through VNC.
- Shares the desktop of the remote device
- Mouse and keyboard for interaction
Secure Shell (SSH)
- Console for command line access
- Keyboard for interaction
Terminal (Telnet)
- Console for command line access
- Keyboard for interaction

For more information about remote access, see Cloud Remote Access.

Accessing the Edge device remotely through VNC

You can access the Edge VM from the Cumulocity IoT tenant by installing the VNC components on your Edge VM.

Info: Ensure that you have registered your Edge VM with the Cumulocity IoT tenant. See Registering the Edge device with the Cumulocity IoT tenant.

Step 1: Installing the VNC components

Info: The Edge VM must be connected to the internet to install the VNC components.

Run the script vnc-setup.sh.

[admin@server ~]$ sudo /opt/c8y/utilities/vnc-setup.sh

The vnc-setup.sh script installs the VNC components. After installing the VNC components, you should configure the VNC server for each user.

Step 2: Configuring VNC server for a user

To configure the VNC server, run the vnc-user-setup.sh script. Each user should run this script to set up VNC components and be able to connect to the Edge VM. The vnc-user-setup.sh script enables the current user to use VNC functionality and set a VNC password for the current user.

Run the script vnc-user-setup.sh.

[admin@server ~]$ /opt/c8y/utilities/vnc-user-setup.sh
Provide and verify the password.
Select Y or N to enter a view-only password.

Record the allocated port number. This port number will be used to connect to the VNC server on your Edge VM.

Info: You can also get the allocated port number from the /opt/c8y/utilities/vnc-display-mapping file. In this file, you will find the VNC display number allocated for each user. For example, admin:1. You must add 5900 to the number associated with the user. In this example, the port number for the user admin is 5901.

Step 3: Connecting to the Edge VM using VNC

To access and connect to the Edge VM, you must create a remote access point.

In the Cumulocity IoT tenant for your registered Edge VM, add a remote access endpoint. See Adding remote access endpoints. You must use the same port number that is allocated for you.
Connect to the endpoint. See Connecting to endpoints.

The connection to the Edge VM is established and the GUI appears for the Edge VM. Right-click in the screen to open the desktop components xterm and firefox.

Important: Do not use the Send Ctrl+Alt+Del button in the VNC interface. If you do so, you will lose the VNC connection and not be able to reconnect until you restart the Edge VM.

Changing the VNC password

You can change the VNC password for the current user by running the vnc-user-setup.sh script. After changing the password, you must update the password in the remote access endpoint.

Data exchange using data broker

Data broker lets you upload the data to a Cumulocity IoT tenant account selectively. Note that you must first create a Cumulocity IoT tenant account.

You can share the following data with the tenant account:

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

Important: Data broker in Cumulocity IoT Edge does not support synchronization of the operations.

To upload the data to a Cumulocity IoT tenant account, you must first create a data connector in the Edge appliance and subscribe this connector in the tenant account.

A data connector describes the subset of the data that you would like to send to a destination tenant. For more information, see Enterprise Tenant > Using the data broker > Data connector in the User guide.

To create a data connector and upload the data to the tenant account, perform the following steps:

In your Edge appliance, log in to the edge tenant.
In your Edge appliance, go to the Administration application. Click Data broker > Data connectors.
Click Add data connector and provide all the information and filters. See Enterprise Tenant > Using the data broker > Data connector > To add a data connector in the User guide.

Note down the security code. This security code will be used to subscribe the connector in the tenant account.
Log in to the Cumulocity IoT tenant account.
In the tenant account, go to the Administration application. Click Data broker > Data subscriptions to subscribe the connector created in your Edge appliance.

Click Add data subscription and provide the security code. Click Submit and accept the subscription. See Enterprise Tenant > Using the data broker > Data subscriptions in the User guide.

You can now navigate to the Device Management application or the Cockpit application. You will find a new “virtual group” with a specific icon showing the forwarded devices. The group will have the same name as your subscription.

For more information about sending and receiving data in Cumulocity IoT, see Enterprise Tenant > Using the data broker.

Monitoring the Edge metrics

In your Cumulocity IoT tenant, you can monitor the measurements of the Edge VM listed in the table below:

Measurement	Metrics	Description
Disk space	- Total disk space - Free disk space - Used disk space - Percentage of used disk space	The Edge VM sends the disk space metrics as a measurement for both installation disk and data disk, every 10 minutes. The measurements are sent in gigabytes (GB) rounded to two decimal places. The percentage is rounded to one decimal place. The data points for this measurement are: - c8y_InstallationDisk - c8y_DataDisk If Cumulocity IoT Edge is unable to read the metrics from the installation disk or the data disk, an alarm is sent to the Cumulocity IoT tenant. The alarms have a minor severity and the data points for the alarms are: - c8y_FileSystemMeasurementErrorInstallationDisk - c8y_FileSystemMeasurementErrorDataDisk
Memory (RAM)	- Total RAM - Free RAM - Used RAM - Percentage of RAM used	The Edge VM sends the memory usage metrics as a measurement every 5 seconds in gibibytes (GiB). The data point for this measurement is c8y_Memory If Cumulocity IoT Edge is unable to read the metrics from the memory, an alarm is sent to the Cumulocity IoT tenant. The data point for the alarm is: - c8y_MemoryMeasurementError.
CPU	Percentage of CPU used Unit: Percentage	The Edge VM sends the percentage of CPU used at intervals over 5 seconds, 60 seconds, and 600 seconds. The data points for this measurement are: - c8y_CpuUsage5Seconds - c8y_CpuUsage60Seconds - c8y_CpuUsage600Seconds If Cumulocity IoT Edge is unable to read the metrics from the CPU, an alarm is sent to the Cumulocity IoT tenant. The data point for the alarm is: - c8y_CPUMeasurementError.
Disk I/O	- Data read per second - Data written per second Unit: KB/s	The Edge VM sends the disk input/output metrics as a measurement for both installation disk and data disk at intervals over 5 seconds, 60 seconds, and 600 seconds. The data points for this measurement are: - c8y_DataDiskIo5Seconds - c8y_DataDiskIo60Seconds - c8y_DataDiskIo600Seconds - c8y_InstallationDiskIo5Seconds - c8y_InstallationDiskIo60Seconds - c8y_InstallationDiskIo5Seconds If Cumulocity IoT Edge is unable to read the metrics from the disk, an alarm is sent to the Cumulocity IoT tenant. The data point for the alarm is: - c8y_DiskIOMeasurementError.
Network	- Data and packets sent per second - Data and packets received per second Unit: KB/s and packets/s	The Edge VM sends the network metrics as a measurement at intervals over 5 seconds, 60 seconds, and 600 seconds. The data points for this measurement are: - c8y_NetworkInterface_lo-5Seconds - c8y_NetworkInterface_lo-60Seconds - c8y_NetworkInterface_lo-600Seconds If Cumulocity IoT Edge is unable to read the metrics from the network, an alarm is sent to the Cumulocity IoT tenant. The data point for the alarm is: - c8y_NetworkIoMeasurementError.

To monitor the metrics in your Cumulocity IoT tenant, you can create a dashboard and add widgets in the Cockpit application of your tenant. For more information about creating dashboards, see Cockpit > Dashboards in the User guide.

Also, you can define smart rules to create alerts or raise alarms for the metrics. For example, when the free disk space is less than 5 GB, create an alert. For more information about smart rules, see Cockpit > Smart rules in the User guide.

Analytical querying with DataHub Edge

DataHub Edge is an optional component of Cumulocity IoT Edge. DataHub Edge complements the ad-hoc querying of recent device data with analytical querying over long periods of time. For that purpose, data is moved from the Operational Store of Cumulocity IoT Edge to a local data lake, with the data being stored in a concise and query-efficient format. DataHub Edge allows you to run SQL queries against the data lake contents so that you can gain more insights into your device data.

DataHub Edge is the counterpart of DataHub, the variant for cloud deployments. To learn more about DataHub in general, see section DataHub overview. To learn more about DataHub Edge, see section Running DataHub on the Edge.

Microservices

Microservices are server-side applications which may be used to extend the Cumulocity IoT Edge platform with customer-specific functionality. For more information, see Microservices SDK.

To enable or disable the microservice hosting feature, see Enabling or Disabling microservice hosting feature. The Device Simulator microservice is pre-installed with Edge VM and is enabled only if the microservice hosting feature is enabled.

Branding

In Cumulocity IoT Edge, you can customize the appearance of your tenant to your own preferences.

Info: Use the domain name to access the Cumulocity IoT Edge platform to properly apply the branding and see the effects after branding.

To access the branding feature:

Log in to the management tenant as sysadmin user using the domain name.
- Username: management/sysadmin
- Password: Use the sysadmin password.
Switch to the Administration application using the application switcher at the right of the top bar .
Go to Settings > Enterprise Tenant.

For information about branding configuration, see Branding in the User guide.