Edge Xpert Command Line Interface Tool

Edge Xpert provides a command line interface (CLI) tool, named edgexpert, which simplifies the management of the microservices.

The license associated with your download defines what microservices are available for use. For more information on licensing, see Licensing.

Using the edgexpert CLI Tool

The tool can be used by following this format:

edgexpert [–version | <v>] <command> [<args>]

Commands

The commands used by edgexpert are described below, for information on the available Edge Xpert services, see Edge Xpert Services:

Parameter Arguments Description
--help or -h   Displays help on the edgexpert command
--version or -v   Displays the version, the repository and the Git-Sha of the installed Edge Xpert
pull [<options>] [<services>] Download the latest Edge Xpert images. Specifying no options pulls the core service images only. Specifying the --all option pulls updates for all images. Specifying one or more services pulls updates for the specified services only
up [<options>], [<services>] Creates and starts the Edge Xpert services. Starts core services by default. Specifying the --no-core option runs the up command without starting the core. Specifying the --no-consul option runs the up command without starting the consul. The services to create and start must be specified
start [<services>] Starts the stopped services. If no services are specified, starts all created services
restart [<services>] Restart the specified Edge Xpert services. If no services are specified, restarts all running services
run [<service>] [<args>] Creates and runs a one-off service with custom arguments
clean --force or -f Stops and deletes the running Edge Xpert services and removes all Edge Xpert volumes except the license volume
stop [<services>] Stops the Edge Xpert services. If no services are specified, stops all running services
down [<services>] Stops and deletes the running Edge Xpert containers. If no services are specified, stops and deletes all created services
rm [<services>] Deletes the stopped Edge Xpert services
status   Displays the current status of the created and/or running Edge Xpert services
ip   Displays the internet protocol (IP) addresses of the running Edge Xpert services
logs [<services>] -o <output_directory> Exports the logs from created and/or running Edge Xpert services to the specified directory. If no services are specified, outputs all logs to the specified directory
config [<options>] Specifying the validate option validates the current docker-compose configuration. Specifying the view option displays the current docker-compose configuration
license [<options>] Specifying the install option installs the specified licenses to the license volume. Specifying the uninstall option uninstalls the specified license. Specifying the view option lists all currently installed licenses. Specifying the check option validates all installed licenses. Specifying the clean option deletes the license volume;sssssssss the license volume must not be mounted. For more information on licensing, see Licensing

Edge Xpert Services

Services Description
--core-consul The default registry service, Consul. Consul provides health checks and service configuration options
--core-data The centralized persistence facility for data readings colledged by devices and sensors
--core-metadata Stores and manages information about Device Services
--core-command Exposes the commands in a common, normaized way to simplify communications with the devices
--sys-mgmt The system managment service. Currently not supported
--support-logging The logging service. Receives logs from all microservices with remote logging enabled
--support-scheduler The scheduling service. Allows for the creation of schedules to be run at regular intervals
--support-notifications The notification service. Allows for the creation of notifications and subscriptions
--export-distro The export distribution service. Attempts to send the encrypted JSON-formatted event or reading data to the client
--export-client The export client registration service. Registers clients as recipients of data coming from Core Data
--portainer Provides a detailed overview of your Docker environments and allows you to manage your containers, images, networks and volumes
--vault Provides secure, storage and control access to tokens, passwords, certificates and encryption keys for protecting secrets and other sensitive data using a UI, CLI, or HTTP API
--kong KONG is an open-source microservice API gateway and platform. Edge Xpert uses KONG as a component of the API gateway. See also --edgex-proxy
--edgex-proxy Initializes KONG , configures proxy routes, applies certificates to routes and enables authentication and Access Control List (ACL) features
--xpert-manager The Edge Xpert Manager. Starts the Edge Xpert Manager, a user interface provided to support management and provisioning
--redis The Redis database
--influxdb The InfluxDB service runs an Influx database (DB) server. This can be used as an export target to power Grafana
--grafana Runs an instance of Grafana, a data visualization and monitoring platform
--nodered Runs an instance of Node-RED, a flow-based programming platform
--mqtt-broker An MQTT broker (Mosquitto) for use with Edge Xpert
--bacnet-server Runs an example BACnet server. This server is intended as an example target for the device-bacnet-ip service
--gps-daemon Runs the GPS Daemon
--device-mqtt Runs the MQTT Device Service
--device-opc-ua Runs the OPC-UA Device Service
--device-bacnet-ip Runs the bacnet-ip Device Service
--device-bacnet-mstp Runs the bacnet-mstp Device Service
--device-modbus Runs the Modbus Device Service
--device-virtual Runs the device-virtual Device Service. This service is a source of random data and is set up to feed random data to Edge Xpert. This service is ideal for demonstration and testing
--device-grove Runs the device-grove Device Service
--device-file Runs the device-file Device Service
--device-bluetooth Runs the device-bluetooth Device Service
--device-gps Runs the device-gps Device Service
--device-mems Runs the device-mems Device Service
--device-zigbee Runs the device-zigbee Device Service

Using the Tool

The edgexpert tool can be used to control Edge Xpert. The following topics describe common use cases.

Before you start using the commands, you must have the latest version of the Edge Xpert microservice images provided by IOTech. To get the latest version, open a terminal and enter the following command:

edgexpert pull --all

You see the following output:

Pulling core-consul           ... done
Pulling redis                 ... done
Pulling sys-mgmt              ... done
Pulling support-logging       ... done
Pulling core-data             ... done
Pulling export-distro         ... done
Pulling export-client         ... done
Pulling core-metadata         ... done
Pulling support-scheduler     ... done
Pulling support-notifications ... done
Pulling core-command          ... done
Pulling xpert-manager         ... done
Pulling device-opc-ua         ... done
Pulling device-bacnet-ip      ... done
Pulling device-bacnet-mstp    ... done
Pulling device-virtual        ... done
Pulling device-modbus         ... done
Pulling device-grove          ... done
Pulling portainer             ... done
Pulling influxdb              ... done
Pulling grafana               ... done
Pulling nodered               ... done
Pulling mqtt-broker           ... done
Pulling device-mqtt           ... done
Pulling bacnet-server         ... done

You can also pull updates for a single image, for example:

edgexpert pull --device-virtual
Pulling device-virtual ... done

Creating and Starting the Microservices

To create and start the microservices, use the up command.

The following example shows the output when creating and starting the services using the up command with the --xpert-manager and --device-virtual parameters:

edgexpert up --ui --device-virtual
Creating network "edgexpert_edgex-network" with driver "bridge"
Creating volume "edgexpert_db-data" with default driver
Creating volume "edgexpert_consul-data" with default driver
Creating volume "edgexpert_grafana-data" with default driver
Creating volume "edgexpert_nodered-data" with default driver
Creating volume "edgexpert_export-data" with default driver
Creating volume "edgexpert_portainer-data" with default driver
Creating edgex-redis       ... done
Creating edgex-core-consul   ... done
Creating edgex-core-metadata ... done
Creating edgex-core-data     ... done
Creating edgex-export-distro ... done
Creating edgex-core-command  ... done
Creating edgex-export-client  ... done
Creating edgex-device-virtual ... done
Creating xpert-manager        ... done

Creating and Starting a single Microservice

The --no-core option starts only specified microservices.

The following example shows the output when creating and starting only the --nodered microservice:

edgexpert up --no-core --nodered
Creating edgex-nodered ... done

Verifying that the Microservices are Running

To verify that the microservices are running, use the status command.

The following example shows the terminal content when using the status command:

edgexpert status
      Name                      Command               State                                                                 Ports
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
edgex-core-command     /core-command --registry=t ...   Up      0.0.0.0:48082->48082/tcp
edgex-core-consul      docker-entrypoint.sh agent ...   Up      8300/tcp, 8301/tcp, 8301/udp, 8302/tcp, 8302/udp, 0.0.0.0:8400->8400/tcp, 0.0.0.0:8500->8500/tcp, 0.0.0.0:8600->8600/tcp, 8600/udp
edgex-core-data        /core-data --registry=true ...   Up      0.0.0.0:48080->48080/tcp, 0.0.0.0:5563->5563/tcp
edgex-core-metadata    /core-metadata --registry= ...   Up      0.0.0.0:48081->48081/tcp
edgex-device-virtual   /device-virtual --profile= ...   Up      0.0.0.0:49990->49990/tcp
edgex-export-client    /export-client --registry= ...   Up      0.0.0.0:48071->48071/tcp
edgex-export-distro    /export-distro --registry= ...   Up      0.0.0.0:48070->48070/tcp
edgex-redis            redis-server /etc/redis/re ...   Up      0.0.0.0:6379->6379/tcp
xpert-manager          /root/go-ui-server               Up      0.0.0.0:8080->8080/tcp

Stopping the Microservices

There are three key commands that can be used to stop, delete and clean an instance of Edge Xpert.

  • The stop command stops all the running Edge Xpert microservices. All containers remain

  • The down command stops all the running Edge Xpert microservices and deletes all containers

  • The clean command stops all the running Edge Xpert microservices, deletes all containers and deletes any volumes or networks used by Edge Xpert

    Caution

    Deleting the volumes can cause a loss of configuration data, proceed carefully!

The following example shows the terminal content when using the clean command:

edgexpert clean
clean: delete all Edge Xpert data (y/n)? y
Stopping xpert-manager        ... done
Stopping edgex-device-virtual ... done
Stopping edgex-export-client  ... done
Stopping edgex-core-command   ... done
Stopping edgex-export-distro  ... done
Stopping edgex-core-data      ... done
Stopping edgex-core-metadata  ... done
Stopping edgex-core-consul    ... done
Stopping edgex-redis          ... done
Removing xpert-manager        ... done
Removing edgex-device-virtual ... done
Removing edgex-export-client  ... done
Removing edgex-core-command   ... done
Removing edgex-export-distro  ... done
Removing edgex-core-data      ... done
Removing edgex-core-metadata  ... done
Removing edgex-core-consul    ... done
Removing edgex-redis          ... done
Removing network edgexpert_edgex-network
Deleting Volumes:
edgexpert_db-data
edgexpert_consul-data
edgexpert_grafana-data
edgexpert_nodered-data
edgexpert_export-data
edgexpert_portainer-data

Using a Custom docker-compose File

The edgexpert tool is driven by a docker-compose file located at /etc/edgexpert/docker-compose.yml.

If you want to make changes to this configuration, it is best practice to copy this file to a local directory. The local copy is used when running the edgexpert tool in a directory with a docker-compose.yml file. A message displays to indicate that a local file is being used, as shown in the following output:

edgexpert
Using local docker-compose
...

Command Line Help

In addition to this documentation, a summary of the options provided by the edgexpert tool can be shown by using the -h or --help parameters:

edgexpert --help
usage: edgexpert [--version | -v] <command> [<args>]

Edge Xpert Commands:

Manage and Update Services:
  pull     Download the latest Edge Xpert images
  up       Create and start Edge Xpert services
  down     Stop and delete running Edge Xpert services
  clean    Stop and delete running Edge Xpert services and remove volumes
  start    Start Edge Xpert services
  stop     Stop Edge Xpert services
  restart  Restart Edge Xpert services
  rm       Delete stopped Edge Xpert services

Monitor and Inspect Running Services:
  status   View the status of any created/running Edge Xpert services
  ip       View the ip addresses of the running Edge Xpert services
  logs     Export the logs from created/running Edge Xpert services

Manage Configuration and Licensing:
  config   View and validate the docker-compose configuration
  license  Validate license files and manage their use in Edge Xpert

Further help is avaiable, 'edgexpert <command> -h' (or --help).
Documentation: [ file:///usr/share/doc/edgexpert/html/index.html ]

Help is also available for the individual parameters. For example, the following command displays the help for the license parameter:

edgexpert license -h
usage: edgexpert license [<options>] <path/file> [--force | -f]
  Manage your Edge Xpert licenses. Edge Xpert provides license files to its services via a docker volume

Options:
  install     install the specified license/s to the license volume
  uninstall   uninstall the specified license
  view        view all currently installed licenses
  check       check the validity all installed licenses
  clean       delete the license volume (volume must not be mounted)


Further help is avaiable, 'edgexpert <command> -h' (or --help).
Documentation: [ file:///usr/share/doc/edgexpert/html/index.html ]

Using Docker Commands

The EdgeX Foundry documentation describes the docker and docker-compose commands required to manage the services.

For further information on Docker, refer to the Docker documentation.

Using Edge Xpert

Once running, there are several ways in which you can configure and interact with Edge Xpert. For example, you can use a REST client to send and receive requests to and from the services. You can use either command line clients, such as cURL, or graphical client tools, such as Postman, to achieve this.

IOTech also provide a graphical tool, called Edge Xpert Manager, to support you further. Where possible, IOTech recommendeds that you use the Edge Xpert Manager tool. For more information on Edge Xpert Manager, see the Edge Xpert Manager topic.