repository·master·Indexed 20 days ago
https://github.com/unitreerobotics/unitree_ros2A communication layer for Unitree robots (Go2, B2, H1, G1) using ROS2 and Cyclone DDS. It enables robot control and sensor/state data acquisition via standard ROS2 messages, providing high-level interfaces like SportClient for behavior control, RobotStateClient for service management, and G1ArmActionClient for G1 arm actions, as well as low-level motor control via the /lowcmd topic.
The Unitree ROS2 package is tested and supported on the following operating systems and ROS2 versions:
| System | ROS2 Version |
|---|---|
| Ubuntu 20.04 | foxy |
| Ubuntu 22.04 | humble (Recommended) |
For containerized development, you can use the Dockerfile located in the .devcontainer folder or use VSCode Dev Containers/GitHub Codespaces.
Since the Go2 robot is compatible with ROS2 topics, you can use RViz2 to visualize its state, such as LiDAR point clouds.
To visualize the LiDAR data:
utlidar/cloud).frame_id by echoing the topic: ros2 topic echo --no-arr /utlidar/cloud (e.g., utlidar_lidar).ros2 run rviz2 rviz2.utlidar/cloud topic and set the Fixed Frame (world_frame) to the identified frame_id (e.g., utlidar_lidar).# List topics
ros2 topic list
# Check frame_id
ros2 topic echo --no-arr /utlidar/cloud
# Run RViz2
ros2 run rviz2 rviz2Unitree SDK2 requires cyclonedds 0.10.2. If you are using ROS2 Humble, you can skip this step.
Important: Before compiling, ensure that ROS2 environment variables are not automatically sourced in your terminal. You must comment out source /opt/ros/foxy/setup.bash in your ~/.bashrc file.
If compilation fails, try running export LD_LIBRARY_PATH=/opt/ros/foxy/lib first.
cd ~/unitree_ros2/cyclonedds_ws/src
# Clone the required repositories
git clone https://github.com/ros2/rmw_cyclonedds -b foxy
git clone https://github.com/eclipse-cyclonedds/cyclonedds -b releases/0.10.x
cd ..
# If build fails, try: export LD_LIBRARY_PATH=/opt/ros/foxy/lib
colcon build --packages-select cycloneddsHigh-level motion control for the Go2 robot is implemented using a request-response pattern. You can control the robot's movement by subscribing to the /api/sport/request topic and publishing unitree_api::msg::Request messages.
To simplify creating these requests, use the SportClient class (found in example/src/common/ros2_sport_client.cpp). For example, you can use SportClient::Euler to generate a request for Euler angle (roll, pitch, yaw) attitude control.
A complete high-level motion control example is provided in example/src/sport_mode_ctrl.cpp. After building, you can run it with ./install/unitree_ros2_example/bin/sport_mode_ctrl to see the robot walk back and forth along the X-axis.
// Create a ROS2 publisher
rclcpp::Publisher<unitree_api::msg::Request>::SharedPtr req_puber = this->create_publisher<unitree_api::msg::Request>("/api/sport/request", 10);
SportClient sport_req; // Instantiate a SportClient
unitree_api::msg::Request req; // Create a motion request msg
sport_req.Euler(req, roll, pitch, yaw); // Get Euler angle motion request and assign to req
req_puber->publish(req); // Publish the dataTo connect your computer to a Unitree robot (Go2, B2, H1):
ifconfig to find the Ethernet interface name (e.g., enp3s0).192.168.123.99255.255.255.0~/unitree_ros2/setup.sh to match your network interface name in the CYCLONEDDS_URI variable.Local Simulation/Loopback: If not connected to a physical robot, use the local loopback interface:
source ~/unitree_ros2/setup_local.sh (uses lo)source ~/unitree_ros2/setup_default.sh (no specific interface)# Example setup.sh content
#!/bin/bash
echo "Setup unitree ros2 environment"
source /opt/ros/foxy/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>'To install the Unitree ROS2 package, clone the repository and prepare the workspace. The repository structure includes:
cyclonedds_ws: Workspace for compiling and installing Unitree ROS2 messages (unitree_go and unitree_api).example: ROS2 examples for Unitree robots.Note: Replace foxy with your specific ROS2 version (e.g., humble) in all commands if using a different version.
git clone https://github.com/unitreerobotics/unitree_ros2Unitree robots use Cyclone DDS version 0.10.2. If you are using ROS2 Foxy, you must compile this specific version to ensure compatibility.
CRITICAL: Ensure your ROS2 environment is NOT sourced in the terminal before starting this compilation. If source /opt/ros/foxy/setup.bash is in your ~/.bashrc, comment it out first.
If compilation fails, try running export LD_LIBRARY_PATH=/opt/ros/foxy/lib before building.
# 1. Prepare environment (ensure ROS2 is NOT sourced)
# 2. Clone and build
cd ~/unitree_ros2/cyclonedds_ws/src
git clone https://github.com/ros2/rmw_cyclonedds -b foxy
git clone https://github.com/eclipse-cyclonedds/cyclonedds -b releases/0.10.x
cd ..
# If build failed, try run: `export LD_LIBRARY_PATH=/opt/ros/foxy/lib` first.
colcon build --packages-select cycloneddsLow-level control of the robot's motors (torque, position, and velocity) is achieved by publishing unitree_go::msg::LowCmd messages to the /lowcmd topic.
The motor_cmd field within the message contains the specific instructions for each motor. You can set the control mode, target position, velocity, torque, and stiffness/damping coefficients (Kp/Kd).
A complete low-level control example is provided in example/src/low_level_ctrl.cpp. After building, running ./install/unitree_ros2_example/bin/sport_mode_ctrl (note: the text indicates this binary for the low-level example) will cause the motors on the front-left leg to rotate to the target joint angles.
// Motor command structure details
// mode: 0x01 (Foc/Working mode), 0x00 (Stop/Standby mode)
// q: target position
// dq: target velocity
// tau: target torque
// kp: stiffness coefficient
// kd: damping coefficientOnce cyclonedds is compiled, you must source your ROS2 environment to provide the necessary dependencies for the Unitree specific packages.
source /opt/ros/foxy/setup.bash
colcon buildTo visualize Lidar data in Rviz2, follow these steps:
ros2 topic list to find the Lidar cloud topic (e.g., utlidar/cloud).frame_id of the Lidar topic using:ros2 topic echo --no-arr /utlidar/cloudutlidar_lidar).ros2 run rviz2 rviz2utlidar/cloud.frame_id found in step 2 (e.g., utlidar_lidar).# 1. List topics
ros2 topic list
# 2. Check frame_id
ros2 topic echo --no-arr /utlidar/cloud
# 3. Run rviz
ros2 run rviz2 rviz2To install the package, clone the repository. Note that the workspace structure is as follows:
cyclonedds_ws: Contains Unitree robot messages in unitree/unitree_go and unitree/unitree_api.example: Contains ROS2 example workspaces.Replace foxy with your ROS2 version (e.g., humble) in the installation steps if necessary.
git clone https://github.com/unitreerobotics/unitree_ros2After configuring the network and sourcing the environment, verify the connection by listing ROS2 topics. You should see topics related to the robot's state.
source ~/unitree_ros2/setup.sh
ros2 topic list
# To verify data flow, echo a specific topic:
ros2 topic echo /sportmodestate