MQTT Exporter Component

The MQTT Exporter component does the following:

Subscribes to topics on a Bus
Exports data matching a subscription pattern to an MQTT server
Publishes data in JSON format on a configured MQTT topic

The MQTT Exporter component supports the use of a metadata map on the published data to control output formatting.

MQTT Exporter Configuration

You can configure the following:

MQTT Exporter Publishing Metadata
MQTT Exporter Configuration Variables
MQTT Configuration Variables
MQTT Client Configuration Variables
MQTT SSL Configuration Variables

MQTT Exporter Publishing Metadata

The following table describes the MQTT exporter publishing metadata:

Map Key String	Type	Description	Required
JSON_SIZE	i64	The initial size of the string buffer used to create the JSON formatted string This improves performance when large data structures are exported	N

MQTT Exporter Configuration Variables

The following table describes the MQTT exporter configuration variables:

Parameter	Type	Description	Valid Values	Required
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
Pattern	String	The pattern to match on the Bus component for subscription	Default: #	N
Topic	String	The MQTT topic on which to publish data	The name of an existing MQTT topic	Y
QueueSize	Unsigned Integer	The size of the queue for the subscriber to hold messages	Range 0 to uint32max Default: 4	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

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 If set to zero (0), the connection does not remain active without connection	Default is 0	N
CleanSession	Boolean	Specifies whether to discard state information at connect and disconnect Specify `0` to retain state information Specify `1` to discard state information	Valid values are as follows: true false (default)	N
Reliable	Boolean	Specifies whether to complete publication of a message before sending the next message Specify true to wait for publication to complete before sending the next message Specify false to send the next message before publication is complete	Valid values are as follows: true false (default)	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
ConnectionTimeout	Unsigned Integer	Interval in seconds to allow for a connection to complete If set to zero (0), the connection never times out		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 Only applicable if MQTTVersion is set to 5	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 set to zero (0), the broker stores the session indefinitely	Default is 0	N
RetryInterval	Unsigned Integer	Interval in seconds to attempt reconnection	Default is 5	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 Exporter Configuration Examples

MQTT Exporter component can be used to export data to external systems, such as the following:

Amazon Web Services (AWS), as described in Export Data to AWS
Google Cloud, as described in Export Data to Google Cloud

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 exporter component is described below.

MQTT Configuration for Export to AWS

The following parameters must be configured, as described in the following table:

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, as described in the following table:

Parameter	String
CleanSession	1

MQTT SSL Configuration for Export to AWS

The following parameters must be configured, as described in the following table:

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/src/c/examples/mqtt_exporter/aws_export/rootCA1.pem
KeyStore	Full path to the certificate generated for the thing For example: /xrt/src/c/examples/mqtt_exporter/aws_export/34aa6e6a89-certificate.pem.crt
PrivateKey	Full path to the private key generated for the thing For example: /xrt/src/c/examples/mqtt_exporter/aws_export/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/src/c/examples/mqtt_exporter/aws_export/rootCA1.pem",
      "KeyStore": "/xrt/src/c/examples/mqtt_exporter/aws_export/34aa6e6a89-
      certificate.pem.crt ",
      "PrivateKey": "/xrt/src/c/examples/mqtt_exporter/aws_export/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 exporter component is described below.

MQTT Configuration for Export to Google Cloud

The following parameters must be configured, as described in the following table:

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, as described in the following table:

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, as described in the following table:

Parameter	String
TrustStore	Full path to the roots.pem file The roots.pem file is available for download on Google Cloud For example: /xrt/src/c/examples/mqtt_exporter/google_export/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/src/c/examples/mqtt_exporter/google_export/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/src/c/examples/mqtt_exporter/google_export/roots.pem",
      "PrivateKey": "/xrt/src/c/examples/mqtt_exporter/google_export/iot_dell_export_
      mqtt.pem ",
      "EnabledCipherSuites": "ALL",
      "PrivateKeyPasswd": " "
    }
  }
}