cyberwave-ugv-cli

A command-line interface for remote-controlling robots via the Cyberwave Python SDK.

Control joint positions, movement, camera capture, and more — from your terminal. Works with any robot supported by the Cyberwave platform (UGV Beast, Unitree Go2, SO101 arms, etc.).

Quick Start

pip install cyberwave>=0.4.1

Create a .env file:

CYBERWAVE_API_KEY="your_token"
CYBERWAVE_TWIN_ID="your-twin-uuid"
CYBERWAVE_ENVIRONMENT_ID="your-env-uuid"

Start commanding:

# Read joint states
python ugv_ctl.py joints

# Move forward 1 metre
python ugv_ctl.py forward 1.0

# Capture a photo
python ugv_ctl.py capture -o photo.jpg

# Emergency stop
python ugv_ctl.py stop

Features

• Joint control — read and set individual joint positions (degrees or radians)
• Movement — forward, backward, turn-left, turn-right with configurable speed
• Camera — cloud-based or direct edge capture via MQTT (--edge)
• Sensors — list available sensors and hardware capabilities
• Workflows — list and trigger Cyberwave workflows
• Simulation/Live mode — target digital twin or physical robot
• Bash completion — tab-complete all commands and options
• JSON output — machine-readable output for scripting (--json)

Commands

Command	Description
joints	Read all joint states
joint-get NAME	Read one joint
joint-set NAME VALUE	Set a joint position
forward METRES	Move forward
backward METRES	Move backward
turn-left DEGREES	Turn left
turn-right DEGREES	Turn right
stop	Emergency stop
pan ANGLE	Camera pan
tilt ANGLE	Camera tilt
capture	Capture camera frame
capture --edge	Edge capture via MQTT
camera-read	Read frame as NumPy/bytes
camera-snapshot	Save JPEG snapshot
sensors	Show sensors and capabilities
position X Y Z	Set twin position
rotation YAW	Set twin rotation
info	Show twin info
workflows	List workflows
workflow-trigger UUID	Trigger a workflow

Full usage guide: UGV_CLI.md

Simulation vs Live

By default, commands target the digital twin (simulation). Use --mode live to command the physical robot:

python ugv_ctl.py --mode live forward 0.5

Edge Capture

The --edge flag captures photos directly from the robot via MQTT, bypassing the cloud:

python ugv_ctl.py capture --edge -o photo.jpg

This is faster and works without cloud connectivity, but requires MQTT access to the edge device. Not all drivers support it — fall back to cloud capture if it times out.

Joint Names

Joint names are robot-specific. Run joints to discover your robot's joints:

python ugv_ctl.py joints

The pan and tilt commands accept --joint to override the default joint name:

python ugv_ctl.py pan 30 --joint shoulder_pan

Configuration

Three ways to provide credentials (in priority order):

1. CLI flags: --token, --twin-id, --environment-id
2. Environment variables: CYBERWAVE_API_KEY, CYBERWAVE_TWIN_ID, CYBERWAVE_ENVIRONMENT_ID
3. .env file: Auto-loaded from current directory

Requirements

• Python 3.10+
• cyberwave >= 0.4.1
• A Cyberwave account with API key and twin/environment UUIDs

License

MIT