Connecting Edge to the cloud

Take a look at how to configure and manage your Cumulocity IoT Edge appliance remotely.

Configuring remote connectivity using the UI

  1. Log in to the Management tenant.

    • Username: management/<username>
    • Password: password provided during the installation
  2. Switch to the Administration application using the application switcher at the right of the top bar Application switcher.

  3. Click Edge > Remote Connectivity in the navigator.

  4. Switch the Enable remote connectivity toggle to enable remote-connectivity.

  5. Provide the URL of the Cumulocity IoT cloud tenant in the Remote tenant URL field.

  6. Click Save.

Next steps: Note down the Edge device ID and register your Edge appliance in the Cumulocity IoT cloud tenant.

Configuring remote connectivity using the REST APIs

To configure remote connectivity using the REST APIs, see the edge/configuration/remote-connectivity API in the Cumulocity IoT Edge OpenAPI Specification.

Registering the Edge appliance in the Cumulocity IoT tenant

Before performing these steps, ensure that you have configured the URL for the Cumulocity IoT cloud tenant in the Edge appliance.

  1. Log in to your Cumulocity IoT tenant.

  2. Go to the Device Management application.

  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.

  6. Click Next.

  7. Click Complete to register your Edge appliance.
    After successful registration, the Edge appliance appears in the Device registration page with the status Waiting for connection.
    Turn on the Edge appliance 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 appliance from the Cumulocity IoT tenant

The Cumulocity IoT Cloud Remote Access allows you to remotely access the Edge appliance through a web browser. The remote Edge appliance 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.
  • A Cumulocity IoT tenant subscribed to the Cloud Remote Access microservice. To get the subscription, contact Software AG support.

Supported protocols

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

Important
Starting with Edge Release 10.15, the support for the Telnet protocol has been removed, as Telnet is considered to be an insecure protocol lacking built-in security measures. For accessing the Edge appliance remotely from the Cumulocity IoT tenant, Software AG recommends you to use the SSH protocol instead.

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

Accessing the Edge appliance remotely through VNC

You can access the Edge appliance from the Cumulocity IoT tenant by installing the VNC components on your Edge appliance. Ensure that you have registered your Edge appliance with the Cumulocity IoT tenant. See Registering the Edge appliance in the Cumulocity IoT tenant.

Info
VNC server does not work if SELinux is set to enforcing mode.

Step 1: Installing the VNC components

Info
The Edge appliance must be connected to the internet to install the VNC components.
  1. Run the script vnc-setup.sh.

    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.

  2. After installing the VNC components, log in as a root user and add the vnc-server service to the firewalld firewall. For example, the following commands add the vnc-server to the firewalld with the zone set to public:

    firewall-cmd --zone=public --permanent --add-service=vnc-server

    firewall-cmd --reload

    Info
    These are sample commands and may vary based on your requirements.

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 appliance. The vnc-user-setup.sh script enables the current user to use VNC functionality and set a VNC password for the current user.

  1. Run the script vnc-user-setup.sh.

    /opt/c8y/utilities/vnc-user-setup.sh

  2. Provide and verify the password.

  3. 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 appliance.

    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 appliance using VNC

To access and connect to the Edge appliance:

  1. In the Cumulocity IoT tenant for your registered Edge appliance, add a remote access endpoint. See To add a remote access endpoint via VNC. You must use the same port number that is allocated for you.

  2. Connect to the endpoint. See To connect to an endpoint.

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

Edge VNC
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 appliance.

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.

Accessing the Edge appliance remotely through SSH

You can access the Edge appliance from the Cumulocity IoT tenant through SSH.

Info
Ensure that you have registered your Edge appliance with the Cumulocity IoT tenant. See Registering the Edge appliance in the Cumulocity IoT tenant.

To access and connect to the Edge appliance:

  1. In the Cumulocity IoT tenant for your registered Edge appliance, add a remote access endpoint. See To add a remote access endpoint via SSH. If you select the Sign-in method as Username and password, you must enter the operating system’s administrator credentials. By default, the port number should always be 22.

  2. Connect to the endpoint. See To connect to an endpoint.

Restarting Edge remotely

The Cumulocity IoT tenant allows you to remotely restart your Edge appliance. To do so:

  1. Log in to your Cumulocity IoT tenant.

  2. Go to the Device Management application.

  3. Click Devices > All devices in the navigator.

  4. Select the Edge appliance that you want to restart.

  5. Click Restart device.

    Remote restart

Updating Edge remotely

You can remotely update your Edge appliance using the Cumulocity IoT’s firmware update feature. This process requires you to upload the Edge archive file (tar.gz) to your tenant account or a server (you must provide the location of the archive on that server). For more information about the firmware feature, see Managing firmware.

Important
The Edge archive file size is about 3GB. If your tenant account has a limitation for uploading files with size over 1GB, contact Software AG support to increase the maximum file size for upload.

Before you update your Edge appliance remotely, you must:

To remotely update your Edge appliance:

  1. Log in to your Cumulocity IoT tenant account.

  2. Go to the Device Management application.

  3. Click Firmware repository in the Management menu in the navigator.

    Firmware list

  4. Click Add firmware at the right of the top menu bar.

  5. Provide a name for the firmware, add a description and its version (all required).

  6. Optionally, you can define the device type filter when adding a new firmware. For example, c8y_EdgeAgent.

  7. Select the Provide a file path option to specify an HTTPS URL of a server from where the archive file can be downloaded.

  8. Click Add firmware. The firmware object appears in the firmware list.

  9. Click All devices in the Devices menu in the navigator, select your Edge appliance from the device list.

  10. Click Firmware. The Firmware tab shows the current Edge appliance version.

    Edge current version

    You can also see the current Edge appliance version in the Info tab.

    Edge version info tab

  11. Click Replace firmware.

  12. Select the firmware that you just uploaded and click Install. Edge firmware selection

    • To check the status of the update, hover over the refresh icon as shown in the figure below: Edge update status
    • To check the details of the update, click the text outlined in red in the figure below: Edge update log
  13. Restart your Edge appliance after the firmware update is complete. You can remotely restart your Edge appliance from your tenant account as shown in the figure below: Edge update restart

Updating Edge appliances using bulk operations

In your tenant account, you can update multiple Edge appliances using the bulk operations feature. To do so, follow the steps below:

  1. Log in to your Cumulocity IoT tenant account.

  2. Go to the Device Management application.

  3. Click Device control in the Overviews menu in the navigator. Edge bulk operation

  4. Click Bulk operations and then click New bulk operation. New bulk operation

  5. Click Firmware update. Edge bulk firmware update

  6. Select a firmware from the list. The list can be filtered by firmware name. Click Next.

  7. Expand the version and select the archive file. Click Next. Edge bulk firmware selection

  8. Select the Edge appliances that you want to update by applying filters to the paginated list of all devices.

    You can filter by status, name, type, model, group, registration date and alarms. You may apply multiple filters. To apply a filter, click the column header, make your filter option choices in the context menu and click Apply. Edge bulk operation filter

  9. Enter a new title or use the preset title. Optionally enter a description. Select a start date and a delay. The delay may either be in seconds or milliseconds and is the time spent between each single operation of the bulk operation. Click Schedule bulk operation to create the bulk operation. Edge schedule bulk operation

For more information about bulk operations, see Working with operations.

Downloading diagnostics remotely

The Cumulocity IoT tenant allows you to download the diagnostics report remotely from your tenant account after you have registered your Edge appliance in the tenant account.

To download the diagnostics report from your tenant account:

  1. Log in to your Cumulocity IoT tenant.

  2. Go to the Device Management application.

  3. Click Devices > All devices in the navigator.

  4. Select the Edge appliance for which you want to download the diagnostics report.

  5. Click Diagnostics > Request diagnostic file.

    Diagnostics report remotely

  6. Click the ZIP file link to download the diagnostic report.

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.

Important
Data broker and Edge connectivity are compatible only with the current version and previous two releases of Cumulocity IoT. Cumulocity IoT has a release every three months.

You can share the following data with the tenant account:

  • Devices (and more generically, managed objects)
  • Events
  • Alarms
  • Measurements
Important
Data broker in 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 Data connectors.

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

  1. In your Edge appliance, log in to the “edge” tenant.

  2. In your Edge appliance, go to the Administration application. Click Data broker > Data connectors.

  3. Click Add data connector and provide all the information and filters. See To add a data connector.

    Note down the security code. This security code will be used to subscribe the connector in the tenant account.

  4. Log in to the Cumulocity IoT tenant account.

  5. 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 Data subscriptions.

    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 Using the data broker.