Robot interface · repose-robot-interface

Write a bridge

A bridge is a Copper CuBridge that translates between the standard Repose channels and one robot's protocol. If it follows the contract, every planner, controller and program in Repose works with your robot unchanged.

Structure

Split the crate the way the existing bridges are split. It keeps the protocol testable without a robot:

paramsThe RON config: block as a struct with deny_unknown_fields and a validate().
protocolPure encode/decode of the wire format. No sockets, no clocks. Unit-test it against captured traffic.
mappingProtocol messages ↔ Repose payloads: joint state, robot status, session events.
transportSockets and threads. Always with timeouts.
bridgeThe CuBridge impl and its Tx/Rx channel sets.

The contract

  1. Publish joint_state as CuJointStatePayload<N> every cycle you have fresh data, in SI units, in the joint order of your chain model.
  2. Map status honestly into CuRobotStatus: Ready only when the robot really accepts commands, Fault(code) and EmergencyStop when reported. Encodings you don't understand stay on a vendor channel, unmapped.
  3. Accept joint_command as CuJointCommandPayload<N>. Support the modes your robot can do, and refuse the others explicitly.
  4. Drive sessions through CuSessionTracker, mapping its outgoing commands and your controller's reports. Don't invent parallel session state. See Session lifecycle.
  5. Never put vendor payloads on a standard channel. Extras go on vendor_* channels.

Safety

  • Session and motion behind a cargo feature (control) and config flags (allow_control, allow_motion), all off by default.
  • A stale command (older than a timeout) becomes a stop, not "keep going".
  • Losing the connection calls tracker.on_disconnected() and stops publishing Ready.
  • Reads always have a timeout, so the Copper cycle can never block forever.

Testing

  1. Protocol round-trips from recorded traffic.
  2. Mapping tables: every status code you know maps to the intended CuRobotStatus.
  3. A read-only build (no control) against the real controller: watch joint_state while you move the robot from its pendant. Positions must match the pendant, in the right order and sign.
  4. Then sessions, then a tiny motion with the e-stop in hand.

Contributing it

Bridges belong in repose-bridges, one crate per vendor directory, with a README listing channels, supported modes and validated hardware.

API reference