ROS 2 Driver

Docker Images

The full robot stack is published as four images on Docker Hub, each available in three tags (jazzy, humble, jetson-humble):

Image	Description
`cyberwaveos/go2-ros2-driver`	Go2 driver, streaming bridges, edge bridge
`cyberwaveos/ros2-nav2`	Nav2 navigation stack (robot-agnostic)
`cyberwaveos/ros2-slam`	SLAM — RTAB-Map, slam_toolbox, Cartographer (robot-agnostic)
`cyberwaveos/ros2-elevation-mapping`	GPU-accelerated elevation mapping (robot-agnostic)

The jetson-humble driver image ships with optimized defaults for constrained hardware.

docker pull cyberwaveos/go2-ros2-driver:jazzy
docker pull cyberwaveos/ros2-nav2:jazzy
docker pull cyberwaveos/ros2-slam:jazzy
docker pull cyberwaveos/ros2-elevation-mapping:jazzy

Quick Start

When connected to the Cyberwave platform, the edge-core service automatically pulls and starts all required containers based on the asset metadata configured for your twin. For local development with Docker Compose, see the driver README.

ROS 2 Topics

The driver publishes standard ROS 2 topics that any ROS 2 node can consume independently:

Topic	Type	Description
`/odom`	`nav_msgs/Odometry`	LiDAR-based odometry
`/point_cloud2`	`sensor_msgs/PointCloud2`	3D point cloud from LiDAR
`/scan`	`sensor_msgs/LaserScan`	2D laser scan (from point cloud)
`/camera/image_raw`	`sensor_msgs/Image`	Front camera frames
`/joint_states`	`sensor_msgs/JointState`	Joint positions and velocities
`/imu/data`	`sensor_msgs/Imu`	IMU measurements
`/map`	`nav_msgs/OccupancyGrid`	Occupancy map (from SLAM)

All robot-specific topics are namespaced as twin_<your-twin-uuid> by default.

Key Environment Variables

Variable	Default	Description
`CYBERWAVE_API_KEY`	—	Cyberwave API token
`CYBERWAVE_TWIN_UUID`	—	Digital twin UUID
`CYBERWAVE_MQTT_HOST`	`mqtt.cyberwave.com`	MQTT broker
`GO2_AES_128_KEY`	—	Per-device AES-128 key for firmware ≥ 1.1.15 (see below)
`ROBOT_IP`	(auto-discovered)	Go2 IP — validated on startup; see below
`ROBOT_IP_FALLBACKS`	`192.168.12.1,192.168.123.161`	Comma-separated IPs to probe when `ROBOT_IP` is unset or unreachable
`CONFIG_PROFILE`	(auto)	Config profile: `jazzy`, `humble`, or `jetson`
`CYBERWAVE_PERIODIC_MAP_UPLOAD_INTERVAL_SEC`	`120`	Periodic map cloud sync interval (0 to disable)
`GO2_USE_CPP_VOXEL_DECODER`	`true`	Use C++ LiDAR decoder (faster)
`GO2_OBSTACLE_AVOIDANCE`	`true`	Enable onboard obstacle avoidance (see below)
`CYBERWAVE_ENABLE_RECORDING`	(see below)	Global recording toggle for video streams
`CYBERWAVE_ENABLE_RECORDING_PREVIEW`	`false`	Record preview streams (occupancy, costmaps)

Obstacle Avoidance

When GO2_OBSTACLE_AVOIDANCE=true (the default), velocity commands are routed through the Go2’s firmware obstacle avoidance pipeline instead of the standard Sport API. The firmware fuses ultrasonic and LiDAR sensors to detect obstacles and will override velocity commands to prevent collisions. On startup the driver sends SwitchSet and UseRemoteCommandFromApi to the robot so the firmware accepts velocity commands from the ROS 2 stack rather than only the physical remote controller.

Onboard obstacle avoidance operates independently from Nav2’s path planner. The firmware may intervene — slowing down or stopping the robot — even when Nav2 considers the path clear. This can cause Nav2 goals to take longer or be aborted if the firmware repeatedly blocks planned motion. If you need full control over obstacle handling through Nav2’s costmaps and local planner, set GO2_OBSTACLE_AVOIDANCE=false.

To disable:

GO2_OBSTACLE_AVOIDANCE=false

Obstacle Avoidance & Teleoperation

There are two layers of obstacle avoidance on the Go2:

Onboard — the robot’s built-in ultrasonic + LiDAR avoidance at the firmware level.
Driver-level — path planning avoidance through costmaps constructed in real time by the navigation stack.

When GO2_OBSTACLE_AVOIDANCE=true (configurable in the twin metadata; enabled by default), the driver activates both layers for autonomous navigation.

Recommended teleoperation during mapping:

Cyberwave keyboard controller — obstacle avoidance is active (onboard + driver-level). This is the recommended way to drive the robot while building a map of your environment.
Unitree physical remote — always retains onboard obstacle avoidance regardless of driver configuration.

Both options are safe for teleoperation during mapping.

Bluetooth gamepad obstacle avoidance now depends on the active controller policy:

Local Bluetooth controller (local): obstacle avoidance stays on the robot-side local controller path.
Keyboard teleop and autonomous navigation: the driver switches to the autonomy/remote-command path, and the gamepad does not keep independent obstacle avoidance.

AES-128 Key (firmware ≥ 1.1.15)

Go2 firmware 1.1.15+ uses a per-device AES-128 key (data2=3 protocol) to encrypt the WebRTC LAN handshake. Without this key, both the driver node and native video node will fail to connect. Fetch the key using the unitree_webrtc_connect CLI (requires the Unitree account used in the Unitree Go/Explore mobile app):

pip install unitree_webrtc_connect
unitree-fetch-aes-key --email your@email.com --password 'your-password' --device-type Go2

Set the 32-hex-char key in your env file or Edge Core shared_env:

GO2_AES_128_KEY=abcdef0123456789abcdef0123456789

Older firmware (below 1.1.15) uses a static key built into the driver and does not require this variable. If GO2_AES_128_KEY is unset and the robot returns data2=3, the driver will log a clear error with instructions.

Robot IP discovery

The driver validates that the Go2 is reachable before starting any ROS 2 node, so you get a fast failure instead of a silent WebRTC hang. Resolution order:

ROBOT_IP (from env or Edge Core metadata) — probed via TCP on port 9991.
If unreachable (or unset), each address in ROBOT_IP_FALLBACKS is tried.
First address that responds is used for the entire stack.
If nothing responds, the container exits with an error and pushes a robot_unreachable alert to Cyberwave (if SDK credentials are available).

The default fallback list covers the two most common Go2 network configurations:

Address	Scenario
`192.168.12.1`	Wi-Fi AP / USB-Ethernet
`192.168.123.161`	Ethernet direct-connect

Custom networks: If your Go2 is on a different subnet (e.g. behind a router), override the fallback list:

# .env file or Edge Core shared_env
ROBOT_IP_FALLBACKS=10.0.0.50,10.0.0.51

You can set both ROBOT_IP (preferred address) and ROBOT_IP_FALLBACKS (safety net). If the preferred IP is unreachable, the driver automatically falls through to the fallback list.

The probe uses a TCP socket connect on port 9991 (Go2 WebRTC signaling) with a 2-second timeout per address. No WebRTC handshake is attempted. Simulation launches skip the check entirely.

Config Profiles

Profile	When to use
`jazzy`	Default for ROS 2 Jazzy on desktop/server hardware
`humble`	ROS 2 Humble ecosystem compatibility
`jetson`	NVIDIA Jetson: reduced costmap resolution, increased transform tolerances, lower rates

Set CONFIG_PROFILE=jetson or use the jetson-humble Docker image which sets this automatically.

Edge Core metadata

When using Cyberwave Edge Core for managed deployment, the driver stack is configured through twin/asset metadata. Edge Core reads this metadata, pulls images, and injects environment variables automatically.

Multi-container configuration

The Go2 ROS 2 stack runs as multiple cooperating containers. Define the stack in metadata.drivers using the services array:

{
  "drivers": {
    "linux-aarch64-jetson": {
      "services": [
        {
          "image": "cyberwaveos/go2-ros2-driver:jetson-humble",
          "name": "driver",
          "command": [
            "ros2",
            "launch",
            "cyberwave_go2_driver",
            "robot_driver.launch.py"
          ]
        },
        {
          "image": "cyberwaveos/go2-ros2-driver:jetson-humble",
          "name": "bridges",
          "command": [
            "ros2",
            "launch",
            "cyberwave_go2_driver",
            "robot_bridges.launch.py"
          ]
        },
        { "image": "cyberwaveos/ros2-nav2:jetson-humble", "name": "nav2" },
        { "image": "cyberwaveos/ros2-slam:jetson-humble", "name": "slam" }
      ],
      "shared_env": {
        "CONFIG_PROFILE": "jetson",
        "ROS_DOMAIN_ID": "0"
      },
      "shared_params": ["--network", "host", "-v", "/data:/data"]
    },
    "default": {
      "docker_image": "cyberwaveos/go2-ros2-driver:jazzy",
      "prefer_gpu": true
    }
  }
}

To add a service (e.g. elevation mapping), append to the services array. To set the robot IP or fallback list, add them to shared_env:

"shared_env": {
  "ROBOT_IP_FALLBACKS": "10.0.0.50,10.0.0.51",
  "CONFIG_PROFILE": "jetson"
}

See Drivers overview for the full metadata schema and Writing compatible drivers for the edge_configs per-device pattern.

Stream Recording

The Go2 driver streams video to the Cyberwave media service via WebRTC. Each stream can request server-side recording (producing MP4 artifacts for later replay).

Variable	Default	Applies to
`CYBERWAVE_ENABLE_RECORDING`	—	All streams (global override)
`CYBERWAVE_ENABLE_RECORDING_PREVIEW`	`false`	Preview streams only (occupancy grid, local/global costmaps)

Default behavior (no env vars set):

camera_bridge — records by default (true).
occupancy_grid_bridge, local_costmap_bridge, global_costmap_bridge — do not record by default.

Resolution order per bridge:

CYBERWAVE_ENABLE_RECORDING — if set, overrides everything.
Per-bridge env var (e.g. CYBERWAVE_ENABLE_RECORDING_PREVIEW) — overrides the built-in default.
Built-in default.

# Record everything including previews
CYBERWAVE_ENABLE_RECORDING_PREVIEW=true

# Disable all recording (e.g. for development)
CYBERWAVE_ENABLE_RECORDING=false

Recording is handled by the media service SFU, not on the edge device. Enabling recording adds negligible load to the robot’s hardware.

Jetson Performance Tuning

Running the full Go2 stack on a Jetson Orin Nano (or similar constrained hardware) requires tuning runtime rates and encoder settings. Add these to your .env file or Edge Core shared_env:

# ── Runtime rates (overrides vs. defaults) ───────────────────────────
GO2_STATE_PUBLISH_HZ=15          # default 10
GO2_POINTCLOUD_MAX_POINTS=4000   # default 25000
GO2_POINTCLOUD_STREAM_FPS=1      # default 5
GO2_SCAN_ANGLE_INCREMENT=0.01745 # default 0.00872
GO2_TRAV_COSTMAP_HZ=5            # default 10
GO2_TRAV_COSTMAP_GLOBAL_HZ=0.5   # default 1
GO2_LOCAL_COSTMAP_FPS=10         # default 5
GO2_GLOBAL_COSTMAP_FPS=10        # default 2

# ── Obstacle avoidance ──────────────────────────────────────────────
# Disable if Nav2 handles obstacle avoidance to save CPU.
GO2_OBSTACLE_AVOIDANCE=false     # default true

# ── H.264 encoding ──────────────────────────────────────────────────
# Jetson Orin Nano has NO hardware H.264 encoder (no NVENC).
# Skip codec probing and constrain libx264 to a single thread so it
# doesn't starve SLAM/Nav2. At 424x240@1fps ultrafast this uses <5%
# of one core.
CYBERWAVE_H264_ENCODER=libx264   # default auto
CYBERWAVE_H264_PRESET=ultrafast  # default veryfast
CYBERWAVE_H264_BITRATE_KBPS=800  # default 2500
CYBERWAVE_H264_THREADS=1         # default 0 (unlimited)

These values are tuned for a Jetson Orin Nano running the full stack (driver + Nav2 + SLAM). If your board has more headroom (e.g. Orin NX) or less (e.g. other services running), you can adjust camera and pointcloud rates accordingly.

NVIDIA Container Toolkit (Jetson / GPU)

GPU-accelerated containers (simulation, video decode, elevation mapping) require the NVIDIA Container Toolkit. This is especially important on Jetson (L4T / JetPack) where the toolkit must be installed and the runtime registered with Docker.

# Install
distribution=$(. /etc/os-release; echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit

# Register with Docker
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

On Jetson, set the NVIDIA runtime as the default so all containers get GPU access automatically:

sudo tee /etc/docker/daemon.json <<'EOF'
{
    "default-runtime": "nvidia",
    "runtimes": {
        "nvidia": {
            "args": [],
            "path": "nvidia-container-runtime"
        }
    }
}
EOF
sudo systemctl restart docker

If nvidia-container-toolkit is already installed but containers cannot access the GPU, re-run the nvidia-ctk runtime configure step, ensure daemon.json has the nvidia runtime, and restart Docker.

Overview

Drivers

MQTT API

Protobuf

REST API

Catalog

Docker Images

Quick Start

ROS 2 Topics

Key Environment Variables

Obstacle Avoidance

Obstacle Avoidance & Teleoperation

AES-128 Key (firmware ≥ 1.1.15)

Robot IP discovery

Config Profiles

Edge Core metadata

Multi-container configuration

Stream Recording

Jetson Performance Tuning

NVIDIA Container Toolkit (Jetson / GPU)

​Docker Images

​Quick Start

​ROS 2 Topics

​Key Environment Variables

​Obstacle Avoidance

​Obstacle Avoidance & Teleoperation

​AES-128 Key (firmware ≥ 1.1.15)

​Robot IP discovery

​Config Profiles

​Edge Core metadata

​Multi-container configuration

​Stream Recording

​Jetson Performance Tuning

​NVIDIA Container Toolkit (Jetson / GPU)

Docker Images

Quick Start

ROS 2 Topics

Key Environment Variables

Obstacle Avoidance

Obstacle Avoidance & Teleoperation

AES-128 Key (firmware ≥ 1.1.15)

Robot IP discovery

Config Profiles

Edge Core metadata

Multi-container configuration

Stream Recording

Jetson Performance Tuning

NVIDIA Container Toolkit (Jetson / GPU)