Supported Edge Protocols

Losant’s Gateway Edge Agent (GEA) gives you the ability to read and write to common edge protocols within a local area network.

The GEA has first-class support for the following protocols:

• MQTT
• HTTP
• Serial
• UDP
• Modbus
• OPC UA
• Allen Bradley
• BACnet
• SNMP
• Siemens S7
• Beckhoff

Because the GEA is extendable and runs as a Docker container, multiple other protocols can be supported through custom programs or containers, such as:

• BLE
• CAN bus
• And many more

How to Use

For each supported protocol, in order to read and write to devices, Edge Workflows are required.

Reading Data Using Local Protocol

In most use cases that leverage a local protocol, you can build an Edge Workflow that reads a local protocol on a timer and reports data to Losant.

The following steps detail how to develop a workflow using a timer, Modbus Read Node, and Device State node to report state of a Modbus Enabled PLC to the Losant Cloud:

1. Drag the Timer Node onto the workflow canvas. This enables you to trigger a read on a recurring basis.
2. Connect a Modbus: Read Node (or the local protocol node of choice) to the Timer Node. This enables you to read the local protocol.
3. Connect a Device: State Node to the Modbus: Read Node. This enables you report the data from the local device to the cloud as state.

Writing Data Using Local Protocol

Edge Workflows can be triggered by Device Commands. Using Device Commands, from an Application Workflow or an Experience Workflow, you can trigger a Device Command to perform a write to the local protocol of your choosing.

The following is an example of using a device command to write to Modbus:

To build an Edge Workflow that listens for a command to trigger a local Modbus Write, you can perform the following steps:

1. Drag the Device: Command Trigger onto the workflow canvas. This enables the workflow to listen for device commands.
2. Connect a Switch Node to the Device: Command Trigger. This enables you to configure different commands for your device.
3. Define the name of your command as a case of the Switch Node
4. Connect a Modbus: Write Node (or the local protocol node of choice).

You may find a full step by step example here: How to Trigger a Modbus Write from an Input Control Block.

Exposing Network and Ports

Protocols like MQTT, HTTP, etc. require you to give the Docker container proper network access to your devices. This generally can be accomplished in two ways:

• You can use the -p flag to expose the necessary ports. For example, you can use -p 8080:80 to map TCP port 8080 on the Docker host to port 80 in the container. Example:

docker run -d --restart always \
      -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:80 \
      losant/edge-agent

• You can also use the Docker host network by passing --network host to the run command. This parameter allows the container’s network stack to be not be isolated from the Docker host and networking namespace. (Some nodes, such as the UDP Send Node and BACnet: Who-Is Nodes, may require starting the container in host mode.) For more, see Docker Network documentation.

Supported Protocols

MQTT

The GEA exposes a local MQTT broker to be used for local machine-to-machine (M2M) communication, or to trigger Edge Workflows using the MQTT Trigger to process and forward sensor data to the cloud. In addition, the GEA can be an MQTT client, connecting to arbitrary brokers as defined in user configuration.

Local Broker Configuration

To configure the local MQTT broker, you can set the following parameters in your GEA configuration file.

[localBroker]
# If the local broker should be enabled - CLI: --local-broker-enabled, EnvVar: LOCAL_BROKER_ENABLED
# enabled = false

# Port to run the local broker on - CLI: --local-broker-port, EnvVar: LOCAL_BROKER_PORT
# port = 1883

# Address to run the local broker on - CLI: --local-broker-address, EnvVar: LOCAL_BROKER_ADDRESS
# address = '0.0.0.0'

# Username for the local broker - CLI: --local-broker-username, EnvVar: LOCAL_BROKER_USERNAME
# username = ''

# Password for the local broker - CLI: --local-broker-password, EnvVar: LOCAL_BROKER_PASSWORD
# password = ''

[localBroker.ssl]
# NOTE 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, EnvVar: LOCAL_BROKER_SSL_KEY_PATH
# Key can also be provided directly using the EnvVar LOCAL_BROKER_SSL_KEY
# keyPath = ''

# Path to the SSL Certificate file to use for the local broker
# CLI: --local-broker-ssl-cert-path, EnvVar: LOCAL_BROKER_SSL_CERT_PATH
# Certificate can also be provided directly using the EnvVar LOCAL_BROKER_SSL_CERT
# certificatePath = ''

# Path to the SSL Bundle file to use for the local broker
# CLI: --local-broker-ssl-bundle-path, EnvVar: LOCAL_BROKER_SSL_BUNDLE_PATH
# Bundle can also be provided directly using the EnvVar LOCAL_BROKER_SSL_BUNDLE
# bundlePath = ''

You must use the -p flag to expose the necessary ports. For example, you can use -p 1883:1883 to map port 1883 on the Docker host to port 1883 in the container. Example:

docker run -d --restart always \
      -v /var/lib/losant-edge-agent/data:/data \
      -v /var/lib/losant-edge-agent/config.toml:/etc/losant/losant-edge-agent-config.toml \
      -p 1883:1883 \
      losant/edge-agent

MQTT Client Configuration

The GEA always creates an MQTT connection to the Losant broker, but in addition, the agent can be configured to connect to other brokers as well. It can subscribe and publish to topics on those brokers using the MQTT Trigger and the MQTT Output nodes. To configure connections to additional brokers, one of the following sections should be added to your GEA configuration file for each broker that you would like to connect to:

[[triggers]]

# A unique name that you provide for this MQTT client configuration.
# This is required. This value will be what you reference in
# MQTT Trigger and MQTT Output Node configuration.
name = 'myMqttTriggerConfig'

# The type of this trigger configuration. This is required.
# For MQTT client configuration, this should always be the value 'mqttClient'.
type = 'mqttClient'

# Address of the broker to connect to. This is required.
host = 'broker.example.com'

# The protocol to use to connect to the broker.
# Valid options are 'mqtts', 'mqtt', 'wss', and 'ws'.
# Will default to 'mqtt' when not provided.
# protocol = 'mqtt'

# Port on the broker to connect to. The default port will change depending on
# the selected protocol.
# port = 1883

# Username to use to authenticate with the broker.
# If not provided, the agent will attempt to connect without authentication.
# username = 'myUser'

# Password to use to authenticate with the broker.
# If not provided, the agent will attempt to connect without authentication.
# password = 'myPassword'

# MQTT client ID to use to connect with the broker.
# If not provided, the agent will use the client ID 'losant_<DEVICE_ID>'.
# clientId = 'myClientId'

# MQTT protocol version, the option is only available for external brokers.
# Protocol version can either be 3.1.1 (default) or 5.
# protocolVersion = '3.1.1'

# If when connecting, the client should set the Clean Session flag.
# Default is true.
# clean = true

# If the agent should accept an invalid SSL Certificate from the broker
# when connecting over a secure protocol. Default is false.
# disableSSLVerification = false

# If the broker uses client certificate based auth, a client SSL key and
# certificate can be provided. If an SSL key is provided, an SSL certificate
# is also required, and vice versa. A path to the key and certificate can
# be provided, or the actual key and certificate can be placed directly
# in this configuration.
#
# clientSsl.keyPath = '' # the path to the key file
# clientSsl.key = '' # OR the key itself
#
# clientSsl.certificatePath = '' # the path to the certificate file
# clientSsl.certificate = '' # OR the certificate itself

# If the broker uses a custom SSL certificate signed by a non-standard CA,
# the CA certificate can be provided. A path to the certificate can be
# provided, or the actual certificate can be placed directly in
# this configuration.
#
# caCertificate = '' # the path to the certificate file
# caCertificatePath '' # OR the certificate itself

# The array of topics to subscribe to on this broker.
# By default, no topics will be subscribed to.
# Does support wildcard topics.
# subscriptions = ['my/first/topic/#', 'my/second/topic/#']

MQTT Resources:

• GEA Local Broker Documentation
• MQTT Trigger
• MQTT Output Node

HTTP

The GEA exposes a local HTTP web server to be used for local machine-to-machine (M2M) communication, or to trigger Edge Workflows using the HTTP Request Trigger.

[webserver]
# If webserver should be enabled - CLI: --webserver-enabled, EnvVar: WEBSERVER_ENABLED
# enabled = true

# Port to run webserver on - CLI: --webserver-port, EnvVar: WEBSERVER_PORT
# port = 8080

# Address to run webserver on - CLI: --webserver-address, EnvVar: WEBSERVER_ADDRESS
# address = '0.0.0.0'

# Basic auth username for webserver - CLI: --webserver-username, EnvVar: WEBSERVER_USERNAME
# username = ''

# Basic auth password for webserver - CLI: --webserver-password, EnvVar: WEBSERVER_PASSWORD
# password = ''

[webserver.ssl]
# NOTE 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 webserver
# CLI: --webserver-ssl-key-path, EnvVar: WEBSERVER_SSL_KEY_PATH
# Key can also be provided directly using the EnvVar WEBSERVER_SSL_KEY
# keyPath = ''

# Path to the SSL Certificate file to use for the webserver
# CLI: --webserver-ssl-cert-path, EnvVar: WEBSERVER_SSL_CERT_PATH
# Certificate can also be provided directly using the EnvVar WEBSERVER_SSL_CERT
# certificatePath = ''

# Path to the SSL Bundle file to use for the webserver
# CLI: --webserver-ssl-bundle-path, EnvVar: WEBSERVER_SSL_BUNDLE_PATH
# Bundle can also be provided directly using the EnvVar WEBSERVER_SSL_BUNDLE
# bundlePath = ''

To implement “Routing” using the Switch Node to branch the workflow on data.path, which is the value of the URL Path.

You must use the -p flag to expose the necessary ports. For example, you can use -p 80:8080 to map port 80 on the Docker host to port 8080 in the container. Example:

docker run -d --restart always \
      -v /var/lib/losant-edge-agent/data:/data \
      -v /var/lib/losant-edge-agent/config.toml:/etc/losant/losant-edge-agent-config.toml \
      -p 80:8080 \
      losant/edge-agent

HTTP Resources:

• HTTP Request Trigger
• HTTP Data Node

Serial

Serial is a popular southbound communication option for many IoT sensors and peripherals.

Serial Configuration

Gaining access to serial devices across the Gateway Edge Agent’s Docker boundary involves navigating some of the more complex areas of Linux and Docker permissions. For help, see: How to Access Serial Devices in Docker.

Serial Resources

• Serial Trigger: Triggers a workflow whenever the Edge Compute device receives data via Serial.
• Serial Write Node: Allows you to write to a specified serial port. How to Access Serial Devices in Docker

UDP

UDP (User Datagram Protocol) is a communications protocol that is primarily used for establishing low-latency and loss-tolerating connections between applications and devices on the internet.

UDP Configuration

[udp]
# Address for UDP server - CLI: --udp-address, EnvVar: UDP_ADDRESS
# address = '0.0.0.0'

You must use the -p flag to expose the necessary ports. For example, you can use -p 6350:220/udp to map UDP port 6350 on the Docker host to port 220 in the container. Example:

docker run -d --restart always \
    -v /var/lib/losant-edge-agent/data:/data \
    -v /var/lib/losant-edge-agent/config.toml:/etc/losant/losant-edge-agent-config.toml \
    -p 6350:220/udp \
    losant/edge-agent

UDP Resources

• Docker Documentation: Published Ports
• UDP Trigger
• UDP Send Node

Modbus

The agent allows you to read and write multiple registers from Modbus-enabled devices via TCP or Serial RTU. For more information on the Modbus Protocol, refer to the Modbus documentation.

Modbus Configuration

• Modbus TCP: See Exposing Network and Ports.
• Modbus RTU: See Serial Configuration.

Modbus Resources

• How to Access Serial Devices in Docker ( Modbus RTU )
• Edge Compute Walkthrough
• How to Trigger a Modbus Write from an Input Control Block

OPC UA

OPC Unified Architecture (OPC UA) is a machine to machine communication protocol for industrial automation. Losant OPC UA Trigger, Browse, Read, and Write nodes are designed to enable the data that exists in the PLC to be sent to the cloud.

To configure, see Exposing Network and Ports.

OPC UA Resources

• Remote Monitoring And Control Using OPC UA With The Losant IoT Platform
• OPC UA Trigger
• OPC UA Browse Node
• OPC UA Read Node
• OPC UA Write Node

Allen-Bradley

Allen-Bradley is the brand name of a line of factory automation equipment, today owned by Rockwell Automation. The Allen-Bradley Read and Write nodes are designed to enable the data that exists in the PLC to be sent to the cloud.

To configure, see Exposing Network and Ports.

Allen-Bradley Resources

• Video: Remote Monitoring and Control of Allen-Bradley PLC Control Systems with the Losant IoT Platform
• Remote Monitoring and Control of Allen-Bradley PLC Control Systems with the Losant IoT Platform

BACnet

BACnet is a standard protocol for interacting with a number of building management systems, including HVAC systems, elevators and escalators, security systems, etc. The BACnet: Who-Is, BACnet: Read and BACnet: Write Nodes give you the ability to discover, record, and command building control systems.

To configure, see Exposing Network and Ports.

SNMP

Simple Network Management Protocol (SNMP) is a standard protocol used mostly for communication between routers, servers, computers, and peripherals (such as printers) on a local network. Losant supports all three major versions of the protocol in the SNMP: Get Subtree, SNMP: Read, and SNMP: Write Nodes.

To configure, see Exposing Network and Ports.

Siemens S7

S7 is a Siemens proprietary protocol used for interacting with the S7 family of PLCs. The Siemens S7: Read and Siemens S7: Write Nodes give you the ability to read and write values in databases stored on the PLC.

Beckhoff

Beckhoff Automation has a proprietary protocol for communicating with their suite of PLCs. The Beckhoff: Read Node and Beckhoff: Write Node allow for reading and writing values on the PLC, and the Beckhoff Trigger can fire a workflow whenever a monitored value changes.