For supported ROS 2 middleware, ROS_AUTOMATIC_DISCOVERY_RANGE controls the scope of automatic discovery, while ROS_STATIC_PEERS names remote addresses to try explicitly. Use them to describe which machines should find one another before debugging topic delivery. Check the effective settings on both endpoints, because one terminal’s environment does not describe the whole graph.
This is useful in a lab with several robots sharing a network. A laptop intended to inspect one robot should not accidentally join every nearby experiment merely because the topic names happen to match.
Choose the automatic scope first
The official documentation at the checked revision defines four values. SUBNET uses the default discovery scope, described for DDS middleware as nodes reachable through multicast. LOCALHOST restricts automatic discovery to the same machine. OFF disables discovery even for other local nodes. SYSTEM_DEFAULT leaves discovery settings to the underlying system configuration.
Choose the value according to the intended graph, then record the domain ID and middleware implementation separately. A discovery-range setting is not a replacement for knowing which ROS domain the endpoints use.
| Intended arrangement | Starting question |
|---|---|
| Processes only on one computer | Can automatic discovery remain local? |
| Nodes throughout a lab subnet | Is multicast discovery appropriate on this network? |
| One robot and named remote computers | Which explicit peer addresses should be attempted? |
| Existing middleware XML configuration | Should ROS leave that configuration unchanged? |
This table is a design aid, not a substitute for testing the selected RMW and network.
Static peers can extend a local automatic scope
The same documentation defines ROS_STATIC_PEERS as a semicolon-separated address list. Its cross-host matrix permits explicit-peer discovery with a local automatic scope when the counterpart’s discovery is not off. The peer list and automatic range therefore need to be interpreted together.
For a hypothetical laptop and robot, write down the intended relationship in both directions. Record which address the laptop tries and which setting the robot starts with. A correct hostname in a note is insufficient if the robot resolves it differently or the launched process inherited another environment.
When setting a semicolon-separated value in a shell, preserve it as one value using that shell’s quoting rules. Do not transplant a Bash command into PowerShell or a Windows command-prompt example without checking its syntax. Prefer a temporary per-process configuration during the first test, then make it persistent only after the graph matches the intended arrangement.
Check the RMW before applying the recipe
The checked ROS documentation explicitly excludes rmw_zenoh from support for these two environment variables and points to Zenoh’s own configuration. Applying DDS-oriented discovery variables to a Zenoh process would leave the actual router and session arrangement unexplained.
Also distinguish SYSTEM_DEFAULT from OFF. The former delegates configuration; the latter disables discovery in the documented behavior. Similar-looking “disable the default” intentions can therefore produce very different results.
Discovery settings control how participants find one another. If the requirement is authorization or protected communications, use the applicable security configuration as a separate design decision. A selected discovery range describes connectivity scope, not who is trusted to send a robot command.
Verify discovery before delivery
Start the intended pair with recorded settings, inspect whether each endpoint appears, then check the required topic’s type and QoS. Repeat after restarting one endpoint and after starting them in the opposite order. Include a machine that should remain outside the intended graph.
The ROS 2 QoS guide covers the next layer: discovered publishers and subscribers still need compatible delivery policies. Keep “endpoint discovered,” “message received” and “message fresh enough for the consumer” as separate observations.
The pinned documentation was checked October 16, 2026. No network or environment variable was changed for this article. The useful troubleshooting artifact is a small endpoint map containing host, domain, RMW, automatic range, explicit peers and observed communication.