16.1. Configuring Fast DDS in ROS 2

ROS 2 only allows for the configuration of certain middleware QoS (see ROS 2 QoS policies). However, rmw_fastrtps offers extended configuration capabilities to take full advantage of the features in Fast DDS. This section describes how to specify this extended configuration.

16.1.1. Changing publication mode

rmw_fastrtps in ROS 2 uses asynchronous publication by default. This can be easily changed setting the environment variable RMW_FASTRTPS_PUBLICATION_MODE to one of the following allowed values:

  • ASYNCHRONOUS: asynchronous publication mode. Setting this mode implies that when the publisher invokes the write operation, the data is copied into a queue, a background thread (asynchronous thread) is notified about the addition to the queue, and control of the thread is returned to the user before the data is actually sent. The background thread is in charge of consuming the queue and sending the data to every matched reader.

  • SYNCHRONOUS: synchronous publication mode. Setting this mode implies that the data is sent directly within the context of the user thread. This entails that any blocking call occurring during the write operation would block the user thread, thus preventing the application from continuing its operation. It is important to note that this mode typically yields higher throughput rates at lower latencies, since there is no notification nor context switching between threads.

  • AUTO: let Fast DDS select the publication mode. This implies using the publication mode set in the XML file, or otherwise, the default value set in Fast DDS (see PublishModeQosPolicy).

rmw_fastrtps defines two configurable parameters in addition to ROS 2 QoS policies. Said parameters, and their default values under ROS 2, are:

Parameter

Description

Default ROS 2 value

MemoryManagementPolicy

Fast DDS preallocates memory for the publisher
and subscriber histories. When those histories fill
up, a reallocation occurs to reserve more memory.

PREALLOCATED_WITH_REALLOC_MEMORY_MODE

PublishModeQosPolicy

User calls to publication method add the messages
in a queue that is managed in a different thread,
meaning that the user thread is available right
after the call to send data.

ASYNCHRONOUS_PUBLISH_MODE

16.1.2. XML configuration

To use specific Fast-DDS features within a ROS 2 application, XML configuration files can be used to configure a wide set of QoS. Please refer to XML profiles to see the whole list of configuration options available in Fast DDS.

When configuring rmw_fastrtps using XML files, there are certain points that have to be taken into account:

  • ROS 2 QoS contained in rmw_qos_profile_t are always honored, unless set to *_SYSTEM_DEFAULT. In that case, XML values, or Fast DDS default values in the absences of XML ones, are applied. This means that if any QoS in rmw_qos_profile_t is set to something other than *_SYSTEM_DEFAULT, the corresponding value in the XML is ignored.

  • By default, rmw_fastrtps overrides the values for MemoryManagementPolicy and PublishModeQosPolicy. This means that the values configured in the XML for these two parameters will be ignored. Instead, PREALLOCATED_WITH_REALLOC_MEMORY_MODE and ASYNCHRONOUS_PUBLISH_MODE are used respectively.

  • The override of MemoryManagementPolicy and PublishModeQosPolicy can be avoided by setting the environment variable RMW_FASTRTPS_USE_QOS_FROM_XML to 1 (its default value is 0). This will make rmw_fastrtps use the values defined in the XML for MemoryManagementPolicy and PublishModeQosPolicy. Bear in mind that setting this environment variable but not setting these policies in the XML results in using the default values in Fast DDS. These are different from the aforementioned rmw_fastrtps default values (see MemoryManagementPolicy and PublishModeQosPolicy).

  • Setting RMW_FASTRTPS_USE_QOS_FROM_XML effectively overrides whatever configuration was set with RMW_FASTRTPS_PUBLICATION_MODE, setting the publication mode to the value specified in the XML, or to the Fast DDS default publication mode if none is set in the XML.

The following table summarizes which values are used or ignored according to the configured variables:

RMW_FASTRTPS_USE_QOS_FROM_XML

rmw_qos_profile_t

Fast DDS XML QoS

Fast DDS XML history memory policy
and publication mode

0 (default)

Default values

Overridden by
rmw_qos_profile_t

Overridden by
rmw_fastrtps default value

0 (default)

Non system default

overridden by
rmw_qos_profile_t

Overridden by
rmw_fastrtps default value

0 (default)

System default

Used

Overridden by
rmw_fastrtps default value

1

Default values

Overridden by
rmw_qos_profile_t

Used

1

Non system default

Overridden by
rmw_qos_profile_t

Used

1

System default

Used

Used

16.1.2.1. XML configuration file location

There are two possibilities for providing Fast DDS with XML configuration files:

  • Recommended: Setting the location with environment variable FASTRTPS_DEFAULT_PROFILES_FILE to contain the path to the XML configuration file (see Environment variables).

    export FASTRTPS_DEFAULT_PROFILES_FILE=<path_to_xml_file>
    
  • Alternative: Placing the XML file in the running application directory under the name DEFAULT_FASTRTPS_PROFILES.xml.

For example:

export FASTRTPS_DEFAULT_PROFILES_FILE=<path_to_xml_file>
export RMW_FASTRTPS_USE_QOS_FROM_XML=1
ros2 run <package> <application>

16.1.2.2. Applying different profiles to different entities

rmw_fastrtps allows for the configuration of different entities with different QoS using the same XML file. For doing so, rmw_fastrtps locates profiles in the XML based on topic names.

16.1.2.2.1. Creating publishers/subscribers with different profiles

  • To configure a publisher, define a <data_writer> profile with attribute profile_name=topic_name, where topic_name is the name of the topic before mangling, i.e., the topic name used to create the publisher. If such profile is not defined, rmw_fastrtps attempts to load the <data_writer> profile with attribute is_default_profile="true".

  • To configure a subscriber, define a <data_reader> profile with attribute profile_name=topic_name, where topic_name is the name of the topic before mangling. If such profile is not defined, rmw_fastrtps attempts to load the <data_reader> profile with attribute is_default_profile="true".

16.1.2.2.2. Creating services with different profiles

ROS 2 services contain a subscriber for receiving requests, and a publisher to reply to them. rmw_fastrtps allows for configuring each of these endpoints separately in the following manner:

  • To configure the request subscriber, define a <data_reader> profile with attribute profile_name=topic_name, where topic_name is the name of the service after mangling. For more information on name mangling, please refer to Topic and Service name mapping to DDS. If such profile is not defined, rmw_fastrtps attempts to load a <data_reader> profile with attribute profile_name="service". If neither of the previous profiles exist, rmw_fastrtps attempts to load the <data_reader> profile with attribute is_default_profile="true".

  • To configure the reply publisher, define a <data_writer> profile with attribute profile_name=topic_name, where topic_name is the name of the service after mangling. If such profile is not defined, rmw_fastrtps attempts to load a <data_writer> profile with attribute profile_name="service". If neither of the previous profiles exist, rmw_fastrtps attempts to load the <data_writer> profile with attribute is_default_profile="true".

16.1.2.2.3. Creating clients with different profiles

ROS 2 clients contain a publisher to send requests, and a subscription to receive the service’s replies. rmw_fastrtps allows for configuring each of these endpoints separately in the following manner:

  • To configure the requests publisher, define a <data_writer> profile with attribute profile_name=topic_name, where topic_name is the name of the service after mangling. If such profile is not defined, rmw_fastrtps attempts to load a <data_writer> profile with attribute profile_name="client". If neither of the previous profiles exist, rmw_fastrtps attempts to load the <data_writer> profile with attribute is_default_profile="true".

  • To configure the reply subscription, define a <data_reader> profile with attribute profile_name=topic_name, where topic_name is the name of the service after mangling. If such profile is not defined, rmw_fastrtps attempts to load a <data_reader> profile with attribute profile_name="client". If neither of the previous profiles exist, rmw_fastrtps attempts to load the <data_reader> profile with attribute is_default_profile="true".

16.1.2.2.4. Creating ROS contexts and nodes

ROS context and node entities are mapped to Fast DDS Participant entity, according to the following table:

ROS entity

Fast DDS entity since Foxy

Fast DDS entity in Eloquent & below

Context

Participant

Not DDS direct mapping

Node

Not DDS direct mapping

Participant

This means that on Foxy and later releases, contexts can be configured using a <Participant> profile with attribute is_default_profile="true". The same profile will be used in Eloquent and below to configure nodes.

For example, a profile for a ROS 2 context on Foxy and later releases would be specified as:

XML

<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
    <participant profile_name="participant_profile_ros2" is_default_profile="true">
        <rtps>
            <name>profile_for_ros2_context</name>
        </rtps>
    </participant>
</profiles>

16.1.3. Example

The following example uses the ROS 2 talker/listener demo, configuring Fast DDS to publish synchronously, and to have dynamically allocated publisher and subscriber histories.

  1. Create a XML file ros_example.xml and save it in path/to/xml/

    XML

    <?xml version="1.0" encoding="UTF-8" ?>
    <profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
        <participant profile_name="participant_profile_ros2" is_default_profile="true">
            <rtps>
                <name>profile_for_ros2_context</name>
            </rtps>
        </participant>
    
        <!-- Default publisher profile -->
        <data_writer profile_name="default publisher profile" is_default_profile="true">
            <qos>
                <publishMode>
                    <kind>SYNCHRONOUS</kind>
                </publishMode>
            </qos>
            <historyMemoryPolicy>DYNAMIC</historyMemoryPolicy>
        </data_writer>
    
        <!-- Publisher profile for topic helloworld -->
        <data_writer profile_name="helloworld">
            <qos>
                <publishMode>
                    <kind>SYNCHRONOUS</kind>
                </publishMode>
            </qos>
        </data_writer>
    
        <!-- Request subscriber profile for services -->
        <data_reader profile_name="service">
            <historyMemoryPolicy>DYNAMIC</historyMemoryPolicy>
        </data_reader>
    
        <!-- Request publisher profile for clients -->
        <data_writer profile_name="client">
            <qos>
                <publishMode>
                    <kind>ASYNCHRONOUS</kind>
                </publishMode>
            </qos>
        </data_writer>
    
        <!-- Request subscriber profile for server of service "add_two_ints" -->
        <data_reader profile_name="rq/add_two_intsRequest">
            <historyMemoryPolicy>DYNAMIC</historyMemoryPolicy>
        </data_reader>
    
        <!-- Reply subscriber profile for client of service "add_two_ints" -->
        <data_reader profile_name="rr/add_two_intsReply">
            <historyMemoryPolicy>DYNAMIC</historyMemoryPolicy>
        </data_reader>
    </profiles>
    
  2. Open one terminal and run:

    export RMW_IMPLEMENTATION=rmw_fastrtps_cpp
    export FASTRTPS_DEFAULT_PROFILES_FILE=path/to/xml/ros_example.xml
    export RMW_FASTRTPS_USE_QOS_FROM_XML=1
    ros2 run demo_nodes_cpp talker
    
  3. Open one terminal and run:

    export RMW_IMPLEMENTATION=rmw_fastrtps_cpp
    export FASTRTPS_DEFAULT_PROFILES_FILE=path/to/xml/ros_example.xml
    export RMW_FASTRTPS_USE_QOS_FROM_XML=1
    ros2 run demo_nodes_cpp listener