Wire format
LiveKit channels, EdgeTelemetry fields, CloudCommand structure, and semantic-command resolution.
This page is a lookup for the exact shape of messages flowing between the platform and a robot. For the mental model behind sessions and channels, see Concepts → Sessions & channels.
LiveKit channels
A session is a LiveKit room. Inside it are three data channels plus two media tracks:
| Channel | Reliability | Direction | Purpose |
|---|---|---|---|
commands | Reliable, ordered | Cloud → Robot | Send CloudCommand — a oneof of velocity, trajectory, or mode |
state | Lossy | Robot → Cloud | Receive EdgeTelemetry at ~10 Hz |
system | Reliable, ordered | Robot → Cloud | Receive EdgeEvent — robot-side events (boot, errors, alerts, mode transitions) |
| Video track | — | Robot → Cloud | FPV and third-person camera streams |
| Audio track | — | Bidirectional | Robot microphone and speaker |
Start a session with POST /v1/robots/{id}/session. The response contains an sfu_endpoint and a webrtc_token to pass to your LiveKit client.
EdgeTelemetry
Delivered over the lossy state channel as protobuf. Each packet contains:
| Field | Description |
|---|---|
timestamp_us | Edge clock timestamp in µs (CLOCK_REALTIME) |
fw_timestamp_us | Firmware clock timestamp in µs |
sequence | Monotonically increasing packet counter |
fw_mode | Current firmware mode (FW_MODE_DAMP / FW_MODE_STAND / FW_MODE_MOVE) |
joint_pos | Joint positions in radians (25-element array, one per motor) |
joint_vel | Joint velocities in rad/s |
joint_current | Motor currents in amps |
joint_temp | Motor temperatures in °C |
imu_quat | IMU orientation quaternion [w, x, y, z] |
imu_gyro | IMU angular velocity [x, y, z] in rad/s |
imu_gravity | Projected gravity vector from the IMU [x, y, z] |
error_flags | Bitfield of active error codes |
alert_count | Number of active alerts |
last_video_timestamp_us | Timestamp of the most recent video frame (backend correlates with LiveKit RTP) |
last_audio_timestamp_us | Timestamp of the most recent audio frame |
Use GET /v1/robots/{id}/snapshot for a one-shot current state read.
CloudCommand
Sent on the reliable commands channel. CloudCommand is a protobuf oneof — exactly one of the three fields is set per message:
| Variant | Purpose |
|---|---|
velocity | VelocityCommand with vx, vy, vyaw |
trajectory | Joint-space trajectory (reserved — used by higher-level planners) |
mode | Firmware mode transition (damp / stand / move) |
VelocityCommand
| Field | Description |
|---|---|
vx | Forward / backward velocity (m/s) |
vy | Left / right lateral velocity (m/s) |
vyaw | Rotational velocity (rad/s) |
EdgeEvent
Delivered over the reliable system channel. Carries boot progress, error reports, alert triggers, and mode-transition notifications from the robot. Use it to react to state changes rather than polling telemetry.
Semantic commands
A higher-level REST abstraction for common directional commands — resolved server-side into a VelocityCommand and published on the commands channel. Nothing named semantic flows on the wire.
POST /v1/robots/{id}/semantic-command
{ "command": "forward" }Valid commands: forward, backward, left, right, turn-left, turn-right, stop.
Also available through the CLI: menlo robot action <command>.
How is this guide?