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). 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.
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.).
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").