1. Edge Xpert Getting Started

Edge Xpert is IOTech’s commercial implementation of the Linux Foundation’s EdgeX Foundry open platform for Industrial IoT Edge Computing. Edge Xpert is based on the latest stable release of EdgeX Foundry open source code base which is then enhanced, productized and supported by IOTech. This approach minimizes any risk of open source adoption and is key to users deploying in mission and business critical industrial systems.

1.1. Downloading Edge Xpert

Edge Xpert is distributed as a Virtual Appliance in the form of an OVA file that can be downloaded from http://www.iotechsys.com/downloads.

An OVA file is a virtual appliance used by virtualization applications such as VMware Workstation and Oracle VM Virtualbox. It is a package that contains files used to describe a virtual machine, which includes an .OVF descriptor file, optional manifest (.MF) and certificate files, and other related files.

The Virtual Appliance provides a convenient environment for the evaluation and use of the Edge Xpert platform. The VM is a Debian-based Linux distribution with a desktop environment that has Edge Xpert already installed and ready to use. It also provides installations of other tools that are likely to be of use, e.g. Portainer, ModbusPal and Postman.

1.2. Importing Edge Xpert Virtual Appliance into VirtualBox

The following section describes how to install Edge Xpert for use with Oracle’s VirtualBox VM player.

Step 1

From the Oracle Virtualbox manager select File -> Import Appliance and then browse to the Edge Xpert OVA file (EdgeX-0.8.ova), then select Next to import the VM

_images/EdgeXpert_GettingStartedImportVM.png

Step 2

To start the VM select the Edge Xpert VM (shown as EdgeX) and click on the Start arrow

_images/EdgeXpert_GettingStartedVM.png

Step 2

Login into the VM with the following username and password:

username: edgex
password: EdgeX
_images/EdgeXpert_GettingStartedLogin.png

You will now be logged into the Edge Xpert VM (Debian Linux guest operating system).

1.3. Installing VirtualBox Guest Additions

It is recommended that you install VirtualBox Guest Additions. VirtualBox Guest Additions consist of device drivers and system applications that optimize the operating system for better performance and usability. The capability to change the display resolution is especially useful here.

Step 1

Select the Edge Xpert VM (shown as EdgeX) and click on the Settings icon.

_images/EdgeXpert_GettingStartedVM.png

Step 2

In General Settings select Storage

Step 3

Click on Controller:IDE and select the empty CD.

_images/EdgeXpert_GettingStartedInstallGuestAdditions.png

Step 4

Then from the Optical Drive drop down browse to the VBoxGuestAdditions.iso file and click OK.

Step 5

Start the VM and you will see the Guest Additions CD icon on the VM desktop.

_images/EdgeXpert_GettingStartedGuestAdditionsCDInstalled.png

Step 6

Open a terminal issue the following commands:

$ sudo bash
$ cd /media/cdrom
$ sh ./VBoxLinuxAdditions.run
_images/EdgeXpert_GettingStartedGuestAdditionsInstaller.png

Step 6

Once installed you can configure the display resolution (recommended 1920 x 950).

Select System -> Preferences -> Hardware -> Displays

_images/EdgeXpert_GettingStartedSettingDisplayResolution.png

1.4. Deploying Edge Xpert

The EdgeX architecture is comprised of a set of microservices deployed as Docker containers. The EdgeX documentation describes the docker and docker-compose commands required to manage the microservices, however Edge Xpert simplifies this even further by way of a convenience script named edge.sh. The edge.sh script can more easily control the EdgeX system and provides the following commands:

up - creates and starts containers for the EdgeX microservices. The up command allows optional services by to be created and started with a set of flags:

--consul
--logging
--ui
--mqtt
--modbus
--bacnet
--bacnet-server
--opc-ua
--virtual
--scheduler

down - stops the EdgeX microservices and removes the containers, network and volumes.

start - starts existing containers for the EdgeX microservices.

stops - stops the EdgeX microservices containers.

status - shows the current status of the microservices.

ip - shows the IP addresses of the running microservices.

pull - updates the microservice images.

The services provided are shown in the table below.

Name Description Optional
data Core Data Stores events sourced from south side devices No
metadata Core Metadata microservice stores metadata relating to devices No
commands Core Command microservice controls requests from north side to south side No
export client Export services registration client No
export distro Export services distribution service No
consul The Consul Registry and Configuration microservice Yes
logging The Logging Microservice Yes
scheduler The Scheduling Microservice can be used to clean up event and reading data Yes
ui The Edge Xpert Manager service Yes
mqtt The MQTT Device Service Yes
modbus The Modbus Device Service Yes
bacnet The BACnet Device Service Yes
bacnet-server Run the BACnet Stack open source BACnet Server Yes
opc-ua The OPC-UA Device Service Yes
virtual The Virtual Device Service Yes

1.5. Starting and Stopping Edge Xpert

To use the edgex.sh script, start a terminal and change directory to the edgexpert directory:

$ cd ~/edgexpert

Get the latest version of the Edge Xpert microservice images provided by IoTech, by using the pull command:

$ ./edgex.sh pull

To create and start the microservices use the up command. If only the required services are to be started, pass no additional parameters:

$ ./edgex.sh up

Creating network "edgexpert_edgex-network" with driver "bridge"
Creating volume "edgexpert_db-data" with default driver
Creating volume "edgexpert_log-data" with default driver
Creating volume "edgexpert_consul-config" with default driver
Creating volume "edgexpert_consul-data" with default driver
Creating edgex-files ... done
Creating edgex-mongo ... done
Creating edgex-core-data ... done
Creating edgex-core-metadata ... done
Creating edgex-core-command ... done
Creating edgex-export-client ... done
Creating edgex-export-distro ... done

To verify that the microservices are running use the status command:

$ ./edgex.sh status

Name                      Command               State                         Ports
----------------------------------------------------------------------------------------------------------------
edgex-core-command    /core-command --consul=fal ...   Up       0.0.0.0:48082->48082/tcp
edgex-core-data       /core-data --consul=false  ...   Up       0.0.0.0:48080->48080/tcp, 0.0.0.0:5563->5563/tcp
edgex-core-metadata   /core-metadata --consul=fa ...   Up       0.0.0.0:48081->48081/tcp
edgex-export-client   /export-client --consul=fa ...   Up       0.0.0.0:48071->48071/tcp
edgex-export-distro   /export-distro --consul=fa ...   Up       0.0.0.0:48070->48070/tcp
edgex-files           /bin/sh                          Exit 0
edgex-mongo           docker-entrypoint.sh /bin/ ...   Up       0.0.0.0:27017->27017/tcp

To stop and remove the all of the microservices use the down command:

$ ./edgex.sh down

Stopping edgex-export-distro ... done
Stopping edgex-export-client ... done
Stopping edgex-core-command  ... done
Stopping edgex-core-metadata ... done
Stopping edgex-core-data     ... done
Stopping edgex-mongo         ... done
Removing edgex-export-distro ... done
Removing edgex-export-client ... done
Removing edgex-core-command  ... done
Removing edgex-core-metadata ... done
Removing edgex-core-data     ... done
Removing edgex-mongo         ... done
Removing edgex-files         ... done
Removing network edgexpert_edgex-network
edgexpert_consul-config
edgexpert_consul-data
edgexpert_db-data
edgexpert_log-data

Once running, there are a number of ways in which to configure and interact with Edge Xpert. For example, a native HTTP client such as Postman could be used to send and receive requests to and from the services. In addition, IOTech have provided a graphical tool named Edge Xpert Manager that can simplify this process further. Where possible, it is recommended to use the Edge Xpert Manager tool which is documented at Edge Xpert Manager