Topic prefix
In non-production deployments the broker may be configured with an environment prefix (e.g.local for local dev). When a prefix is set, every topic below is written {prefix}cyberwave/.... The Python SDK’s topic_prefix parameter and the CYBERWAVE_MQTT_TOPIC_PREFIX environment variable handle this automatically (when neither is set, the SDK derives the prefix from CYBERWAVE_ENVIRONMENT). The SDK logs a warning when the resolved prefix does not match a hosted broker (staging.mqtt.cyberwave.com expects staging, mqtt.cyberwave.com expects none), since mismatched messages are silently dropped. All topic patterns on this page omit the prefix for clarity.
Source types
Most payloads include asource_type field. The allowed values are:
Twin transform
cyberwave/twin/{twin_uuid}/position
Direction: publish (edge / sim) → subscribe (backend, frontend)
Reports the 3D world position of the twin. Published by edge drivers and simulators; consumed by the backend (Vector) and the frontend.
cyberwave/twin/{twin_uuid}/rotation
Direction: publish (edge / sim) → subscribe (backend, frontend)
Reports the orientation of the twin as a quaternion.
cyberwave/twin/{twin_uuid}/scale
Direction: publish (edge / editor) → subscribe (backend, frontend)
Sets the render scale of the twin’s 3D model.
Joint states
cyberwave/joint/{twin_uuid}/update
Direction: publish (edge / sim / tele) → subscribe (backend, frontend)
Reports the state of one or more joints. Two payload formats are supported.
Single-joint format
Use this to report one joint at a time.Flat multi-joint format
Use this to report many joints efficiently. Joint positions become top-level keys.Aggregated multi-joint format
Use this when you also want to send velocities, efforts, or telemetry metadata.Navigation
cyberwave/twin/{twin_uuid}/navigate/command
Direction: publish (backend) → subscribe (edge driver)
Sends a navigation command to the robot. Published by the backend in response to a REST API call.
The current payload uses Cartesian coordinates. The proposed extension for
supporting both Cartesian and GPS-native vehicles is documented in
Navigation Coordinate Convention.
cyberwave/twin/{twin_uuid}/navigate/status
Direction: publish (edge driver) → subscribe (backend)
Reports the execution status of a navigation command. The action_id must match the one received in navigate/command.
Locomotion commands
cyberwave/twin/{twin_uuid}/command
Direction: publish (backend / frontend) → subscribe (edge driver)
Sends a discrete command to an edge device. Used for locomotion (move/turn), video control, and robot-specific actions.
Locomotion commands
Sent by the Cyberwave platform when the user presses a keyboard binding.
Robot-specific command strings used by bundled controllers:
Video control commands
Sent by the backend to start or stop video streaming on the edge device.Telemetry lifecycle
cyberwave/twin/{twin_uuid}/telemetry
Direction: publish (edge driver) → subscribe (backend)
Lifecycle events for the telemetry session. Send these to let the backend track driver connectivity.
Other
type values used internally by edge drivers:
Sensor data
cyberwave/twin/{twin_uuid}/depth
Direction: publish (edge driver) → subscribe (backend / cloud nodes)
Depth camera frame as a base64-encoded array.
cyberwave/twin/{twin_uuid}/pointcloud
Direction: publish (backend / edge) → subscribe (frontend)
Point cloud data as a base64-encoded array.
cyberwave/twin/{twin_uuid}/camera/photo
Direction: publish (edge driver) → subscribe (backend / frontend / SDK clients)
A single still image captured on demand. This is the result of a take_photo command:
- A client (frontend keyboard control, or your own code) publishes
{ "command": "take_photo" }tocyberwave/twin/{twin_uuid}/command. - The driver grabs the current camera frame, JPEG-encodes it (downscaled to keep the payload small), and base64-encodes the bytes.
- The driver publishes the payload below to
cyberwave/twin/{twin_uuid}/camera/photo.
Matching a photo to its request
Thetake_photo command may carry a data object:
Drivers that support these fields (currently the Unitree GO2) also add
status ("ok" or "error") to the reply. An error reply has a message and no image. Other drivers ignore both fields, so match on request_id only for a driver known to echo it.
On the GO2, a take_photo without upload: false is stored as a navigation capture, which only succeeds during an active navigation action; otherwise the reply is an error.
Retrieving the photo
Subscribe to the topic, then base64-decode theimage field. Remember to prepend the topic prefix in non-production deployments (e.g. localcyberwave/twin/...).
cyberwave/twin/{twin_uuid}/metrics
Direction: publish (edge driver) → subscribe (backend)
Periodic robot metrics snapshot (battery, navigation status, load, errors, etc.).
cyberwave/twin/{twin_uuid}/metrics/{channel}
Direction: publish (edge driver, simulator) → subscribe (backend)
One sample of one structured metric. A channel is a timeseries of a single scalar, such as a gripper position or a motor temperature. Use it for signals that need their own rate: every valid sample is stored as its own row, nothing is sampled, and a channel sample does not fire metrics workflow triggers. The newest sample of each channel is served under channels by GET /twins/{uuid}/metrics/latest.
The channel name is .-separated and each segment is one topic level, so channel arm.gripper is published on cyberwave/twin/{twin_uuid}/metrics/arm/gripper. A key of that name in the metrics snapshot above (the Python SDK’s publish_metrics) names the same channel.
The payload may also carry the optional envelope fields
source_subtype, producer_instance, workload_uuid and session_id (strings), producer_sequence, layout_version, source_timestamp_ns, clock_id, suppress_workflow_dispatch and trigger_chain. A field that is in neither this list nor the table drops the whole message.
Rules for the topic:
- Each
.-separated segment of the channel is non-empty and has none of/,+,#. - The channel is at most 120 characters.
source_typeis not a valid channel name: it is the sample’s source stamp.- A message the backend refuses is dropped without an error reply, so validate before you publish. The Python SDK’s
publish_metricandpublish_metricscheck these rules and raise instead of sending.
cyberwave/twin/{twin_uuid}/frame_poses
Direction: publish (edge driver, simulator) → subscribe (backend)
Poses a driver or simulator reports for named frames of its own robot (a camera mount, an end effector), each tagged with how it was obtained. Optional: publish it when you know where a frame is better than the base pose and joint state alone say. Each message is recorded whole as one twin_frame_poses telemetry event. The backend keeps at most five messages per second per twin and drops the rest, so publish at the rate you want stored.
The payload is the JSON form of the cyberwave.mqtt.twin.v1.TwinFramePosesPayload contract (common/protobuf/proto/cyberwave/mqtt/twin/v1/frame_poses.proto): proto3 JSON with the field names below as keys. Enums travel as their full names (SUBSTRATE_SIM), never as numbers or lowercase words. There is no source_type field; it is derived from header.substrate.
common/protobuf/fixtures/mqtt/twin/v1/frame_poses.json (simulator, with every optional field) and frame_poses_hardware.json (wheel odometry with a covariance, and a SLAM pose for the same frame).
header
Frame pose entries (
frames[])
pose_provenance values: POSE_PROVENANCE_GROUND_TRUTH, POSE_PROVENANCE_ODOMETRY, POSE_PROVENANCE_VISUAL_ODOMETRY, POSE_PROVENANCE_VIO, POSE_PROVENANCE_SLAM, POSE_PROVENANCE_LIDAR_LOCALIZATION, POSE_PROVENANCE_GPS, POSE_PROVENANCE_DEAD_RECKONING, POSE_PROVENANCE_CHARUCO, POSE_PROVENANCE_MOCAP, POSE_PROVENANCE_FUSED. POSE_PROVENANCE_UNSPECIFIED is rejected.
The same frame can appear more than once in a message under different provenances (odometry and SLAM for base_link), but each (child_frame_id, pose_provenance) pair appears once. A message that breaks any rule is dropped whole, with no error reply. The Python SDK’s publish_frame_poses checks these rules and raises instead of sending.
Edge health
cyberwave/twin/{twin_uuid}/edge_health
Direction: publish (edge driver) → subscribe (backend, frontend)
Periodic health status published by the edge driver (every ~5 seconds).
The frontend uses these payloads to drive the live “green dot” online
indicator on twin tiles, the workflow-pane Edge Devices tab, and the lab
queue heuristics. The backend additionally bumps the corresponding
Edge.last_heartbeat row (debounced to ~30 s per edge) so that the REST
Edge.is_online flag agrees with the live MQTT signal.
Driver log
cyberwave/twin/{twin_uuid}/driverlog
Direction: publish (edge core / driver) → subscribe (backend)
Structured log messages from edge drivers. Displayed in the platform UI.
WebRTC signalling
These topics set up WebRTC video between the edge and Cyberwave’s media service (SFU), which forwards the stream to browsers and SDK consumers.cyberwave/twin/{twin_uuid}/webrtc-offer
Direction: publish (edge) → subscribe (backend / media-service)
cyberwave/twin/{twin_uuid}/webrtc-answer
Direction: publish (backend / media-service) → subscribe (edge)
cyberwave/twin/{twin_uuid}/webrtc-candidate
Direction: bidirectional
ICE candidate exchange during WebRTC negotiation. Payload is the raw ICE candidate object.
Environment
cyberwave/environment/{environment_uuid}/{update_type}
Direction: publish (backend / edge) → subscribe (frontend, other services)
Generic environment update channel. update_type is a free-form string (e.g. "twin_added", "twin_removed", "sensor_binding", "event").