humanoid_controller

ROS 2 Humble package implementing neural network-based controllers for humanoid robots using the legged_control2 framework. Controllers run ONNX policy inference to generate joint commands.

Available Controllers

Controller	Description	Contributor	Source	License
MotionTrackingController	Whole-body motion tracking (BeyondMimic)	Qiayuan Liao (Hybrid Robotics)	HybridRobotics/motion_tracking_controller	MIT
AmpLocomotionController	AMP-style locomotion with observation history	Zitong Bai (BUAA)	zitongbai/legged_lab	Apache-2.0
HolosomaLocomotionController	Locomotion with history from experiment config JSON	Amazon FAR	amazon-far/holosoma	Apache-2.0
UnitreeLocomotionController	Unitree RL Gym locomotion with optional LSTM	Unitree Robotics	unitreerobotics/unitree_rl_gym	BSD-3-Clause

Supported Robots

Organization	Robot	Default Walking Controller
unitree	g1	AmpLocomotionController
agibot	x2	HolosomaLocomotionController

Installation

1. Install ROS 2 Humble

Follow the official instructions.

2. Install legged_control2

Follow the Debian Source installation. Then add the Unitree-specific source and packages:

echo "deb [trusted=yes] https://github.com/qiayuanl/unitree_buildfarm/raw/jammy-humble-amd64/ ./" | sudo tee /etc/apt/sources.list.d/qiayuanl_unitree_buildfarm.list
echo "yaml https://github.com/qiayuanl/unitree_buildfarm/raw/jammy-humble-amd64/local.yaml humble" | sudo tee /etc/ros/rosdep/sources.list.d/1-qiayuanl_unitree_buildfarm.list
sudo apt-get update
sudo apt-get install ros-humble-unitree-description ros-humble-unitree-systems

3. Build

Create a workspace and clone the required packages:

mkdir -p ~/colcon_ws/src
cd ~/colcon_ws/src
git clone https://github.com/qiayuanl/unitree_bringup.git
git clone https://github.com/HybridRobotics/humanoid_controller.git
cd ~/colcon_ws

Install dependencies and build:

rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo --packages-up-to unitree_bringup
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo --packages-up-to humanoid_controller
source install/setup.bash

Usage

Policies are loaded from a local ONNX file or downloaded automatically from Weights & Biases.

Simulation (MuJoCo)

# From a local ONNX file
ros2 launch humanoid_controller mujoco.launch.py \
  policy_path:=/path/to/policy.onnx

# From a WandB run
ros2 launch humanoid_controller mujoco.launch.py \
  wandb_path:=<entity/project/run_id>

Optional arguments:

Argument	Default	Description
organization	unitree	Robot organization (unitree, agibot, engineai)
robot_type	g1	Robot model (g1, x2, pm01)
policy_path	``	Absolute or ~-expanded path to .onnx file
wandb_path	``	WandB run path (used when policy_path is empty)
start_step	0	Start frame index for motion tracking
ext_pos_corr	false	Enable external position correction (e.g. LiDAR odometry)

Real Robot

Warning: Running on real hardware is dangerous and entirely at your own risk. Provided for research purposes only.

1. Connect to the robot via Ethernet and set the adapter to static IP 192.168.123.11.
2. Find the network interface name with ifconfig (e.g. eth0, enp3s0).

ros2 launch humanoid_controller real.launch.py \
  network_interface:=<interface> \
  policy_path:=/path/to/policy.onnx

Joystick Controls (Unitree remote)

Combo	Action
L1 + A	Standby controller (joint position hold)
R1 + A	Activate policy controller
B	E-stop (damping mode)

ONNX Policy Paths

By default, policies are read from /opt/onnx_policy/<organization>/<robot>/controller_policies/. Place your ONNX files there or override the path via policy_path launch argument or the policy.path ROS parameter.

Code Structure

humanoid_controller/
├── include/humanoid_controller/
│   ├── common.h                    # Quaternion utilities
│   └── tasks/<task_name>/
│       ├── Controller.h / .cpp     # RlController subclass
│       ├── Policy.h / .cpp         # ONNX policy wrapper
│       ├── Command.h / .cpp        # Command terms (reference inputs)
│       └── Observation.h / .cpp    # Observation terms (state measurements)
├── config/<org>/<robot>/
│   ├── sim.yaml                    # MuJoCo simulation config
│   ├── real.yaml                   # Real robot config
│   └── joy.yaml                    # Joystick mappings
├── launch/
│   ├── mujoco.launch.py            # Simulation launch
│   ├── real.launch.py              # Real robot launch
│   └── wandb.launch.py             # WandB ONNX downloader (included automatically)
└── humanoid_controller.xml         # pluginlib registration

For instructions on implementing a custom controller, see CLAUDE.md.

License

MIT

Portions of this project are derived from third-party sources under their respective licenses. See individual file headers and the Available Controllers table for details.