2. Configuration

This section describes how to configure Routing Service MQTT Adapter.

All configuration is specified in Routing Service’s XML configuration file.

2.1. Load the MQTT Adapter Plugin

Routing Service MQTT Adapter must be registered as a plugin on Routing Service using the <adapter_plugin> tag.

Once the dynamic library and constructor function have been registered, Routing Service will create an instance of the plugin during start-up, and the plugin can be used to create one or more connections to an MQTT Broker.

The following snippet demonstrates how to register the plugin in the <plugin_library> section of Routing Service’s XML configuration:

<?xml version="1.0"?>
<dds>
    <plugin_library name="MyPlugins">
        <adapter_plugin name="Mqtt">
            <dll>rtimqttadapter</dll>
            <create_function>
                RTI_RS_MQTT_AdapterPlugin_create
            </create_function>
        </adapter_plugin>
    </plugin_library>
</dds>

Warning

Routing Service must be able to find the Routing Service MQTT Adapter dynamic library (librtimqttadapter.so on Linux® systems, librtimqttadapter.dylib on macOS® systems, or rtimqttadapter.dll on Windows® systems). Make sure to include the library’s directory in the library search path environment variable appropriate for your system (LD_LIBRARY_PATH on Linux systems, RTI_LD_LIBRARY_PATH on macOS systems, PATH on Windows systems, etc.).

2.2. Register MQTT Data Types

Routing Service MQTT Adapter exposes data to Routing Service using two possible DDS Types: RTI::MQTT::Message and RTI::MQTT:KeyedMessage.

The IDL definition of these types is included with Routing Service MQTT Adapter, and built in into the library, but it is necessary to register them in Routing Service’s XML configuration to make it available outside of the adapter:

<?xml version="1.0"?>
<dds>
    <types>
        <module name="RTI">
            <module name="MQTT">
                <enum name="QosLevelKind">
                    <enumerator name="RTI_MQTT_QosLevel_UNKNOWN"/>
                    <enumerator name="RTI_MQTT_QosLevel_ZERO"/>
                    <enumerator name="RTI_MQTT_QosLevel_ONE"/>
                    <enumerator name="RTI_MQTT_QosLevel_TWO"/>
                </enum>
                <struct name= "MessageInfo" nested="true">
                    <member name="id" type="int32"/>
                    <member name="qos_level" type="nonBasic"
                            nonBasicTypeName="RTI::MQTT::QosLevelKind"/>
                    <member name="retained" type="boolean"/>
                    <member name="duplicate" type="boolean"/>
                </struct>
                <struct name= "MessagePayload" nested="true">
                    <member name="data" sequenceMaxLength="-1" type="byte"/>
                </struct>
                <struct name= "Message">
                    <member name="topic" stringMaxLength="-1"
                            type="string" optional="true"/>
                    <member name="info" type="nonBasic"
                            nonBasicTypeName="RTI::MQTT::MessageInfo"
                            optional="true"/>
                    <member name="payload" type="nonBasic"
                            nonBasicTypeName="RTI::MQTT::MessagePayload"/>
                </struct>
                <struct name= "KeyedMessage">
                    <member name="topic" stringMaxLength="-1"
                            type="string" key="true"/>
                    <member name="info" type="nonBasic"
                            nonBasicTypeName="RTI::MQTT::MessageInfo"
                            optional="true"/>
                    <member name="payload" type="nonBasic"
                            nonBasicTypeName= "RTI::MQTT::MessagePayload"/>
                </struct>
            </module>
        </module>
    </types>
</dds>

2.3. Configure QoS

The types used by Routing Service MQTT Adapter make used of “unbounded” strings and sequences.

The following QoS parameters must be configured in order to enable use of “unbounded” types:

<?xml version="1.0"?>
<dds>
    <qos_library name="MyQosLib">
        <qos_profile name="MyQos" is_default_qos="true">
            <datareader_qos>
                <reader_resource_limits>
                    <dynamically_allocate_fragmented_samples>
                        true
                    </dynamically_allocate_fragmented_samples>
                </reader_resource_limits>
                <property>
                    <value>
                        <element>
                            <name>dds.data_reader.history.memory_manager.fast_pool.pool_buffer_max_size</name>
                            <!-- Modify this value according to your preference -->
                            <value>10485760</value>
                        </element>
                    </value>
                </property>
            </datareader_qos>
            <datawriter_qos>
                <property>
                    <value>
                        <element>
                            <name>dds.data_writer.history.memory_manager.fast_pool.pool_buffer_max_size</name>
                            <!-- Modify this value according to your preference -->
                            <value>10485760</value>
                        </element>
                    </value>
                </property>
            </datawriter_qos>
        </qos_profile>
    </qos_library>
</dds>

2.4. Connect to an MQTT Broker

Once the plugin has been registered with Routing Service, it can be used to create <connection> elements within a <domain_route>.

The <connection>’s configuration must include properties client.id, and client.servers to configure the associated MQTT Client.

The following snippet shows an example <connection> that connects to a local MQTT Broker:

<?xml version="1.0"?>
<dds>
    <routing_service>
        <domain_route>
            <connection name="mqtt" plugin_name="MyPlugins::Mqtt">
                <property>
                    <value>
                        <element>
                            <name>client.id</name>
                            <value>mqtt_router</value>
                        </element>
                        <element>
                            <name>client.servers</name>
                            <value>tcp://127.0.0.1:1883</value>
                        </element>
                    </value>
                </property>
                <registered_type name="RTI::MQTT::Message"
                                 type_name="RTI::MQTT::Message"/>
                <registered_type name="RTI::MQTT::KeyedMessage"
                                 type_name="RTI::MQTT::KeyedMessage"/>
            </connection>
            <!-- Create a DDS DomainParticipant to connect other
                 applications in the Domain to the MQTT Clients
                 connected to the Broker -->
            <participant name="dds">
                <domain_id>0</domain_id>
                <registered_type name="RTI::MQTT::Message"
                                 type_name="RTI::MQTT::Message"/>
                <registered_type name="RTI::MQTT::KeyedMessage"
                                 type_name="RTI::MQTT::KeyedMessage"/>
            </participant>
        </domain_route>
    </routing_service>
</dds>

2.5. Route Data from MQTT to DDS

A <connection> created by Routing Service MQTT Adapter can be used to define <input> elements which will subscribe to MQTT Messages from the MQTT Broker, and expose them to the enclosing <route> as DDS Samples of either RTI::MQTT::Message, or RTI::MQTT::KeyedMessage.

The specific DDS Type to use is determined from the value of the <registered_type_name> element.

The MQTT Client associated with the <connection> will be used to create subscriptions on the MQTT Broker for every topic filter specified in property subscription.topics.

The value of this property is a list of semicolon-separated MQTT Topic Filters.

The following snippet demonstrate how to create an <input> which will subscribe to all topics available on the MQTT Broker, and route them to DDS Topic "dds_mqtt" using DDS Type RTI::MQTT:KeyedMessage:

<?xml version="1.0"?>
<dds>
    <routing_service>
        <session>
            <route>
                <input name="mqtt_reader" connection="mqtt">
                    <registered_type_name>
                      RTI::MQTT::KeyedMessage
                    </registered_type_name>
                    <property>
                        <value>
                            <element>
                                <name>subscription.topics</name>
                                <value>#</value>
                            </element>
                        </value>
                    </property>
                </input>
                <dds_output name="dds_mqtt" participant="dds">
                    <registered_type_name>
                        RTI::MQTT::KeyedMessage
                    </registered_type_name>
                </dds_output>
            </route>
        </session>
    </routing_service>
</dds>

Warning

While possible, it is discouraged to specify the same topic filter on multiple <input> elements belonging to the same <connection>. Each duplicated topic filter will result in a single subscription on the MQTT Broker with settings from the last <input> to be created.

2.6. Route Data from DDS to MQTT

A <connection> created by Routing Service MQTT Adapter can be used to define <output> elements that will convert DDS Samples into MQTT Messages, and publish them to a topic on the <connection>’s MQTT Broker.

DDS Samples must be of type RTI::MQTT::Message, or RTI::MQTT::KeyedMessage.

The following snippet demonstrate how to configure an <output> to publish the payload of RTI::MQTT::KeyedMessage DDS Samples published on topic "dds_mqtt" to MQTT Topic "foo/bar", with MQTT Qos 1:

<?xml version="1.0"?>
<dds>
    <routing_service>
        <session>
            <route>
                <dds_input name="dds_mqtt" participant="dds">
                    <registered_type_name>
                        RTI::MQTT::KeyedMessage
                    </registered_type_name>
                </dds_input>
                <output name="mqtt_writer" connection="mqtt">
                    <registered_type_name>
                        RTI::MQTT::KeyedMessage
                    </registered_type_name>
                    <property>
                        <value>
                            <element>
                                <name>publication.topic</name>
                                <value>foo/bar</value>
                            </element>
                            <element>
                                <name>publication.qos</name>
                                <value>1</value>
                            </element>
                        </value>
                    </property>
                </input>
            </route>
        </session>
    </routing_service>
</dds>

Alternatively, property publication.use_message_info be used to have the <output> use the metadata contained in published DDS Samples to determine other publication setttings (e.g. topic, qos, retained flags, etc.):

<?xml version="1.0"?>
<dds>
    <routing_service>
        <session>
            <route>
                <dds_input name="dds_mqtt" participant="dds">
                    <registered_type_name>
                        RTI::MQTT::KeyedMessage
                    </registered_type_name>
                </dds_input>
                <output name="mqtt_writer" connection="mqtt">
                    <registered_type_name>
                        RTI::MQTT::KeyedMessage
                    </registered_type_name>
                    <property>
                        <value>
                            <element>
                                <name>publication.use_message_info</name>
                                <value>true</value>
                            </element>
                        </value>
                    </property>
                </input>
            </route>
        </session>
    </routing_service>
</dds>

2.7. XML Configuration properties

This section describes the properties that can be used to configure Routing Service MQTT Adapter.

2.7.1. <connection> Properties

Each <connection> created by the Routing Service MQTT Adapter plugin is associated with an MQTT Client which must be configured using the <properties> tag.

Most configuration properties have “reasonable” default values, except for client.id, and client.servers which must be always specified.

Table 2.1 <connection> Properties
Property	Required
client.id	Yes
client.servers	Yes
client.protocol_version	No
client.connection_timeout.sec	No
client.connection_timeout.nanosec	No
client.max_connection_retries	No
client.keep_alive_period.sec	No
client.keep_alive_period.nanosec	No
client.clean_session	No
client.unsubscribe_on_disconnect	No
client.max_reply_timeout.sec	No
client.max_reply_timeout.nanosec	No
client.reconnect	No
client.max_unack_messages	No
client.persistence	No
client.persistence_storage	No
client.username	No
client.password	No
client.ssl.ca	No
client.ssl.id	No
client.ssl.key	No
client.ssl.key_password	No
client.ssl.protocol_version	No
client.ssl.verify_server_certificate	No
client.ssl.cypher_suites	No

2.7.1.1. client.id

Required: Yes
Default: None
Description: The “client id” that will be sent to the MQTT Broker during connection. The value must be unique within all clients connected to the same MQTT Broker.
Accepted Values: Any non-empty alphanumeric string

2.7.1.2. client.servers

Required

Yes

Default

None

Description

A list of MQTT Broker URIs to which the MQTT Client will try to connect, in the specified order, until a connection can be successfully established.

Accepted Values

A list of MQTT Broker URIs, separated by semicolon. Each URI takes the form <protocol>://<address>:<port>, where <protocol> can be one of:

tcp: connect to MQTT Broker using a TCP connection.
ssl: connect to MQTT Broker using an SSL/TLS connection.

Note

tcp://127.0.0.1:1883 is usually the default URI to connect to an MQTT Broker deployed on your local machine (e.g. if you are using Mosquitto).

2.7.1.3. client.protocol_version

Required: No
Default: default
Description
Accepted values

2.7.1.4. client.connection_timeout.sec

Required: No
Default: 10
Description
Accepted values

2.7.1.5. client.connection_timeout.nanosec

Required: No
Default: 0
Description
Accepted values

2.7.1.6. client.max_connection_retries

Required: No
Default: 10
Description
Accepted values

2.7.1.7. client.keep_alive_period.sec

Required: No
Default: 10
Description
Accepted values

2.7.1.8. client.keep_alive_period.nanosec

Required: No
Default: 0
Description
Accepted values

2.7.1.9. client.clean_session

Required: No
Default: false
Description
Accepted values

2.7.1.10. client.unsubscribe_on_disconnect

Required: No
Default: true
Description
Accepted values

2.7.1.11. client.max_reply_timeout.sec

Required: No
Default: 10
Description
Accepted values

2.7.1.12. client.max_reply_timeout.nanosec

Required: No
Default: 10
Description
Accepted values

2.7.1.13. client.reconnect

Required: No
Default: false
Description
Accepted values

2.7.1.14. client.max_unack_messages

Required: No
Default: 10
Description
Accepted values

2.7.1.15. client.persistence

Required: No
Default: none
Description
Accepted values

2.7.1.16. client.persistence_storage

Required: No
Default: None
Description
Accepted values

2.7.1.17. client.username

Required: No
Default: None
Description
Accepted values

2.7.1.18. client.password

Required: No
Default: None
Description
Accepted values

2.7.1.19. client.ssl.ca

Required: No
Default: None
Description
Accepted values

2.7.1.20. client.ssl.id

Required: No
Default: None
Description
Accepted values

2.7.1.21. client.ssl.key

Required: No
Default: None
Description
Accepted values

2.7.1.22. client.ssl.key_password

Required: No
Default: None
Description
Accepted values

2.7.1.23. client.ssl.protocol_version

Required: No
Default: default
Description
Accepted values

2.7.1.24. client.ssl.verify_server_certificate

Required: No
Default: true
Description
Accepted values

2.7.1.25. client.ssl.cypher_suites

Required: No
Default: "ALL"
Description
Accepted values

2.7.2. <input> Properties

Table 2.2 <input> Properties
Property	Required
subscription.topics	Yes
subscription.max_qos	No
subscription.queue_size	No

2.7.2.1. subscription.topics

Required: Yes
Default: None
Description
Accepted values

2.7.2.2. subscription.max_qos

Required: No
Default: 2
Description
Accepted values

2.7.2.3. subscription.queue_size

Required: No
Default: 0
Description
Accepted values

2.7.3. <output> Properties

Table 2.3 <input> Properties
Property	Required
publication.topic	Yes*
publication.qos	No
publication.retained	No
publication.use_message_info	Yes*
publication.max_wait_time.sec	No
publication.max_wait_time.nanosec	No

2.7.3.1. publication.topic

Required: Yes (if publication.use_message_info is not enabled).
Default: None
Description
Accepted values

2.7.3.2. publication.qos

Required: No
Default: 0
Description
Accepted values

2.7.3.3. publication.retained

Required: No
Default: false
Description
Accepted values

2.7.3.4. publication.use_message_info

Required: Yes (if publication.topic is empty).
Default: false
Description
Accepted values

2.7.3.5. publication.max_wait_time.sec

Required: No
Default: 10
Description
Accepted values

2.7.3.6. publication.max_wait_time.nanosec

Required: No
Default: 0
Description
Accepted values