The husarnet/ros2router Docker image is designed to effortlessly bridge local ROS 2 nodes, even those with standard DDS settings, to nodes on different machines across various networks. It runs seamlessly with the Husarnet VPN, ensuring that neither distance nor network differences become obstacles in your ROS 2 projects.

Compatible with both natively-executed ROS 2 nodes and those operating within Docker.

Based on DDS Router project by eProsima.

1. Run ROS 2 Nodes on Two Machines:

   Whether they're in the same LAN or different ones, execute the following on your first machine:

   ROS_LOCALHOST_ONLY=1
   ros2 run demo_nodes_cpp listener 

   And on your second machine:

   ROS_LOCALHOST_ONLY=1
   ros2 run demo_nodes_cpp talker

2. Husarnet Account Setup

• Register for a free account on app.husarnet.com.
• Establish a new Husarnet network in the Online Dashboard.
• Click the [Add element] button and copy the code under the Join Code tab.

3. Connect Devices to Husarnet:

   If you're on Ubuntu, follow these steps:

   • Install Husarnet:

   curl https://install.husarnet.com/install.sh | sudo bash

   • Connect to the Husarnet network:

   sudo husarnet join <paste-join-code-here>

4. Start the DDS Router Docker Image:

   Launch the following command on each host:

   docker run \
   --detach \
   --restart=unless-stopped \
   --network host \
   husarnet/ros2router:1.4.0

5. Verify Connection:

   Open the terminal for the listener. You should start seeing incoming messages.

This guide provides a straightforward setup. Dive deeper and explore additional options and examples in the sections below.

The all-in-one example, that should be fine in most cases (both with ROS 2 nodes running on host and in Docker containers) is in the demo/auto/general directory.

services:
  ros2router:
    image: husarnet/ros2router:1.8.0
    network_mode: host
    ipc: shareable
    volumes:
      - ./filter.yaml:/filter.yaml
    environment:
      - DISCOVERY_SERVER_ID=2
      - DISCOVERY_SERVER_LISTENING_PORT=8888
      - PARTICIPANTS=husarnet,shm
      - |
        CONFIG_BASE=
          version: v4.0
          specs:
            discovery-trigger: writer
          participants:
            - name: LocalParticipant
              kind: local
              domain: 0
              transport: builtin
      - ROS_DOMAIN_ID=123

  talker:
    image: husarion/ros2-demo-nodes:humble
    ipc: service:ros2router
    network_mode: service:ros2router
    volumes:
      - ./shm-only.xml:/shm-only.xml
    environment:
      - FASTRTPS_DEFAULT_PROFILES_FILE=/shm-only.xml
      - ROS_DOMAIN_ID=123
    command: ros2 run demo_nodes_cpp talker

# On the same host to connect to LocalParticipant, just execute:
# export ROS_LOCAHOST_ONLY=1
# ros2 run demo_nodes_cpp talker

# On the other host, to listen to /chatter topic:
# 
# Option 1: ROS 2 Iron (assuming "laptop" is the husarnet hostname of the host running ros2router):
# export ROS_DISCOVERY_SERVER=;;laptop:8888
# ros2 run demo_nodes_cpp listener
# 
# Option 2: ROS 2 Humble:
# Modify superclient.xml to point to the host with ros2router (line 31)
# export FASTRTPS_DEFAULT_PROFILES_FILE=${PWD}/superclient.xml
# ros2 run demo_nodes_cpp listener

The Docker image for the Husarnet ROS 2 Router can accept a portion of the typical ROS 2 Router configuration *.yaml file. This segment only includes the allowlist, blocklist, and builtin-topics sections. The provided configuration is then integrated with the automatically generated config file content.

Here's a sample of the filter.yaml file:

Example of the filter.yaml file:

allowlist:
  - name: "rt/camera/color/image_raw/theora"
    type: "theora_image_transport::msg::dds_::Packet_"
  - name: "rt/camera/color/image_raw/compressed"
    type: "sensor_msgs::msg::dds_::CompressedImage_"
  - name: "rt/cmd_vel"
    type: "geometry_msgs::msg::dds_::Twist_"
blocklist: []
builtin-topics: []

Note that each ROS 2 topic name is preceded with rX/ prefix (more here):

The repository includes the create_filter.sh script, which facilitates the automated creation of DDS Router filter rules:

curl -s https://raw.githubusercontent.com/husarnet/husarnet-ros2router/main/create_filter.sh > create_filter.sh
chmod +x create_filter.sh
./create_filter.sh /chatter /cmd_vel > filter.yaml

Modify the filter.yaml file if needed and assign it as a bind mount volume:

docker run \
--detach \
--restart=unless-stopped \
--network host \
-e ROS_DOMAIN_ID \
-v $(pwd)/filter.yaml:/filter.yaml \
husarnet/ros2router:1.2.0

1. Connect both hosts to the same Husarnet network (eg. named host_a and host_b).

2. On both host_a and host_b execute:

docker run \
--detach \
--restart=unless-stopped \
--network host \
-e ROS_DOMAIN_ID \
husarnet/ros2router:1.2.0

3. Start a chatter demo:

• on the host_a:

export ROS_LOCALHOST_ONLY=1 # is required to connect with a LocalUdpParticipant
ros2 run demo_nodes_cpp talker

• on the host_b:

export ROS_LOCALHOST_ONLY=1 # is required to connect with a LocalUdpParticipant
ros2 run demo_nodes_cpp listener

1. Connect both hosts to the same Husarnet network (eg. named host_a and host_b).

2. Execute on host_a:

docker run \
--detach \
--restart=unless-stopped \
--network host \
-e DISCOVERY_SERVER_PORT="11888" \
husarnet/ros2router:1.2.0

3. Execute on host_b:

docker run \
--detach \
--restart=unless-stopped \
--network host \
-e ROS_DISCOVERY_SERVER="host_a:11888" \
husarnet/ros2router:1.2.0

4. Start a chatter demo:

• on the host_a:

export ROS_LOCALHOST_ONLY=1 # is required to connect with a LocalUdpParticipant
ros2 run demo_nodes_cpp talker

• on the host_b:

export ROS_LOCALHOST_ONLY=1 # is required to connect with a LocalUdpParticipant
ros2 run demo_nodes_cpp listener

1. Connect both hosts to the same Husarnet network (eg. named host_a and host_b).

2. Create a DDS Router config file on the host_a:

user@host_a:~$ vim config.yaml

with the following content:

version: v3.0

allowlist:
  - name: "rt/chatter"
    type: "std_msgs::msg::dds_::String_"

participants:

  - name: SimpleParticipant
    kind: local
    domain: 0

  - name: ServerDSParticipant
    kind: local-discovery-server
    discovery-server-guid:
      id: 200
    listening-addresses:
      - domain: host_a
        port: 11811
        transport: udp

3. Create a DDS Router config file on the host_b:

user@host_b:~$ vim config.yaml

with the following content:

version: v3.0

allowlist:
  - name: "rt/chatter"
    type: "std_msgs::msg::dds_::String_"

participants:

  - name: SimpleParticipant
    kind: local
    domain: 0

  - name: ClientDSParticipant
    kind: local-discovery-server
    discovery-server-guid:
      id: 202
    connection-addresses:
      - discovery-server-guid:
          id: 200
        addresses:
          - domain: host_a 
            port: 11811
            transport: udp

4. On both host_a and host_b execute (in the same folder as config.yaml file):

docker run --name ros2router \
  --restart=unless-stopped \
  --network host \
  --ipc host \
  --user $(id -u):$(id -g) \
  -v $(pwd)/config.yaml:/config.yaml \
  -v /etc/group:/etc/group:ro \
  -v /etc/passwd:/etc/passwd:ro \
  -v /etc/shadow:/etc/shadow:ro \
  -e AUTO_CONFIG=FALSE \
  husarnet/ros2router:1.2.0 bash -c "ddsrouter -c /config.yaml -r 10"

5. Start a chatter demo:

• on the host_a:

export ROS_DOMAIN_ID=0
ros2 run demo_nodes_cpp talker

• on the host_b:

export ROS_DOMAIN_ID=0
ros2 run demo_nodes_cpp listener