Skip to main content
The Cyberwave platform uses MQTT for real-time communication between edge drivers, the cloud backend, and the frontend. This page lists every topic and payload schema so you can write compatible drivers, simulators, or integrations without reading source code.

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 a source_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.

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.
Standard locomotion command strings: 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:
  1. A client (frontend keyboard control, or your own code) publishes { "command": "take_photo" } to cyberwave/twin/{twin_uuid}/command.
  2. The driver grabs the current camera frame, JPEG-encodes it (downscaled to keep the payload small), and base64-encodes the bytes.
  3. The driver publishes the payload below to cyberwave/twin/{twin_uuid}/camera/photo.
The camera does not need to be streaming video for this to work — the driver captures a frame on demand.

Matching a photo to its request

The take_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 the image 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_type is 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_metric and publish_metrics check 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.
Golden payloads: 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").

Sensor binding update


Health check

cyberwave/ping/{resource_uuid}/request

Direction: publish (any client) → subscribe (backend) Connectivity probe. The backend replies on the corresponding pong topic.

cyberwave/pong/{resource_uuid}/response

Direction: publish (backend) → subscribe (client)

Workflow run status

cyberwave/workflow-run/{run_uuid}/status

Direction: publish (backend) → subscribe (SDK clients) Status updates for a running workflow execution.