Zenoh
The agent and your robot software communicate over a local Zenoh bus using Cap'n Proto messages. This is the contract native (non-ROS 2) integrations implement directly.
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 an external bridge that maps DDS topics onto these same local Zenoh topics — the contract below is identical either way.
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 UplinkMsg (Cap'n Proto) |
a sub-key of robot/**, e.g. robot/telemetry/motion |
| Receive commands (downlink) | Subscribe (Cap'n Proto) | command (or command/** for per-type subtopics) |
The agent subscribes to the wildcard robot/** for uplink and publishes commands
under command. The full per-type key conventions and their defaults are listed
in Uplink Messages → Publishing and
Command Messages → Receiving.
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 |
Bare spatial features (Shape | Route), geometry only |
agent/spatial_directives/get_bulk |
GetSpatialDirectivesRequest → GetSpatialDirectivesResponse |
Full field rules (timing, params, capabilities + geometry) |
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.
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 robot config. 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.