legubiao/quadruped_ros2_control

Purpose and Runtime

A ROS 2 Jazzy workspace for ros2_control-based quadruped locomotion across simulation and real Unitree hardware. It combines robot descriptions, ros2_control hardware adapters, command publishers, and interchangeable controllers: classical Unitree Guide, OCS2 MPC/WBC, RL policy, and leg PD. ROS 2 launch files are the operational entry points; build uses colcon/CMake.

System Entry Points

Typical startup loads a robot description plus hardware adapter and controller via:

• controllers/unitree_guide_controller/launch/gazebo.launch.py

• controllers/unitree_guide_controller/launch/mujoco.launch.py

• libraries/gz_quadruped_playground/launch/ocs2.launch.py

Inputs are separate ROS nodes, notably keyboard and joystick publishers:

• commands/keyboard_input/src/KeyboardInput.cpp

• commands/control_input_msgs/msg/Inputs.msg

• commands/joystick_input/launch/joystick.launch.py

Robot Model and ros2_control Boundary

Each supported robot is a package containing URDF/Xacro, transmissions, Gazebo integration, and controller parameters. The description is the contract binding controller joint/foot assumptions to simulation or hardware interfaces. Go2 is the primary documented deployment target:

• descriptions/unitree/go2_description/xacro/robot.xacro

• descriptions/unitree/go2_description/xacro/ros2_control.xacro

• descriptions/unitree/go2_description/config/robot_control.yaml

Equivalent model packages cover Unitree, Deep Robotics, Xiaomi/Magiclab, and ANYmal variants.

Hardware and Simulation Adapters

ros2_control controllers operate against hardware-system plugins rather than simulator- or device-specific APIs. Gazebo Harmonic uses a custom GZ system/plugin; real Unitree control uses Unitree SDK2 with its DDS/network stack:

• hardwares/gz_quadruped_hardware/src/gz_system.cpp

• hardwares/gz_quadruped_hardware/src/gz_quadruped_plugin.cpp

• hardwares/hardware_unitree_sdk2/src/HardwareUnitree.cpp

MuJoCo support is launched through controller packages and depends on the external unitree_mujoco environment. The README identifies an RMW compatibility boundary between CycloneDDS and unitree_sdk2.

Controller Families

The controller packages are alternative ros2_control execution cores, each translating state and command inputs into joint commands:

• Unitree Guide FSM locomotion: controllers/unitree_guide_controller/src/UnitreeGuideController.cpp, controllers/unitree_guide_controller/src/FSM/StateTrotting.cpp

• OCS2 MPC locomotion: controllers/ocs2_quadruped_controller/src/Ocs2QuadrupedController.cpp, controllers/ocs2_quadruped_controller/src/FSM/StateOCS2.cpp

• RL inference locomotion: controllers/rl_quadruped_controller/src/RlQuadrupedController.cpp, controllers/rl_quadruped_controller/src/FSM/StateRL.cpp

• Direct leg PD control: controllers/leg_pd_controller/src/LegPdController.cpp

Shared FSM interfaces and safe stand/passive states live in libraries/controller_common/include/controller_common/FSM/.

Locomotion Data Flow

Command nodes publish Inputs; selected controllers consume commands alongside ros2_control joint/IMU/contact state. The Unitree Guide path estimates state, selects FSM behavior, generates gait phase and foot targets, solves balance control, then emits leg commands. Its key stages are:

• controllers/unitree_guide_controller/src/control/Estimator.cpp

• controllers/unitree_guide_controller/src/gait/GaitGenerator.cpp

• controllers/unitree_guide_controller/src/control/BalanceCtrl.cpp

The RL path buffers filtered observations and evaluates packaged PyTorch policies associated with robot descriptions, e.g. descriptions/unitree/go2_description/config/legged_gym/policy.pt.

OCS2 Planning, Constraints, and Perception

OCS2 is the advanced planning/control pipeline: target and gait managers establish references; a legged model interface constructs MPC costs and constraints; WBC converts planned motion into executable joint-level commands. Safety and perceptive terrain extensions are explicit layers:

• controllers/ocs2_quadruped_controller/src/control/TargetManager.cpp

• controllers/ocs2_quadruped_controller/src/interface/LeggedInterface.cpp

• controllers/ocs2_quadruped_controller/src/wbc/HierarchicalWbc.cpp

Perceptive locomotion consumes planar terrain/elevation data, chooses convex foothold regions, and applies foot-placement/collision constraints. Gazebo playground provides worlds, camera/lidar models, and Cartographer or FAST-LIO launch/configuration:

• controllers/ocs2_quadruped_controller/src/perceptive/synchronize/PlanarTerrainReceiver.cpp

• libraries/gz_quadruped_playground/launch/slam/fast_lio.launch.py

• libraries/gz_quadruped_playground/worlds/warehouse.sdf