cyberwave 0.1.6

Python SDK for the CyberWave Platform

Cyberwave Python SDK

The official Python SDK for the Cyberwave Digital Twin Platform. Create, control, and simulate digital twins with ease.

Installation

pip install cyberwave

Quick Start

1. Get Your Token

Get your API token from the Cyberwave platform:

• Log in to your Cyberwave instance
• Navigate to Settings → API Tokens
• Copy your token

2. Create Your First Digital Twin

import cyberwave as cw

# Configure with your token
cw.configure(
    token="your_token_here",
)

# Create a digital twin from an asset
robot = cw.twin("cyberwave/so101")

# Control position and rotation
robot.move(x=1.0, y=0.0, z=0.5)
robot.rotate(yaw=90)  # degrees

# Control robot joints (for URDF assets)
robot.joints.shoulder_joint = 45  # degrees
robot.joints.elbow_joint = -30

# Get current joint positions
print(robot.joints.get_all())

Core Features

Working with Workspaces and Projects

from cyberwave import Cyberwave

client = Cyberwave(
    token="your_token_here"
)

# List workspaces
workspaces = client.workspaces.list()
print(f"Found {len(workspaces)} workspaces")

# Create a project
project = client.projects.create(
    name="My Robotics Project",
    workspace_id=workspaces[0].uuid
)

# Create an environment
environment = client.environments.create(
    name="Development",
    project_id=project.uuid
)

Managing Assets and Twins

# Search for assets
assets = client.assets.search("robot")

# Create a twin from an asset
twin_data = client.twins.create(
    asset_id=assets[0].uuid,
    environment_id=environment.uuid,
    name="Robot-01"
)

# Use the high-level Twin API
from cyberwave import Twin
robot = Twin(client, twin_data)

# Move to a specific position
robot.move_to([1.0, 0.5, 0.0])

# Update scale
robot.scale(x=1.5, y=1.5, z=1.5)

# Delete when done
robot.delete()

Real-time Updates with MQTT

# Define callback for position updates
def on_position_change(data):
    print(f"Twin moved to: {data}")

# Subscribe to real-time updates
client.mqtt.subscribe_twin_position("twin_uuid", on_position_change)

# Publish position updates
client.mqtt.publish_twin_position(
    twin_id="twin_uuid",
    x=1.0, y=0.0, z=0.5
)

# Subscribe to joint states
def on_joint_update(data):
    print(f"Joint states: {data}")

client.mqtt.subscribe_joint_states("twin_uuid", on_joint_update)

Configuration Options

Using Environment Variables

export CYBERWAVE_BASE_URL="https://your-instance.cyberwave.com"
export CYBERWAVE_TOKEN="your_token_here"
export CYBERWAVE_ENVIRONMENT_ID="your_environment_id"

import cyberwave as cw

# SDK will automatically load from environment variables
robot = cw.twin("cyberwave/so101")

Programmatic Configuration

import cyberwave as cw

cw.configure(
    base_url="https://your-instance.cyberwave.com",
    token="your_token_here",              # Bearer token
    environment="env_uuid",                # Default environment
    workspace="workspace_uuid",            # Default workspace
    mqtt_host="mqtt.cyberwave.com",       # MQTT broker (optional)
    mqtt_port=1883                         # MQTT port (default: 1883)
)

Advanced Usage

Context Manager for Cleanup

from cyberwave import Cyberwave

with Cyberwave(base_url="https://api.cyberwave.com", token="token") as client:
    twins = client.twins.list()
    for twin in twins:
        print(twin.name)
# Automatically disconnects MQTT and cleans up resources

Direct API Access

For full control, access the auto-generated REST API client directly:

from cyberwave import Cyberwave

client = Cyberwave(base_url="https://api.cyberwave.com", token="token")

# Access any REST endpoint
response = client.api.src_users_api_workspaces_list_workspaces()

Joint Control

robot = cw.twin("cyberwave/so101")

# Set individual joints (degrees by default)
robot.joints.set("shoulder_joint", 45, degrees=True)

# Or use radians
import math
robot.joints.set("elbow_joint", math.pi/4, degrees=False)

# Get current joint position
angle = robot.joints.get("shoulder_joint")

# List all joints
joint_names = robot.joints.list()

# Get all joint states at once
all_joints = robot.joints.get_all()

API Reference

Cyberwave Client

• client.workspaces - Workspace management
• client.projects - Project management
• client.environments - Environment management
• client.assets - Asset catalog operations
• client.twins - Digital twin CRUD operations
• client.mqtt - Real-time MQTT client

Twin Class

• twin.move(x, y, z) - Move twin to position
• twin.move_to([x, y, z]) - Move to position array
• twin.rotate(yaw, pitch, roll) - Rotate using euler angles
• twin.rotate(quaternion=[x,y,z,w]) - Rotate using quaternion
• twin.scale(x, y, z) - Scale the twin
• twin.joints - Joint controller for robot manipulation
• twin.delete() - Delete the twin
• twin.refresh() - Reload twin data from server

Examples

Check the SDK repository for complete examples:

• Basic twin control
• Multi-robot coordination
• Real-time synchronization
• Joint manipulation for robot arms

Testing

Unit Tests

Run basic import tests:

poetry install
poetry run python tests/test_imports.py

Integration Tests

Integration tests require a running Cyberwave backend instance. Set up your credentials:

# Set backend URL (defaults to http://localhost:8000)
export CYBERWAVE_BASE_URL="http://localhost:8000"

# Set authentication (use either API key or token)
export CYBERWAVE_API_KEY="your_api_key"
# OR
export CYBERWAVE_TOKEN="your_bearer_token"

Run all integration tests:

./run_integration_tests.sh

Or run specific test suites:

# Quick read-only tests
./run_integration_tests.sh quick

# Complete workflow test (creates/deletes resources)
./run_integration_tests.sh workflow

# Error handling tests
./run_integration_tests.sh errors

# Context manager tests
./run_integration_tests.sh context

Or use pytest directly:

poetry run pytest tests/test_integration.py -v -s

Support

• Documentation: docs.cyberwave.com
• Issues: GitHub Issues
• Community: Discord