You're reading the documentation for an older, but still supported, version of ROS 2. For information on the latest version, please have a look at Jazzy.

Improved Dynamic Discovery

Goal: This tutorial will show how to use the improved dynamic discovery configuration.

Tutorial level: Advanced

Time: 15 minutes

Overview

By default, ROS 2 will attempt to find all nodes on all hosts on the same subnet automatically. However, the following options are available to control the ROS 2 discovery range.

Configuration Parameters

  • ROS_AUTOMATIC_DISCOVERY_RANGE: controls how far ROS nodes will try to discover each other.

    Valid options are:

    • SUBNET is the default, and for DDS based middleware it means it will discover any node reachable via multicast.

    • LOCALHOST means a node will only try to discover other nodes on the same machine.

    • OFF means the node won’t discover any other nodes, even on the same machine.

    • SYSTEM_DEFAULT means “don’t change any discovery settings”.

  • ROS_STATIC_PEERS: is a semicolon (;) separated list of addresses that ROS should try to discover nodes on. This allows connecting to nodes on specific machines (as long as their discovery range is not set to OFF).

The combination of these two environment variables for local and remote nodes will enable and control the ROS 2 communication discovery range. The following tables highlight the discovery range behavior for possible combination.

A X indicates that nodes A and B will not discover each other and communicate. A O indicates that nodes A and B will discover each other and communicate.

Node A and B running in the same host

Same host

Node B setting

No static peer

With static peer

Off

Localhost

Subnet

Off

Localhost

Subnet

Node A setting

No static peer

Off

X

X

X

X

X

X

Localhost

X

O

O

X

O

O

Subnet

X

O

O

X

O

O

With static peer

Off

X

X

X

X

X

X

Localhost

X

O

O

X

O

O

Subnet

X

O

O

X

O

O
Node A and B running in the different hosts

Different hosts

Node B setting

No static peer

With static peer

Off

Localhost

Subnet

Off

Localhost

Subnet

Node A setting

No static peer

Off

X

X

X

X

X

X

Localhost

X

X

X

X

O

O

Subnet

X

X

O

X

O

O

With static peer

Off

X

X

X

X

X

X

Localhost

X

O

O

X

O

O

Subnet

X

O

O

X

O

O

Examples

For example, the following commands will limit the ROS 2 communication only with localhost and specific peers:

export ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST
export ROS_STATIC_PEERS=192.168.0.1;remote.com

To maintain this setting between shell sessions, you can add the command to your shell startup script:

echo "export ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST" >> ~/.bashrc
echo "export ROS_STATIC_PEERS=192.168.0.1;remote.com" >> ~/.bashrc