ROS 2 on Unitree robots: from zero to your first topic

ROS 2 on Unitree robots works without reverse engineering and without translation nodes: the robot publishes its data over DDS (CycloneDDS), and ROS 2 uses DDS as its communication layer. The official unitree_ros2 package provides the message definitions and the environment scripts. This guide summarises the procedure from the official README, including the points where people usually get stuck.

Which Unitree robots support ROS 2

Software development is only available on the developer versions. For the Go2, the official page indicates secondary development on the EDU version, not on Air and Pro; for the G1 the same applies with the G1 EDU.

For R1 and A2, as of October 2026 unitree_sdk2 contains dedicated C++ examples, but unitree_ros2 still has no specific examples. Before buying one of these models for a ROS 2-only project, check the state of the repository.

Requirements: Ubuntu and the ROS 2 version

The unitree_ros2 README lists two tested combinations:

• Ubuntu 22.04 + ROS 2 Humble, listed as recommended;
• Ubuntu 20.04 + ROS 2 Foxy.

According to the ROS 2 releases table, Foxy reached end of support on 20 June 2023, while Humble is supported until May 2027 and Jazzy until May 2029. For a project starting today the practical choice is Humble; Jazzy is not among the combinations tested by Unitree. ROS 2 Humble installs from Debian packages following the official guide.

Installing unitree_ros2 step by step

1. Clone the repository and install the dependencies (with Humble replace foxy with humble):

git clone https://github.com/unitreerobotics/unitree_ros2
sudo apt install ros-humble-rmw-cyclonedds-cpp
sudo apt install ros-humble-rosidl-generator-dds-idl
sudo apt install libyaml-cpp-dev

2. Only with Foxy: build CycloneDDS 0.10.x in the cyclonedds_ws workspace, in a terminal where ROS 2 has not been sourced. The robot uses CycloneDDS 0.10.2; with Humble this step is not needed.

3. Build the message packages (unitree_go, unitree_hg, unitree_api):

cd ~/unitree_ros2/cyclonedds_ws
source /opt/ros/humble/setup.bash
colcon build

Network and CycloneDDS

Connect the PC to the robot with an Ethernet cable. In the interface settings set manual IPv4, address 192.168.123.99, netmask 255.255.255.0, as the README says. With ifconfig or ip a find the interface name (for example enp3s0) and put it in ~/unitree_ros2/setup.sh:

#!/bin/bash
source /opt/ros/humble/setup.bash
source $HOME/unitree_ros2/cyclonedds_ws/install/setup.bash
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
export CYCLONEDDS_URI='<CycloneDDS><Domain><General><Interfaces>
  <NetworkInterface name="enp3s0" priority="default" multicast="default" />
</Interfaces></General></Domain></CycloneDDS>'

The decisive line is RMW_IMPLEMENTATION=rmw_cyclonedds_cpp: Humble's default middleware is a different one, and without this variable the PC does not see the robot. The ROS 2 documentation explains how to choose the DDS middleware. Without a robot connected you can use setup_local.sh, which works on the loopback interface.

First topic

source ~/unitree_ros2/setup.sh
ros2 topic list
ros2 topic echo /sportmodestate

On Go2 and B2 /sportmodestate reports position, velocity and gait; /lowstate reports motors, IMU and battery. To build and run the examples:

cd ~/unitree_ros2/example
colcon build
./install/unitree_ros2_example/bin/read_motion_state

The README also shows how to visualise the Go2 LiDAR point cloud in RViz2, on the utlidar/cloud topic with the utlidar_lidar frame.

Control: high level and low level

• High level (Go2, B2): requests on /api/sport/request with unitree_api messages, generated by the SportClient class in the examples. The robot uses its own motion control.
• Low level: position, velocity, torque and gain commands on /lowcmd. The built-in motion service must first be disabled, otherwise the commands overlap. On humanoids you enter debug mode with L2+R2, with the robot suspended: the full procedure is in the programming the G1 guide.

Simulate before touching hardware

unitree_mujoco is the official MuJoCo-based simulator: it accepts programs written with unitree_sdk2, unitree_sdk2_python and unitree_ros2, with the same low-level messages as the real robot. The recommended flow is to develop in simulation on loopback, then run the same code on the robot by changing the network interface. For locomotion policies there is unitree_rl_gym (Go2, G1, H1, H1-2).

Common errors

• No topics: RMW not set, wrong interface in setup.sh or the PC outside the subnet. The README also recommends rebooting the PC after the first configuration.
• CycloneDDS build failed on Foxy: the terminal had already sourced /opt/ros/foxy/setup.bash; comment out the line in ~/.bashrc and reopen the terminal.
• Multiple ROS installs on the same PC: avoid putting setup.sh in ~/.bashrc and source it by hand when needed.

For university labs, Abra Robotics supplies the Unitree range in the UK and offers SDK training and development as separate services, with support in English: see Universities and Research and Software. The developer version pages are Go2 EDU and G1 EDU.