Running Examples

git clone https://github.com/ZettaScaleLabs/ros-z.git
cd ros-z

Start the Zenoh Router

All examples require a Zenoh router to be running first (see Networking for why ros-z uses router-based architecture by default).

From the ros-z Repository

If you're working in the ros-z repository, use the included router example:

cargo run --example zenoh_router

From Your Own Project

If you're working on your own project, you need to install a Zenoh router. Quick options:

# Using cargo
cargo install zenohd

# Using Docker
docker run --init --net host eclipse/zenoh:latest

# Using apt (Ubuntu/Debian)
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

Then run:

zenohd

Available Examples

Leave the router running in a separate terminal, then run any example in another terminal from the ros-z repository root:

# Pure Rust example with custom messages (no ros-z-msgs needed)
cargo run --example z_custom_message -- --mode status-pub

# Examples using bundled messages (requires ros-z-msgs)
cargo run --example z_pubsub          # Publisher/Subscriber with std_msgs
cargo run --example twist_pub         # Publishing geometry_msgs
cargo run --example battery_state_sub # Receiving sensor_msgs
cargo run --example z_srvcli          # Service example with example_interfaces

Demo Nodes

The demo_nodes examples are basic ROS 2 patterns referenced from ROS 2 demo_nodes_cpp. These demonstrate fundamental pub/sub and service patterns.

Talker (Publisher)

A simple publisher node that publishes "Hello World" messages to the /chatter topic.

Features:

• Publishes std_msgs/String messages
• Uses async API for non-blocking publishing
• Publishes at 1 Hz (configurable)
• Uses QoS history depth of 7 (KeepLast)

Usage:

# Default settings (topic: chatter, period: 1.0s)
cargo run --example demo_nodes_talker

# Custom topic and faster publishing
cargo run --example demo_nodes_talker -- --topic /my_topic --period 0.5

# Connect to specific Zenoh router
cargo run --example demo_nodes_talker -- --endpoint tcp/localhost:7447

Command-line Options:

Listener (Subscriber)

A simple subscriber node that listens to messages on a topic.

Features:

• Subscribes to std_msgs/String messages
• Uses async API for receiving messages
• Uses QoS history depth of 10 (KeepLast)
• Prints received messages to console

Usage:

# Default settings (topic: chatter)
cargo run --example demo_nodes_listener

# Custom topic
cargo run --example demo_nodes_listener -- --topic /my_topic

# Connect to specific Zenoh router
cargo run --example demo_nodes_listener -- --endpoint tcp/localhost:7447

Command-line Options:

Test the pub/sub pattern:

Terminal 1:

cargo run --example demo_nodes_talker

Terminal 2:

cargo run --example demo_nodes_listener

Expected output in Terminal 2:

I heard: [Hello World: 1]
I heard: [Hello World: 2]
I heard: [Hello World: 3]
...

Add Two Ints Server

A simple service server that adds two integers and returns the result.

Features:

• Provides example_interfaces/AddTwoInts service
• Handles addition requests synchronously
• Uses async API for service handling
• Prints received requests and sent responses

Usage:

# Default settings (handles unlimited requests)
cargo run --example demo_nodes_add_two_ints_server

# Handle only one request and exit
cargo run --example demo_nodes_add_two_ints_server -- --count 1

# Connect to specific Zenoh router
cargo run --example demo_nodes_add_two_ints_server -- --endpoint tcp/localhost:7447

Command-line Options:

Add Two Ints Client

A simple service client that sends addition requests to the server.

Features:

• Calls example_interfaces/AddTwoInts service
• Supports both synchronous and asynchronous response waiting
• Uses async API for client operations
• Configurable numbers to add

Usage:

# Default settings (sync mode, adds 2 + 3)
cargo run --example demo_nodes_add_two_ints_client

# Async mode
cargo run --example demo_nodes_add_two_ints_client -- --async-mode

# Custom numbers
cargo run --example demo_nodes_add_two_ints_client -- --a 10 --b 20

# Async mode with custom numbers
cargo run --example demo_nodes_add_two_ints_client -- --a 10 --b 20 --async-mode

# Connect to specific Zenoh router
cargo run --example demo_nodes_add_two_ints_client -- --endpoint tcp/localhost:7447

Command-line Options:

Test the service pattern:

Terminal 1 (Server):

cargo run --example demo_nodes_add_two_ints_server -- --count 1

Terminal 2 (Client - sync mode):

cargo run --example demo_nodes_add_two_ints_client

Or Terminal 2 (Client - async mode):

cargo run --example demo_nodes_add_two_ints_client -- --async-mode

Expected output (Client):

AddTwoInts service client started (mode: sync/async)
Sending request: 2 + 3
Received response: 5
Result: 5

Expected output (Server):

AddTwoInts service server started
Received request: 2 + 3
Sending response: 5

Custom Messages Demo

This example demonstrates how to generate Rust types from user-defined ROS 2 message definitions. See the Custom Messages chapter for comprehensive documentation.

Quick start:

cd crates/ros-z/examples/custom_msgs_demo
ROS_Z_MSG_PATH="./my_robot_msgs" cargo build

Protobuf Demo

This example demonstrates using protobuf serialization with ros-z, both for ROS messages and custom protobuf messages. See the Protobuf Serialization chapter for comprehensive documentation.

Quick start:

cd crates/ros-z/examples/protobuf_demo
cargo run