4. 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.

4.1. Topic Filtering

Note

The DDS Router topic discovery module is a work in progress. Thus, the functionality regarding Topic filtering is still in its early stages.

The DDS Router requires a list of allowed Topics. The data transmitted under these topics will be the data relayed by the DDS Router. The YAML configuration file must contain an allowlist tag which is a vector ([]). This vector elements contains the Topics that will be forwarded (subsequently the DDS Router creates a Writers and Readers for each topic for each Participant). See Topic section for further information about the topic.

In the following configuration example, the DDS Router will transmit the topic rt/chatter (default ROS 2 topic for talker and listener) with type name std_msgs::msg::dds_::String_. It also will transmit the topic HelloWorldTopic (default FastDDS topic for HelloWorldExample) with type name HelloWorld.

allowlist:
[
    {name: "rt/chatter", type: "std_msgs::msg::dds_::String_"},
    {name: "HelloWorldTopic", type: "HelloWorld"},
]

Note

Tag allowlist must be at yaml base level (it must not be inside any other tag).

4.2. Participant Configuration

At the yaml base level, along with allowlist tag, there will be the Participants that will be created, together with their specific configuration. Each Participant is identified by a unique Participant Id that will be the yaml key. The yaml value for this key is the configuration for this specific Participant. There could be any number of Participants, and Participant types could be repeated.

Each Participant has its specific configuration. Please, refer to Participant types in order to see each of the Participant Types requirements.

Warning

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 domain 1. 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.

Participant0:       # Participant Id = Participant0
    type: local     # Participant Type = simple
    domain: 3       # DomainId = 3

################

simple:             # Participant Id = simple ; Participant Type = simple
    domain: 6       # DomainId = 6

The first Participant Participant0 has Participant Id Participant0 and is configured to be of the simple Participant Type. The second Participant has Participant Id simple and it is configured to be of the simple type. That is because the type is not required to be specified as it is get from the Participant Id.

Note

Participant Type is not case sensitive. A Participant called Simple would be of type simple.

Note

The Participant Id is get as Participant Type when type is not specified. If type is explicitly specified, the Participant Id is not used to get the type.

4.3. Domain Id

Tag domain configures the Domain Id of a specific Participant. Be aware that some Participants (e.g. Discovery Servers) does not need a Domain Id configuration.

domain: 101

4.4. 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.

  • Transport Protocol: UDP or TCP. If it is not set, it would be chosen by default depending on the Participant Type.

  • IP version: v4 or v6. If it is not set, it would be chosen depending on the IP string format.

ip: "127.0.0.1"
port: 11666
transport: "tcp"
ip-version: "v4"

################

ip: "2001:4860:4860::8844"      # Recognized as IPv6
port: 1616

Warning

ip field does not currently support DNS names, only well-formed IP addresses.

4.5. Discovery Server GuidPrefix

A Discovery Server requires a DDS GuidPrefix in order to other Participants connect to it. There are several possibilities for configuring a GuidPrefix.

4.5.1. Discovery Server GuidPrefix by string

The GuidPrefix of the Discovery Server can be configured using guid tag. Be aware of using the correct format for GuidPrefix. That is, 12 hexadecimal numbers (lower than ff) separated with ..

guid: "1.f.1.0.0.0.0.0.0.0.ca.fe"       # GuidPrefix = 01.0f.01.00.00.00.00.00.00.00.ca.fe

4.5.2. Discovery Server GuidPrefix by Id

Using tag id, the GuidPrefix will be calculated arbitrarily using a default DDS Router GuidPrefix. This default GuidPrefix is 01.0f.<id>.00.00.00.00.00.00.00.ca.fe. Default value for id is 0.

id: 13                                  # GuidPrefix = 01.0f.0d.00.00.00.00.00.00.00.ca.fe

Note

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.

4.5.3. ROS Discovery Server GuidPrefix

There is a specific GuidPrefix for ROS 2 executions, so it could be used using Fast DDS CLI and ROS 2 ROS_DISCOVERY_SERVER environment variable (https://fast-dds.docs.eprosima.com/en/v2.4.1/fastdds/ros2/discovery_server/ros2_discovery_server.html).

The ROS 2 Discovery Server GuidPrefix is set by default to 44.53.<id>.5f.45.50.52.4f.53.49.4d.41 where <id> is the specific id of the Server. This GuidPrefix also allow an id` value to specify which id is used in the GuidPrefix. Default value for id is 0.

ros-discovery-server: true              # GuidPrefix = 44.53.x.5f.45.50.52.4f.53.49.4d.41
id: 13                                  # GuidPrefix = 44.53.0d.5f.45.50.52.4f.53.49.4d.41

4.6. Discovery Server Listening Addresses

Tag listening-addresses configures the network addresses where the Discovery Server configured is going to listen for remote clients or servers. listening-addresses is key for an array of Network Addresses.

listening-addresses:
[
    {                                   # UDP by default
        ip: "127.0.0.1",
        port: 11667,
    },
    {
        ip: "2001:4860:4860::8844",     # Recognized as IPv6
        port: 11668,
        transport: "tcp"
    }
]

4.7. Discovery Server Connection Addresses

Tag 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:
[
    {
        guid: "44.53.0d.5f.45.50.52.4f.53.49.4d.41"
        addresses:
        [
            {
                ip: "127.0.0.1",
                port: 11666,
            }
        ]
    },
    {
        id: 4,
        addresses:
        [
            {
                ip: "2001:4860:4860::8888",
                port: 11667,
                transport: "tcp"
            },
            {
                ip: "2001:4860:4860::8844",
                port: 11668,
                transport: "tcp"
            }
        ]
    }
]

4.8. General Example

A complete example of all the configurations described on this page can be found below.

# Relay topic rt/chatter and type std_msgs::msg::dds_::String_
# Relay topic HelloWorldTopic and type HelloWorld

allowlist:
[
    {name: "rt/chatter", type: "std_msgs::msg::dds_::String_"},
    {name: "HelloWorldTopic", type: "HelloWorld"},
]

####################

# Simple DDS Participant in domain 3

Participant0:                       # Participant Id = Participant0

    type: local                     # Participant Type = 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

simple:                             # Participant Id = simple

    type: "local-discovery-server"  # Participant Type = local-discovery-server

    id: 1
    ros-discovery-server: true      # ROS Discovery Server id => GuidPrefix = 44.53.01.5f.45.50.52.4f.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
            transport: "UDP",       # Transport = UDP
        }
    ]

####################

# Participant that will communicate with a DDS Router in a different LAN.
# This Participant will work as the remote DDS Router Client, so it set the connection address of the remote one.

Wan:                                # Participant Id = simple ; Participant Type = wan

    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
    [
        {
            id: 4,                   # External WAN Discovery Server id => GuidPrefix = 01.0f.04.00.00.00.00.00.00.00.ca.fe
            addresses:
            [
                {
                    ip: "8.8.8.8",          # IP = 8.8.8.8 ; transport = TCP (by default)
                    port: 11666,            # Port = 11666
                }
            ]
        }
    ]