Zenoh
The agent and your robot software communicate over a local Zenoh bus using Cap'n Proto messages. This is the contract native integrations implement directly (including the Copper Bridge).
Roles
- Robot software publishes uplink messages (telemetry, faults, objects, mission feedback) and subscribes to commands; it also answers/issues local queries.
- The agent ingests those uplink messages, relays them to the cloud, and republishes downlink commands onto local Zenoh.
- ROS 2 robots use
rover_ros2_bridge(see ROS 2 Bridge), which talks to the agent over a Unix domain socket using the same Cap'n Proto messages. The contract below is the Zenoh form of that same contract. - copper-rs robots use
rovernexus-cu-components(see Copper Bridge).NexusBridgeis a Copper component that speaks this local Zenoh contract for you.
Publish / subscribe
The local keys do not include the robot id; they identify only the message, not the robot. The agent adds the robot's identity (assigned during enrollment) when it relays to and from the cloud over mTLS.
| You want to… | Action | Default local key |
|---|---|---|
| Send telemetry / faults / objects / feedback (uplink) | Publish a tagged ApplicationToAgent (Cap'n Proto) |
robot/**, or any key that expression matches |
| Receive commands (downlink) | Subscribe and decode an AgentToApplication (Cap'n Proto) |
command (or command/** when a command has its own subtopic) |
The agent subscribes to one uplink key, robot/** by default, and publishes
commands on command unless a command's subtopic is set. The topic names are
in Robot Configuration. Publishing details are in
Uplink Messages and
Command Messages.
Queryables (request / reply)
The agent exposes local Zenoh queryables so robot software can fetch assets on demand from the agent's local store. An empty request returns all items. These three topics are fixed: unlike the telemetry/command topics, they are not configurable.
| Queryable | Request → Response | Returns |
|---|---|---|
agent/features/get_bulk |
GetFeaturesRequest → GetFeaturesResponse |
Full features (Feature: geometry plus identity, layer role, scope, expiry) |
agent/spatial_directives/get_bulk |
GetSpatialDirectivesRequest → GetSpatialDirectivesResponse |
Full field rules (timing, parameters, capabilities, geometry, revision, enabled, and entryAllowed) |
agent/settings/query |
GetSettingsRequest → GetSettingsResponse |
Robot settings (all or by key) |
The Cap'n Proto field schemas for each request/response are defined in the schema bundled with the client libraries.
Serialization
- All messages are Cap'n Proto encoded.
- The full message definitions are documented per direction: Uplink Messages (robot → cloud) and Command Messages (cloud → robot), with shared structs and enums in Common Types.
- The authoritative schema (
messages.capnp) and ready-made Rust/Python/C++ bindings are available via the client libraries: generate your own bindings from the schema, or use a library directly. There is no turnkey Zenoh client; on this transport you pair a client library's message types with a Zenoh session you create (the Rustrover_nexus_corecrate plus thezenohcrate is the common pairing).
Coordinate frames
Geometry travels in one of two frames (WGS84 or local ENU), and the agent
converts between them using a configured local origin. Uplink telemetry is
normalized to WGS84; downlink geometry is WGS84 by default, or your local ENU
frame when convert_commands_to_local is set. See
Coordinate Frames.
Configuration
Zenoh connectivity is configured on the agent host. The agent loads a dedicated Zenoh
configuration with a fallback to the [zenoh] section of the agent config (agent.toml).
Detailed local Zenoh endpoint and listen settings are coming soon.
Note. Endpoints, certificates, and credentials are environment-specific and are not published here. The topic and wire contract above is stable and safe to build on.