Skip to content

Networking

Configure ros-z's Eclipse Zenoh transport layer for optimal performance in your deployment environment. ros-z uses router-based architecture by default, matching ROS 2's official rmw_zenoh_cpp middleware for production-ready scalability.

graph TB
    Router["zenohd (router)"]

    Talker["Talker node (peer)"]
    Listener["Listener node (peer)"]

    Router <-->|Discovery| Talker
    Router <-->|Discovery| Listener
    Talker <-.->|P2P Communication| Listener

How ROS 2 Discovery Works

ROS 2 nodes find each other automatically through a discovery process — no central registry or manual configuration needed. Discovery scope depends on ROS domain: only nodes with the same ROS_DOMAIN_ID can see each other (default: 0). The standard ROS 2 middleware (DDS) uses multicast UDP to announce node presence on the local network. Once discovered, nodes check QoS compatibility — connections only form when publisher and subscriber have compatible settings.

The discovery cycle:

  1. Announce: a new node broadcasts its presence and advertises its publishers, subscribers, services, and actions
  2. Respond: existing nodes reply with their own information; endpoints with matching topics negotiate connections
  3. Periodic heartbeat: nodes re-broadcast periodically so nodes that join later can discover the system
  4. Departure: nodes announce when going offline (best-effort — the system may not detect crashes immediately)

Why ros-z replaces DDS discovery with Zenoh:

Standard DDS multicast discovery has known limitations:

  • Cloud networks and containers often block multicast/container networks and across subnets
  • Discovery traffic grows quadratically with node count in large systems
  • Configuration (tuning QoS, domain separation) is complex

ros-z and rmw_zenoh_cpp use router-based discovery instead. All nodes connect to a zenohd router via TCP. The router acts as the rendezvous point — nodes announce themselves to the router, which propagates the information to interested peers. This works across subnets, containers, and cloud environments without multicast, and scales linearly: adding more nodes does not increase per-node discovery traffic.

sequenceDiagram
    participant R as zenohd (router)
    participant A as Node A (Publisher)
    participant B as Node B (Subscriber)

    A->>R: Connect + declare publisher on /chatter
    B->>R: Connect + declare subscriber on /chatter
    R->>A: Subscriber joined /chatter
    R->>B: Publisher available on /chatter
    Note over A,B: Connection negotiated — data flows
    A->>B: Messages (Eclipse Zenoh transport)

QoS and discovery: even after discovery, a publisher and subscriber will not exchange messages if their QoS policies are incompatible (e.g., a best-effort publisher and a reliable subscriber). ros-z checks compatibility at connection time.

The following sections describe how to configure ros-z's router connection for your deployment environment.

Router-Based Architecture

ros-z uses a centralized Zenoh router for node discovery and communication, providing:

Benefit Description
Scalability Centralized discovery handles large deployments efficiently
Lower Network Overhead TCP-based discovery instead of multicast broadcasts
ROS 2 Compatibility Matches rmw_zenoh_cpp behavior for seamless interoperability
Production Ready Battle-tested configuration used in real robotics systems

Quick Start

The default ros-z configuration connects to a Zenoh router on tcp/localhost:7447:

use ros_z::context::ZContextBuilder;
use ros_z::Builder;

// Uses default ROS session config (connects to tcp/localhost:7447)
let ctx = ZContextBuilder::default().build()?;
let node = ctx.create_node("my_node").build()?;

Success

That's it! The default configuration automatically connects to the router. Now you need to run one.

Running the Zenoh Router

ros-z applications require a Zenoh router to be running. There are several ways to get one - choose based on your environment and requirements.

Quick Comparison

Method Best For Requires Setup Speed
Cargo Install Rust developers Rust toolchain Slower (build from source)
Pre-built Binary Quick setup, no Rust None Fast
Docker Containers, CI/CD Docker Fast
Package Manager System-wide install apt/brew/etc Fast
ros-z Example ros-z repo developers ros-z repository Fast
ROS 2 rmw_zenoh ROS 2 interop testing ROS 2 installed Already installed

Method 1: Cargo Install

Recommended for Rust developers building standalone projects.

Install the official Zenoh router using Cargo:

cargo install zenohd

Run the router:

zenohd

Pros:

  • Always up-to-date with latest Zenoh
  • Builds optimized for your system
  • Easy to update: cargo install zenohd --force

Cons:

  • Requires Rust toolchain
  • Takes 2-5 minutes to compile

Method 2: Pre-built Binary

Fastest way to get started without Rust installed.

Download: Go to the Zenoh Releases page and download the appropriate archive for your platform:

  • Linux (x86_64): zenoh-*-x86_64-unknown-linux-gnu-standalone.zip
  • macOS (Apple Silicon): zenoh-*-aarch64-apple-darwin-standalone.zip
  • macOS (Intel): zenoh-*-x86_64-apple-darwin-standalone.zip
  • Windows: zenoh-*-x86_64-pc-windows-msvc-standalone.zip

Extract and run:

Linux/macOS:

unzip zenoh-*.zip
chmod +x zenohd
./zenohd

Windows (PowerShell):

Expand-Archive zenoh-*.zip
.\zenoh\zenohd.exe

Pros:

  • No build tools required
  • Instant startup
  • Portable - can run from any directory

Cons:

  • Manual download and extraction
  • Need to track updates yourself

More info: https://zenoh.io/docs/getting-started/installation/

Method 3: Docker

Perfect for containerized deployments and CI/CD pipelines.

Pull and run the official Zenoh router image:

docker run --init --net host eclipse/zenoh:latest

For production with persistent config:

docker run -d \
  --name zenoh-router \
  --net host \
  -v /path/to/config:/zenoh/config \
  eclipse/zenoh:latest \
  --config /zenoh/config/zenoh.json5

Pros:

  • Isolated from host system
  • Easy to deploy and scale
  • Works great in Kubernetes/Docker Compose
  • Consistent across environments

Cons:

  • Requires Docker installed
  • Network setup can be tricky (use --net host for simplicity)

Docker Hub: https://hub.docker.com/r/eclipse/zenoh/tags

Method 4: Package Manager (apt, brew)

Best for system-wide installation on Linux/macOS.

Ubuntu/Debian (via apt):

echo "deb [trusted=yes] https://download.eclipse.org/zenoh/debian-repo/ /" | sudo tee /etc/apt/sources.list.d/zenoh.list
sudo apt update
sudo apt install zenoh

Run as a service:

sudo systemctl enable zenoh
sudo systemctl start zenoh

Or run manually:

zenohd

macOS (via Homebrew):

brew tap eclipse-zenoh/homebrew-zenoh
brew install zenoh
zenohd

Arch Linux (via AUR):

yay -S zenoh
zenohd

Pros:

  • System-wide installation
  • Easy updates via package manager
  • Can run as systemd service (Linux)
  • Integrates with OS security/firewall settings

Cons:

  • May not have the absolute latest version
  • Requires sudo/admin privileges

Method 5: ros-z Example Router

Only available when working in the ros-z repository - perfect for quick development/testing.

If you've cloned the ros-z repository:

cd /path/to/ros-z
cargo run --example zenoh_router

This runs a pre-configured router that matches ros-z defaults exactly.

Pros:

  • No installation needed
  • Already configured for ros-z
  • Useful for debugging ros-z itself

Cons:

  • Only available in the ros-z repository
  • Not suitable for standalone projects
  • Slower startup (rebuilds if code changes)

Warning

This method is for ros-z repository development only. If you're building your own project with ros-z as a dependency, use one of the other methods instead.

Method 6: ROS 2 rmw_zenoh

Use this if you have ROS 2 installed and want to test interoperability with ROS 2 nodes.

If you have ROS 2 Jazzy or newer with the Zenoh middleware:

ros2 run rmw_zenoh_cpp rmw_zenohd

Pros:

  • Already installed with ROS 2 Jazzy+
  • Guaranteed compatibility with ROS 2 nodes
  • Can interoperate ros-z nodes with C++/Python ROS 2 nodes

Cons:

  • Requires full ROS 2 installation
  • Overkill if you only want to use ros-z

Tip

This is excellent for testing interoperability - run ros-z nodes alongside standard ROS 2 nodes using the same router.

Verifying the Router is Running

After starting a router with any method above, verify it's working:

Check the router is listening on port 7447:

# Linux/macOS
netstat -an | grep 7447

# Or use lsof
lsof -i :7447

Test with a ros-z application:

# In another terminal, try running a ros-z node
# If it connects successfully, the router is working

You should see log output from the router showing connections when your ros-z nodes start.

Next Steps

Choose the configuration approach that fits your needs:

Ready to optimize your deployment? Experiment with different configurations and measure performance impact.