# unitreerobotics/unitree_guide architecture

> Architecture diagram of the GitHub repository unitreerobotics/unitree_guide, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/unitreerobotics/unitree_guide
- Repository: https://github.com/unitreerobotics/unitree_guide

## Overview

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.

Main entry points: [`unitree_guide`](https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_guide) (Unitree Guide), [`unitree_move_base`](https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_move_base) (Move Base), [`unitree_actuator_sdk`](https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_actuator_sdk) (Actuator SDK), [`unitree_guide/include/FSM/FSM.h`](https://github.com/unitreerobotics/unitree_guide/blob/main/unitree_guide/include/FSM/FSM.h) (FSM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_actuator_sdk["Actuator SDK"]
  node_actuator_sdk["Actuator SDK<br/>serial sdk"]
  node_serial_comm["Serial Link<br/>transport<br/>[LSerial.h]"]
  node_motor_api["Motor API<br/>command api<br/>[motor_ctrl.h]"]
  node_sdk_tools["ID Tools<br/>support tools"]
  node_motor_ros["ROS Wrapper<br/>ros package"]
end

subgraph group_group_locomotion["Locomotion Control"]
  node_guide["Unitree Guide<br/>control stack"]
  node_io_layer["IO Layer<br/>interface"]
  node_keyboard["Keyboard<br/>teleop input<br/>[KeyBoard.h]"]
  node_ros_io["ROS Bridge<br/>io bridge<br/>[IOROS.h]"]
  node_fsm(("FSM<br/>behavior manager<br/>[FSM.h]"))
  node_fsm_states["FSM States<br/>modes"]
  node_gait["Gait<br/>motion pattern"]
  node_control["Control<br/>stabilization"]
  node_common["Common<br/>robot model"]
  node_messages["Messages<br/>state structs"]
  node_runtime["Junior Ctrl<br/>controller binary<br/>[main.cpp]"]
  node_sim_launch["Gazebo Sim<br/>launch<br/>[gazeboSim.launch]"]
end

subgraph group_group_navigation["Navigation Stack"]
  node_move_base["Move Base<br/>navigation stack"]
  node_nav_preprocess["Scan Convert<br/>sensor preprocessing"]
  node_nav_costmaps["Costmaps<br/>navigation params"]
  node_nav_tf["TF / RViz<br/>visualization<br/>[robotTF.launch]"]
  node_nav_worlds["Gazebo Worlds<br/>simulation assets"]
end

node_workspace["Catkin WS<br/>workspace"]

node_workspace -->|"contains"| node_actuator_sdk
node_workspace -->|"contains"| node_guide
node_workspace -->|"contains"| node_move_base
node_actuator_sdk -->|"uses"| node_serial_comm
node_actuator_sdk -->|"defines"| node_motor_api
node_actuator_sdk -.->|"supports"| node_sdk_tools
node_actuator_sdk -->|"wraps"| node_motor_ros
node_guide -->|"accepts input from"| node_io_layer
node_io_layer -->|"includes"| node_keyboard
node_io_layer -->|"includes"| node_ros_io
node_guide -->|"orchestrates"| node_fsm
node_fsm -->|"switches among"| node_fsm_states
node_fsm -->|"activates"| node_gait
node_fsm -->|"activates"| node_control
node_gait -->|"uses"| node_common
node_control -->|"uses"| node_common
node_control -->|"outputs"| node_messages
node_guide -->|"builds into"| node_runtime
node_sim_launch -.->|"starts with"| node_runtime
node_move_base -->|"uses"| node_nav_preprocess
node_move_base -->|"configured by"| node_nav_costmaps
node_move_base -->|"integrates"| node_nav_tf
node_move_base -->|"simulates in"| node_nav_worlds
node_guide -.->|"shares ROS ecosystem"| node_move_base
node_motor_ros -.->|"feeds SDK access"| node_guide

click node_actuator_sdk "https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_actuator_sdk"
click node_serial_comm "https://github.com/unitreerobotics/unitree_guide/blob/main/unitree_actuator_sdk/include/LSerial.h"
click node_motor_api "https://github.com/unitreerobotics/unitree_guide/blob/main/unitree_actuator_sdk/include/motor_ctrl.h"
click node_sdk_tools "https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_actuator_sdk/ChangeID_Tool"
click node_motor_ros "https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_actuator_sdk/unitree_motor_ctrl"
click node_guide "https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_guide"
click node_io_layer "https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_guide/include/interface"
click node_keyboard "https://github.com/unitreerobotics/unitree_guide/blob/main/unitree_guide/include/interface/KeyBoard.h"
click node_ros_io "https://github.com/unitreerobotics/unitree_guide/blob/main/unitree_guide/include/interface/IOROS.h"
click node_fsm "https://github.com/unitreerobotics/unitree_guide/blob/main/unitree_guide/include/FSM/FSM.h"
click node_fsm_states "https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_guide/include/FSM"
click node_gait "https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_guide/include/Gait"
click node_control "https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_guide/include/control"
click node_common "https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_guide/include/common"
click node_messages "https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_guide/include/message"
click node_runtime "https://github.com/unitreerobotics/unitree_guide/blob/main/unitree_guide/src/main.cpp"
click node_sim_launch "https://github.com/unitreerobotics/unitree_guide/blob/main/unitree_guide/launch/gazeboSim.launch"
click node_move_base "https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_move_base"
click node_nav_preprocess "https://github.com/unitreerobotics/unitree_guide/blob/main/unitree_move_base/launch/pointCloud2LaserScan.launch"
click node_nav_costmaps "https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_move_base/config"
click node_nav_tf "https://github.com/unitreerobotics/unitree_guide/blob/main/unitree_move_base/launch/robotTF.launch"
click node_nav_worlds "https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_move_base/worlds"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_actuator_sdk,node_serial_comm,node_motor_api,node_sdk_tools,node_motor_ros toneBlue
class node_guide,node_io_layer,node_keyboard,node_ros_io,node_fsm,node_fsm_states,node_gait,node_control,node_common,node_messages,node_runtime,node_sim_launch toneAmber
class node_move_base,node_nav_preprocess,node_nav_costmaps,node_nav_tf,node_nav_worlds toneMint
class node_workspace toneNeutral
```

## Components

### Actuator SDK

Serial motor control SDK and ROS wrapper

- [Actuator SDK](https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_actuator_sdk): serial sdk · Low-level actuator communication and command structures · `unitree_actuator_sdk`
- [Serial Link](https://github.com/unitreerobotics/unitree_guide/blob/main/unitree_actuator_sdk/include/LSerial.h): transport · LSerial-based device communication layer · `unitree_actuator_sdk/include/LSerial.h`
- [Motor API](https://github.com/unitreerobotics/unitree_guide/blob/main/unitree_actuator_sdk/include/motor_ctrl.h): command api · Motor control and message definitions · `unitree_actuator_sdk/include/motor_ctrl.h`
- [ID Tools](https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_actuator_sdk/ChangeID_Tool): support tools · Device ID and type-check helper scripts and utilities · `unitree_actuator_sdk/ChangeID_Tool`
- [ROS Wrapper](https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_actuator_sdk/unitree_motor_ctrl): ros package · ROS-packaged variant of the actuator SDK · `unitree_actuator_sdk/unitree_motor_ctrl`

### Locomotion Control

Finite-state locomotion controller stack

- [Unitree Guide](https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_guide): control stack · Main quadruped locomotion controller · `unitree_guide`
- [IO Layer](https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_guide/include/interface): interface · Keyboard, wireless, SDK, and ROS input bridges · `unitree_guide/include/interface`
- [Keyboard](https://github.com/unitreerobotics/unitree_guide/blob/main/unitree_guide/include/interface/KeyBoard.h): teleop input · Keyboard teleoperation and mode switching · `unitree_guide/include/interface/KeyBoard.h`
- [ROS Bridge](https://github.com/unitreerobotics/unitree_guide/blob/main/unitree_guide/include/interface/IOROS.h): io bridge · ROS and SDK interfaces for runtime I/O · `unitree_guide/include/interface/IOROS.h`
- [FSM](https://github.com/unitreerobotics/unitree_guide/blob/main/unitree_guide/include/FSM/FSM.h): behavior manager · Top-level mode switching and behavior orchestration · `unitree_guide/include/FSM/FSM.h`
- [FSM States](https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_guide/include/FSM): modes · Passive, stand, trot, test, and move_base modes · `unitree_guide/include/FSM`
- [Gait](https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_guide/include/Gait): motion pattern · Step timing and foot trajectory generation · `unitree_guide/include/Gait`
- [Control](https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_guide/include/control): stabilization · Estimator, balance control, and command frame generation · `unitree_guide/include/control`
- [Common](https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_guide/include/common): robot model · Shared math, filters, time, and robot geometry models · `unitree_guide/include/common`
- [Messages](https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_guide/include/message): state structs · Low-level command, state, and joystick message types · `unitree_guide/include/message`
- [Junior Ctrl](https://github.com/unitreerobotics/unitree_guide/blob/main/unitree_guide/src/main.cpp): controller binary · Compiled locomotion controller entrypoint · `unitree_guide/src/main.cpp`
- [Gazebo Sim](https://github.com/unitreerobotics/unitree_guide/blob/main/unitree_guide/launch/gazeboSim.launch): launch · Simulation launch entrypoint for the controller stack · `unitree_guide/launch/gazeboSim.launch`

### Navigation Stack

ROS move_base navigation and simulation integration

- [Move Base](https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_move_base): navigation stack · ROS navigation package built around move_base · `unitree_move_base`
- [Scan Convert](https://github.com/unitreerobotics/unitree_guide/blob/main/unitree_move_base/launch/pointCloud2LaserScan.launch): sensor preprocessing · Point cloud to laser scan conversion for navigation · `unitree_move_base/launch/pointCloud2LaserScan.launch`
- [Costmaps](https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_move_base/config): navigation params · Global/local costmap and planner parameters · `unitree_move_base/config`
- [TF / RViz](https://github.com/unitreerobotics/unitree_guide/blob/main/unitree_move_base/launch/robotTF.launch): visualization · Robot transform and RViz navigation setup · `unitree_move_base/launch/robotTF.launch`
- [Gazebo Worlds](https://github.com/unitreerobotics/unitree_guide/tree/main/unitree_move_base/worlds): simulation assets · Indoor worlds and simulation models · `unitree_move_base/worlds`

### Other components

- **Catkin WS**: workspace · ROS catkin workspace tying all packages together

## Connections

- Catkin WS → Actuator SDK: contains · Workspace includes the actuator SDK package
- Catkin WS → Unitree Guide: contains · Workspace includes the locomotion controller package
- Catkin WS → Move Base: contains · Workspace includes the navigation package
- Actuator SDK → Serial Link: uses · Serial transport underpins actuator communication
- Actuator SDK → Motor API: defines · Motor commands and messages are defined here
- Actuator SDK → ID Tools: supports · Utilities for ID management and type checks
- Actuator SDK → ROS Wrapper: wraps · ROS-packaged variant of the SDK
- Unitree Guide → IO Layer: accepts input from · Controller consumes operator and ROS inputs
- IO Layer → Keyboard: includes · Keyboard teleoperation path
- IO Layer → ROS Bridge: includes · ROS and SDK bridge interfaces
- Unitree Guide → FSM: orchestrates · Finite-state machine coordinates behavior
- FSM → FSM States: switches among · Behavior modes such as stand, trot, and tests
- FSM → Gait: activates · Locomotion states drive gait generation
- FSM → Control: activates · Behavior states drive control and estimation
- Gait → Common: uses · Gait generation relies on robot math/model utilities
- Control → Common: uses · Estimator and balance control use shared robot models
- Control → Messages: outputs · Low-level commands and states flow through message structs
- Unitree Guide → Junior Ctrl: builds into · Main controller compiles to junior_ctrl-style runtime
- Gazebo Sim → Junior Ctrl: starts with · Gazebo simulation is used alongside the controller binary
- Move Base → Scan Convert: uses · Point cloud to laser scan preprocessing feeds navigation
- Move Base → Costmaps: configured by · Planner and costmap parameters steer navigation behavior
- Move Base → TF / RViz: integrates · Transforms and RViz launch support navigation runtime
- Move Base → Gazebo Worlds: simulates in · Gazebo world assets support navigation testing
- Unitree Guide → Move Base: shares ROS ecosystem · Separate autonomy layer coexisting in the same ROS workspace
- ROS Wrapper → Unitree Guide: feeds SDK access · Locomotion controller sits on top of Unitree legged SDK access