Robot Live Socket - Rhombus Developer Documentation

Each Rhombus robot has a live WebSocket for control and telemetry: you send commands such as velocity, posture and emergency stop, and receive the robot's pose, state, planned path, behavior events and sensor data. The message reference below is generated from the robot's AsyncAPI specification, so it always matches what the service publishes.

Connect

Call getAllMediaUris for the robot and take wanLiveRobotUri, a wss:// URL on the robot's media host.
Open a WebSocket to that URL with a credential (see Authenticate).
Send commands as text frames holding JSON. Every command needs type and timestamp (Unix epoch milliseconds); the robot silently drops a command without them.
Read messages from the robot as binary frames holding UTF-8 JSON, and switch on their type.

Authenticate

The socket accepts an API key, an OAuth access token or a federated token. Send it on the WebSocket handshake:

Client	Credential	How
Server or native app	API key	Headers `x-auth-scheme: api-token` and `x-auth-apikey`
Server or native app	OAuth access token whose grant includes the `physical` scope	Header `Authorization: Bearer <token>`
Browser	Federated token minted by your backend	Query parameters `?x-auth-scheme=federated-token&x-auth-ft=<token>` (or the same names as headers, from clients that can set them)

Moving a robot is a physical action, so an OAuth token needs the physical scope: without it the handshake is refused with 403 PERMISSION_REQUIRED and WWW-Authenticate: Bearer error="insufficient_scope", scope="physical".
Partner credentials also send the client organization's UUID in the x-auth-org header.
A refused handshake returns 401 (credential missing, unknown, expired or revoked) or 403 (valid but not allowed) with the JSON error body described in Errors.
If the credential is deleted or revoked, or its role changes, the open socket closes with code 1008 within 60 seconds. Check the credential before reconnecting.

See Media and streams for how each credential works on the media hosts.

Connection behavior

If the robot isn't connected to the media host in the URL, the handshake is refused with 403: get wanLiveRobotUri again (the robot's media host can change) and retry later. If the robot is connected but its control channel isn't ready, the socket sends a reconnect message as a text frame and stays open: close it and try again shortly. The socket closes after 180 seconds without traffic.

New message types, fields and enum values can be added at any time, so ignore what you don't recognize. A BEHAVIOR_EVENT can arrive twice when the robot retries a delivery; deduplicate by its event_uuid.

Warning

Commands move a physical machine. Keep emergency stop (CMD_EMERGENCY_STOP_LOCK) one action away in any interface you build, stop sending velocity commands when your operator lets go of the control, and test in a clear area.

Messages you send

Message	Summary
`CMD_ACTION`	Run a platform-specific action; see the action field for the values each robot platform supports.
`CMD_EMERGENCY_STOP_LOCK`	Engage the emergency stop. The robot stays stopped until CMD_EMERGENCY_STOP_UNLOCK.
`CMD_EMERGENCY_STOP_UNLOCK`	Release the emergency stop.
`CMD_INITIALIZE_POSE`	Set the robot's localization estimate to a pose in the map frame.
`CMD_NAVIGATE_CANCEL`	Cancel navigation: the current pose, waypoint, home, route/patrol, idle docking or exploration activity, plus queued ones. Low-battery docking continues.
`CMD_POSTURE`	Adjust body posture. axes is a sparse map of platform-specific axis name to value (e.g. pitch in rad); empty or missing axes returns to neutral.
`CMD_VEL`	Teleoperate with a velocity twist in the robot base frame: linear [x, y, z] in m/s, angular [x, y, z] in rad/s.

`CMD_ACTION`

Run a platform-specific action; see the action field for the values each robot platform supports.

actionstringbodyrequired

Supported values by robot platform; other values are ignored.

Platform	Actions
go2, go2_v2, go2_2d	GO2_STAND_UP, GO2_SIT, GO2_LAY_DOWN, GO2_WALK_MODE, GO2_POSE_MODE, GO2_TERRAIN_WALK_MODE, GO2_ECONOMIC_GAIT_MODE, GO2_HELLO, GO2_ENABLE_AVOIDANCE_MODE, GO2_ENABLE_FREE_AVOID, ENABLE_RH_SIMPLE_AVOIDANCE, DISABLE_ALL_AVOIDANCE
diablo, diablo_2dlidar	DIABLO_STAND_MODE, DIABLO_CAR_MODE, ENABLE_RH_SIMPLE_AVOIDANCE, DISABLE_ALL_AVOIDANCE
turtlebot4	ENABLE_RH_SIMPLE_AVOIDANCE, DISABLE_ALL_AVOIDANCE

timestampinteger<int64>bodyrequired

Epoch milliseconds

typeenum<string>bodyrequired

Available options: CMD_ACTION

Examplejson

{
  "action": "GO2_STAND_UP",
  "timestamp": 1727800000000,
  "type": "CMD_ACTION"
}

`CMD_EMERGENCY_STOP_LOCK`

Engage the emergency stop. The robot stays stopped until CMD_EMERGENCY_STOP_UNLOCK.

timestampinteger<int64>bodyrequired

Epoch milliseconds

typeenum<string>bodyrequired

Available options: CMD_EMERGENCY_STOP_LOCK

Examplejson

{
  "timestamp": 1727800000000,
  "type": "CMD_EMERGENCY_STOP_LOCK"
}

`CMD_EMERGENCY_STOP_UNLOCK`

Release the emergency stop.

timestampinteger<int64>bodyrequired

Epoch milliseconds

typeenum<string>bodyrequired

Available options: CMD_EMERGENCY_STOP_UNLOCK

Examplejson

{
  "timestamp": 1727800000000,
  "type": "CMD_EMERGENCY_STOP_UNLOCK"
}

`CMD_INITIALIZE_POSE`

Set the robot's localization estimate to a pose in the map frame.

poseobjectbodyrequired

Show child attributes

orientationnumber<double>[]body

Items: 4 to 4

positionnumber<double>[]body

Items: 3 to 3

timestampinteger<int64>bodyrequired

Epoch milliseconds

typeenum<string>bodyrequired

Available options: CMD_INITIALIZE_POSE

Examplejson

{
  "pose": {
    "orientation": [
      0,
      0,
      0,
      1
    ],
    "position": [
      0.5,
      0,
      0
    ]
  },
  "timestamp": 1727800000000,
  "type": "CMD_INITIALIZE_POSE"
}

`CMD_NAVIGATE_CANCEL`

Cancel navigation: the current pose, waypoint, home, route/patrol, idle docking or exploration activity, plus queued ones. Low-battery docking continues.

timestampinteger<int64>bodyrequired

Epoch milliseconds

typeenum<string>bodyrequired

Available options: CMD_NAVIGATE_CANCEL

Examplejson

{
  "timestamp": 1727800000000,
  "type": "CMD_NAVIGATE_CANCEL"
}

`CMD_POSTURE`

Adjust body posture. axes is a sparse map of platform-specific axis name to value (e.g. pitch in rad); empty or missing axes returns to neutral.

axesobjectbody

duration_msinteger<int64>body

Hold time; absent holds until replaced

timestampinteger<int64>bodyrequired

Epoch milliseconds

typeenum<string>bodyrequired

Available options: CMD_POSTURE

Examplejson

{
  "axes": {
    "pitch": -0.1
  },
  "duration_ms": 5000,
  "timestamp": 1727800000000,
  "type": "CMD_POSTURE"
}

`CMD_VEL`

Teleoperate with a velocity twist in the robot base frame: linear [x, y, z] in m/s, angular [x, y, z] in rad/s.

timestampinteger<int64>bodyrequired

Epoch milliseconds

twistobjectbodyrequired

Show child attributes

angularnumber<double>[]bodyrequired

Items: 3 to 3

linearnumber<double>[]bodyrequired

Items: 3 to 3

typeenum<string>bodyrequired

Available options: CMD_VEL

Examplejson

{
  "timestamp": 1727800000000,
  "twist": {
    "angular": [
      0,
      0,
      0.2
    ],
    "linear": [
      0.3,
      0,
      0
    ]
  },
  "type": "CMD_VEL"
}

Messages you receive

Message	Summary
`BEHAVIOR_EVENT`	Activity lifecycle and progress: STARTED, PROGRESS, SUSPENDED, RESUMED, COMPLETED, FAILED, CANCELED or REJECTED.
`LASER_SCAN`	Nearest obstacle per angular sector around the robot.
`OCCUPANCY_GRID`	Live occupancy grid of the map being built or used.
`PLANNED_PATH`	Planned navigation path as [x, y] points.
`ROBOT_STATE`	Robot state: locomotion, battery, navigation mode and latest pose.
`TELEMETRY`	Robot pose sample. correlationId is the activity_uuid of the activity in progress.
`reconnect`	Sent by the cloud when the robot is not connected; reconnect later.

`BEHAVIOR_EVENT`

Activity lifecycle and progress: STARTED, PROGRESS, SUSPENDED, RESUMED, COMPLETED, FAILED, CANCELED or REJECTED.

activityenum<string>

Available options: IDLE, MANUAL_CMD_VEL, MANUAL_ACTION, MANUAL_POSTURE, NAVIGATE_TO_POSE, NAVIGATE_TO_HOME, NAVIGATE_TO_WAYPOINT, ROUTE_RUN, LOW_BATTERY_DOCKING, IDLE_DOCKING, DWELLING, EMERGENCY, EXPLORE_AND_MAP, EXPLORE_AREA, MAINTENANCE_HOLD, UNKNOWN

activity_uuidstring<RUUID>

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

batteryobject

Show child attributes

active_msinteger<int64>

charged_during_activityboolean

consumed_pctnumber<double>

distance_mnumber<double>

end_pctnumber<double>

start_pctnumber<double>

descriptionstring

distance_remainingnumber<float>

estimated_time_remaining_secnumber<double>

eventenum<string>

Available options: STARTED, PROGRESS, SUSPENDED, RESUMED, COMPLETED, FAILED, CANCELED, REJECTED, UNKNOWN

event_uuidstring<RUUID>

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

failure_reasonstring

goal_poseobject

Show child attributes

orientationnumber<double>[]

Items: 4 to 4

positionnumber<double>[]

Items: 3 to 3

navigation_time_secnumber<double>

originator_contextstring

originator_namestring

originator_uuidstring<RUUID>

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

patrol_uuidstring<RUUID>

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

phasestring

phase_eventstring

phase_uuidstring<RUUID>

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

predictionobject

Show child attributes

availableboolean

confidenceenum<string>

Available options: NONE, LOW, HIGH, UNKNOWN

consumption_pctnumber<double>

distance_basisenum<string>

Available options: planned, straight_line

distance_mnumber<double>

reasonstring

preempted_byobject

Show child attributes

activityenum<string>

priorityinteger<int32>

route_uuidstring<RUUID>

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

started_at_msinteger<int64>

timestampinteger<int64>required

typeenum<string>required

Available options: BEHAVIOR_EVENT

waypoint_indexinteger<int32>

waypoint_totalinteger<int32>

waypoint_uuidstring<RUUID>

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

Examplejson

{
  "activity": "ROUTE_RUN",
  "activity_uuid": "kX9mQ2rTSa6vL0pWcYb1Ng",
  "battery": {
    "start_pct": 91
  },
  "description": "Patrol run",
  "distance_remaining": 6.4,
  "estimated_time_remaining_sec": 18,
  "event": "PROGRESS",
  "event_uuid": "Q1w2E3r4T5y6U7i8O9p0AQ",
  "goal_pose": {
    "orientation": [
      0,
      0,
      0.7071,
      0.7071
    ],
    "position": [
      4.2,
      -1.5,
      0
    ]
  },
  "navigation_time_sec": 42.5,
  "originator_uuid": "Zx8Cv7Bn6Mm5Ll4Kk3Jj2A",
  "phase": "NAVIGATE_TO_WAYPOINT",
  "phase_uuid": "G7Qpbx5-RnC9av0WwS3jbA",
  "prediction": {
    "available": true,
    "confidence": "HIGH",
    "consumption_pct": 4.5,
    "distance_basis": "planned",
    "distance_m": 120
  },
  "priority": 50,
  "route_uuid": "Pz5Lc8Xe1Wa4Ru7Ty0Io3Q",
  "started_at_ms": 1727799950000,
  "timestamp": 1727800000000,
  "type": "BEHAVIOR_EVENT",
  "waypoint_index": 2,
  "waypoint_total": 5,
  "waypoint_uuid": "Hw4Rt7Yp2Kd9Vs3Bn6Mq1w"
}

`LASER_SCAN`

Nearest obstacle per angular sector around the robot.

event_uuidstring<RUUID>

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

framestring

indicesinteger<int32>[]

Covered sectors; a missing sector is a blind spot

max_range_mnumber<double>

originator_contextstring

originator_namestring

originator_uuidstring<RUUID>

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

rangesnumber<double>[]

Meters, parallel to indices; null = covered but clear out to max_range_m

rawobject

Show child attributes

angle_incrementnumber<double>

angle_minnumber<double>

countinteger<int32>

framestring

originnumber<double>[]

origin_okboolean

range_maxnumber<double>

range_minnumber<double>

ranges_b64string

sectorsinteger<int32>

Total sector count around the robot

timestampinteger<int64>required

typeenum<string>required

Available options: LASER_SCAN

Examplejson

{
  "frame": "base_footprint",
  "indices": [
    0,
    1,
    2,
    35
  ],
  "max_range_m": 3,
  "ranges": [
    1.25,
    null,
    2.4,
    0.8
  ],
  "sectors": 36,
  "timestamp": 1727800000000,
  "type": "LASER_SCAN"
}

`OCCUPANCY_GRID`

Live occupancy grid of the map being built or used.

data_compressedstring

base64(zlib(width*height bytes, row-major)). Each byte is the ROS occupancy value + 1: 0 unknown, 1 free, 2-101 occupied 1-100%

event_uuidstring<RUUID>

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

heightinteger<int32>

originnumber<double>[]

Map-frame pose of cell (0,0): [x m, y m, yaw rad]

Items: 3 to 3

originator_contextstring

originator_namestring

originator_uuidstring<RUUID>

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

resolutionnumber<double>

Meters per cell

timestampinteger<int64>required

typeenum<string>required

Available options: OCCUPANCY_GRID

widthinteger<int32>

Examplejson

{
  "data_compressed": "eJxjYASC1FRGBgZGRgAFWwDS",
  "height": 3,
  "origin": [
    -10,
    -5,
    0
  ],
  "resolution": 0.1,
  "timestamp": 1727800000000,
  "type": "OCCUPANCY_GRID",
  "width": 4
}

`PLANNED_PATH`

Planned navigation path as [x, y] points.

event_uuidstring<RUUID>

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

framestring

originator_contextstring

originator_namestring

originator_uuidstring<RUUID>

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

posesnumber<double>[][]

timestampinteger<int64>required

typeenum<string>required

Available options: PLANNED_PATH

Examplejson

{
  "frame": "map",
  "poses": [
    [
      1.2,
      -0.4
    ],
    [
      1.8,
      -0.2
    ],
    [
      2.5,
      0.1
    ]
  ],
  "timestamp": 1727800000000,
  "type": "PLANNED_PATH"
}

`ROBOT_STATE`

Robot state: locomotion, battery, navigation mode and latest pose.

avoidance_modeenum<string>

Available options: DISABLED, RH_SIMPLE_AVOIDANCE, DOCKING_AVOIDANCE, GO2_AVOIDANCE_MODE, GO2_FREE_AVOID

battery_current_mainteger<int32>

Positive = charging

battery_levelnumber<double>

Percent, 0-100

battery_stateenum<string>

Available options: OFF, CHARGING, DISCHARGING, FULL, NOT_CHARGING, UNKNOWN

battery_voltage_mvinteger<int32>

event_uuidstring<RUUID>

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

latest_transformobject

Show child attributes

framestring

transformobject

Show child attributes

rotationnumber<double>[]

Items: 4 to 4

translationnumber<double>[]

Items: 3 to 3

locomotion_statestring

map_uuidstring

navigation_stack_stateenum<string>

Available options: DISABLED, MAPPING, NAVIGATING

operational_stateenum<string>

Available options: DISCONNECTED, OPERATIONAL, EMERGENCY_STOP

originator_contextstring

originator_namestring

originator_uuidstring<RUUID>

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

return_homeobject

Show child attributes

availableboolean

confidenceenum<string>

Available options: NONE, LOW, HIGH, UNKNOWN

distance_basisenum<string>

Available options: planned, straight_line

distance_mnumber<double>

reasonstring

required_pctnumber<double>

sufficientboolean

timestampinteger<int64>required

typeenum<string>required

Available options: ROBOT_STATE

Examplejson

{
  "avoidance_mode": "GO2_AVOIDANCE_MODE",
  "battery_current_ma": -3200,
  "battery_level": 82,
  "battery_state": "DISCHARGING",
  "battery_voltage_mv": 28600,
  "latest_transform": {
    "frame": "map",
    "transform": {
      "rotation": [
        0,
        0,
        0.38,
        0.92
      ],
      "translation": [
        1.2,
        -0.4,
        0
      ]
    }
  },
  "locomotion_state": "STANDING",
  "map_uuid": "bL0cfvn7Squz3-swZjifpg",
  "navigation_stack_state": "NAVIGATING",
  "operational_state": "OPERATIONAL",
  "return_home": {
    "available": true,
    "confidence": "HIGH",
    "distance_basis": "planned",
    "distance_m": 38.5,
    "required_pct": 7.2,
    "sufficient": true
  },
  "timestamp": 1727800000000,
  "type": "ROBOT_STATE"
}

`TELEMETRY`

Robot pose sample. correlationId is the activity_uuid of the activity in progress.

activityenum<string>

correlationIdstring

event_uuidstring<RUUID>

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

framestring

mapUuidstring

originator_contextstring

originator_namestring

originator_uuidstring<RUUID>

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

timestampinteger<int64>required

transformationobject

Show child attributes

rotationnumber<double>[]

Items: 4 to 4

translationnumber<double>[]

Items: 3 to 3

typeenum<string>required

Available options: TELEMETRY

Examplejson

{
  "activity": "ROUTE_RUN",
  "correlationId": "kX9mQ2rTSa6vL0pWcYb1Ng",
  "frame": "map",
  "mapUuid": "bL0cfvn7Squz3-swZjifpg",
  "timestamp": 1727800000000,
  "transformation": {
    "rotation": [
      0,
      0,
      0.38,
      0.92
    ],
    "translation": [
      1.2,
      -0.4,
      0
    ]
  },
  "type": "TELEMETRY"
}

`reconnect`

Sent by the cloud when the robot is not connected; reconnect later.

actionenum<string>

Available options: reconnect

reasonstring

Examplejson

{
  "action": "reconnect",
  "reason": "device_not_connected"
}