# Edge Configuration

In order to be able to send telemetry, and/or get your ABB Ability™ Edge configured with your modules, your Edge must connect to the ABB Ability™ Platform. There are multiple instances of the ABB Ability™ Platform deployed in various regions for different clients, so you need to make sure to point your Edge to the correct one for your needs. This procedure covers the configuration of any Edge device using any Certificate Authority.

The following information should be available to complete the configuration:

Access to an ABB Ability™ Platform Admin Portal
Proper configuration of an Ability Solution that will allow devices to be registered.
Installed the matching Edge software for the Platform the Edge will connect to.

ONE TIME SETUP

The official ABB Ability™ Edge Setup tool is not reentrant. This means that you can run it only once on every Edge. In order to change the parameters of your ABB Ability™ Edge device, you have to reinstall the environment after clearing the TPM.

# Prerequisites

An Edge module must have a type registered in the type definition registry.
An Edge's abb.ability.device type must include references to all modules permitted to run on it under the 'modules' reference definition.
An Edge module must be published as a docker image in a registry accessible from the Edge (the build should be based on Ability-provided base images whenever possible).
An Edge module must have an associated entry created in the Admin Portal, matching the common name of the device's certificate.
All Edge module communication to/from the cloud must be performed using MQTT broker. Only intranet access is allowed from the module. Modules can also communicate with each other using predefined MQTT topics (see the 'Send messages to another module' section, below).

# Just Show Me the Commands (TL;DR)

Prepare your platform by uploading all the type definitions necessary to run the Edge.
Edit /etc/dpcm.config to configure the correct certificate authority, certificate signing request subject templates (PKI_CERTIFICATE_OU, PKI_CERTIFICATE_O) and other required parameters (IDServiceURL, REGISTER_DEV_ID, DEVICEID_DUPLICATION_CHECK_REQUIRED) according to instructions in comments.
Edit /var/ability/config/edge.env updating at least DEVICE_ID, EDGEPROXYIMAGE, EDGE_TYPE and DPS_SCOPE_ID.
Run installer and wait until it's done (observe output)
```
sudo abb-iot-edge-setup
```
Once successful, copy the DEVICE_ID and register the Edge in the appropriate tenant using the Ability Admin Portal.

Start edge proxy service

sudo systemctl enable --now abb-iot-edge

Wait for the Edge to finish provisioning.

You can monitor the progress using:
```
journalctl --unit abb-iot-edge.service --follow -n 20
```
Verify edge-proxy service is running
```
docker service ls
```

# Load Edge Type into Your Platform Instance

Before you can run an Edge, an Edge type must be loaded. Several Edge examples are available but custom types can be loaded if available. To simplify this effort, the following example types are available and can be used if a custom type is not available.

Example Modules

Once the EDGE_TYPE is defined in the ABB Ability™ Platform instance, the Edge can be configured and started.

# Connecting Edge to the Platform

Before You Begin

If working on the ABB corporate network, make sure to configure your VM to use a proxy server.

# Overview of the Process

Your ABB Ability™ Edge device needs to be provisioned with a correct ABB Ability™ Platform instance. It needs to know which Device Provisioning Service (DPS) instance it should talk to in order to be connected with the correct IoT Hub.

On the ABB Ability™ Edge device a DPCM (Device Provisioning and Configuration Module) takes care of the provisioning process that involves:

Creating a unique device ID - As part of the setup process, you will have to generate a Device ID as a random UUIDv4 value that is globally unique across all instances of the ABB Ability™ Platform. DPCM verifies that it is not taken by any other ABB Ability™ device using the Global ID Generator REST Service.
Obtaining the identity certificate (X.509) - DPCM talks to the configured Certificate Authority (CA) SCEP endpoint to obtain and authenticate the CA's certificate and enroll the device to the CA. After this step your ABB Ability™ Edge gets its own X.509 certificate with its Device ID set as a Common Name in the certificate's Distinguished Name (Subject) field. ABB Ability™ devices use this certificate to authenticate with DPS's & IoT Hubs. As an outcome of this step, you'll see a Certificate Signing Request, private key and device certificate PEM files in a location specified in /etc/dpcm.config.
Enrolling to the DPS - DPCM uses the Device Provisioning Service of your ABB Ability™ Platform to have a correct IoT Hub assigned after authenticating to the service. As an outcome of this step, there will be a new device record added to the respective IoT Hub's device registry.
Starting edge-proxy - After all the above steps are completed, we will start the edge-proxy service to allow this ABB Ability™ Edge orchestration and communication component to take over the management of your device.

# Using the SSH Command Line Client (Linux, Mac, Windows) or Other Clients

TIP

Windows users may need to install the OpenSSH command line client by installing the Git for Windows package and use Git bash for their terminal emulator.

Open your default console emulator/terminal and type:

ssh <username>@<edge-hostname-or-ip-addr>

to connect as an <username> user to the host <edge-hostname-or-ip-addr>. To specify an SSH port number (default is 22), use the -p argument.

If you're running Ability Edge SDK virtual machine on Oracle VirtualBox, by default Edge's SSH port is redirected to your localhost:2222, so connecting via SSH as an ability user (default SDK username) would look like:

ssh ability@localhost -p 2222

# Set a Global Identity Generator URL

Use your favorite text editor (e.g. GNU nano) to edit DPCM configuration file at /etc/dpcm.config.
Find a line that starts with IDServiceURL and put in the correct Global ID Generator (GIG) Service URL.
Save the file. (in nano editor, press CTRL+X then Enter)

# Configure Certificate Authority

Five parameters in the /etc/dpcm.config file are required to connect to a certificate authority.

Use your favorite text editor (e.g. Nano) to open the DPCM configuration file at /etc/dpcm.config.
```
$ sudo nano /etc/dpcm.config
```

Use the correct settings for the certificate authority desired.

Example: Using ABB Ability™ PKI Development Profile

PKI_RA_SERVER_ADDRESS=https://ptnr-pki-scep.bbtest.net/scep/2.16.840.1.113733.1.16.1.3.1.4.1.127290527/cgi-bin/pkiclient.exe
PKI_RA_SERVER_PORT=443
PKI_CA_AUTH_HASH=1F7620B115DE521F1D71AD2ADF7D8FE1
PKI_ENROLL_PASWD=c7Gyh7BjSHwBDsZM

Make sure that all required parameters are configured properly (see comments in the file for explanations). In most cases you'll want to set at least PKI_CERTIFICATE_OU, PKI_CERTIFICATE_O, IDServiceURL, REGISTER_DEV_ID, DEVICEID_DUPLICATION_CHECK_REQUIRED
Save the file. (in nano editor, press CTRL+X then Enter)

# Set EDGE_TYPE, EDGEPROXYIMAGE, and DPS_SCOPE_ID

Use your favorite text editor (e.g., Nano) to open the Edge configuration file at /var/ability/config/edge.env.
```
$ sudo nano /var/ability/config/edge.env
```

Find a line that starts with EDGE_TYPE and put your desired Edge device's type definition after the equals sign.

...
# Information model type definition. Must be already registered in the corresponding type registry
EDGE_TYPE=abb.ability.device.edge.sample@2
...

Find a line that starts with EDGEPROXYIMAGE. Update the value to use the latest version supported for this version of the ABB Ability™ Platform
```
...
 # Docker related settings
 EDGEPROXYIMAGE=abbability.azurecr.io/edge/proxy:2.4.15
...
```
DEPRECIATION

EDGEMQTTIMAGE is no longer used and the line can be ignored.
Find a line that starts with DPS_SCOPE_ID and put the correct scope ID after the equals sign
```
# This is an example value only
DPS_SCOPE_ID=0neXXXXXXX
```
Find a line that starts with DEVICE_ID and put the Device ID after the equals sign. Use uuidgen or uuid command to generate a UUID (a.k.a. GUID).
```
# This is an example value only
DEVICE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```
Save the file. (in nano editor, press CTRL+X then Enter)

# Run the Installer

Run the official ABB Ability™ Edge framework installer script to finish the installation process.

For additional validation, use the following command to view and confirm the certtificate downloaded. Look for Not Before and Not After dates.

$ sudo openssl x509 -text -noout -in /var/ability/certs/edgedevice-cert.pem

:::

Wait for the script to finish. Observe the output on your console to make sure there were no critical errors during the execution. As part of the execution, your Device ID is printed in the console.
From the Admin Portal, go to the Solutions zone and select the solution Name from the list on the left. Click the corresponding eye icon in the Actions column on the right to view the solution.
Select the Devices tab and click the New Device button.
Copy the device ID generated by the console log in step 3 and paste it into the Device field in the Create Device popup.
Select a Tenant from the drop-down list.
Select the Identity Provider (registered certificate) from the drop-down list.
Click Save. The device will now appear in the list of named devices.
After registering the device, enable and start edge-proxy service to connect your Edge to the Ability Platform instance.
```
sudo systemctl enable --now abb-iot-edge
```
Check the logs of the abb-iot-edge service to make sure the provisioning process is finished ande device connected to the IoT Hub succesfully.

# To see all previous logs of the abb-iot-edge service
$ journalctl --unit abb-iot-edge.service
# To get a live view of new logs and 20 historical lines
$ journalctl --unit abb-iot-edge.service --follow -n 20
# You can return to your shell by pressing CTRL+C

Verify that edge-proxy service is working (1 of 1 replicas running)

docker service ls

# Next Steps

If you selected one of the provided CSharp tutorials, your ABB Ability™ Edge is running one or all of the tutorials. Navigate here to learn what the tutorial module or modules are doing. It is also possible to modify the tutorials, build a new container and deploy the updated container to this Edge or another Edge. See creating a custom module.

← Edge Upgrade Edge Configurator Tool →