---
id: ros2-integration
title: "ROS2 Integration"
status: established
source_sections: "reference/sources/github-unitree-ros2.md, reference/sources/official-developer-guide.md"
related_topics: [sdk-programming, networking-comms, simulation]
key_equations: []
key_terms: [ros2, dds, cyclone_dds]
images: []
examples: []
open_questions:
  - "Complete list of ROS2 topics and services for G1"
  - "RViz visualization configuration details"
  - "Is ROS2 Jazzy supported?"
---

# ROS2 Integration

ROS2 middleware integration, packages, topics, and services for the G1.

## 1. Supported Distributions

| OS              | ROS2 Distribution | Status        | Tier |
|----------------|-------------------|---------------|------|
| Ubuntu 20.04    | Foxy              | Supported     | T0   |
| Ubuntu 22.04    | Humble            | Recommended   | T0   |

[T0 — unitree_ros2 GitHub README]

## 2. Architecture

The `unitree_ros2` package communicates directly via DDS at the middleware level — it does **not** wrap the SDK. Instead, it uses the same CycloneDDS 0.10.2 protocol that the SDK uses, providing native ROS2 compatibility. [T0]

```
ROS2 Application ←→ CycloneDDS 0.10.2 ←→ Robot (DDS topics)
                                          ↕
unitree_sdk2 ←→ CycloneDDS 0.10.2 ←→ Robot (DDS topics)
```

Both paths use the same underlying DDS transport and can coexist.

## 3. Unitree ROS2 Packages

| Package / Directory  | Purpose                                      |
|---------------------|----------------------------------------------|
| `cyclonedds_ws/`     | ROS2 message definitions for Unitree DDS types |
| `example/src/`       | Sample state reading and motor control apps   |
| `.devcontainer/`     | Docker development environments               |

Repository: https://github.com/unitreerobotics/unitree_ros2 [T0]

### Related Packages

| Package               | Repository                                              | Purpose                        |
|-----------------------|--------------------------------------------------------|--------------------------------|
| `unitree_ros2_to_real` | https://github.com/unitreerobotics/unitree_ros2_to_real | Real-time control from ROS2   |
| `g1pilot`              | https://github.com/hucebot/g1pilot                     | Community ROS2 G1 control     |

## 4. Capabilities

- **State acquisition:** Sport mode states, position/velocity/gait data, motor states, power info, wireless controller input [T0]
- **Robot control:** High-level sport mode (request/response), low-level motor control (torque/position/velocity) [T0]
- **Visualization:** RViz support for LiDAR point clouds and sensor data [T0]
- **Joint state publishing:** Standard `sensor_msgs/JointState` for visualization and planning [T1]

## 5. Installation

```bash
# Clone repository
git clone https://github.com/unitreerobotics/unitree_ros2.git

# Build CycloneDDS workspace first
cd unitree_ros2/cyclonedds_ws
colcon build

# Source the workspace
source install/setup.bash

# Build examples
cd ../example
colcon build
```

**Critical:** CycloneDDS version must be exactly 0.10.2. Version mismatches will cause communication failures. [T0]

## 6. URDF / Robot Description

| Source                 | Format | Location                            | Notes                    |
|-----------------------|--------|-------------------------------------|--------------------------|
| `unitree_ros`          | URDF   | `robots/g1_description/`            | Mass, inertia, joint limits |
| MuJoCo Menagerie       | MJCF   | `unitree_g1/g1.xml`                 | Optimized for MuJoCo     |
| `unitree_model`        | USD    | Deprecated → HuggingFace            | For Isaac Sim             |

The primary URDF is in the `unitree_ros` repository at https://github.com/unitreerobotics/unitree_ros. It includes mass, inertia, moment, and joint limits data. [T0]

**Note:** The URDF is designed for MuJoCo, not Gazebo. Gazebo simulation cannot do high-level control (walking). [T1]

## 7. Middleware Configuration

- **DDS implementation:** CycloneDDS 0.10.2 (mandatory)
- **Domain ID:** Configure via `ROS_DOMAIN_ID` environment variable
- **Sim vs Real:** Change domain ID to switch between simulated and real robot
- **QoS:** Default QoS profiles work for most use cases

## Key Relationships
- Built on: [[sdk-programming]] (shared DDS communication layer)
- Uses: [[networking-comms]] (CycloneDDS middleware)
- Enables: [[simulation]] (ROS2 bridge to sim environments)
- Models in: [[simulation]] (URDF/MJCF for visualization and planning)