Connecting Edge to the cloud

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 .

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.

   

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:

• 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

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.

Step 1: Installing 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.

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.

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.

   

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.

Before you update your Edge appliance remotely, you must:

• Enable the remote-connectivity feature in your Edge appliance
• Register your Edge appliance in your Cumulocity IoT tenant account

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.

   

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.

    

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

    

11. Click Replace firmware.

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

    • To check the status of the update, hover over the refresh icon as shown in the figure below:
    • To check the details of the update, click the text outlined in red in the figure below:

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:

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.

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

5. Click 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.

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.

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.

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.

   

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.

You can share the following data with the tenant account:

• Devices (and more generically, managed objects)
• Events
• Alarms
• Measurements

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.