MQTT Device Service

The Message Queuing Telemetry Transport (MQTT) Device Service enables Edge Xpert to subscribe to data and send commands to MQTT devices.

The Edge Xpert MQTT Device Service also enables the integration of MQTT devices into Edge Xpert. For more information about the MQTT protocol, see the MQTT website.

The Edge Xpert MQTT Device Service is based on Eclipse Paho, a widely used open source implementation of MQTT written in Go.

Key Features

The MQTT Device Service supports the following key features. For more information, see MQTT Async read, MQTT Get Command, and MQTT Put Command.

Asynchronous read: Data can be read from an MQTT topic asynchronously.
Get command: The MQTT Device Service can send a read request to an MQTT topic and listen to another MQTT topic for the result.
Put command: The MQTT device service can send write requests to the MQTT topic on which the MQTT device will listen.

MQTT Broker Configuration

Definition

Schema - MQTT broker schema
Host - MQTT broker host
Port - MQTT broker port
User - username for authentication
Password - password for authentication
KeepAlive - MQTT keep alive function
ConnWaitTimeout - MQTT client connection timeout
GetCmdTimeout - timeout for GetCommand to wait for the response message from the MQTT broker
ConnPoolEnable - Indicates Device Service should enable the connection pool to manage MQTT connection
ConnPoolInitialSize - Indicates the initial size of the MQTT connection pool

ConnPoolMaximumSize - Indicates the maximum size of the MQTT connection pool

[MQTTBrokerInfo]
Scheme = "tcp"
Host = "mqtt-broker"
Port = 1883
KeepAlive = 30
ConnWaitTimeout = 5
GetCmdTimeout = 5
ConnPoolEnable = true
ConnPoolInitialSize = 10
ConnPoolMaximumSize = 30
# SecretPath is the name of the path in secret provider to retrieve your secrets. Must be non-blank.
SecretPath = "mqtt"
# AuthMode indicates what to use when connecting to the broker. Options are "none", "cacert" , "usernamepassword", "clientcert".
# If a CA Cert exists in the SecretPath then it will be used for all modes except "none".
AuthMode = "none"
# SkipCertVerify indicates if the server certificate verification should be skipped
SkipCertVerify = false

Overriding with Environment Variables

You can override any of the above configurations using environment variables to meet the requirement, see Docker Compose Override for more information. For example:

Note

Before proceeding, you have to go through the configuration setting of the preferred MQTT Broker and apply the changes on docker-compose.yaml.

version: '3.7'

services:
  device-mqtt:
    environment:
      MQTTBROKERINFO_HOST: <your_broker_host_name>
      MQTTBROKERINFO_PORT: <your_broker_port_number>
      MQTTBROKERINFO_KEEPALIVE: "40"

Authentication in MQTT

The MQTT device service supports different authentication modes in the MQTT Broker, including password-based, certificate-based and client certificates based modes. When connecting to your broker using one of these modes, please deploy MQTT device service with the following match settings.

Password-based authentication

version: '3.7'

services:
  device-mqtt:
    environment:
      MQTTBROKERINFO_HOST: <your_broker_host_name>
      MQTTBROKERINFO_PORT: <your_broker_port_number>
      MQTTBROKERINFO_AUTHMODE: "usernamepassword"
      WRITABLE_INSECURESECRETS_MQTT_SECRETS_USERNAME: <username>
      WRITABLE_INSECURESECRETS_MQTT_SECRETS_PASSWORD: <password>

MQTT Broker with Transport Layer Security (TLS)

If your remote MQTT Broker is TLS-enabled, we also provide the following configuration to connect to the MQTT Broker.

Using TLS-enabled MQTT Broker without certificate

version: '3.7'

services:
  device-mqtt:
    environment:
      MQTTBROKERINFO_HOST: <your_broker_host_name>
      MQTTBROKERINFO_PORT: <your_broker_port_number>
      MQTTBROKERINFO_SCHEME: tcps

Certificate-based authentication

version: '3.7'

services:
  device-mqtt:
    environment:
      MQTTBROKERINFO_HOST: <your_broker_host_name>
      MQTTBROKERINFO_PORT: <your_broker_port_number>
      MQTTBROKERINFO_SCHEME: tcps
      MQTTBROKERINFO_AUTHMODE: "cacert"
      WRITABLE_INSECURESECRETS_MQTT_SECRETS_CACERT: <your_cacert>

Client Certificates based authentication

version: '3.7'

services:
  device-mqtt:
    environment:
      MQTTBROKERINFO_HOST: <your_broker_host_name>
      MQTTBROKERINFO_PORT: <your_broker_port_number>
      MQTTBROKERINFO_SCHEME: tcps
      MQTTBROKERINFO_AUTHMODE: "clientcert"
      WRITABLE_INSECURESECRETS_MQTT_SECRETS_CACERT: <your_cacert>
      WRITABLE_INSECURESECRETS_MQTT_SECRETS_CLIENTKEY: <your_client_key>
      WRITABLE_INSECURESECRETS_MQTT_SECRETS_CLIENTCERT: <your_client_cert>

Deploy MQTT Broker

Edge Xpert ships with its own MQTT broker, which is a docker container called mqtt-broker. It can be started by default with Edge Xpert, but can also be specified with the following command:

edgexpert up mqtt-broker

To get the IP address of mqtt-broker, you can use the following command:

edgexpert ip | grep mqtt-broker

Supported Data Types

The MQTT Device Service supports the JSON text format and passes the reading value to the following data types:

Bool
String
Uint8, Uint16, Uint32, Uint64
Int8, Int16, Int32, Int64
Float32, Float64
BoolArray, StringArray
Uint8Array, Uint16Array, Uint32Array, Uint64Array
Int8Array, Int16Array, Int32Array, Int64Array
Float32Array, Float64Array

MQTT Device Profile

The device profile defines what resources are available on a particular device.

The following profile attributes can be defined in the YAML file:

Attribute	Description
`subTopic`	Defines the topic to which to subscribe
`qos`	Defines the Quality of Service (qos) level The qos level is an agreement between the sender of a message and the recipient, which defines the guarantee of delivery for a specific message
`jsonPath`	Defines the field to fetch from the target JSON
`msgFormat`	Defines the format of the message for the Device Service to use when parsing the message from the MQTT broker
`pubTopic`	Defines the publishing topic used when the Device Service publishes the message
`reqTopic`	Defines the request topic used when publishing a request to a specific device The device take this request and returns a response
`reqTemp`	Generates the request template used to generate the body of the request The MQTT protocol can receive multiple responses from the `resTopic`; a `UUID` field can be used to match the response and the request
`resTopic`	Defines the response topic used when subscribing to the request and parsing the message using the specified message format

MQTT Protocol Properties

The available MQTT protocol properties are described in the following table:

Protocol Property	Description	Valid Values	Required
`TopicReplacement`	The replacement for replacing the MQTT topic path Eg, if the TopicReplacement is 'test-identifier' and the user define the topic "test/resource/${topicReplacement}" in the device resource, then the actual topic should be "test/resource/test-identifier" for the Device Service.	Any string value	No
`HeartbeatResource`	The resource indicates the device is alive. The device operatingState will become `DOWN` if there is no message received from this device resource after a duration defined in `HeartbeatTimeout`.	A device resource name	No
`HeartbeatTimeout`	The time duration to check whether the device is alive	A valid duration string. Eg, "30s", "10m", "24h" The available minimum value is 1s	Yes (for HeartbeatResource is defined)

Using the MQTT Device Service

For an example of how to set up and use devices with the Edge Xpert MQTT Device Service, see MQTT Example.