Losant’s Gateway Edge Agent (GEA) is a command-line utility exposed through Docker as a container that you run on your Edge Compute device(s). To get the Edge Agent running on your device, follow along with the video below.
For help getting the Docker and GEA installed on your device, see the installation instructions. All command examples below assume you can run
sudo or that you are logged in as
root (not recommended). If you wish to run
docker as your current user, see these instructions.
It is strongly recommended to create a bind mount from the device’s file system into the Gateway Edge Agent as a workspace for persistent data at the container’s
/data directory. By doing so, you have access to the data created by the GEA on your host machine and can reuse it if you have to destroy the agent’s container (for instance, when upgrading the image).
Creating a bind mount is simple: All we need to do is create a folder locally to house the data and then tell Docker to reference that directory at our path within the container. This folder can be anywhere on your file system, so long as permissions are set so
docker can write to it. For instance …
- Create a directory on your host machine at the path of your choosing. This can be done with the following command:
sudo mkdir -p /var/lib/losant-edge-agent/data
- Set the permission level of the directory in such a way that the
dockeruser can read and write to it. The following command changes the permission so all users can do so:
sudo chmod -R a+rwx /var/lib/losant-edge-agent
- When starting the container, use the
-vargument to mount this directory into the container at its
/datadirectory. The second line of this Docker command illustrates how:
docker run -d --restart always --name docs-agent \ -v /var/lib/losant-edge-agent/data:/data \ losant/edge-agent
This directory stores the following data:
- Edge Workflows: The workflows deployed to the device from the cloud. Storing these outside of the agent container allows these workflows to begin executing on the device as soon as a new container starts up. Not mounting a volume requires an Internet connection (so the device can receive its workflows from the MQTT broker) before the flows can execute in a new container.
- Workflow storage: Data persisted across workflow executions using the Storage: Set Value Node, and accessed using the Storage: Get Value Node. Failing to store this data in a mounted volume means the values will be lost and will revert to their defaults when the container is destroyed.
- Buffered messages: Device state and custom MQTT topic messages to be sent to the Losant MQTT Broker. The GEA stores these messages when the device loses its Internet connection so that they can be sent up when the connection is re-established. These messages would be lost on removal of the container if a mounted volume is not used.
- Files: Arbitrary files created or modified using the File: Write Node. The files can be written to any volume mounted into the container. If a volume is not mounted, then these files are written within the container itself and are lost when the container is destroyed.
Losant’s Gateway Edge Agent has many configuration options, many of which can be set with a TOML-formatted configuration file. In addition to using a configuration file for this example, we’re also going to configure the GEA to log to a file. See the section below for a full example configuration file.
Let’s create a configuration file in the directory we created earlier. Here’s our
/var/lib/losant-edge-agent/config.toml file. The
touch command is being used to create the config file, and
nano to edit the newly created file.
touch /var/lib/losant-edge-agent/config.toml sudo nano /var/lib/losant-edge-agent/config.toml
[logger] level = 'error' [gateway] id = '<your-device-id>' key = '<your-access-key>' secret = '<your-access-secret>' [store] path = '/data/losant-edge-agent-store.db'
Now we can run the GEA container without specifying environment variables, and instead simply provide the path to our
docker run -d --restart always --name docs-agent \ -v /var/lib/losant-edge-agent/data:/data \ -v /var/lib/losant-edge-agent/config.toml:/etc/losant/losant-edge-agent-config.toml \ losant/edge-agent
/etc/losant/losant-edge-agent-config.toml is the default location for the
toml configuration file inside the container, so we mount our local configuration to that location in the container. Now that our GEA container is running, we can see the output by watching the log file we specified with
$ tail -f /var/lib/losant-edge-agent/data/losant-edge-agent-log.log 0000-00-00T00:00:00.000Z [info] Agent Starting... 0000-00-00T00:00:00.000Z [info] Connecting to: mqtts://broker.losant.com... 0000-00-00T00:00:00.000Z [info] Webserver started on port: 8080 0000-00-00T00:00:00.000Z [info] Workflows initialized and running... 0000-00-00T00:00:00.000Z [info] Connected to mqtts://broker.losant.com
Because we have designated a configuration file and configured our GEA container to read from it, making changes are easy. Let’s say we decide that
error logging is not enough logging and we want to see more logging information. We can simply modify our
/var/lib/losant-edge-agent/config.toml like so:
# ... [logger] level = 'info' # ...
In the above change to the configuration file, the logger level is set to
info. You can change this value to other levels such as
error to help with troubleshooting, but
error is recommended for production scenarios.
You can optionally add an
out destination, which allows you to choose where the log output is sent as seen in GEA Configuration Options. (Note: If your
out destination is a file path, you may fill up your device’s disk space with log files.) Without an
out destination, the log output is recognized by Docker and allows you to view the Gateway Edge Agent’s logs with
docker logs <container-name> command.
Then restart the Gateway Edge Agent to have the GEA pick up our new configuration changes.
docker restart docs-agent
A configuration file may contain a list of unique Edge Workflow trigger configurations. If the trigger supports this feature, it will have the option to select Agent Config File as the Configuration Type.
Configuration file triggers are supported in Gateway Edge Agent versions 1.40.0 or higher.
Each trigger type will require the same fields that are required by the Edge Workflow trigger of the same type. Minimally, these require a
type and a unique
[[triggers]] name = 'opcuaTrig2' type = 'opcua'
Triggers may contain their own list of fields, as in the case of OPCUA monitoredItems:
[[triggers]] name = 'opcuaTrig2' type = 'opcua' uri = 'opc.tcp://localhost:4335/UA/Server' eventFilter = ['Value'] [[triggers.monitoredItems]] identifier = 'i=2254' [[triggers.monitoredItems]] identifier = 'i=2255'
If you wish to enable the HTTP Request Trigger for your Edge Compute device, you can do so by binding a host port at the time of container creation. In order to build on the configuration we have going, we only need to add the
-p flag and then configure the Gateway Edge Agent to enable the trigger. See exposing ports with Docker for more information. See below for more advanced configuration of the HTTP Request Trigger and HTTP Response Node.
docker run -d --restart always --name docs-agent \ -v /var/lib/losant-edge-agent/data:/data \ -v /var/lib/losant-edge-agent/config.toml:/etc/losant/losant-edge-agent-config.toml \ -p 8080:8080 \ losant/edge-agent
# ... [webserver] enabled = true
There are only three required environment variables that must be set to connect the Gateway Edge Agent to Losant, which allows for bidirectional communication between the platform and your device. You must provide the
DEVICE_ID obtained when you created your Edge Compute device, as well as the
ACCESS_SECRET associated with your application.
docker run -d --restart always --name docs-agent \ -e 'DEVICE_ID=<your-device-id>' \ -e 'ACCESS_KEY=<your-access-key>' \ -e 'ACCESS_SECRET=<your-access-secret>' \ -v /var/lib/losant-edge-agent/data:/data \ losant/edge-agent
Let’s break this down a little bit …
- By specifying the
docker run, we are asking the Gateway Edge Agent to run in the background so we have control of our terminal after executing the command.
--restart alwaysoption tells Docker to always restart the container if it were to die unexpectedly or on device boot. This aids in keeping your Edge Compute device up and running with minimal intervention.
--nameoption allows us to name our container so that we may stop and start it more easily in the future.
-eallows us to enumerate any and all environment variables we would like to pass in as configuration.
docker runthat we would like to mount our host folder
/datainside the container.
- Finally, specifying an image (
losant/edge-agent) without a tag, we are asking for the
latesttag of the GEA. It is recommended that you select a version -
Before we move on to more advanced ways of configuring the GEA, let’s quickly talk about how to manage it once it’s running. If you’re familiar with Docker, you can skip this section.
In general, the
docker --help information is very useful for familiarizing yourself with the commands. Below, we’re going to cover some basic management commands (a few of which we’ve already started using). Let’s recap those plus some additional ones that should allow you to get up and running for basic use cases.
docker run [-d] [--restart] [--rm] [--name] [-e] [-v] <image-name> (more info)
This command allows us to configure a container from a base image—in our case,
losant/edge-agent. We’ve talked about most of the above options in this document as we’ve been using the GEA. The only one not mentioned elsewhere is the
--rm flag, which will tell Docker to destroy the container after it has been stopped/killed. This is useful as you work to figure out your final configuration. There are, of course, many more flags you can use with
docker logs [-f] <container-name|container-id> (more info)
This command allows us to look at the console output of the GEA after it has been started and is running. Unless you are writing your logs to a file, this is the primary way you’ll get a glimpse into what the GEA has been doing.
docker ps -a (more info)
This command will output all containers that have been created on your host whether they are running or not. This is useful for getting the ID of the container running the Gateway Edge Agent after it has been started. It is also useful for getting the container ID of a stopped container so that you may restart it.
docker stop <container-name|container-id> (more info)
You can stop a GEA container that is running in the background using the
stop command. This will simply stop the container, but not destroy it. All your environment configuration and any other flags used when running
docker run will be preserved when starting again.
docker kill <container-name|container-id> (more info)
If the GEA container isn’t responding to a
container stop command, you may need to
kill the container. This will forcefully exit the container and could cause unexpected behavior on future runs of the Gateway Edge Agent.
docker start <container-name|container-id> (more info)
After stopping a container, you can restart it using the
start command. This will preserve all configuration that was entered when running
docker restart <container-name|container-id> (more info)
Instead of running
docker stop and then
docker start, you can simply run
docker rm <container-name|container-id> (more info)
It’s a good practice to name your containers on your Edge Compute device to prevent many containers being created and taking up space on your device. Because of this practice, you’ll need to remove your container before creating another with the same name. Or, you can create a container with a different name as you determine the best way to run the Gateway Edge Agent on your device.
With these basic
docker commands, we can manage our running GEA container. Note, this example shows how to remove a container and will destroy the container we have running permanently. You would need to create another container from the image if you do so.
$ docker logs docs-agent 0000-00-00T00:00:00.000Z [info] Agent Starting... 0000-00-00T00:00:00.000Z [info] Connecting to: mqtts://broker.losant.com... 0000-00-00T00:00:00.000Z [info] Webserver started on port: 8080 0000-00-00T00:00:00.000Z [info] Workflows initialized and running... 0000-00-00T00:00:00.000Z [info] Connected to mqtts://broker.losant.com $ docker ps -a CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 51aff3e4b650 losant/edge-agent:latest "/opt/losant/tini -g..." 30 minutes ago Up 5 minutes 8080/tcp docs-agent $ docker stop docs-agent docs-agent $ docker start docs-agent docs-agent $ docker kill docs-agent docs-agent $ docker ps -a CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 51aff3e4b650 losant/edge-agent:latest "/opt/losant/tini -g..." 31 minutes ago Exited docs-agent $ docker rm docs-agent docs-agent $ docker ps -a CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
Updating the Gateway Edge Agent to the latest version is accomplished through a series of
docker stop <container-name|container-id> docker rm <container-name|container-id> docker pull losant/edge-agent:<version of edge agent> docker run …
With the following steps, the old container will be removed and replaced with a new container running the latest version of the Gateway Edge Agent. Note that if
sudo is being used to pull, it should be used consistently to avoid unexpected behavior.
When you create an Edge Workflow, you specify a target agent version. Edge Workflows can only run on devices running that specified target GEA version or higher. The GEA is always backward compatible.
After you update the GEA image, you will need to update your Edge Workflows to the proper target agent version in order to take advantage of the new features. Upgrading your target agent version is easily accomplished within the Agent Version tab in the Workflow Settings Panel.
The GEA can be used with compatible Windows machines that have Docker installed. For more info on installing Docker on Windows, please see our documentation here.
The Docker CLI can be invoked using a variety of command-line tools. In the examples below, we’re using Windows Command Prompt (
cmd). These examples also assume that the local user account executing these commands will be the same user account running Docker and the GEA container.
First, let’s create a storage area on our host machine to use as a bind mount. This can be any directory. For this example, we’re going to create a new folder called “docker-data” in our user home directory (e.g.
C:\Users\your-username\) using the
%USERPROFILE% environment variable:
Now we’ll create a TOML configuration file…
type nul > %USERPROFILE%\docker-data\config.toml
…And open it with Notepad:
Enter in the configuration file options you want to include. In this example, we’re going to include the desired level of logging, the GEA device access key details, and the path to the persistent GEA store:
[logger] level = 'error' [gateway] id = '<your-device-id>' key = '<your-access-key>' secret = '<your-access-secret>' [store] path = '/data/losant-edge-agent-store.db'
Voila! Now we can run our GEA container:
cd %USERPROFILE%\docker-data \ docker run -d --restart always --name losant-edge-agent ^ -v %cd%:/data -v %cd%\config.toml:/etc/losant/losant-edge-agent-config.toml ^ losant/edge-agent
As seen above, you can configure the GEA with the following options. Most of the following options can be set through:
- Command-line flags.
- Environment variables (most common for Docker).
- Configuration file.
If an option is set multiple ways, the command line flag is used first, followed by the environment variable, and then finally falling back to the configuration file.
|Environment Variable||Configuration File Option||Command Line Flag|
# Losant Gateway Edge Agent Configuration File # # Configuration file location can be configured when running # the agent by either the command line flag --conf-path or the # environment variable CONF_PATH # # Any configuration variables that are commented out # below have defaults or are not required. Many can also be provided # through command line flags or environment variables. # [logger] # Desired logger output destination # Valid options are 'console' or a file path # CLI: --logger-out # Environment Variable: LOGGER_OUT # # out = 'console' # # Desired level of logging # Valid options are 'error', 'warn', 'info', 'verbose' # CLI: --logger-level # Environment Variable: LOGGER_LEVEL # # level = 'info' # [gateway] # Losant Device ID of Edge Compute device # CLI: --device-id # Environment Variable: DEVICE_ID # id = '' # # Losant Access Key for connecting the device to the MQTT broker # CLI: --access-key # Environment Variable: ACCESS_KEY # key = '' # # Losant Access Secret for connecting the device to the MQTT broker # CLI: --access-secret # Environment Variable: ACCESS_SECRET # secret = '' # # If the GEA, when it is not connected to Losant, should queue up MQTT messages to # then send later when the agent does successfully connect # CLI: --queue-offline-messages # Environment Variable: QUEUE_OFFLINE_MESSAGES # # queueOfflineMessages = true # # When the agent reconnects to Losant and queueOfflineMessages is true, the order in # which any queued offline messages should be sent # Valid options are 'oldestFirst', and 'newestFirst' # CLI: --offline-message-replay-order # Environment Variable: OFFLINE_MESSAGE_REPLAY_ORDER # # offlineMessageReplayOrder = 'oldestFirst' # # If the GEA, when it is not connected to Losant, should subscribe to # peripheral device information, for use by the Peripheral: Get Node # Valid options are true, false, 'floating', and 'peripheral' # CLI: --subscribe-to-peripheral-updates # Environment Variable: SUBSCRIBE_TO_PERIPHERAL_UPDATES # # subscribeToPeripheralUpdates = true # # Address of the Losant broker # Environment Variable: BROKER_HOST # # host = 'broker.losant.com' # # Protocol to use to connect to the broker # Valid options are 'mqtts', 'mqtt', 'wss', and 'ws' # Environment Variable: BROKER_PROTOCOL # # protocol = 'mqtts' # [gateway.clientSsl] # If an SSL key is provided, an SSL certificate is also required, and vice versa. # If provided, the key and secret fields above are not required. # # Path to the SSL key file to use for client certificate based authentication # Environment Variable: BROKER_CLIENT_SSL_KEY_PATH (path to the key file) # Environment Variable: BROKER_CLIENT_SSL_KEY (the key itself) # # keyPath = '' # # Path to the SSL certificate file to use for client certificate based authentication # Environment Variable: BROKER_CLIENT_SSL_CERT_PATH (path to the certificate file) # Environment Variable: BROKER_CLIENT_SSL_CERT (the certificate itself) # # certificatePath = '' # [store] # Path to the GEA persistent store # CLI: --store-path # Environment Variable: STORE_PATH # # path = './losant-edge-agent-store.db' # [udp] # Address for UDP server # CLI: --udp-address # Environment Variable: UDP_ADDRESS # # address = '0.0.0.0' # [webserver] # Whether the web server should be enabled # CLI: --webserver-enabled # Environment Variable: WEBSERVER_ENABLED # # enabled = true # # Port to run web server on # CLI: --webserver-port # Environment Variable: WEBSERVER_PORT # # port = 8080 # # Address to run web server on # CLI: --webserver-address # Environment Variable: WEBSERVER_ADDRESS # # address = '0.0.0.0' # # Basic auth username for web server # CLI: --webserver-username # Environment Variable: WEBSERVER_USERNAME # # username = '' # # Basic auth password for web server # CLI: --webserver-password # Environment Variable: WEBSERVER_PASSWORD # # password = '' # [webserver.ssl] # If an SSL key is provided, an SSL certificate is # also required, and vice versa. An SSL bundle is optional. # # Path to the SSL key file to use for the web server # CLI: --webserver-ssl-key-path # Environment Variable: WEBSERVER_SSL_KEY_PATH (path to the key file) # Environment Variable: WEBSERVER_SSL_KEY (the key itself) # # keyPath = '' # # Path to the SSL certificate file to use for the web server # CLI: --webserver-ssl-cert-path # Environment Variable: WEBSERVER_SSL_CERT_PATH (path to the certificate file) # Environment Variable: WEBSERVER_SSL_CERT (the certificate itself) # # certificatePath = '' # # Path to the SSL Bundle file to use for the web server # CLI: --webserver-ssl-bundle-path # Environment Variable: WEBSERVER_SSL_BUNDLE_PATH (path to the bundle file) # Environment Variable: WEBSERVER_SSL_BUNDLE (the bundle itself) # # bundlePath = '' # [workflow] # The directory containing on-disk workflows # CLI: --workflow-directory # Environment Variable: WORKFLOW_DIRECTORY # # directory = '/data/workflows' # [localBroker] # Whether the local broker should be enabled # CLI: --local-broker-enabled # Environment Variable: LOCAL_BROKER_ENABLED # # enabled = false # # Port to run the local broker on # CLI: --local-broker-port # Environment Variable: LOCAL_BROKER_PORT # # port = 1883 # # Address to run the local broker on # CLI: --local-broker-address # Environment Variable: LOCAL_BROKER_ADDRESS # # address = '0.0.0.0' # # Username for the local broker # CLI: --local-broker-username # Environment Variable: LOCAL_BROKER_USERNAME # # username = '' # # Password for the local broker # CLI: --local-broker-password # Environment Variable: LOCAL_BROKER_PASSWORD # # password = '' # [localBroker.ssl] # If an SSL key is provided, an SSL certificate is # also required, and vice versa. An SSL bundle is optional. # # Path to the SSL key file to use for the local broker # CLI: --local-broker-ssl-key-path # Environment Variable: LOCAL_BROKER_SSL_KEY_PATH (path to the key file) # Environment Variable: LOCAL_BROKER_SSL_KEY (the key itself) # # keyPath = '' # # Path to the SSL certificate file to use for the local broker # CLI: --local-broker-ssl-cert-path # Environment Variable: LOCAL_BROKER_SSL_CERT_PATH (path to the certificate file) # Environment Variable: LOCAL_BROKER_SSL_CERT (the certificate itself) # # certificatePath = '' # # Path to the SSL Bundle file to use for the local broker # CLI: --local-broker-ssl-bundle-path # Environment Variable: LOCAL_BROKER_SSL_BUNDLE_PATH (path to the bundle file) # Environment Variable: LOCAL_BROKER_SSL_BUNDLE (the bundle itself) # # bundlePath = '' # # [[triggers]] # Array of trigger configs which can configure an Edge Workflow trigger # Minimally, these require a type and a unique name. # # Example OPCUA Trigger Configuration: # # [[triggers]] # name = 'opcuaTrig1' # type = 'opcua' # uri = 'opc.tcp://localhost:4335/UA/Server' # samplingInterval = '10' # eventFilter = ['Message', 'Value'] # # [[triggers.monitoredItems]] # nameSpace = '1' # identifier = 's=MyVar3' # # [[triggers.monitoredItems]] # identifier = 'i=2255' # # Example MQTT Client (External Broker) Trigger Configuration: # # [[triggers]] # name = 'mqttTrig1' # type = 'mqttClient' # protocol = 'mqtts' # host = 'myexample.broker.com' # username = 'myUser' # password = 'myPassword' # clientId = 'myClientId' # subscriptions = ['my/first/topic/#', 'my/second/topic/#']
The following are exposed only as environment variables, and meant for advanced control of the Gateway Edge Agent’s behavior:
MAX_FLOW_RUN_TIME- Controls the maximum amount of time, in milliseconds, a single workflow is allowed to run. Default value is
MAX_EXTERNAL_CALL_TIME- Controls the maximum amount of time, in milliseconds, a workflow will wait for a response from an external service. Default value is
BROKER_HOST- Controls the address of the MQTT broker for the GEA to connect to. Default value is
BROKER_PROTOCOL- Controls if the connection to the broker should be TCP vs WebSockets, and if it should be over SSL or not. Default is
mqtts. Valid values are
MQTT_CONNECT_TIMEOUT- Controls the timeout when attempting to connect to the MQTT broker. Default value is
30000(30 seconds). Minimum value is
MQTT_KEEPALIVE- Controls the keepalive for the MQTT connection to the MQTT broker, in milliseconds. Default value is
60000(1 minute). A value of
0will disable keepalive.
MQTT_RECONNECT_INTERVAL- Controls the base interval at which the MQTT connection will try to reconnect to the MQTT broker. Default value is
30000(30 seconds). Minimum value is
5000(5 seconds). This will not be the actual reconnect interval; see
MQTT_RECONNECT_VARIABILITY- Controls variability against the base reconnection interval. This is used to define the possible range of reconnect times around
MQTT_RECONNECT_INTERVAL, in which a random value will be chosen. Default value is
15000(15 seconds), minimum value is
5000(5 seconds). This means that by default, a reconnect will be attempted in the window of 15 to 45 seconds after a disconnection.
STATS_REPORT_TIME- Controls how frequently the GEA reports workflow statistics to the Losant cloud, in milliseconds. Default is
BROADCAST_UPDATE_TOPIC_BASE- Controls the MQTT topic base for broadcast updates from the Losant cloud to the Gateway Edge Agent. Default is
IDLE_OPCUA_SESSION_TTL- Controls how long until an unused OPC UA session is considered idle. Default is 30000 (30 seconds).
IDLE_OPCUA_CLIENT_TTL- Controls how long until an unused OPC UA client is considered idle. Default is 60000 (60 seconds).
IDLE_OPCUA_CLEANUP_INTERVAL- Controls how frequently the GEA cleans up idle OPC UA clients and sessions. Default is 10000 (10 seconds).
RAW_FUNCTION_STARTUP_TIMEOUT- Controls how long to allow a raw function background worker to take to become ready. Default is 2x the
RAW_FUNCTION_MEM_LIMIT_MB- Controls how much memory a raw function background worker is allowed to consume. Default is 128.
RAW_FUNCTION_INSTANCES- Controls how many background workers are created to process raw function nodes. Default is 4.
Was this page helpful?
Still looking for help? You can also search the Losant Forums or submit your question there.