EdgeX Integration

Edge Xpert is built using the Linux Foundation's open-source EdgeX Foundry platform and remains compatible to the base open-source EdgeX APIs. This compatibility to the EdgeX APIs allows users the option to run the Edge Xpert Device Services alongside the open-source EdgeX Foundry services, if desired.

This section describes the steps the user should take to integrate and run the Edge Xpert Device Services alongside the open source EdgeX Foundry services.

Compatibility

General compatibility of the Edge Xpert Device Services to EdgeX Foundry is represented by matching major version numbers. For example, version 2.3 of the Edge Xpert Device Services implies compatibility with all editions of EdgeX version 2.

Note that some advanced features of the Edge Xpert Device Services may require specific functionality to be available in the EdgeX Core Services. For example, automatic discovery in the BACnet and OPC-UA Device Services requires automatic discovery capability that was only added to EdgeX Foundry version 3.0.

Installation

Edge Xpert should be installed as normal by following the installation instructions here. Note that this process will install the Device Service docker-compose entries and example files that are described below on to the host machine.

Licensing

The Edge Xpert Device Services require a license file in order to be run. Instructions for licensing any of the Edge Xpert services with the edgexpert command line utility can be found in the licensing instructions here. However a license file can also be installed by the following native commands:

docker volume create license-data
docker create -v license-data:/lic --name license-add alpine:3.17
docker cp <license name> license-add:/lic
docker rm license-add

Replace <license name> above with the name of your license.

Configuration

The Edge Xpert Device Services that are required to run should simply be added to the base EdgeX Foundry docker-compose file.

A base EdgeX Foundry docker-compose file for EdgeX 2.1 (Jakarta), for example, can be created using the edgex-compose repository as follows:

git clone --branch jakarta https://github.com/edgexfoundry/edgex-compose.git

As described next, the instructions then vary slightly depending on whether EdgeX security is enabled and which internal EdgeX message bus (Redis Pub/Sub or MQTT) is selected for use:

Non-Secure Mode

Redis Pub/Sub

Use the following command to generate a basic EdgeX docker-compose that specifies no security and sets Redis Pub/Sub as the internal message bus. Note Redis Pub/Sub is the default so does not need to be explicitly specified:

cd edgex-compose/compose-builder 
make gen no-secty 

For each Device Service that is intended to be ran, copy the specific service entry from the full service list at /etc/edgexpert/edgex/device-services/non-secure/redis-pubsub/docker-compose.yml into the above generated docker-compose file.

MQTT

Use the following command to generate a basic EdgeX docker-compose that specifies no security and sets MQTT as the internal message bus:

cd edgex-compose/compose-builder 
make gen no-secty mqtt-bus

For each Device Service that is intended to be ran, copy the specific service entry from the full service list at /etc/edgexpert/edgex/device-services/non-secure/mqtt/docker-compose.yml into the above generated docker-compose file.

Secure Mode

Redis Pub/Sub

Use the following command to generate a basic EdgeX docker-compose that specifies security and sets Redis Pub/Sub as the internal message bus. Note both security and Redis Pub/Sub are the default options so do not need to be explicitly specified:

cd edgex-compose/compose-builder 
make gen 

For each Device Service that is intended to be ran, copy the specific service entry from the full service list at /etc/edgexpert/edgex/device-services/secure/redis-pubsub/docker-compose.yml into the above generated docker-compose file.

MQTT

Use the following command to generate a basic EdgeX docker-compose that specifies security and sets MQTT as the internal message bus. Note that security is the default option so does not need to be explicitly specified:

cd edgex-compose/compose-builder 
make gen mqtt-bus

For each Device Service that is intended to be ran, copy the specific service entry from the full service list at /etc/edgexpert/edgex/device-services/secure/mqtt/docker-compose.yml into the above generated docker-compose file.

services:
  secretstore-setup:
    environment:
      ADD_SECRETSTORE_TOKENS: device-modbus,device-bacnet-ip,device-opc-ua
      ADD_KNOWN_SECRETS: redisdb[device-modbus],redisdb[device-bacnet-ip],redisdb[device-opc-ua]
  consul:
    environment:
      ADD_REGISTRY_ACL_ROLES: device-modbus,device-bacnet-ip,device-opc-ua

services:
  proxy-setup:
    environment:
      ADD_PROXY_ROUTE: >-
        device-modbus.http://device-modbus:59901,
        device-bacnet-ip.http://device-bacnet-ip:59980,
        device-opc-ua.http://device-opc-ua:59953

Docker Volumes

Find the volumes section at the end of the docker-compose file and add a named volumes for each Device Service and one for the license volume. This example adds volumes for Modbus, BACnet and OPC-UA:

volumes: 
  ... 
  device-modbus-data: {} 
  device-bacnet-ip-data: {} 
  device-opc-ua-data: {} 
  license-data: 
    external: true

Running the services

From the same directory as your docker-compose file, start EdgeX Foundry and the selected Edge Xpert device services with the following command:

docker-compose up -d

Once the services are running, the Device Services should now operate as normal. Refer to the regular Device Service documentation for more details.

Each of the Device Services is provided with an example that describes device onboarding via the EdgeX REST APIs. For example, see the example for Modbus, BACnet, OPC-UA, etc.