Asset and driver spec - Cyberwave Docs

This page lists the files, fields and limits you use when you add your own robot. For the step-by-step walkthrough, see Add your own robot.

Asset package

An asset is the reusable definition of a piece of hardware: its 3D meshes and kinematic model. Cyberwave creates a custom asset from a URDF package that you upload.

What is a URDF?

URDF (Unified Robot Description Format) is the standard XML format used in ROS to describe a robot’s links, joints, visuals, and collisions. Useful open-source references:

A complete sample is available: dji-mini-4-pro.zip (one base_link, four propeller links, four continuous joints).

ZIP layout

The package is a single ZIP archive that contains:

One main .urdf (or .xacro) file
Every file referenced by that URDF (meshes, textures, materials)

Put them in a folder, then zip that folder.

my-robot/
  urdf/
    robot.urdf
  meshes/
    base_link.stl
    arm_collision.stl
    arm_visual.obj
  textures/
    arm_albedo.png

Limit	Value
Maximum ZIP size	512 MB, enough for large full-mesh assets like humanoid robots
URDF files per ZIP	One main file. If there are several, set Main URDF path
Symbolic links	Supported and resolved automatically

Cyberwave unpacks and validates the archive after you create the asset.

File references inside URDF

Your URDF can reference other files, for example:

STL files for collision geometry
OBJ files for visual geometry / textured visuals
Texture image files used by materials (for example PNG/JPG)

Use relative paths that match your ZIP structure. If the URDF references meshes/arm_visual.obj, that file must exist in the ZIP. ROS package:// URIs must be switched to relative paths.

Upload form fields

The dashboard upload has three steps: Package, Details and Access. The steps are in Create the asset.

Step	Field	Notes
Package	URDF Package (ZIP)	The ZIP described above. Drag and drop, or click to select
Details	Name	A clear name, for example `Acme Arm v1`
Details	Description	A short description of what the robot or prop is
Details (Advanced)	Main URDF path	Optional. Path to the main URDF inside the ZIP, for example `urdf/robot.urdf`. Leave it empty to auto-detect when the ZIP has only one URDF. Set it when the ZIP has more than one
Details (Advanced)	Thumbnail	Optional. Preview image (PNG or JPG) for the asset card. If you don’t upload one, Cyberwave can generate one automatically
Access	Visibility	See below. Can be changed after creation
Access	Workspace	The workspace the asset belongs to

Visibility	Who can view
Private	Only you
Organization	All members of your organization
Public	Anyone on the platform

Upload from the API (`create-with-urdf`)

Use:

POST /api/v1/assets/create-with-urdf

Example:

curl -X POST "https://api.cyberwave.com/api/v1/assets/create-with-urdf" \
  -H "Authorization: Bearer $CYBERWAVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://example.com/my-robot.zip",
    "force_name": "my-robot",
    "main_file_path": "urdf/robot.urdf",
    "description": "My robot uploaded from URDF ZIP"
  }'

API payload fields:

Field	Required	Description
`file_url`	Yes	URL to your ZIP file
`force_name`	Yes	Name for the asset
`main_file_path`	Yes	Main URDF path in the ZIP
`description`	No	Asset description
`subfolder`	No
`branch`	No

For API uploads, make sure file_url is reachable by Cyberwave and points to the final ZIP file.

Python SDK upload methods are listed on the Catalog page.

Set physics properties

When Cyberwave processes your URDF ZIP it generates a universal schema — the canonical JSON representation of your robot. The schema includes a physics object that controls world-level simulation parameters such as gravity, timestep, solver, and default contact surface.

There is no physics editor in the UI yet. Use the PATCH API below to configure physics after uploading.

Physics object structure

Field	Type	Default	Description
`gravity`	`{x, y, z}`	`{x: 0, y: 0, z: -9.81}`	World gravity vector
`timestep`	`float`	`0.001`	Simulation timestep (seconds)
`solver.type`	`string`	`"quick"`	Solver type: `quick`, `ode`, `bullet`, `dart`, `simbody`
`solver.iterations`	`int`	`50`	Solver iterations per step
`contact.mu_static`	`float`	`0.8`	Default static friction
`contact.mu_dynamic`	`float`	`0.7`	Default dynamic friction
`contact.restitution`	`float`	`0.1`	Default restitution (bounciness)
`contact.stiffness`	`float`	`10000.0`	Contact stiffness
`contact.damping`	`float`	`20.0`	Contact damping

Set physics via API

Use the universal schema PATCH endpoint:

PATCH /api/v1/assets/{uuid}/universal-schema

Each call sends a single JSON Pointer operation:

curl -X PATCH "https://api.cyberwave.com/api/v1/assets/$ASSET_UUID/universal-schema" \
  -H "Authorization: Bearer $CYBERWAVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "op": "add",
    "path": "/physics",
    "value": {
      "gravity": { "x": 0, "y": 0, "z": -9.81 },
      "timestep": 0.001,
      "solver": {
        "type": "quick",
        "iterations": 50
      },
      "contact": {
        "mu_static": 0.8,
        "mu_dynamic": 0.7,
        "restitution": 0.1
      }
    }
  }'

You can also patch individual sub-fields without overwriting the entire object:

curl -X PATCH "https://api.cyberwave.com/api/v1/assets/$ASSET_UUID/universal-schema" \
  -H "Authorization: Bearer $CYBERWAVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "op": "replace",
    "path": "/physics/gravity",
    "value": { "x": 0, "y": 0, "z": -3.71 }
  }'

Set physics via Python SDK

The Python SDK provides convenience methods so you don’t need to craft JSON Pointer operations manually. All setter methods use a read-modify-write pattern: omitted fields keep their current values.

import cyberwave

cw = cyberwave.Cyberwave()

`set_physics` — set multiple physics fields at once

cw.assets.set_physics(
    asset_id,
    gravity={"x": 0, "y": 0, "z": -9.81},
    timestep=0.002,
    solver={"type": "quick", "iterations": 100},
    contact={"mu_static": 1.0, "restitution": 0.05},
)

Parameter	Type	Description
`gravity`	`dict`	`{"x", "y", "z"}` vector
`timestep`	`float`	Simulation timestep (seconds)
`solver`	`dict`	Solver config (merged with existing)
`contact`	`dict`	Contact surface (merged with existing)

`set_gravity` — shorthand for the gravity vector

cw.assets.set_gravity(asset_id, z=-3.71)   # Mars
cw.assets.set_gravity(asset_id, z=0.0)     # Zero-g
cw.assets.set_gravity(asset_id)             # Earth (default)

`set_physics_solver` — configure the solver

cw.assets.set_physics_solver(
    asset_id,
    solver_type="bullet",
    iterations=200,
)

Parameter	Type	Description
`solver_type`	`str`	`"quick"`, `"ode"`, `"bullet"`, `"dart"`, `"simbody"`
`iterations`	`int`	Solver iterations per step
`sor`	`float`	Successive Over-Relaxation (ODE)
`min_step_size`	`float`	Minimum step size
`max_step_size`	`float`	Maximum step size
`tolerance`	`float`	Solver tolerance

`set_contact_properties` — tune the default contact surface

cw.assets.set_contact_properties(
    asset_id,
    mu_static=1.0,
    restitution=0.0,
)

Parameter	Type	Default	Description
`mu_static`	`float`	`0.8`	Static friction
`mu_dynamic`	`float`	`0.7`	Dynamic friction
`restitution`	`float`	`0.1`	Bounciness
`stiffness`	`float`	`10000.0`	Contact stiffness
`damping`	`float`	`20.0`	Contact damping

`get_physics` — read the current physics

physics = cw.assets.get_physics(asset_id)
if physics:
    print(physics["gravity"])    # {"x": 0, "y": 0, "z": -9.81}
    print(physics["timestep"])   # 0.001

Returns None if no physics have been configured yet.

Universal schema helpers (Python SDK)

Beyond physics, the SDK exposes general-purpose methods for reading and writing any part of the universal schema.

`get_universal_schema` — download the full schema

schema = cw.assets.get_universal_schema(asset_id)
print(schema["links"])
print(schema["extensions"]["cyberwave"]["capabilities"])

`get_universal_schema_at_path` — read a specific sub-path

result = cw.assets.get_universal_schema_at_path(asset_id, "/sensors/0")
sensor = result["value"]

result = cw.assets.get_universal_schema_at_path(asset_id, "/physics/gravity")
gravity = result["value"]

`patch_universal_schema` — write to any JSON Pointer path

cw.assets.patch_universal_schema(
    asset_id,
    path="/extensions/cyberwave/capabilities/locomotion",
    value={"mode": "wheeled", "has_wheels": True},
    op="add",
)

Parameter	Type	Description
`path`	`str`	JSON Pointer (e.g. `"/physics/gravity"`, `"/sensors/0/name"`)
`value`	`any`	Value to set
`op`	`str`	`"add"` or `"replace"` (default: `"replace"`)

`rebuild_universal_schema` — regenerate from source files

cw.assets.rebuild_universal_schema(asset_id)

Re-parses the uploaded URDF/MJCF/SDF and regenerates the schema. Useful after uploading new source files or to discard manual edits.

Physics tuning best practices

Getting physics parameters right is the difference between a simulation that behaves like the real world and one that explodes on the first contact. This section distills practical guidance from the MuJoCo, Bullet, and Gazebo communities.

Pick the right timestep

The timestep is the single most impactful parameter. Too large and the simulation becomes unstable; too small and you waste compute for no visible gain.

Scenario	Recommended timestep	Notes
General-purpose robotics	0.001 – 0.002 s	Safe default; matches most control loops
High-frequency control (impedance, force)	0.0003 – 0.0005 s	Required for stiff contacts and precise force control
Fast prototyping / locomotion RL	0.002 – 0.005 s	Acceptable if contacts are simple
> 0.005 s	Avoid	High risk of instability, tunneling, and divergence

Your control timestep must be an exact integer multiple of the physics timestep. For example, a 50 Hz control loop (0.02 s) with a 0.002 s physics timestep means 10 physics sub-steps per control step. Fractional ratios cause subtle timing bugs.

Choose a solver type

Cyberwave maps solver types to the underlying engine. Use this as a starting point:

Solver	Strengths	When to use
`quick` (default)	Fast, good general stability	Most use cases — manipulators, mobile robots
`ode`	Mature LCP solver, predictable friction	Wheeled / skid-steer robots, legacy Gazebo models
`bullet`	Good for large scenes, GPU-friendly	Multi-robot environments, RL at scale
`dart`	Accurate analytical LCP	Academic benchmarking, precision contact studies
`simbody`	Multibody dynamics focus	Biomechanics, articulated soft bodies

Increase iterations (default 50) when you see jitter or interpenetration at contacts. Higher iterations improve accuracy at the cost of speed — 100–200 is a reasonable upper bound before you should reduce the timestep instead.

Tune contact parameters for realism

Default contact values are deliberately “grippy” (high friction, low restitution). This works well for tabletop manipulation but may need adjustment for other scenarios. Friction (mu_static, mu_dynamic)

Surface pair	Typical `mu_static`	Typical `mu_dynamic`
Rubber on concrete	0.8 – 1.0	0.6 – 0.8
Metal on metal	0.3 – 0.5	0.2 – 0.4
Plastic on wood	0.3 – 0.4	0.2 – 0.3
Teflon / low-friction	0.04 – 0.1	0.03 – 0.08

When two objects collide, most engines pick the minimum friction of the two surfaces. Set friction on your robot’s gripper pads separately from the rest of the body.

Restitution (bounciness)

0.0 – completely inelastic (objects stick on contact) — good for grippers and heavy payloads
0.1 – default; slight energy absorption
0.5 – 0.8 – bouncy; use for balls, elastic impacts
1.0 – perfectly elastic (no energy loss) — rarely realistic

Stiffness and damping control how “soft” contacts feel. The defaults (10 000 / 20) model hard rigid bodies. Lower stiffness for deformable objects or compliant surfaces; increase damping if contacts oscillate.

Prepare for sim-to-real transfer

If your goal is to deploy policies trained in simulation onto real hardware, physics parameters are a critical part of the reality gap. 1. Measure, don’t guess. Use a scale, force gauge, or system identification to get real mass, inertia, and joint friction values. Even rough measurements beat defaults — research shows unexpectedly high friction-torque ratios in real joints compared to simulation defaults. 2. Randomize what you can’t measure. Domain randomization over physics parameters helps policies generalize. Randomize friction (±30%), mass (±10%), and contact stiffness across training episodes. This is especially important for contact-rich tasks like assembly or grasping. 3. Validate on simple motions first. Before training a full policy, compare simulated vs. real joint trajectories on a basic motion (e.g., gravity drop, sine-wave tracking). If these diverge, fix the model before scaling up. 4. Iterate on the timestep last. Changing the timestep affects controller gains, contact behavior, and training speed simultaneously. Get other parameters right first, then tune timestep if needed.

A policy that achieves 95% success in simulation can drop to 30–50% on real hardware without careful parameter calibration. Investing time in physics tuning pays off more than training longer.

Common pitfalls

Symptom	Likely cause	Fix
Objects explode on contact	Timestep too large	Reduce to 0.001 s or lower
Robot slides on flat ground	Friction too low	Increase `mu_static` to 0.8+
Grasped objects slip through fingers	Solver iterations too low	Increase to 100+; check collision geometry
Joints oscillate / vibrate	Damping too low or timestep too large	Increase contact damping; reduce timestep
Simulation runs but doesn’t match real robot	Default inertia / friction values	Measure real parameters; use domain randomization
Objects bounce unrealistically	Restitution too high	Set to 0.0 – 0.1 for most rigid contacts

Driver config files

Four files come up when you integrate a robot. They do different jobs.

Artifact	What it declares	Who writes it	Who reads it	Required?
Asset `metadata.drivers` (JSON on the asset or twin)	Which Docker image(s) run for this robot, per platform, with Docker params, GPU and multi-container `services`	You, on the asset	Edge Core, when it starts drivers for linked twins	Yes, from L2
`cw-driver.yml`	The driver’s interface: MQTT topics, Zenoh channels, supported commands	You, or exported from your `BaseDriver` subclass	The platform compiles it into the twin’s `metadata.mqtt` / `metadata.zenoh` when you call `twin.driver.set_schema(...)`. The UI teleop overlay and `twin.commands.*` read the result	Yes, from L2
`manifest.yaml` (ROS 2 drivers)	ROS node parameters, topics and `managed_launch`, merged with the `cw-driver` catalog	Exported by `BaseROS2Driver.write_manifest()`; don’t hand-edit it	`BaseROS2Driver` at runtime (`CW_DRIVER_MANIFEST`), and `set_schema`, which extracts the `cw-driver` keys	Only for ROS 2 drivers, instead of a separate `cw-driver.yml`
`cyberwave.yml`	Cloud nodes and edge ML workers: install, inference, training, models	You, for cloud nodes and workers	Cloud nodes, Edge Core’s worker container	Not for drivers

The image that runs for your robot is set in the asset’s metadata.drivers, not in a cyberwave.yml driver: block. The method that registers a driver interface is twin.driver.set_schema(...). twin.commands only invokes and lists commands.

Where each is documented: Drivers (metadata.drivers) · Writing compatible drivers (cw-driver.yml) · BaseROS2Driver (combined manifest) · cyberwave.yml.

`cw-driver.yml` topic mapping

Each YAML path under mqtt compiles to a flat MQTT topic:

YAML path	MQTT topic
`mqtt.joint.update`	`cyberwave/joint/{twin_uuid}/update`
`mqtt.twin.command`	`cyberwave/twin/{twin_uuid}/command`

commands.supported entries are either a plain name (discrete, one-shot) or an object such as { name: move_forward, continuous: true, rate_hz: 10 } (stick-held). set_schema compiles the file through POST /api/v1/twins/{uuid}/driver-schema. Full topic list: MQTT reference.

`metadata.drivers` keys

Edge Core reads metadata.drivers on the asset (or twin) and starts one container per linked twin.

Key or field	Meaning
`default`	Entry used when no platform key matches the host
Platform keys, for example `linux-aarch64-jetson` or `darwin-arm64`	Edge Core uses the most specific key for the host
`docker_image`	Image to run for a single-container driver
`services`	Use instead of `docker_image` for multi-container stacks (driver + Nav2 + SLAM)
`params`	Extra Docker arguments, for example `["--network", "host"]`. Pass env vars as `-e KEY=value` pairs
`prefer_gpu`	GPU preference for the container, for example `true`

On a Jetson with no Jetson key, Edge Core tries a jetson--prefixed tag first. Changing the asset affects twins created afterwards. Reference: Drivers.

Driver environment variables

Edge Core injects these when it runs your container, so you can assume they’re always set:

Variable	Description
`CYBERWAVE_TWIN_UUID`	UUID of the twin this driver manages
`CYBERWAVE_API_KEY`	API key scoped to this driver
`CYBERWAVE_TWIN_JSON_FILE`	Path to a writable JSON file with the twin’s current state
`CYBERWAVE_CHILD_TWIN_UUIDS`	(optional) Comma-separated UUIDs of attached child twins (e.g. cameras)

Other variables used by drivers:

Variable	Description
`CW_ROS2_AUTO_ACTIVATE`	`true` is recommended during development of `BaseROS2Driver` drivers
`CW_DRIVER_MANIFEST`	Combined manifest that `BaseROS2Driver` reads at runtime
`CYBERWAVE_DATA_BACKEND`	Set to `zenoh` when you run the driver locally with `docker run`

Supported protocols

Integration happens at the driver layer, so Cyberwave is protocol-agnostic and sits alongside the tools your team already uses. The same driver pattern bridges any of these to the digital twin:

ROS 1 / ROS 2: robot arms, mobile robots, and sensor stacks
VDA5050: AGV / AMR fleet communication
OPC UA: industrial automation and PLC connectivity
Modbus TCP / RTU: sensor and actuator networks
gRPC / REST: custom services and microservice architectures
Serial / USB: direct device control (servos, microcontrollers)

Drivers run as Docker containers managed by Edge Core, on the edge device, on the robot, in the cloud, or on your laptop.

Open-source repositories

All integration libraries and reference drivers live under the cyberwave-os GitHub organization:

Repository	Description
cyberwave-edge-core	Edge orchestrator
cyberwave-edge-python	Python Edge SDK
cyberwave-python	Python platform SDK
cyberwave-edge-camera-driver	Reference camera driver
cyberwave-edge-so101	Reference SO-101 arm driver
cyberwave-edge-ros-ugv	Reference mobile base driver (locomotion + onboard camera)
driver-skill	AI scaffolding skill for new drivers

​Asset package

​What is a URDF?

​ZIP layout

​File references inside URDF

​Upload form fields

​Upload from the API (create-with-urdf)

​Set physics properties

​Physics object structure

​Set physics via API

​Set physics via Python SDK

​set_physics — set multiple physics fields at once

​set_gravity — shorthand for the gravity vector

​set_physics_solver — configure the solver

​set_contact_properties — tune the default contact surface

​get_physics — read the current physics

​Universal schema helpers (Python SDK)

​get_universal_schema — download the full schema

​get_universal_schema_at_path — read a specific sub-path

​patch_universal_schema — write to any JSON Pointer path

​rebuild_universal_schema — regenerate from source files

​Physics tuning best practices

​Pick the right timestep

​Choose a solver type

​Tune contact parameters for realism

​Prepare for sim-to-real transfer

​Common pitfalls

​Driver config files

​cw-driver.yml topic mapping

​metadata.drivers keys

​Driver environment variables

​Supported protocols

​Open-source repositories

Asset package

What is a URDF?

ZIP layout

File references inside URDF

Upload form fields

Upload from the API (`create-with-urdf`)

Set physics properties

Physics object structure

Set physics via API

Set physics via Python SDK

`set_physics` — set multiple physics fields at once

`set_gravity` — shorthand for the gravity vector

`set_physics_solver` — configure the solver

`set_contact_properties` — tune the default contact surface

`get_physics` — read the current physics

Universal schema helpers (Python SDK)

`get_universal_schema` — download the full schema

`get_universal_schema_at_path` — read a specific sub-path

`patch_universal_schema` — write to any JSON Pointer path

`rebuild_universal_schema` — regenerate from source files

Physics tuning best practices

Pick the right timestep

Choose a solver type

Tune contact parameters for realism

Prepare for sim-to-real transfer

Common pitfalls

Driver config files

`cw-driver.yml` topic mapping

`metadata.drivers` keys

Driver environment variables

Supported protocols

Open-source repositories