Skip to content

MQTT Bridge Component

The MQTT bridge component extends the Bus across multiple nodes.

Subscribed topics on one node are published using an MQTT client to republish on the Bus present on another node.

MQTT Bridge Configuration

The following tables describe the configuration variables that can be used with the MQTT bridge component:

MQTT Bridge Configuration Variables

Parameter Type Description Valid Values Required Y/N
Bus String The name of the Bus component to use The name of an existing Bus component Y
Logger String The name of the Logger component to use The name of an existing Logger component N
QueueSize Unsigned Integer The size of the queue for the subscriber to hold messages Default: 4 N
Cookie Integer The cookie value for the subscriber A valid cookie N
Patterns Array of Strings Array of patterns to match on the Bus component for subscription Y
MQTTPatterns Array of Strings Array of patterns to match for MQTT subscription Pattern, or patterns, to match Y
Compress Array of Objects An array of maps with each map containing MQTT Topic name and Compression Type Only gzip compression type is supported N
MQTTConfig Object The MQTT configuration to use See MQTT Configuration Variables Y

MQTT Configuration Variables

The following table describes the MQTT configuration variables:

Parameter Type Description Valid Values Required
ServerURI String The URI of the MQTT server to use The URI where the MQTT server is started Y
ClientID String The name of the MQTT client to use The name of an MQTT client Y
QoS Unsigned Integer Specifies the MQTT quality of service level

  • Specify 0 to use QOS0
  • Specify 1 to use QOS1
  • Specify 2 to use QOS2
 Valid values are as follows:
  • 0 (default)
  • 1
  • 2
 N
MQTTInstance Unsigned Integer The instance type

If using Google Cloud, this must be set to 1 		Valid values are as follows:
  • 0 (default)
  • 1
 N
ClientConfig Object The MQTT Client configuration to use See MQTT Client Configuration Variables N

MQTT Client Configuration Variables

The following table describes the MQTT client configuration variables:

Parameter Type Description Valid Values Required
KeepAliveInterval Unsigned Integer The maximum time in seconds for the connection to remain active without connection between the MQTT server and client Default is 60 N
Username String The username to use in authentication and authorization A valid username N
Password String The password to use in authentication and authorization A valid password for the specified username N
ConnectTimeout Unsigned Integer Interval in seconds to allow for a connection to complete

If set to zero (0), the connection never times out 		Default is 0 N
DisconnectTimeout Unsigned Integer Time interval in ms to allow in-flight message transfers to complete before disconnection Default is 0 N
MQTTVersion Unsigned Integer Specifies the MQTT version for communication

  • Specify 0 to use MQTTVERSION_DEFAULT
  • Specify 4 to use MQTTVERSION_3_1_1
  • Specify 5 to use MQTTVERSION_5
 Valid values are as follows:
  • 0 (default)
  • 4
  • 5
 N
SSLConfig Object The MQTT SSL configuration to use See MQTT SSL Configuration Variables N
CleanStart Boolean Clears the state at the start of the session

Used on all MQTTVersions (3.1.1 & V5)
  • Specify false to retain state information
  • Specify true to discard state information
 Valid values are as follows:
  • true (default)
  • false
 N
SessionExpiry Unsigned Integer Only used if MQTTVersion is set to 5

The time in seconds for which the broker stores the session of a particular client

If cleanstart is false, Session state is stored until the session expiry interval. 		Default is 0 N
RetryInterval Unsigned Integer Time in seconds to retry publish requests if not acknowledged Default is 0 N
MinRetryInterval Unsigned Integer The minimum automatic reconnect retry interval in seconds. Doubled on each failed retry Default is 1 N
MaxRetryInterval Unsigned Integer The maximum automatic reconnect retry interval in seconds. The doubling stops on failed retries Default is 60 N
MaxBufferedMessages Unsigned Integer The maximum number of messages to be buffered. The value should always be greater than 0 as the same buffer is used when the client is connected Default is 100 N

MQTT SSL Configuration Variables

The following table describes the MQTT SSL configuration variables:

Parameter Type Description Valid Values Required
SSLVersion Unsigned Integer Specifies the SSL version

  • Specify 0 to use XRT_MQTT_SSL_VERSION_DEFAULT
  • Specify 1 to use XRT_MQTT_SSL_VERSION_TLS_1
  • Specify 2 to use XRT_MQTT_SSL_VERSION_TLS_1_1
  • Specify 3 to use XRT_MQTT_SSL_VERSION_TLS_1_2
Note: Both AWS and Google Cloud require version TLS1.2. 		Valid values are as follows:
  • 0
  • 1
  • 2
  • 3 (default)
 N
EnableServerCertAuth Boolean Specifies whether to enable verification of the server certificate

  • Specify true to verify the server certificate
  • Specify false to disable verification of the server certificate
 Valid values are as follows:
  • true (default)
  • false
 N
TrustStore String The Public Digital certificate trusted by the MQTT client in PEM format A valid certificate in PEM format N
KeyStore String The Public certificate chain of the MQTT client in PEM format A valid certificate chain in PEM format N
PrivateKey String The private key of the MQTT client in PEM format A valid key in PEM format N
PrivateKeyPasswd String The password to load the client's private key A valid password for the private key N
EnabledCipherSuites String The Cipher suite presented by the client to the server during the SSL handshake Default is All

For valid values, refer to the OpenSSL cipher list

For further information, refer to the OpenSSL documentation 		N

MQTT Bridge as an Exporter

MQTT Bridge can be configured for use as an Exporter that can subscribe topic(s) on a bus to publish to a configured MQTT topic in JSON format. When used as an Exporter, the data can be exported to external systems, such as:

Export Data to AWS

To export data to AWS, you must have already done the following:

  • Created the required resources
  • Attached a policy to a thing
  • Activated the certificate on the AWS console

For further information on creating a thing and activating a device certificate, refer to the AWS Developer's Guide.

Example Configuration for Export to AWS

The configuration required to export data to AWS using the MQTT Bridge component is described below.

MQTT Configuration for Export to AWS

The following parameters must be configured:

Parameter Setting
ServerURI The REST API endpoint

For example ssl://apuyluiqj895v-ats.iot.us-east-1.amazonaws.com:8883
ClientID The identifier of the thing

For example: c-sdk-client-id
MQTT Client Configuration for Export to AWS

The following parameters must be configured:

Parameter String
ClearStart 1
MQTT SSL Configuration for Export to AWS

The following parameters must be configured:

Parameter String
SSLVersion 3
TrustStore Full path to the root CA file for AWS

The CA file was downloaded during the creation of the certificate

For example: /xrt/examples/Exporters/mqtt/aws/rootCA1.pem
KeyStore Full path to the certificate generated for the thing

For example: /xrt/examples/Exporters/mqtt/aws/34aa6e6a89-certificate.pem.crt
PrivateKey Full path to the private key generated for the thing

For example: /xrt/examples/Exporters/mqtt/aws/34aa6e6a89-private.pem.key
Example Configuration File for Export to AWS

The following JSON configuration could be used to apply the settings described above:

"MQTTConfig":
{
  "ServerURI": "ssl://apuyluiqj895v-ats.iot.us-east-1.amazonaws.com:8883",
  "ClientID": "c-sdk-client-id",
  "MQTTInstance": 0,
  "QoS": 1,
  "ClientConfig":
  {
    "KeepAliveInterval": 10,
    "MQTTVersion": 4,
    "Reliable": true,
    "ConnectTimeout": 30,
    "CleanSession": 1,
    "SSLConfig":
    {
      "EnableServerCertAuth": true,
      "SSLVersion": 3,
      "TrustStore": "/xrt/examples/Exporters/mqtt/aws/rootCA1.pem",
      "KeyStore": "/xrt/examples/Exporters/mqtt/aws/34aa6e6a89-
      certificate.pem.crt ",
      "PrivateKey": "/xrt/examples/Exporters/mqtt/aws/34aa6e6a89-
      private.pem.key ",
      "EnabledCipherSuites": "ALL"
    }
  }
}

Export Data to Google Cloud

To export data to Google Cloud, you must have already done the following:

  • Created the Google Cloud project
  • Created a device
  • Created registries

For further information on creating a Google Cloud project, refer to the Google Cloud documentation.

Example Configuration for Export to Google Cloud

The configuration required to export data to Google Cloud using the MQTT Bridge component is described below.

MQTT Configuration for Export to Google Cloud

The following parameters must be configured:

Parameter String
ServerURI The REST API endpoint

For example: ssl://mqtt.googleapis.com:8883
ClientID The full path to the device

For example: projects/PROJECT_ID/locations/REGION/registries/REGISTRY_ID/devices/DEVICE_ID
Topic The MQTT topic to which to publish

This is /devices/<Device_ID>/events/<topic>
MQTT Client Configuration for Export to Google Cloud

The following parameters must be configured:

Parameter String
Username An arbitrary username, such as unused or ignored, to allow the Password parameter to be sent
Password Set this to default
MQTT SSL Configuration for Export to Google Cloud

The following parameters must be configured:

Parameter String
TrustStore Full path to the roots.pem file

The roots.pem file is available for download on Google Cloud

For example: /xrt/examples/Exporters/mqtt/google/roots.pem
PrivateKey Full path to the 2048 bit RSA key pair private key

This can be generated as described in the Creating key pairs section of the Google Cloud documentation

Upload the public key to the device registered

For example: /xrt/examples/Exporters/mqtt/google/iot_dell_export_mqtt.pem
Example Configuration File for Export to Google Cloud

The following JSON configuration could be used to apply the settings described above:

"MQTTConfig":
{
  "ServerURI": "ssl://mqtt.googleapis.com:8883",
  "ClientID": "projects/light-trail-249010/locations/europe-west1/registries/xrt-mqtt-export-
  test / devices / test - device - xrt - mqttexport ",
  "MQTTInstance": 1,
  "QoS": 1,
  "ClientConfig":
  {
    "KeepAliveInterval": 60,
    "MQTTVersion": 4,
    "Reliable": true,
    "ConnectTimeout": 30,
    "Username": "ignored",
    "Password": "default",
    "SSLConfig":
    {
      "EnableServerCertAuth": true,
      "SSLVersion": 3,
      "TrustStore": "/xrt/examples/Exporters/mqtt/google/roots.pem",
      "PrivateKey": "/xrt/examples/Exporters/mqtt/google/iot_dell_export_mqtt.pem ",
      "EnabledCipherSuites": "ALL",
      "PrivateKeyPasswd": " "
    }
  }
}

Export Data to Azure

It is possible to export data to Azure via MQTT without using Azure IoT SDK. For details, refer to the IoTHub MQTT Support

You must have already done the following:

Here are the steps to install CLI and generate the token for use in the configuration:

  1. Install Azure CLI on Ubuntu

    curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

  2. Create a device

    az iot hub device-identity create -n <iot_hub> -d <device_name>

    Note

    This require Azure login

  3. Generate a SAS token

    az iot hub generate-sas-token -d <device_name> -n <iot_hub>

    Note

    Add an optional parameter --du <time> to provide the duration of the token validity. Default value is 3600 seconds. For details, refer to the Azure IoT Hub Generate SAS Token

  4. Root CA

    To use MQTT protocol directly from xrt, the connection must be over TLS/SSL. In order to connect over TSL, download the DigiCert Baltimore CyberTrust Root Certificate from digicert-root-certificates and store it as root.pem to secure the connection.

MQTT Bridge Configuration changes required to export data to Microsoft Azure

The configuration required to export data to Azure Cloud using the MQTT Bridge component is described below.

MQTT Configuration for Export to Azure

The following parameters must be configured:

Parameter Setting
ServerURI The REST API endpoint

ssl://<hubname>.azure-devices.net:8883
ClientID Device Id created as mentioned in Step 2

For example:test-azure-device
MQTT Client Configuration for Export to Azure

The following parameters must be configured:

Parameter String
Username Username to authenticate

<iot_hub>.azure-devices.net/<device-id>
Password SAS token generated as mentioned in Step 3

SharedAccessSignature sr=<SAS>
MQTTVersion MQTT v3.1.1 on port 8883

4
MQTT SSL Configuration for Export to Azure

The following parameters must be configured:

Parameter String
TrustStore Full path to the root.pem file

Downloaded roots.pem file as mentioned in Step 4

For example: /xrt/examples/Exporters/mqtt/azure/root.pem
MQTT Bridge Configuration to communicate with Azure

The following parameters must be configured:

Parameter Setting
Patterns Topic to publish telemetry (device to cloud)

devices/<device-id>/messages/events/readpipe
MQTTPatterns Topic filter to subscribe for receiving messages from IoT Hub (cloud to device)

devices/<device_id>/messages/devicebound/#

Use Azure portal to send data to the device

To receive data back to the device, do the following:

In the Azure Portal, open the IoT hub that is being used and navigate to the created device. Select Message to Device button and the fill in the message body to send the data.

Here is an example:

{
  "client": "example",
  "request_id": "1010",
  "op": "device:add",
  "type": "xrt.request:1.0",
  "device": "Virtual-Device",
  "device_info":  {
    "profileName": "device-virtual",
    "protocols":{
      "Other":{
        "Address": "device-virtual-01"
      }
    }
  }
}
This will update devices.json in the configuration to indicate a device by name Virtual-Device is added. For details on the operations supported, refer section MQTT Management

MQTT Bridge Configuration Example

The following example configures an MQTT bridge component to publish data on the topics defined in Patterns and subscribes to the topic defined in MQTTPatterns

"Patterns": [ "xrt/devices/bacnet_ip/telemetry", "xrt/devices/bacnet_ip/reply", "xrt/devices/bacnet_ip/discovery" ],
"MQTTPatterns": ["xrt/devices/bacnet_ip/request"],
"Compress": [{"xrt/devices/bacnet_ip/telemetry": "gzip"}]
"MQTTConfig":
{
  "ServerURI": "tcp://127.0.0.1:1883",
  "ClientID": "mqtt_bridge",
  "MQTTInstance": 0,
  "QoS": 1,
  "ClientConfig":
  {
    "KeepAliveInterval": 0,
    "Reliable": true,
    "Username": "test",
    "Password": "test",
    "ConnectTimeout": 0,
    "MQTTVersion": 5,
    "SSLConfig":
    {
      "EnableServerCertAuth": true,
      "SSLVersion": 3,
      "TrustStore": "roots.pem",
      "KeyStore": "public_key.pem",
      "PrivateKey": "PEM format - private_key.pem",
      "EnabledCipherSuites": "ALL",
      "PrivateKeyPasswd": " "
    }
  }
}