3. DDS Router Configuration¶
A DDS Router is configured by a .yaml configuration file. This .yaml file contains all the information regarding the DDS Router configuration, such as topics filtering and Participants configurations. Configuration files may be easily validated by using the YAML Validator tool.
3.1. Configuration version¶
The YAML Configuration supports a
version value to identify the configuration version to parse the file.
In future releases the YAML format (some key words,
fields, etc.) may change.
This value allows users to keep using the same YAML file with an old configuration format, maintaining compatibility
with future releases.
DDS Router activation release
version 3.0 (default)
Current configuration version is v3.0. This is the configuration version that is described along this page.
The current default version when the tag
version is not set is v3.0.
In future releases, the tag
version will be mandatory.
Deprecation warning. Update to version v3.0 since v1.0 is no longer supported.
3.2. Specs Configuration¶
The YAML Configuration supports a
specs optional tag that contains certain options related with the
overall configuration of the DDS Router instance to run.
The values available to configure are:
3.2.1. Number of Threads¶
specs supports a
threads optional value that allows the user to set a maximum number of threads
for the internal
This ThreadPool allows to limit the number of threads spawned by the application.
This improves the performance of the data transmission between Participants.
This value should be set by each user depending on each system’s characteristics.
In case this value is not set, the default number of threads used is
3.2.2. Maximum History Depth¶
specs supports a
max-depth optional value that configures the history size
of the Fast DDS internal entities.
By default, the depth of every RTPS History instance is
5000, which sets a constraint on the maximum number of
samples a DDS Router instance can deliver to late joiner Readers configured with
Its value should be decreased when the sample size and/or number of created endpoints (increasing with the number of
topics and DDS Router participants) are as big as to cause memory exhaustion issues.
Likewise, one may choose to increase this value if wishing to deliver a greater number of samples to late joiners and
enough memory is available.
3.3. Load XML Configuration¶
Fast DDS supports configuration of its internal entities (DomainParticipant, DataWriter, etc.) via XML Profiles. These XML files contain different profiles that set specific QoS, and entities can be created following such profiles. These XML files can be loaded in the process by their default file name or by an environment variable. Check the Fast DDS documentation <https://fast-dds.docs.eprosima.com/en/latest/fastdds/xml_configuration/xml_configuration.html> for more information.
Another way of loading these XML configurations is using the DDS Router yaml configuration.
The YAML Configuration supports a
xml optional tag that contains certain options to load Fast DDS XML configurations.
XML configurations are then used to configure an XML Participant.
3.3.1. Load XML Files¶
Under the optional tag files, a list can be set with the names of files to load XML from.
3.3.2. Raw XML¶
Under the optional tag raw, an XML configuration (with the same format as an XML file) can be set as a string to be loaded.
xml: files: - "./xml_configuration.xml" raw: | <?xml version="1.0" encoding="UTF-8" ?> <profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles" > <participant profile_name="custom_participant_configuration"> <domainId>1</domainId> <rtps></rtps> </participant> </profiles>
3.4. Built-in Topics¶
Apart from the dynamic creation of Endpoints in DDS Topics discovered,
the discovery phase can be accelerated by using the builtin topic list (
By defining topics in this list, the DDS router will create the DataWriters and DataReaders in router initialization.
This feature also allows to manually force the QoS of a specific topic, so the entities created in such a topic
will follow the specified QoS and not the one first discovered.
3.4.1. Topic Quality of Service¶
For every topic contained in this list, both
type must be specified and contain no wildcard
characters. The entry
keyed is optional, and defaults to
Apart from these values, the tag
qos under each topic allows to configure the following values:
Quality of Service
Writers and Readers History Depth
Topic with / without partitions
Topic with / without key
builtin-topics: - name: HelloWorldTopic type: HelloWorld qos: reliability: true # Use QoS RELIABLE durability: true # Use QoS TRANSIENT_LOCAL depth: 100 # Use History Depth 100 partitions: true # Topic with partitions ownership: false # Use QoS SHARED_OWNERSHIP_QOS keyed: false # Topic without keys
3.5. Topic Filtering¶
DDS Router includes a mechanism to automatically detect which topics are being used in a DDS network. By automatically detecting these topics, a DDS Router creates internal DDS Writers and Readers for each topic and for each Participant in order to relay the data published on each discovered topic.
DDS Router entities are created with the QoS of the first Subscriber found in this Topic.
DDS Router allows filtering of DDS Topics, that is, it allows to define which DDS Topics are going to be relayed by the application. This way, it is possible to define a set of rules in DDS Router to filter those data samples the user does not wish to forward.
It is not mandatory to define such set of rules in the configuration file. In this case, a DDS Router will forward all the data published under the topics that it automatically discovers within the DDS network to which it connects.
To define these data filtering rules based on the Topics to which they belong, three lists are available:
Allowed topics list (
Block topics list (
Builtin topics list (
These three lists of topics listed above are defined by a tag in the YAML configuration file, which defines a
YAML vector (
This vector contains the list of topics for each filtering rule.
Each Topic is determined by its entries
type, with only the first one being mandatory.
builtin-topics must be at yaml base level (it must not be inside any
Placing quotation marks around values in a YAML file is generally optional. However, values containing wildcard characters must be enclosed by single or double quotation marks.
3.5.1. Allow topic list (
This is the list of topics that DDS Router will forward, i.e. the data published under the topics matching the
expressions in the
allowlist will be relayed by DDS Router.
allowlist is provided, data will be forwarded for all topics (unless filtered out in
3.5.2. Block topic list (
This is the list of topics that the DDS Router will block, that is, all data published under the topics matching the
filters specified in the
blocklist will be discarded by the DDS Router and therefore will not be relayed.
This list takes precedence over the
If a topic matches an expression both in the
allowlist and in the
blocklist takes precedence,
causing the data under this topic to be discarded.
3.5.3. Examples of usage¶
The following is an example of how to use the
builtin-topics configurations to
setup the DDS Router filtering rules.
188.8.131.52. Dynamic topic discovery example¶
This example shows how the DDS Router is initially configured to forward the
rt/chatter topic (default ROS 2
listener) with type name
std_msgs::msg::dds_::String_, while the rest of the
topics in the DDS network are expected to be dynamically discovered.
Additionally, two rules are specified in the
blocklist in order to filter out messages of no interest to the user
(in this case ROS2 services related topics).
builtin-topics: - name: rt/chatter type: std_msgs::msg::dds_::String_ blocklist: - name: "rq/*" - name: "rr/*"
184.108.40.206. Allowlist and blocklist collision¶
In the following example, the
HelloWorldTopic topic is both in the
allowlist and (implicitly) in the
blocklist, so according to the
blocklist preference rule this topic is blocked.
Moreover, only the topics present in the allowlist are relayed, regardless of whether more topics are dynamically
discovered in the DDS network.
In this case the forwarded topics are
AllowedTopic1 with data type
AllowedTopic2 regardless of its data type.
allowlist: - name: AllowedTopic1 type: Allowed - name: AllowedTopic2 type: "*" - name: HelloWorldTopic type: HelloWorld blocklist: - name: "*" type: HelloWorld
3.6. Participant Configuration¶
At the yaml base level, along with the
builtin-topics tag, there will be the tag
participants to handle an array of Participant configurations.
Each Participant is identified by a unique Participant Name and requires to set the
kind of the Participant.
There can be any number of Participants, and Participant kinds can be repeated.
Do not configure two Participants in a way that they can communicate to each other (e.g. two Simple participants in the same domain). This will lead to an infinite feedback loop between each other.
In the following configuration example, the DDS Router will create two
Simple Participants, one for
domain 0 and one for
This is a typical use case of DDS Domain bridge.
The topics allowed in the two domains will start communicating to each other.
Note that the communication is not P2P performed between the end-user DDS entities,
i.e. the data must reach the DDS Router and this will forward the data.
participants: # Tag to introduce the participants configurations array ################ - name: Participant0 # Participant Name = Participant0 kind: local # Participant Kind = simple domain: 0 # DomainId = 0 ################ - name: my_custom_part # Participant Name = my_custom_part kind: simple # Participant Kind = echo domain: 1 # DomainId = 1
The first Participant Participant0 has Participant Name Participant0 and is configured to be of the simple Participant Kind, and to communicate locally in domain 0. The second Participant has Participant Name simple and it is configured to be of the simple kind and to communicate locally with domain 1.
3.6.1. Domain Id¶
domain configures the Domain Id of a specific Participant.
Be aware that some Participants (e.g. Discovery Servers) do not need a Domain Id configuration.
3.6.2. Ignore Participant Flags¶
A set of discovery traffic filters can be defined for Simple Participants in order to add an extra level of isolation.
This configuration option can be set through the
ignore-participant-flags: no_filter # No filter (default) # or ignore-participant-flags: filter_different_host # Discovery traffic from another host is discarded # or ignore-participant-flags: filter_different_process # Discovery traffic from another process on same host is discarded # or ignore-participant-flags: filter_same_process # Discovery traffic from own process is discarded # or ignore-participant-flags: filter_different_and_same_process # Discovery traffic from own host is discarded
See Ignore Participant Flags for more information.
3.6.3. Custom Transport Descriptors¶
By default, Simple Participants are created with enabled UDP and Shared Memory transport descriptors.
The use of one or the other for communication will depend on the specific scenario, and whenever both are viable candidates, the most efficient one (Shared Memory Transport) is automatically selected.
However, a user may desire to force the use of one of the two, which can be accomplished via the
transport configuration tag in Simple Participants.
transport: builtin # UDP & SHM (default) # or transport: udp # UDP only # or transport: shm # SHM only
Participants configured with
transport: shm will only communicate with applications using Shared Memory Transport exclusively (with disabled UDP transport).
3.6.4. Interface Whitelist¶
whitelist-interfaces allows to limit the network interfaces used by UDP and TCP transport.
This may be useful to only allow communication within the host (note: same can be done with Ignore Participant Flags), or in the WAN scenario one may choose to only communicate through the Ethernet or WiFi interface (when both available).
whitelist-interfaces: - "127.0.0.1" # Localhost only
See Interface Whitelist for more information.
When providing an interface whitelist, external participants with which communication is desired must also be configured with interface whitelisting.
3.6.5. Repeater Participant¶
The optional tag
repeater configures a WAN Participant as a Repeater point.
This means that this Participant will forward all the information received from its Readers to its Writers.
Check the Repeater DDS Router use case to see how the
repeater Participant attribute is used.
This tag is only supported in configuration versions above v2.0.
3.6.6. Network Address¶
Network Addresses are elements that can be configured for specific Participants. An Address is defined by:
IP: IP of the host (public IP in case of WAN communication).
Port: Port where the Participant is listening.
External Port: Public port accessible for external entities (only for TCP).
TCP. If it is not set, it would be chosen by default depending on the Participant Kind.
v6. If it is not set, it would be chosen depending on the IP string format.
Domain Name: Domain’s unique name to ask the DNS server for the related IP. This field is ignored if
ip: 127.0.0.1 port: 11666 external-port: 11670 transport: tcp ip-version: v4 ################ ip: 2001:4860:4860::8844 # Recognized as IPv6 port: 1616 transport: udp ################ domain: localhost # DNS call return value = 127.0.0.1 port: 33333 # Uses UDP by default
3.6.7. External Port¶
External port is used to configure a Server (Discovery Server or Initial Peers) that runs under a NAT and uses TCP transport. This value could be set in a TCP listening address to differentiate the public and the internal port. In case this value is not set, the external port is considered to be the same as the internal one. If both ports coincide, external and internal port in the network router port forwarding rules must coincide. For more information, check section External port.
3.6.8. Discovery Server GuidPrefix¶
220.127.116.11. Discovery Server GuidPrefix by string¶
The GuidPrefix of the Discovery Server can be configured using
Be aware of using the correct format for GuidPrefix.
That is, 12 hexadecimal numbers (lower than
ff) separated with
discovery-server-guid: guid: "1.f.18.104.22.168.0.0.0.0.ca.fe" # GuidPrefix = 01.0f.01.00.00.00.00.00.00.00.ca.fe
22.214.171.124. Discovery Server GuidPrefix by Id¶
id, the GuidPrefix will be calculated arbitrarily using a default DDS Router GuidPrefix.
This default GuidPrefix is
Default value for
This entry is ignored if
guid is specified.
discovery-server-guid: id: 13 # GuidPrefix = 01.0f.0d.00.00.00.00.00.00.00.ca.fe
In the current version of the DDS Router only ids in the range 0 to 256 are allowed. In future releases it would be implemented to allow a wider range of ids.
126.96.36.199. ROS Discovery Server GuidPrefix¶
There is a specific GuidPrefix for ROS 2 executions which can be used with Fast DDS CLI and
ROS_DISCOVERY_SERVER environment variable
The ROS 2 Discovery Server GuidPrefix is set by default to
is the specific id of the Server.
This GuidPrefix also allows an
id` value to specify which id is used in the GuidPrefix.
The default value for
discovery-server-guid: ros-discovery-server: true # GuidPrefix = 44.53.x.5f.188.8.131.52f.53.49.4d.41 id: 13 # GuidPrefix = 44.53.0d.5f.184.108.40.206f.53.49.4d.41
3.6.9. Listening Addresses¶
listening-addresses configures the network addresses where this Participant is going to
listen for remote Participants.
listening-addresses is key for an array of Network Addresses.
listening-addresses: - ip: 127.0.0.1 # UDP by default port: 11667 - ip: 2001:4860:4860::8844 # Recognized as IPv6 port: 11666 external-port: 11668 transport: tcp
3.6.10. Initial Peers Connection Addresses¶
connection-addresses configure a connection with one or multiple remote WAN Participants.
connection-addresses is key for an array of Network Addresses.
connection-addresses: - ip: 127.0.0.1 port: 11666 - ip: 2001:4860:4860::8844 port: 11668 transport: tcp
3.6.11. Discovery Server Connection Addresses¶
connection-addresses configure a connection with one or multiple remote Discovery Servers.
connection-addresses is the key for an array in which each element has a GuidPrefix referencing the Discovery
Server to connect with; and a tag
addresses configuring the addresses of such Discovery Server.
Each element inside
addresses must follow the configuration for Network Address.
connection-addresses: - discovery-server-guid: guid: 44.53.0d.5f.220.127.116.11f.53.49.4d.41 addresses: - ip: 127.0.0.1 port: 11666 - discovery-server-guid: id: 4 addresses: - ip: 2001:4860:4860::8888 port: 11667 transport: tcp - ip: 2001:4860:4860::8844 port: 11668 transport: tcp
3.7. General Example¶
A complete example of all the configurations described on this page can be found below.
# Version Latest version: v3.0 # Specifications specs: threads: 10 max-depth: 1000 # XML configurations to load xml: # Load this file as Fast DDS XML configuration files: - "./xml_configuration.xml" # Load text as Fast DDS XML configuration raw: | <?xml version="1.0" encoding="UTF-8" ?> <profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles" > <participant profile_name="custom_participant_configuration"> <domainId>1</domainId> <rtps></rtps> </participant> </profiles> # Relay topic rt/chatter and type std_msgs::msg::dds_::String_ # Relay topic HelloWorldTopic and type HelloWorld builtin-topics: - name: rt/chatter type: std_msgs::msg::dds_::String_ - name: HelloWorldTopic type: HelloWorld qos: reliability: true durability: true # Do not allow ROS2 services blocklist: - name: "rr/*" - name: "rq/*" participants: #################### # Simple DDS Participant in domain 3 - name: Participant0 # Participant Name = Participant0 kind: local # Participant Kind = local (= simple) domain: 3 # DomainId = 3 #################### # Discovery Server DDS Participant with ROS GuidPrefix so a local ROS 2 Client could connect to it # This Discovery Server will listen in ports 11600 and 11601 in localhost - name: ServerROS2 # Participant Name = ServerROS2 kind: local-discovery-server # Participant Kind = local-discovery-server discovery-server-guid: id: 1 ros-discovery-server: true # ROS Discovery Server id => GuidPrefix = 44.53.01.5f.18.104.22.168f.53.49.4d.41 listening-addresses: # Local Discovery Server Listening Addresses - ip: 127.0.0.1 # IP = localhost ; Transport = UDP (by default) port: 11600 # Port = 11600 - ip: 127.0.0.1 # IP = localhost port: 11601 # Port = 11601 external-port: 11602 # External Port = 11602 transport: tcp # Transport = TCP connection-addresses: - discovery-server-guid: id: 2 ros-discovery-server: true addresses: - domain: "localhost" port: 22000 #################### # Participant that will communicate with a DDS Router in a different LAN. # This Participant will work as the remote DDS Router Client, so it sets the connection address of the remote one. - name: Wan # Participant Name = Wan kind: wan-ds # Participant Kind = Discovery Server WAN discovery-server-guid: id: 2 # Internal WAN Discovery Server id => GuidPrefix = 01.0f.02.00.00.00.00.00.00.00.ca.fe connection-addresses: # WAN Discovery Server Connection Addresses - discovery-server-guid: id: 4 # External WAN Discovery Server id => GuidPrefix = 01.0f.04.00.00.00.00.00.00.00.ca.fe addresses: - ip: 22.214.171.124 # IP = 126.96.36.199 port: 11666 # Port = 11666 transport: udp # Transport = UDP #################### # Participant that will use a user set configuration via QoS Profile. - name: xml_participant # Participant Name = xml_participant kind: xml profile: custom_participant_configuration # Configure participant with this profile