Socket en vivo del robot - Documentación para desarrolladores de Rhombus

Nota

Esta página se tradujo automáticamente. Si encuentras errores o tienes sugerencias, escríbenos.

Cada robot de Rhombus tiene un WebSocket en vivo para control y telemetría: envías comandos como velocidad, postura y parada de emergencia, y recibes la pose, el estado, la ruta planificada, los eventos de comportamiento y los datos de sensores del robot. La referencia de mensajes de abajo se genera a partir de la especificación AsyncAPI del robot, así que siempre coincide con lo que publica el servicio; sus descripciones están en inglés.

Conectarse

Llama a getAllMediaUris para el robot y toma wanLiveRobotUri, una URL wss:// en el host de medios del robot.
Abre un WebSocket a esa URL con una credencial (consulta Autenticarse).
Envía los comandos como tramas de texto con JSON. Cada comando necesita type y timestamp (milisegundos de época Unix); el robot descarta sin avisar un comando que no los tenga.
Lee los mensajes del robot como tramas binarias con JSON en UTF-8, y distingue cada uno por su type.

Autenticarse

El socket acepta una clave de API, un access token de OAuth o un token federado. Envíalo en el handshake del WebSocket:

Cliente	Credencial	Cómo
Servidor o app nativa	Clave de API	Encabezados `x-auth-scheme: api-token` y `x-auth-apikey`
Servidor o app nativa	Access token de OAuth cuyo grant incluye el scope `physical`	Encabezado `Authorization: Bearer <token>`
Navegador	Token federado generado por tu backend	Parámetros de consulta `?x-auth-scheme=federated-token&x-auth-ft=<token>` (o los mismos nombres como encabezados, desde clientes que puedan definirlos)

Mover un robot es una acción física, así que un token de OAuth necesita el scope physical: sin él, el handshake se rechaza con 403 PERMISSION_REQUIRED y WWW-Authenticate: Bearer error="insufficient_scope", scope="physical".
Las credenciales de partner también envían el UUID de la organización cliente en el encabezado x-auth-org.
Un handshake rechazado devuelve 401 (credencial ausente, desconocida, expirada o revocada) o 403 (válida pero no permitida) con el cuerpo de error JSON que se describe en Errores.
Si la credencial se elimina o revoca, o su rol cambia, el socket abierto se cierra con el código 1008 en 60 segundos o menos. Revisa la credencial antes de reconectarte.

Consulta Medios y transmisiones para ver cómo funciona cada credencial en los hosts de medios.

Comportamiento de la conexión

Si el robot no está conectado al host de medios de la URL, el handshake se rechaza con 403: vuelve a obtener wanLiveRobotUri (el host de medios del robot puede cambiar) y reintenta más tarde. Si el robot está conectado pero su canal de control no está listo, el socket envía un mensaje reconnect como trama de texto y sigue abierto: ciérralo y vuelve a intentarlo en unos momentos. El socket se cierra tras 180 segundos sin tráfico.

Se pueden agregar en cualquier momento nuevos tipos de mensaje, campos y valores de enum, así que ignora lo que no reconozcas. Un BEHAVIOR_EVENT puede llegar dos veces cuando el robot reintenta una entrega; elimina duplicados por su event_uuid.

Advertencia

Los comandos mueven una máquina física. Mantén la parada de emergencia (CMD_EMERGENCY_STOP_LOCK) a una sola acción de distancia en cualquier interfaz que construyas, deja de enviar comandos de velocidad cuando el operador suelte el control y haz pruebas en un área despejada.

Mensajes que envías

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.

actionstringbodyobligatorio

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>bodyobligatorio

Epoch milliseconds

typeenum<string>bodyobligatorio

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>bodyobligatorio

Epoch milliseconds

typeenum<string>bodyobligatorio

Available options: CMD_EMERGENCY_STOP_LOCK

Examplejson

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

`CMD_EMERGENCY_STOP_UNLOCK`

Release the emergency stop.

timestampinteger<int64>bodyobligatorio

Epoch milliseconds

typeenum<string>bodyobligatorio

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.

poseobjectbodyobligatorio

Mostrar child attributes

orientationnumber<double>[]body

Items: 4 to 4

positionnumber<double>[]body

Items: 3 to 3

timestampinteger<int64>bodyobligatorio

Epoch milliseconds

typeenum<string>bodyobligatorio

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>bodyobligatorio

Epoch milliseconds

typeenum<string>bodyobligatorio

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>bodyobligatorio

Epoch milliseconds

typeenum<string>bodyobligatorio

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>bodyobligatorio

Epoch milliseconds

twistobjectbodyobligatorio

Mostrar child attributes

angularnumber<double>[]bodyobligatorio

Items: 3 to 3

linearnumber<double>[]bodyobligatorio

Items: 3 to 3

typeenum<string>bodyobligatorio

Available options: CMD_VEL

Examplejson

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

Mensajes que recibes

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

Mostrar 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

Mostrar 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

Mostrar 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

Mostrar child attributes

activityenum<string>

priorityinteger<int32>

route_uuidstring<RUUID>

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

started_at_msinteger<int64>

timestampinteger<int64>obligatorio

typeenum<string>obligatorio

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

Mostrar 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>obligatorio

typeenum<string>obligatorio

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>obligatorio

typeenum<string>obligatorio

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>obligatorio

typeenum<string>obligatorio

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

Mostrar child attributes

framestring

transformobject

Mostrar 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

Mostrar 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>obligatorio

typeenum<string>obligatorio

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>obligatorio

transformationobject

Mostrar child attributes

rotationnumber<double>[]

Items: 4 to 4

translationnumber<double>[]

Items: 3 to 3

typeenum<string>obligatorio

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"
}