Remote connectivity

This section describes configuring and managing your 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 icon.

  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 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 tenant.

Configuring remote connectivity using the REST APIs

To configure remote-connectivity, use the following endpoints:

Registering the Edge appliance in the Cumulocity IoT tenant

Before performing these steps, ensure that you have configured the URL for the Cumulocity IoT 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:

Supported protocols

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

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.

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

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

  1. Run the script vnc-setup.sh.

    [admin@iot-edge-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 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.

    [admin@iot-edge-server ~]$ /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 Adding remote access endpoints. You must use the same port number that is allocated for you.

  2. Connect to the endpoint. See Connecting to endpoints.

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. x

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 Adding remote access endpoints. You must use the same port number that is allocated for you.

  2. Connect to the endpoint. See Connecting to endpoints.

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.

    General device registration

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 Device Management > Managing device data > Managing device firmware in the User guide.

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 version

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

    Edge version

  11. Click Replace firmware.

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

    • To check the status of the update, hover over the refresh icon as shown in the figure below: Edge version
    • To check the details of the update, click the text outlined in red in the figure below: Edge version
  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 version

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 version

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

  5. Click Firmware update. Edge version

  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 version

  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 version

  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 version

For more information about bulk operations, see Device Management > Monitoring and controlling devices > Working with operations in the User guide.

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:

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:

  1. In your Edge applaince, log in to the edge tenant.

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

    Data broker menus
  3. 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.

  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 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 in the User guide.