legged_ros2

ROS 2 packages for the control, simulation, and deployment of legged robots. Mujoco simulation can be performed in two ways:

• Mujoco Direct: Implements a custom hardware interface that communicates directly with Mujoco via its API. This approach offers greater flexibility and supports non-Unitree robots.
• Mujoco SDK2: Uses the modified Mujoco version provided by Unitree, allowing the same hardware interface as the real robot through the Unitree SDK2. This enables running identical code on both the real robot and the Mujoco simulation, providing a more convenient workflow for Unitree robots.

The deployment is based on the ROS2 Control framework.

Supported robots:

Robot Name	Mujoco Direct	Mujoco SDK2	Real
Unitree G1	✔️	✔️	✔️
Unitree Go2	✔️	✔️	TODO

Installation

Dependencies

You need to install the following dependencies:

sudo apt install ros-humble-ros2-control ros-humble-ros2-controllers

Change DDS Implementation (Optional)

If you want to use the Mujoco SDK2 method to simulate the Unitree robots, you need to change the default DDS implementation, otherwise you may encounter error, see this issue. The following steps is referred from unitree official doc.

First install the dependences:

sudo apt install ros-humble-rmw-cyclonedds-cpp
sudo apt install ros-humble-rosidl-generator-dds-idl

Before compiling cyclonedds, please ensure that ros2 environment has NOT been sourced when starting the terminal. Otherwise, it may cause errors in compilation.

If source/opt/ros/humble/setup.bash has been added to the ~/.bashrc file when installing ROS2, it needs to be commented out:

sudo apt install gedit
sudo gedit ~/.bashrc

# in .bashrc
# source /opt/ros/humble/setup.bash 

Then build cyclone-dds:

mkdir -p ~/cyclonedds_ws/src
cd ~/cyclonedds_ws/src
git clone https://github.com/ros2/rmw_cyclonedds -b humble
git clone https://github.com/eclipse-cyclonedds/cyclonedds -b releases/0.10.x 
cd ..
colcon build --packages-select cyclonedds #Compile cyclone-dds package
source /opt/ros/humble/setup.bash # source ROS2 environment
colcon build # Compile all packages in the workspace

After that, you can rewrite the source/opt/ros/humble/setup.bash in .bashrc:

# in .bashrc
source /opt/ros/humble/setup.bash
source ~/cyclonedds_ws/install/setup.bash
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
# To avoid conflict with Unitree SDK2's DDS Communication:
export ROS_DOMAIN_ID=10 # or other number you like, except 0

Build

Download Mujoco 3.2.7 (Prebuilt binaries) from the releases page. Extract the downloaded file to a directory of your choice.

Create a ros2 workspace and clone the repository:

mkdir -p ~/legged_ws/src
cd ~/legged_ws/src
# Https: 
git clone https://github.com/zitongbai/legged_ros2.git
# or SSH:
# git clone [email protected]:zitongbai/legged_ros2.git

Download the ONNX Runtime to the src/legged_ros2/third_party directory:

cd ~/legged_ws/src/legged_ros2/third_party
# Download the ONNX Runtime
wget https://github.com/microsoft/onnxruntime/releases/download/v1.22.0/onnxruntime-linux-x64-1.22.0.tgz
# Extract the downloaded file
tar -xvzf onnxruntime-linux-x64-1.22.0.tgz

Set the environment variable for Mujoco and build the workspace:

cd ~/legged_ws
export MUJOCO_DIR=/PATH/TO/mujoco-3.2.7 # Replace with your actual path
colcon build --symlink-install
source install/setup.bash

Usage

Use Unitree G1 as an example, the usage is similar for other robots.

Mujoco Direct

Todo: Add usage instructions for Mujoco Direct.

Mujoco SDK2

A joystick (support "xbox" and "switch" gamepad layout) connected to your computer is required to control the robot in the Mujoco simulation.

1. Launch the Mujoco simulation in one terminal:

source ~/legged_ws/install/setup.bash
ros2 launch unitree_mujoco sim.launch.py config:=config_g1.yaml

The config file is located at: ~/legged_ws/src/legged_ros2/third_party/unitree_mujoco/simulate/config/config_g1.yaml. For more details about the config's parameters, please refer to Unitree Mujoco.

Press '9' to activate or release the strap, press '8' to lower the robot, and press '7' to lift the robot.

2. Launch the controllers in another terminal:

source ~/legged_ws/install/setup.bash
ros2 launch g1_description sdk.launch.py

Args of sdk.launch.py:

• gui: Launch the rviz2 to visualize the robot state, default is false.
• network_interface: Specify the network interface used for Unitree SDK2 communication, default is lo, which is used for simulation.

3. You would see a ros controller manager GUI pop up, which shows the state of the controllers. Joystick Operation Instructions:

• A: Switch to RL controller
• B: Switch to Static controller
• Y: Switch to Joint State Broadcaster only
• left joystick axis: Move the robot forward/backward and left/right
• right joystick axis: Rotate the robot

Real Robot

Caution

Users are advised to follow Unitree's recommendations for safety while using the real robot. This is research code; use at your own risk; we do not take responsibility for any damage.

1. Setup the real robot according to Unitree's official documentation.

2. Launch the controllers:

source ~/legged_ws/install/setup.bash
ros2 launch g1_description sdk.launch.py network_interface:=<your_network_interface>

3. Operate the robot using the joystick as in simulation.

Sim2Sim / Sim2Real Tips

• Order of joints
• armature of joint in mujoco model