unitreerobotics/unitree_guide

This repository is a ROS-based control workspace for Unitree quadruped robots, with three main parts: low-level actuator SDK support, a higher-level legged robot controller, and a navigation stack built around ROS move_base.

1. Top-level architecture

The repo is organized as a catkin workspace containing:

- unitree_actuator_sdk for direct motor/actuator communication,

- unitree_guide for quadruped locomotion control,

- unitree_move_base for ROS navigation integration in simulation.

2. Low-level actuator boundary: unitree_actuator_sdk

This package is a serial-based motor control SDK. Its core headers (LSerial.h, motor_ctrl.h, motor_msg.h) define communication and command/message structures for actuators. It includes a standalone CMake build and a ROS-packaged variant under unitree_motor_ctrl, indicating it can be used both as a raw SDK and as a ROS-integrated component.

3. Higher-level robot control stack: unitree_guide

This is the main locomotion controller package. It is structured as a layered control system:

- Interface layer for inputs and runtime I/O,

- FSM layer for behavior switching,

- Gait layer for step timing and foot trajectory generation,

- Control layer for balance and low-level command generation,

- Common/math layer for kinematics, filters, and robot abstractions,

- Message layer for low-level command/state structs.

4. Behavior orchestration via finite state machine

The FSM subsystem is the top-level behavior manager. States include Passive, FixedStand, FreeStand, Trotting, StepTest, SwingTest, BalanceTest, and move_base. This is the main architectural boundary between operator intent and motion generation: the robot’s mode changes drive which control logic is active.

5. Control pipeline inside unitree_guide

The control flow is:

input command → FSM state → gait/estimation/control modules → low-level command output.

The control layer includes BalanceCtrl, Estimator, ControlFrame, and CtrlComponents, which together compute body stabilization and joint/leg commands based on robot state.

6. Gait and leg motion generation

The Gait subsystem (GaitGenerator, WaveGenerator, FeetEndCal) handles trot timing, stance/swing scheduling, and foot trajectory calculation. This separates locomotion pattern generation from balance/control logic, which is important for diagramming the control stack correctly.

7. Inputs and operator interfaces

The interface directory contains multiple input paths:

- KeyBoard for keyboard teleoperation,

- WirelessHandle and CmdPanel for remote-command style control,

- IOSDK and IOROS as bridges to the robot SDK and ROS,

- IOInterface as the abstraction layer.

In the quick-start flow, keyboard input is used to switch FSM states and issue translational/rotational commands.

8. Robot model, state, and message definitions

common and message hold the data model used throughout the controller:

- unitreeRobot, unitreeLeg for robot geometry/kinematics,

- LowPassFilter, mathTools, mathTypes, timeMarker,

- LowlevelCmd, LowlevelState, and joystick message types.

These form the shared data boundary between estimation, control, and IO.

9. Bundled external SDK dependency

unitree_guide/library includes several versions of unitree_legged_sdk and prebuilt static libraries for x86_64 and ARM64. This makes the control stack self-contained across target platforms and highlights that the controller sits on top of Unitree’s legged robot communication SDK rather than talking directly to hardware.

10. Simulation and ROS integration

The launch/gazeboSim.launch entry point starts the simulated robot environment. The README’s runtime flow is: source the workspace, launch Gazebo, then run junior_ctrl, which is the compiled controller binary from unitree_guide. This shows a two-process architecture: simulation in ROS/Gazebo and controller in a separate executable.

11. Navigation-focused package: unitree_move_base

This package is a ROS navigation setup centered on move_base. It provides:

- local/global costmap parameter files,

- base planner parameters,

- TF launch files,

- RViz configuration,

- point cloud to laser scan conversion,

- Gazebo launch files and room/world assets.

Its role is not locomotion control itself, but higher-level navigation around the robot or simulated platform.

12. Navigation data flow

unitree_move_base bridges perception and navigation by converting point clouds to laser scans, feeding costmaps, and using TF transforms to support move_base. This is a separate autonomy layer from unitree_guide’s gait and balance controller, though both operate in the same ROS ecosystem.

13. Auxiliary tooling

The actuator SDK areas include ChangeID_Tool for device ID management and Python/C checkscripts (check.py, typedef.py) for validating message/type definitions. These are support tools around hardware setup and SDK consistency rather than runtime control logic.

14. Overall architectural picture

At a high level, the repository spans three control strata:

- hardware/actuator communication (unitree_actuator_sdk),

- locomotion control and behavior management (unitree_guide),

- ROS navigation and simulation tooling (unitree_move_base).

The main runtime control path is operator input and robot state → FSM/gait/control → low-level robot commands, with ROS/Gazebo and Unitree SDKs serving as the integration boundaries.