Advanced Configuration

Generating Config Files

ros-z can generate JSON5 config files matching rmw_zenoh_cpp defaults. This is opt-in via the generate-configs feature flag.

Basic Generation

cargo build --features generate-configs

Output location:

target/debug/build/ros-z-*/out/ros_z_config/
  ├── DEFAULT_ROSZ_ROUTER_CONFIG.json5
  └── DEFAULT_ROSZ_SESSION_CONFIG.json5

Custom Output Directory

Specify a custom directory using the ROS_Z_CONFIG_OUTPUT_DIR environment variable:

Absolute path:

ROS_Z_CONFIG_OUTPUT_DIR=/etc/zenoh cargo build --features generate-configs

Relative path (from package root):

ROS_Z_CONFIG_OUTPUT_DIR=./config cargo build --features generate-configs

From workspace root:

ROS_Z_CONFIG_OUTPUT_DIR=$PWD/config cargo build -p ros-z --features generate-configs

Tip

Generated files include inline comments explaining each setting, making them perfect documentation references.

Using Generated Files

let ctx = ZContextBuilder::default()
    .with_config_file("./config/DEFAULT_ROSZ_SESSION_CONFIG.json5")
    .build()?;

Configuration Reference

Key Settings Explained

Setting	Router	Session	Purpose
Mode	router	peer	Router relays messages, peers connect directly
Listen Endpoint	tcp/[::]:7447	-	Router accepts connections
Connect Endpoint	-	tcp/localhost:7447	Session connects to router
Multicast	Disabled	Disabled	Uses TCP gossip for discovery
Unicast Timeout	60s	60s	Handles slow networks/large deployments
Query Timeout	10min	10min	Long-running service calls
Max Sessions	10,000	-	Supports concurrent node startup
Keep-Alive	2s	2s	Optimized for loopback

Note

These defaults target ROS 2 deployments and match rmw_zenoh_cpp exactly. Only modify them if you have specific performance requirements.

Example: Full Session Config

A typical generated DEFAULT_ROSZ_SESSION_CONFIG.json5 looks like this. Copy it, edit the fields you need, and pass it to .with_config_file():

{
  // Session mode: "peer" connects to a router, "router" acts as one
  mode: "peer",

  connect: {
    endpoints: [
      // Connect to the local router by default
      "tcp/localhost:7447",
    ],
    // Retry failed connections every 5 seconds
    retry: {
      period_init_ms: 5000,
      period_max_ms: 5000,
    },
  },

  listen: {
    endpoints: [],
  },

  scouting: {
    multicast: {
      // Multicast disabled — ros-z uses router-based discovery
      enabled: false,
    },
    gossip: {
      enabled: true,
      multihop: false,
    },
  },

  transport: {
    unicast: {
      // Timeout for initial connection handshake
      open_timeout: 60000,
      // Keep-alive interval (optimised for loopback traffic)
      keepalive: 2,
    },
    qos: {
      enabled: true,
    },
  },

  // Timeout for service calls (set high for long-running operations)
  queries_default_timeout: 600000,
}

Common Customisations

Connect to a Remote Router

Replace localhost with the router's IP address or hostname:

connect: {
  endpoints: ["tcp/10.0.0.1:7447"],
},

Or set it in code without editing a file:

let ctx = ZContextBuilder::default()
    .with_connect_endpoints(["tcp/10.0.0.1:7447"])
    .build()?;

Connect to Multiple Routers

For resilient deployments with redundant routers:

connect: {
  endpoints: [
    "tcp/10.0.0.1:7447",
    "tcp/10.0.0.2:7447",
  ],
},

Reduce Service Call Timeout

The default 10-minute query timeout is conservative. For real-time applications:

queries_default_timeout: 5000,  // 5 seconds

Enable TLS

For encrypted inter-robot communication:

connect: {
  endpoints: ["tls/10.0.0.1:7448"],
},
transport: {
  unicast: {
    lowlatency: false,
    qos: { enabled: true },
    tls: {
      server_name: "robot-router",
      root_ca_certificate: "/etc/zenoh/ca.pem",
    },
  },
},

Validating a Config File

Before deploying a modified config, verify it parses correctly:

# Run a short-lived session — if it connects cleanly, the config is valid
RUST_LOG=zenoh=info cargo run --example z_pubsub -- --config ./my_config.json5

A valid config produces:

[INFO] Opening session...
[INFO] Declaring Publisher on 'ros-z/example'...

An invalid config produces a parse error before the session opens.