Skip to content

Custom Integrations

Integrate a non-ROS 2 or custom robot by implementing the agent's local messaging contract yourself, in any language. The contract is the same Cap'n Proto messages either way; you choose the transport that carries them:

  • Zenoh: the primary, native surface. Your software publishes and subscribes the local Zenoh topic contract directly. Best for off-host messaging or richer pub/sub.
  • Unix domain socket: a length-delimited frame protocol over a local socket, for robot software on the same host as the agent. Selected by agent configuration.

Both are on-host hops with the same payloads, so switching between them is a configuration change, not a rewrite. Neither requires a bridge.

Shortcut. If your robot software is written in Rust, Python, or C++, a client library already implements this for you: the Python and C++ clients speak the Unix-domain-socket hop out of the box, and the core libraries give you the message types to pair with your own Zenoh session. Implement the raw contract below only if you use another language or want full control.

When to choose this path

  • Your controller is custom, embedded, or built on a non-ROS framework.
  • You can serialize Cap'n Proto and speak either Zenoh or a Unix domain socket in your software.
  • You want full control over how your robot's data maps onto the contract.

If you already run ROS 2, the ROS 2 Bridge is usually faster.

What you implement

  1. Install the agent on the robot's Linux host by running its bootstrap command, which installs and enrolls the robot in one step.
  2. Choose a transport and connect to the agent:
  3. Zenoh: open a local Zenoh session and use the topic contract.
  4. Unix domain socket: connect to the agent's socket (default /run/rover-agent/agent.sock) and use the frame protocol.
  5. Send uplink messages (telemetry, faults and messages, objects, and mission feedback) as tagged RobotUplinkMsg payloads. On Zenoh these publish under the robot/** key space (for example robot/telemetry/motion); on the socket they are Uplink frames. The local keys carry no robot id; the agent adds it on the cloud hop.
  6. Receive downlink commands (mission commands, teleop, mode/velocity commands, settings, and field rules) as RobotCommand payloads. On Zenoh these arrive on the command key; on the socket they are Command frames. Dispatch on the union variant.
  7. Run the local queries as needed (features, field rules, settings). These are Zenoh queryables or the equivalent request/response frames.
  8. Handle coordinate frames: decide whether you send and receive geometry in WGS84 or your local ENU frame, and configure a local origin if you use the local frame.
  9. Declare capabilities so the cloud can match missions to the robot.

Contract summary

Concern Reference
Transport (Zenoh topics) Zenoh
Transport (socket frames) Unix Domain Socket
Message types and fields Messaging
Coordinate frames Coordinate Frames
Mapping your data → messages Telemetry Mappings
Configuration Robot configuration

Serialization

All messages are Cap'n Proto encoded, identical on both transports. Use a ready-made client library (Rust, Python, or C++) for the message types, or generate types from the Cap'n Proto schema in your language of choice. See Client Libraries for both.

Next steps