Writing compatible drivers

What is a compatible driver?

A compatible driver connects your hardware’s native API to a Cyberwave asset and twin: it translates the device’s protocol into MQTT topics, command envelopes, and (optionally) edge data channels that the UI, workflows, and SDK understand. This guide is for integrators building a driver from scratch for a custom or third-party asset in your workspace. Cyberwave-maintained drivers use the same rules; their cw-driver.yml files are linked later as examples only. Drivers can run on edge hardware, on the robot, in the cloud, or on a developer laptop. In production they usually run beside the device under Edge Core. Each driver ships as a Docker image. Edge Core pulls and runs it with the environment variables below, so local development matches production deployment.

Quickstart: scaffold with the Claude skill

The fastest way to get started is the Cyberwave Driver skill for Claude Code. It asks you a few questions about your hardware and scaffolds a complete, production-ready driver project — including the Dockerfile, local dev setup, and a working twin connection. Install the skill:

git clone https://github.com/cyberwave-os/driver-skill ~/.claude/skills/cyberwave-driver

Then in any Claude Code session:

/cyberwave-driver

Claude will generate the full project tree and walk you through connecting it to a real twin locally. The skill source is open source at cyberwave-os/driver-skill.

Quickstart: use the SDK

The fastest way to write a compatible driver is to use one of the official SDKs:

Python SDK — cyberwave-sdk
C++ SDK — see the C++ SDK docs

The SDKs handle twin synchronization, file I/O, reconnection logic, and more, so you can focus on the hardware integration.

Environment variables

When Edge Core starts a driver container it injects the following environment variables. You can develop your driver assuming these are always set to valid values — no need to handle the case where they are absent.

Variable	Description
`CYBERWAVE_TWIN_UUID`	UUID of the twin instance this driver manages
`CYBERWAVE_API_KEY`	API key scoped to this driver for authenticating platform calls
`CYBERWAVE_TWIN_JSON_FILE`	Absolute path to a writable JSON file containing the twin’s current state (see Twin JSON file)
`CYBERWAVE_CHILD_TWIN_UUIDS`	(optional) Comma-separated UUIDs of child twins (e.g. cameras) attached to this driver

CYBERWAVE_CHILD_TWIN_UUIDS is set when child twins are attached to the driver twin. Drivers can use this to coordinate child devices (for example, multiple cameras) without additional configuration.

Restart behavior tuning

The following optional variables let you override Edge Core’s restart defaults:

Variable	Default	Description
`CYBERWAVE_DRIVER_RESTART_LOOP_THRESHOLD`	`4`	Number of restarts before the driver is marked as flapping
`CYBERWAVE_DRIVER_RESTART_LOOP_WINDOW_SECONDS`	`60`	Time window (seconds) used to count restarts
`CYBERWAVE_DRIVER_TROUBLESHOOTING_URL`	`https://docs.cyberwave.com`	URL surfaced in platform alerts for operator guidance

Driver failure handling

Drivers must exit with a non-zero code when they cannot access required hardware (for example, a missing /dev/video* device or a disconnected peripheral). This allows Edge Core to detect startup failures and trigger restart logic. Edge Core raises the following alerts:

driver_start_failure — raised when a driver container cannot reach a stable running state.
driver_restart_loop — raised when a driver exceeds the restart threshold within the window. The container is stopped and marked as flapping.

Twin JSON file

CYBERWAVE_TWIN_JSON_FILE points to a JSON file on disk that contains the digital twin instance (including its metadata) and the associated catalog twin data, matching the TwinSchema and AssetSchema API schemas. Drivers may read and modify this file. Edge Core syncs any changes back to the backend when connectivity is available.

Runtime configuration

Drivers should treat metadata["edge_configs"] as the source of truth for per-device runtime configuration, and metadata["edge_fingerprint"] as the edge identity (not duplicated inside edge_configs). Read edge_configs from CYBERWAVE_TWIN_JSON_FILE at startup to obtain per-device settings without hardcoding them in the image.

Declare your driver interface (`cw-driver.yml`)

To make a custom asset work with Cyberwave, your driver project should include a cw-driver.yml at the repository root (next to your Dockerfile). The file is the contract between your hardware bridge, the platform APIs, the web UI, and the SDK: it lists which MQTT topics you use and which command strings you accept. Cyberwave’s own edge drivers (Go2, SO-101, DJI Mini, and others) use the same format — treat them as reference implementations, not as something you must fork. Copy the patterns that match your robot (locomotion, joint bus, camera stream, etc.) and trim what you do not implement.

Compliance checklist

Step	What you do
1. Asset	Create an asset in your workspace for the hardware type you are integrating. Note its `registry_id` (or `slug`) — your manifest must target that id.
2. Manifest	Add `cw-driver.yml` to your driver repo. Declare every topic segment and `commands.supported` entry your code actually handles.
3. Implement	Subscribe/publish on the MQTT topics from your catalog (e.g. `cyberwave/twin/{uuid}/command`); see Runtime messaging (MQTT) and MQTT API Reference.
4. Register interface	`twin.commands.set_schema("./cw-driver.yml")` → `PUT /api/v1/twins/{uuid}` (see Apply the manifest and Platform API reference).
5. Deploy	Run the image with Edge Core (or locally with the same env vars). New twins spawned from that asset inherit `metadata["mqtt"]`.

If the manifest and the running driver disagree (undeclared command, wrong topic), teleop, agents, and SDK helpers will not line up with what the hardware actually does.

Why you need it

Without a declared interface catalog, the platform cannot know which MQTT topics your driver uses, which command strings are valid on cyberwave/twin/{uuid}/command, or whether a command is continuous (stick-held) vs discrete (one-shot). That metadata drives:

Consumer	What it uses from the catalog
Web UI	Dynamic control surfaces — e.g. the keyboard teleop overlay lists only `commands.supported` entries and respects `commands.specs[name].continuous`
Python SDK	`twin.commands.get_schema()` and catalog methods such as `twin.commands.move_forward(...)` bound from `commands.supported`
Your driver	A single source of truth for reviews, tests, and parity with production behavior

Planned — topic entries will also reference dedicated payload schemas (protobuf / robot-native layouts) for typed robot data on the wire. Today, payload_schema_ref names the logical schema; strict validation against those refs is not enforced yet.

What `cw-driver.yml` contains

Top-level fields:

Field	Purpose
`registry_ids`	One or more asset `registry_id` values this manifest describes — use the id of your workspace asset (e.g. `acme-corp/my-arm-v1`)
`mqtt.schema_version`	Catalog format version (currently `1`)
`mqtt.driver_family`	Implementation hint (`ros_cpp`, `python`, `android`, …)
`mqtt.<namespace>.<leaf>`	Per-topic contract — see YAML path → MQTT topic below
`mqtt.commands.supported`	Command names the driver accepts on the twin command topic — plain strings (discrete) or `{name, continuous, rate_hz}` objects
`mqtt.commands.routers`	Optional routing hints for the edge bridge (e.g. `actuation`, `get_status`)
`mqtt.commands.constraints`	Human-readable rules (source types, safety notes) surfaced to agents and docs

YAML path → MQTT topic

Topic entries are nested as mqtt.<namespace>.<leaf>. The leaf key is the MQTT path segment (use hyphens in YAML, e.g. webrtc-offer). Each entry becomes a flat key in metadata["mqtt"]["topics"] by joining a namespace prefix with the leaf:

YAML path	Compiled slug	Example live topic (`twin_uuid = abc`)
`mqtt.joint.update`	`cyberwave/joint/{twin_uuid}/update`	`cyberwave/joint/abc/update`
`mqtt.joint.+`	`cyberwave/joint/{twin_uuid}/+`	`cyberwave/joint/abc/+` (wildcard)
`mqtt.twin.command`	`cyberwave/twin/{twin_uuid}/command`	`cyberwave/twin/abc/command`
`mqtt.twin.position`	`cyberwave/twin/{twin_uuid}/position`	`cyberwave/twin/abc/position`
`mqtt.twin.telemetry`	`cyberwave/twin/{twin_uuid}/telemetry`	`cyberwave/twin/abc/telemetry`
`mqtt.twin.webrtc-offer`	`cyberwave/twin/{twin_uuid}/webrtc-offer`	`cyberwave/twin/abc/webrtc-offer`
`mqtt.twin.webrtc-answer`	`cyberwave/twin/{twin_uuid}/webrtc-answer`	`cyberwave/twin/abc/webrtc-answer`
`mqtt.twin.webrtc-candidate`	`cyberwave/twin/{twin_uuid}/webrtc-candidate`	`cyberwave/twin/abc/webrtc-candidate`
`mqtt.environment.<leaf>`	`cyberwave/environment/{environment_uuid}/<leaf>`	environment-scoped

Namespace prefixes:

`mqtt` namespace	MQTT prefix
`joint`	`cyberwave/joint/{twin_uuid}`
`twin`	`cyberwave/twin/{twin_uuid}`
`environment`	`cyberwave/environment/{environment_uuid}`

Each leaf entry sets direction, payload_schema_ref, description, and optional source_types. WebRTC signaling is always on the twin prefix (cyberwave/twin/{uuid}/webrtc-offer, webrtc-answer, webrtc-candidate, and webrtc-command for media-service commands). Declare them under mqtt.twin with hyphenated leaf names — not as a separate top-level namespace:

mqtt:
  twin:
    command:
      # ...
    webrtc-offer:
      direction: both
      payload_schema_ref: WebRTCOfferPayload
    webrtc-answer:
      direction: both
      payload_schema_ref: WebRTCAnswerPayload

Only list WebRTC leaves when this twin participates in signaling (e.g. onboard camera or gimbal stream). Arm-only or joint-bus drivers (such as SO-101) should omit them; camera video uses child camera twins and the media service, not WebRTC topics on the arm twin.

In some first-party Cyberwave profiles you may see a legacy mqtt.webrtc.offer shorthand (offer → webrtc-offer under the twin prefix). For new drivers, use mqtt.twin.webrtc-* only.

Compiled catalog shape

On the platform, your asset (and twins created from it) store a JSON bundle at metadata["mqtt"]:

topics — map of canonical slug → { direction, payload_schema_ref, description, … }
commands.supported — list of command name strings
commands.specs — per-command flags such as continuous and rate_hz
schema_version, driver_family — format and implementation hints

Author in YAML for readability; the SDK compiles it into metadata["mqtt"] when you call set_schema on a twin.

Reference implementations (Cyberwave drivers)

Use these open-source manifests as templates — copy the namespaces and command style that match your hardware, then delete what you do not implement:

Profile	Manifest	Good template for
UGV Beast	cw-driver.yml	Mobile base, continuous locomotion, discrete utilities
SO-101 arm	cw-driver.yml	`joint` bus + `twin.command` script commands (no WebRTC on the arm twin)

Apply the manifest to your twin

After you author cw-driver.yml, register it on a twin you own with the Python SDK. You do not need to hand-build JSON or call low-level asset APIs — point set_schema at your manifest file and the platform updates that twin’s metadata["mqtt"], refreshes the catalog cache, and binds catalog-derived command methods on twin.commands (for example twin.commands.stop(), twin.commands.move_forward(...) when those names appear in commands.supported).

from cyberwave import Cyberwave

cw = Cyberwave(api_key="...")
twin = cw.twin("your-twin-uuid")  # or resolve from environment

# Compile cw-driver.yml, persist on this twin, re-bind catalog methods
twin.commands.set_schema("./cw-driver.yml")

# Inspect the catalog the UI and SDK now use
print(twin.commands.get_schema()["commands"]["supported"])

# Call any command you declared — derived from the manifest
twin.commands.stop()
twin.commands.move_forward(linear_x=0.3, duration=0.5, rate_hz=10)

Set registry_ids in the YAML to match the asset your twin was created from. Re-run set_schema whenever you change the manifest so teleop, agents, and SDK callers stay aligned with your driver.

`set_schema` — REST and SDK


Python SDK	`twin.commands.set_schema(path_or_dict, merge=True)` — compiles `cw-driver.yml`, calls the twin update API, re-binds `twin.commands.<name>`
REST	`PUT /api/v1/twins/{uuid}`
Auth	`Authorization: Bearer <token>` (same as `CYBERWAVE_API_KEY`)
Request body	`{ "metadata": { "mqtt": { "schema_version": 1, "topics": { ... }, "commands": { "supported": [...], "specs": { ... } }, ... } } }` — only fields you want to change need to be sent; `set_schema` sends the full `metadata` object with `mqtt` set or merged
Response	`TwinSchema` including updated `metadata`
Read back	`GET /api/v1/twins/{uuid}` → `metadata.mqtt`; SDK: `twin.commands.get_schema()`

Full OpenAPI entry: Update Twin. merge=True (default) deep-merges the new metadata.mqtt into existing twin metadata. merge=False replaces the entire mqtt block. Invoke catalog commands after set_schema — they publish over MQTT, not REST:

SDK	Wire
`twin.commands.<command>(**kwargs)`	Publish to `cyberwave/twin/{twin_uuid}/command` with envelope `{ source_type, command, data, timestamp }`

Platform API reference

Use the Python SDK for day-to-day driver work; use REST when integrating from another language or CI. All REST paths are under /api/v1 and require a bearer token unless noted otherwise. See the REST API reference for request/response schemas.

Bring-up (workspace)

Step	REST	Python SDK
Create catalog asset	`POST /api/v1/assets` — Create Asset	`client.assets.create(...)`
Check `registry_id` free	`GET /api/v1/assets/check-registry-id/{registry_id}` — Check Registry Id	—
Update asset (optional shared catalog on asset)	`PUT /api/v1/assets/{uuid}` — Update Asset — set `metadata.mqtt` on the asset if every new twin should inherit the same manifest	`client.assets.update(asset_uuid, {"metadata": {"mqtt": ...}})`
Create twin	`POST /api/v1/twins` — Create Twin	`client.twins.create(...)`
List twins in environment	`GET /api/v1/environments/{uuid}/twins` — Get Environment Twins	environment helpers / twin resolution
Register driver manifest on one twin	`PUT /api/v1/twins/{uuid}` — Update Twin	`twin.commands.set_schema("./cw-driver.yml")`
Read twin + catalog	`GET /api/v1/twins/{uuid}` — Get Twin	`twin.commands.get_schema()` or `twin.refresh()`

Runtime state (REST alternatives to MQTT)

Drivers normally stream state over MQTT (see below). These REST endpoints are available for tools, simulators, or HTTP-only bridges:

Data	REST	Python SDK
Pose (position / rotation / scale)	`PATCH /api/v1/twins/{uuid}/state` — Update Twin State	`client.twins.update_state(twin_uuid, {...})`
Joint states (HTTP)	`PUT /api/v1/twins/{uuid}/joint_states` — Update Twin Joint States	`client.twins.update_joint_state(...)` / URDF helpers
Single joint	`PUT /api/v1/twins/{uuid}/joints/{joint_name}/state` — Update Twin Joint State	—
Latest camera frame	`GET /api/v1/twins/{uuid}/latest-frame` — Get Twin Latest Frame	`client.twins.get_latest_frame(...)`
Driver logs	`GET /api/v1/twins/{uuid}/logs` — Get Twin Driver Logs	—

Runtime messaging (MQTT)

Declared in cw-driver.yml → compiled into metadata.mqtt.topics. At runtime the driver (or SDK teleop) uses the MQTT broker (WebSocket URL in NEXT_PUBLIC_MQTT_URL for frontends; port 1883 / 9001 locally for edge). Topic prefix may include an environment segment in deployed stacks; slugs below are canonical.

Catalog slug (`metadata.mqtt.topics` key)	Example topic	Typical driver role
`cyberwave/twin/{twin_uuid}/command`	`cyberwave/twin/abc/command`	Subscribe for `source_type: tele` commands; map `command` string to hardware
`cyberwave/joint/{twin_uuid}/update`	`cyberwave/joint/abc/update`	Subscribe for tele joint targets; publish follower/sim observations
`cyberwave/twin/{twin_uuid}/position`	`cyberwave/twin/abc/position`	Publish pose updates
`cyberwave/twin/{twin_uuid}/telemetry`	`cyberwave/twin/abc/telemetry`	Publish lifecycle / status JSON
`cyberwave/twin/{twin_uuid}/webrtc-offer`	`cyberwave/twin/abc/webrtc-offer`	Subscribe/publish signaling (camera twins)
`cyberwave/twin/{twin_uuid}/webrtc-answer`	`cyberwave/twin/abc/webrtc-answer`	Signaling
`cyberwave/twin/{twin_uuid}/webrtc-candidate`	`cyberwave/twin/abc/webrtc-candidate`	ICE candidates

SDK publish helper	MQTT topic pattern
`twin.commands.<name>(...)`	`cyberwave/twin/{uuid}/command`
`client.mqtt.update_joints_state(...)`	`cyberwave/joint/{uuid}/update`
`client.mqtt.update_twin_position(...)`	`cyberwave/twin/{uuid}/position`
`client.mqtt.update_twin_rotation(...)`	`cyberwave/twin/{uuid}/rotation`

Payload shapes: MQTT API Reference.

Edge data bus (local, not REST)

SDK	Key expression
`cw.data.publish("joint_states", {...})`	`cw/{twin_uuid}/data/joint_states`
`cw.data.publish("frames/default", ndarray)`	`cw/{twin_uuid}/data/frames/default`

See Data Wire Format for encoding rules.

Assets, twins, and public catalog entries

Layer	Who controls it	Behavior
Your asset	Your workspace	Defines the hardware type; twins usually start with asset metadata.
Your twin	Your workspace	`set_schema` updates this twin’s `metadata["mqtt"]` so you can iterate without changing a shared asset definition.
Public Cyberwave assets	Cyberwave	You can spawn twins from them; use `set_schema` on your twin if you need a custom command surface for a private integration.

First-party Cyberwave drivers ship a cw-driver.yml in their repositories for reference — you follow the same file format, then apply it to your twin with set_schema during bring-up.

Sensor data output

If your driver produces sensor data (video frames, depth maps, audio, joint states, etc.), publish it to the edge data bus so worker containers and ML models can consume it locally with zero network overhead. There are two options: the Zenoh data bus (recommended) and the filesystem convention (fallback for constrained environments). Both use the same channel names — a driver can switch between them by changing one env var.

Option A: Zenoh data bus (recommended)

The Zenoh data bus provides zero-copy shared memory between driver and worker containers. Data is consumed directly by worker hooks and cw.data.latest().

Key expression convention

cw/{twin_uuid}/data/{channel}

Segment	Value	Example
`cw`	Fixed prefix	`cw`
`twin_uuid`	UUID of the twin	`a1b2c3d4-...`
`data`	Fixed namespace	`data`
`channel`	Canonical channel name	`frames/default`

The DataBus handles key composition automatically via CYBERWAVE_TWIN_UUID.

Canonical channels

Channel	Encoding	Pattern	Wire payload
`frames/default`	`numpy/ndarray`	Stream	SDK header + raw BGR/RGB uint8
`depth/default`	`numpy/ndarray`	Stream	SDK header + raw uint16 depth (mm)
`joint_states`	`application/json`	Latest value	`{ts, names, positions, velocities?, efforts?, source_type}`
`position`	`application/json`	Latest value	`{ts, x, y, z, qx?, qy?, qz?, qw?}`
`audio/default`	`numpy/ndarray`	Stream	SDK header + float32 PCM
`pointcloud/default`	`numpy/ndarray`	Stream	SDK header + Nx3 float32
`imu`	`application/json`	Stream	`{ts, accel: {x,y,z}, gyro: {x,y,z}}`
`battery`	`application/json`	Latest value	`{ts, voltage_v, current_a, charge_pct}`
`telemetry`	`application/json`	Latest value	Free-form `{ts, ...}`

You can define custom channels by picking any channel name.

Python SDK example

from cyberwave import Cyberwave
import numpy as np
import os, time

cw = Cyberwave(api_key=os.environ["CYBERWAVE_API_KEY"], source_type="edge")

# Binary stream: numpy array published with SDK header
frame = np.zeros((480, 640, 3), dtype=np.uint8)
cw.data.publish("frames/default", frame)

# JSON latest-value: dict published as application/json
cw.data.publish("joint_states", {
    "ts": time.time(),
    "names": ["shoulder_pan", "elbow_flex"],
    "positions": [0.1, -0.5],
})

CYBERWAVE_TWIN_UUID is read automatically from the environment. CYBERWAVE_DATA_BACKEND selects the transport (zenoh or filesystem).

Wire format reference (for native language publishers)

For C++, Rust, or any language that needs to publish without the Python SDK:

┌──────────────────┬──────────┬──────────┬─────────────────────┬─────────────────┐
│ header_len (u32) │ ts (f64) │ seq (i64)│ header JSON (UTF-8) │ payload (bytes) │
│   4 bytes, LE    │ 8 bytes  │ 8 bytes  │ variable length     │ variable length │
└──────────────────┴──────────┴──────────┴─────────────────────┴─────────────────┘

Required JSON fields:

content_type: "numpy/ndarray" | "application/json" | "application/octet-stream"
shape: [H, W, C] (for ndarray; omit for JSON/bytes)
dtype: "uint8" | "uint16" | "float32" etc. (for ndarray; omit for JSON/bytes)

C++ native publish example

Minimal zenoh-cpp snippet that publishes frames with the correct header:

#include <zenoh.hxx>
#include <nlohmann/json.hpp>
#include <cstring>
#include <cstdint>

std::vector<uint8_t> pack_frame(
    const uint8_t* pixels, size_t pixel_bytes,
    int height, int width, int channels,
    double ts, int64_t seq
) {
    nlohmann::json meta;
    meta["content_type"] = "numpy/ndarray";
    meta["shape"] = {height, width, channels};
    meta["dtype"] = "uint8";
    std::string json_str = meta.dump();

    uint32_t header_len = 16 + static_cast<uint32_t>(json_str.size());
    std::vector<uint8_t> buf(4 + header_len + pixel_bytes);

    size_t off = 0;
    memcpy(buf.data() + off, &header_len, 4); off += 4;
    memcpy(buf.data() + off, &ts, 8); off += 8;
    memcpy(buf.data() + off, &seq, 8); off += 8;
    memcpy(buf.data() + off, json_str.data(), json_str.size());
    off += json_str.size();
    memcpy(buf.data() + off, pixels, pixel_bytes);
    return buf;
}

int main() {
    auto config = zenoh::Config::default_config();
    auto session = zenoh::Session::open(std::move(config));

    std::string twin_uuid = std::getenv("CYBERWAVE_TWIN_UUID");
    std::string key = "cw/" + twin_uuid + "/data/frames/default";
    auto pub = session.declare_publisher(key);

    int64_t seq = 0;
    while (true) {
        // ... capture frame into pixels[] ...
        auto wire = pack_frame(pixels, pixel_bytes, 480, 640, 3,
                               wall_clock_seconds(), seq++);
        pub.put(zenoh::Bytes(wire.data(), wire.size()));
    }
}

The Python SDK’s DataBus.subscribe() automatically decodes this payload — no adapter code needed.

Option B: Filesystem convention (fallback)

The filesystem convention is the fallback for environments where eclipse-zenoh cannot be installed. For most drivers, use cw.data.publish() (Zenoh data bus) instead — it provides zero-copy shared memory and is consumed directly by worker hooks. Both conventions use the same channel names.

Write sensor data to a subfolder of the config directory that Edge Core mounts into your container:

$CYBERWAVE_EDGE_CONFIG_DIR/data/{twin_uuid}/{channel}/{sensor_name}/

CYBERWAVE_EDGE_CONFIG_DIR is always set by Edge Core (defaults to /app/.cyberwave).

Ring buffer (for stream data)

data/{twin_uuid}/frames/default/
├── ring/
│   ├── 000000.npy
│   ├── 000001.npy
│   └── ...         # numbered slots, wraps around
└── meta.json       # write pointer + format info

Rules:

Write .npy files to numbered slots: {slot:06d}.npy
Slot index = write_count % buffer_size (default: 120)
Atomic writes: write to {slot}.npy.tmp, then rename() to {slot}.npy
Update meta.json after each write

Latest value (for state data)

data/{twin_uuid}/joint_states/
└── latest.json     # overwritten each update

Rules:

Write a single JSON file: latest.json
Atomic writes: write to latest.json.tmp, then rename()
Include a timestamp field

This is a filesystem convention, not a Python API. C++, Rust, or any other language can write .npy files and JSON to the same paths.

MQTT topics and payloads

If you publish data over MQTT directly (rather than through the SDK’s cw.data.publish), see the MQTT API Reference for the complete list of topics and payload schemas supported by the platform. That page covers:

Twin transform: position, rotation, scale
Joint state updates (single-joint, flat multi-joint, and aggregated formats)
Navigation commands and status reporting
Locomotion commands (move_forward, turn_left, etc.)
Telemetry lifecycle events (connected, telemetry_start, telemetry_end)
Sensor data: depth frames, point clouds, metrics
Edge health reporting
WebRTC signalling
Health check ping/pong

Migrating from MQTT-only drivers

If your driver currently publishes sensor data over MQTT, you can add Zenoh publishing without removing the MQTT path. The two paths serve different consumers:

MQTT → cloud backend (telemetry, frontend, workflows)
Zenoh → local worker containers (zero-copy inference, fusion)

Step 1: Set CYBERWAVE_DATA_BACKEND

Ensure CYBERWAVE_DATA_BACKEND=zenoh is set in the driver container. Edge Core sets this automatically for managed drivers. For manual testing:

docker run -e CYBERWAVE_DATA_BACKEND=zenoh ...

Step 2: Add cw.data.publish alongside the MQTT call

# Before (MQTT only)
twin.client.mqtt.update_joints_state(twin_uuid=twin_uuid, ...)

# After (dual-publish)
twin.client.mqtt.update_joints_state(twin_uuid=twin_uuid, ...)   # unchanged
cw.data.publish("joint_states", {"ts": ts, "names": [...], "positions": [...]})

Zenoh publish errors are caught and logged — they do not affect the MQTT path.

Step 3: Verify with a subscriber

sub = cw.data.subscribe("joint_states", lambda data: print(data))
# Run your driver; you should see joint dicts printed

Controlling which paths are active

Set CYBERWAVE_PUBLISH_MODE to choose:

Value	Effect
`dual`	Both MQTT and Zenoh publish (default)
`zenoh_only`	Only Zenoh (local-only drivers)
`mqtt_only`	Only MQTT (legacy mode)

Licensing your driver

You own your driver code. There are two common paths:

Open source — publish your driver as a public repository on GitHub under the Apache 2.0 license. This is our recommended default and makes it easier for the community to contribute and reuse your work.
Closed source — keep your driver proprietary. In this case, we recommend obfuscating your code before distributing the image and including a clear license file that reflects your distribution terms. Interested in writing a closed-source driver? Reach out to us.

Example driver repositories

Fork or read these repositories when building your own compliant driver — each includes a Dockerfile, Edge Core env contract, and (where applicable) a cw-driver.yml:

Camera — cyberwave-edge-camera-driver: USB/RTSP camera as a twin (child of a parent robot twin).
SO-101 arm — cyberwave-edge-so101: joint bus + command topic pattern for a manipulator.
ROS UGV — cyberwave-edge-ros-ugv: locomotion and onboard camera profiles under cw-driver-profiles/.

Advanced topics

Once you have a working driver, these guides cover the platform features your driver can leverage:

Edge Workers

Hook-based worker modules for on-device ML inference and event-driven processing.

Data Wire Format

SDK header encoding, key expressions, and the on-wire contract for edge data channels.

Data Fusion Primitives

Time-aware sensor fusion: interpolated point reads and time-window queries.

Synchronized Multi-Channel Hooks

Approximate time synchronizer that fires when samples from all listed channels arrive within tolerance.

Record & Replay

Capture live edge data to disk and replay it for deterministic debugging.

MQTT API Reference

Complete list of MQTT topics and payload schemas: telemetry, commands, navigation, joint states, and more.

​What is a compatible driver?

​Quickstart: scaffold with the Claude skill

​Quickstart: use the SDK

​Environment variables

​Restart behavior tuning

​Driver failure handling

​Twin JSON file

​Runtime configuration

​Declare your driver interface (cw-driver.yml)

​Compliance checklist

​Why you need it

​What cw-driver.yml contains

​YAML path → MQTT topic

​Compiled catalog shape

​Reference implementations (Cyberwave drivers)

​Apply the manifest to your twin

​set_schema — REST and SDK

​Platform API reference

​Bring-up (workspace)

​Runtime state (REST alternatives to MQTT)

​Runtime messaging (MQTT)

​Edge data bus (local, not REST)

​Assets, twins, and public catalog entries

​Sensor data output

​Option A: Zenoh data bus (recommended)

​Key expression convention

​Canonical channels

​Python SDK example

​Wire format reference (for native language publishers)

​C++ native publish example

​Option B: Filesystem convention (fallback)

​Ring buffer (for stream data)

​Latest value (for state data)

​MQTT topics and payloads

​Migrating from MQTT-only drivers

​Step 1: Set CYBERWAVE_DATA_BACKEND

​Step 2: Add cw.data.publish alongside the MQTT call

​Step 3: Verify with a subscriber

​Controlling which paths are active

​Licensing your driver

​Example driver repositories

​Advanced topics

Edge Workers

Data Wire Format

Data Fusion Primitives

Synchronized Multi-Channel Hooks

Record & Replay

MQTT API Reference

What is a compatible driver?

Quickstart: scaffold with the Claude skill

Quickstart: use the SDK

Environment variables

Restart behavior tuning

Driver failure handling

Twin JSON file

Runtime configuration

Declare your driver interface (`cw-driver.yml`)

Compliance checklist

Why you need it

What `cw-driver.yml` contains

YAML path → MQTT topic

Compiled catalog shape

Reference implementations (Cyberwave drivers)

Apply the manifest to your twin

`set_schema` — REST and SDK

Platform API reference

Bring-up (workspace)

Runtime state (REST alternatives to MQTT)

Runtime messaging (MQTT)

Edge data bus (local, not REST)

Assets, twins, and public catalog entries

Sensor data output

Option A: Zenoh data bus (recommended)

Key expression convention

Canonical channels

Python SDK example

Wire format reference (for native language publishers)

C++ native publish example

Option B: Filesystem convention (fallback)

Ring buffer (for stream data)

Latest value (for state data)

MQTT topics and payloads

Migrating from MQTT-only drivers

Step 1: Set CYBERWAVE_DATA_BACKEND

Step 2: Add cw.data.publish alongside the MQTT call

Step 3: Verify with a subscriber

Controlling which paths are active

Licensing your driver

Example driver repositories

Advanced topics