Unitree Qmini Robot

硬件

• UART1: 右腿 [0, 1, 2]
• UART2: 左腿 [0, 1, 2]
• UART3: 髋关节滚转 [0, 1]
• UART4: 髋关节偏航 [0, 1]

          [躯干]
            ||
     _______||_______
    |                |
    |                |
左髋关节偏航 <--> 右髋关节偏航 <-->     (Yaw：腿的内旋 / 外旋)
RL_HIP_YAW      RR_HIP_YAW
    ↑                ↑
左髋关节滚转       右髋关节滚转         (Roll：腿的左右摆动)
    ↓                ↓
RL_HIP_ROLL      RR_HIP_ROLL
<-------->       <-------->
左髋关节俯仰       右髋关节俯仰         (Pitch：腿的前后摆动，用于走路)
RL_HIP_PITCH     RR_HIP_PITCH
    |                |
  <-->             <-->
左膝关节            右膝关节           (Knee Pitch：膝盖弯曲/伸展)
RL_KNEE            RR_KNEE
    |                |
<-------->        <-------->
踝关节俯仰           踝关节俯仰         (Ankle Pitch：脚掌抬起/放下)
RL_ANKLE_PITCH    RR_ANKLE_PITCH
    ↑                ↑
踝关节滚转         踝关节滚转           (Ankle Roll：脚左右倾斜)
    ↓                ↓
RL_ANKLE_ROLL    RR_ANKLE_ROLL
    |                |
   / \              / \
  /   \            /   \
[左脚底]           [右脚底]
[RL_FOOT]        [RR_FOOT]

运控 SDK 主程序

VSISLAB 为 Qmini 专门开发了运控程序，可运行在树莓派或 Jetson 平台。

运控程序特性

• High-Performance Inference — Optimized C++ implementation with ONNX Runtime for low-latency, real-time policy execution on robots like Unitree Qmini.
• Hardware Acceleration — Supports CPU/GPU backends (including CUDA) for maximum inference speed on Linux-based edge devices.
• Modular Architecture — Easy-to-use API for integrating with custom robot hardware, sensors, and actuators.
• Safety-Critical Design — Built-in emergency stop mechanisms, sensor validation, and fail-safe protocols for real-world operation.
• Real-Time Control — Thread-safe implementation supporting hard real-time constraints.
• Documentation & Examples — Step-by-step guides for robot deployment and custom hardware setups.

前置条件

• Ubuntu(20.04 或 22.04)
• Python 3 (version 3.8.12 or higher)
• CMake (version 2.8.3 or higher)
• Unitree SDK 2
• Unitree Actuator SDK
• Yaml-cpp (version 0.6.0 or higher)
• Eigen (version 3.3.7 or higher)
• OnnxRuntime (version 1.17.1 or higher)
• JsonCpp
• pygame (version 2.6.1 or higher)

安装依赖

$ sudo apt install cmake && sudo apt install python3-pip && sudo apt install libjsoncpp-dev
$ cmake --version

Unitree SDK 2

编译环境

• OS (Ubuntu 20.04 LTS 或 22.04)
• CPU (aarch64 或 x86_64)
• Compiler (gcc version 9.4.0)

$ sudo apt install libeigen3-dev
$ cd ~/
$ git clone https://github.com/unitreerobotics/unitree_sdk2
$ cd unitree_sdk2 && mkdir build && cd build
$ cmake .. -DCMAKE_INSTALL_PREFIX=/opt/unitree
$ sudo make install

You can refer to example/cmake_sample on how to import the unitree_sdk2 into your CMake project.

Note that if you install the library to other places other than /opt/unitree_robotics, you need to make sure the path is added to ${CMAKE_PREFIX_PATH} so that cmake can find it with "find_package()".

If you just want to test it temporarily, run:

$ export CMAKE_PREFIX_PATH=/opt/unitree:$CMAKE_PREFIX_PATH

Alternatively, to make this change permanent, add the export command to your shell configuration file.

$ echo "export CMAKE_PREFIX_PATH=/opt/unitree:$CMAKE_PREFIX_PATH" >> ~/.bashrc

To validate it:

$ echo $CMAKE_PREFIX_PATH

Alternative: Pass Path Directly in CMake, when building your project, you can also explicitly specify the path:

$ cmake .. -DCMAKE_PREFIX_PATH=/opt/unitree

Unitree Actuator SDK

• Support motor: GO-M8010-6 motor
• Not support motor: A1 motor、 B1 motor (Check A1B1 branch for support)

Prerequisites

• gcc >= 5.4.0 (for libUnitreeMotorSDK_M80106_Linux64.so)
• gcc >= 8.3.0 (for libUnitreeMotorSDK_M80106_Arm64.so)

Run gcc -v command to check your gcc version

Build

$ cd ~/
$ git clone https://github.com/unitreerobotics/unitree_actuator_sdk
$ cd unitree_actuator_sdk
$ git checkout GO-M8010-6
$ mkdir build
$ cd build
$ cmake ..
$ make

宇树电机工具包

1. 查看电机 ID

To view and modify a motor ID, the motor must be switched to factory mode. Before switching, ensure that all motors have stopped working and the host is no longer sending motion control commands to the motors.

$ cd ~/unitree_actuator_sdk/motor_tools/Unitree_MotorTools_<version>_<architecture>
$ ./swboot /dev/ttyUSB0

Under normal circumstances, there should be no motors with an ID greater than 15 in the printed list. If this occurs, please power cycle the motor and try again. If there is a motor with ID 15, it indicates that the motor has not yet been assigned an ID. Please follow the instructions below to modify the motor ID.

2. Change motor ID

Before changing motor ID, ensure that all motors have stopped working and that the host is no longer sending motion control commands to the motors.

For example: Change all motors with ID 0 on the bus to ID 1.

$ cd ~/unitree_actuator_sdk/motor_tools/Unitree_MotorTools_<version>_<architecture>
$ ./changeid /dev/ttyUSB0 0 1

3. Back to Motor Mode

Viewing and modifying the motor ID switches the motor to factory mode. If you do not manually switch back to motor mode, the motor will remain in factory mode even after power cycling.

Motors in factory mode have a green indicator light on the back that flashes quickly three times per second. To switch back to motor mode, use the following command:

$ cd ~/unitree_actuator_sdk/motor_tools/Unitree_MotorTools_<version>_<architecture>
$ ./swmotor /dev/ttyUSB0

This command will switch all motors on the CAN bus back to motor mode. At this point, the motors can receive motion control commands. Motors without firmware will not start, and the terminal will display their status.

4. Motor Firmware Upgrade

The GO-M8010-6 motor supports firmware upgrades, which allow for performance improvements and safety fixes in the future. Use the firmware file provided by Unitree and the unisp tool to download the firmware to the motor.

Command format:

$ unisp [serial port] [.bin upgrade file] [target motor ID]

For example:

$ cd ~/unitree_actuator_sdk/motor_tools/Unitree_MotorTools_<version>_<architecture>
$ ./unisp /dev/ttyUSB0 ./GoM80106_v1.0.bin 0

Yaml CPP

$ cd ~
$ git clone https://github.com/jbeder/yaml-cpp
$ cd yaml-cpp
$ mkdir build
$ cd build
$ cmake ..
$ make
$ sudo make install

Eigen Template Library

Eigen is a C++ template library for linear algebra: matrices, vectors, numerical solvers, and related algorithms.

$ cd ~
$ git clone https://gitlab.com/libeigen/eigen
$ cd eigen && mkdir build && cd build
$ cmake .. && make && sudo make install

It will be installed into /usr/local/include/eigen3/

JsonCpp

$ cd ~
$ git clone https://github.com/Microsoft/vcpkg
$ cd vcpkg
$ ./bootstrap-vcpkg.sh
$ ./vcpkg integrate install
$ ./vcpkg install jsoncpp

Joystick Controller

$ sudo apt install python3-pygame

Bluetooth Connectivity

Step 1: Install Required Packages

$ sudo apt update
$ sudo apt install bluetooth

Step 2: Start Bluetooth Service

$ sudo systemctl start bluetooth
$ sudo systemctl enable bluetooth

Step 3: Put PS4/5 Controller in Pairing Mode

• Hold Share + PS button simultaneously for 3 seconds
• The light bar should start flashing rapidly (white or blue)

Step 4: Pair using bluetoothctl

$ bluetoothctl

bluetoothctl> scan on
# Pair with the controller (replace MAC_ADDRESS with actual address)
bluetoothctl> pair XX:XX:XX:XX:XX:XX

# Trust the device
bluetoothctl> trust XX:XX:XX:XX:XX:XX

# Connect to the device
bluetoothctl> connect XX:XX:XX:XX:XX:XX

bluetoothctl> exit

按键定义

PS Controller Pair via Bluetooth Script

#!/bin/bash
# ps4_pair.sh

echo "Put PS controller in pairing mode (Share + PS button for 3 seconds)"
echo "Press Enter when controller is flashing..."
read

# Start scanning and get MAC address
echo "Scanning for PS controller..."
timeout 10s bluetoothctl scan on &
sleep 5

# Get the MAC address of Wireless Controller
MAC=$(bluetoothctl devices | grep "Wireless Controller" | awk '{print $2}')

if [ -z "$MAC" ]; then
    echo "PS controller not found. Make sure it's in pairing mode."
    exit 1
fi

echo "Found PS controller: $MAC"

# Pair, trust, and connect
echo "Pairing..."
echo -e "pair $MAC\ntrust $MAC\nconnect $MAC\nexit" | bluetoothctl

echo "PS controller should now be paired and connected!"

Make it executable and run:

$ chmod +x ps_pair.sh
$ ./ps_pair.sh

USB Connectivity

You typically need to set up permissions in Ubuntu 22.04 for PS4 controllers connected via USB. Here's what you need to do:

1. Add udev rules

$ sudo nano /etc/udev/rules.d/99-ps4-controller.rules

2. Add the following content:

# PS4 Controller (DualShock 4)
SUBSYSTEM=="usb", ATTRS{idVendor}=="054c", ATTRS{idProduct}=="05c4", MODE="0666"
SUBSYSTEM=="usb", ATTRS{idVendor}=="054c", ATTRS{idProduct}=="09cc", MODE="0666"
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="054c", ATTRS{idProduct}=="05c4", MODE="0666"
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="054c", ATTRS{idProduct}=="09cc", MODE="0666"

3. Reload udev rules:

$ sudo udevadm control --reload-rules
$ sudo udevadm trigger

4. Verify controller detection

$ lsusb | grep Sony
# or check input device
$ ls /dev/input/js*

Install ONNX Runtime GPU (CUDA 12.x)

ONNX Runtime is a cross-platform machine-learning model accelerator, with a flexible interface to integrate hardware-specific libraries. ONNX Runtime can be used with models from PyTorch, Tensorflow/Keras, TFLite, scikit-learn, and other frameworks.

Please visit the Jetson Zoo ONNX Runtime page and locate the appropriate .whl file corresponding to your installed Python and JetPack versions on the Jetson Orin Nano. Copy the link for use in your environment setup.

$ conda create -n qmini python=3.11
$ conda activate qmini
$ pip install "numpy<2" #Downgrade Numpy
$ wget https://nvidia.box.com/shared/static/9yvw05k6u343qfnkhdv2x6xhygze0aq1.whl -O onnxruntime_gpu-1.19.0-cp311-cp311-linux_aarch64.whl
$ pip install onnxruntime_gpu-1.19.0-cp311-cp311-linux_aarch64.whl
$ python3
>>> import onnxruntime as ort
>>> ort.get_available_providers()

Clone the RoboTammerSdk4Qmini

$ cd ~
$ git clone https://github.com/vsislab/RoboTamerSdk4Qmini
$ cd RoboTamerSdk4Qmini/lib/onnx
$ sudo cp -r libonnxruntime.so libonnxruntime.so.1.<x>.1 /usr/local/lib
$ sudo ldconfig

$ cd ~/RoboTamerSdk4Qmini/lib/m8010motor
$ sudo cp libUnitreeMotorSDK_Linux64.so /usr/local/lib/
#or
$ sudo cp libUnitreeMotorSDK_Arm64.so /usr/local/lib/

Simulation

1. Load the URDF into robot_state_publisher

$ ros2 run robot_state_publisher robot_state_publisher <robot.urdf>

2. Start RViz2

$ rviz2

3. Configure Rviz2

• In RViz2, add a RobotModel display.
• Set the Fixed Frame to the root link in your URDF (e.g., base_link).
• You should now see your robot in the 3D viewer.

Full steps of operating RoboTamerSdk4Qmini on the real Qmini robot

Check USB Device Recognition

Plugin the Unitree USB to 485 adapter and run the following commands:

$ lsusb

It will output something like this:

Bus 001 Device 004: ID 0403:6011 Future Technology Devices International, Ltd FT4232H Quad HS USB-UART/FIFO IC

Here, vendor ID is 0403 and product ID is 6011. Remember both ID and use them for the rules later.

Next, add current user to the dialout group:

$ sudo usermod -a -G dialout $USER

Alternative: Use a udev rule for persistent permissions, create a udev rule to automatically set permissions:

$ sudo nano /etc/udev/rules.d/99-usb-serial.rules

Add this line:

SUBSYSTEM=="tty", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6011", MODE="0666", GROUP="dialout", OWNER="ubuntu"

$ sudo udevadm control --reload-rules
$ sudo udevadm trigger

Modification

1. Modify the USB to 485 adapter serial ports by editing include/user/Motor_thread file.
2. Modify network interface to be your Jetson Orin Nano or Raspberry Pi with the actual network interface by editing source/run_interface.cpp file.

$ cd ~/RoboTamerSdk4Qmini
$ mkdir -p build && cd build
$ cmake -DPLATFORM=arm64 .. && make && cd ../bin

Step 1: Check the start-up posture of the robot Step 2: Boot up both the joy stick and the robot Step 3: Run the executable file

Manage Process

$ ps aux | grep run_interface
$ kill -9 ****

$ ./run_interface
#or
$ sudo ./run_interface

Step 4: Check the initial state of the robot Step 5: Enter 1 and press enter into ready mode. Step 6: Enter 2 and press enter into position stand mode. Step 7: Enter 3 and press enter into AI stand control mode. Now enjoy your robot!

SDK 代码 解析

act_pos_low 和 act_pos_high

cwiseMax 和 cwiseMin 是 C++ Eigen 库中的函数，用于执行 coefficient-wise（逐元素）的操作。

• cwise: 这个前缀是 coefficient-wise 的缩写，意思是操作将分别应用于向量或矩阵的每一个元素。
• cwiseMax(other_vector): 这个函数会比较调用它的向量和作为参数传入的 other_vector。它会逐个对比两个向量中位置相同的元素，并取其中较大的值，最终返回一个包含这些最大值的新向量。
• cwiseMin(other_vector): 类似地，这个函数会逐个对比两个向量的元素，但取的是其中较小的值，并返回一个包含这些最小值的新向量。

在 source/user/rl_controller.cpp 文件中:

joint_act = joint_act.cwiseMax(act_pos_low).cwiseMin(act_pos_high);

这行代码是一个链式调用，作用是将 joint_act（关节的目标位置）限制在 act_pos_low（允许的最低位置）和 act_pos_high（允许的最高位置）所定义的范围之内。这个过程通常被称为 钳位 (Clamping)。

它分两步完成：

1. joint_act.cwiseMax(act_pos_low): 首先，确保 joint_act 中的每个值都不低于 act_pos_low 中对应的最小值。如果某个计算出的目标位置低于允许的下限，它就会被拉高到这个下限值。
2. .cwiseMin(act_pos_high): 接着，在上一步结果的基础上，确保每个值都不高于 act_pos_high 中对应的最大值。如果某个值高于允许的上限，它就会被压低到这个上限值。

简单来说，这行代码保证了无论计算出的目标位置是多少，最终发送给执行器的指令都会被强制约束在预设的安全活动范围 [act_pos_low, act_pos_high] 之内。

Reinforcement Learning

This repository offers an open-source framework for bipedal robot motion control, leveraging deep reinforcement learning within NVIDIA's Isaac Gym environment. It enables training robots like Unitree Qmini to walk on rough terrain and includes critical domain randomization and random pushes during training for sim-to-real transfer. The repository contains the complete codebase for both training and deploying the biped robots in simulation environments.

Source Code URL: https://github.com/vsislab/RoboTamer4Qmini

Prerequisites

• Ubuntu 18.04 or 20.04
• NVIDIA driver version 470+
• Hardware: NVIDIA Pascal or later GPU with at least 8 gb of VRAM
• CUDA 11.4+
• Python 3.8+
• PyTorch 2.0.0+
• Isaac Gym 1.0rc3+ (for simulation environments)
• Additional dependencies (see requirements.txt and Install dependencies)
• Miniconda

Installation

$ conda create -n isaac python==3.8 && conda activate isaac
$ pip install torch==2.0.0 torchvision==0.15.1 torchaudio==2.0.0
$ tar -zxvf IsaacGym_Preview_4_Package.tar.gz && cd ./isaacgym/python && pip install -e . 
$ pip3 install requirements.txt
$ pip3 install matplotlib pandas tensorboard opencv-python numpy==1.23.5 openpyxl onnxruntime onnx

Training

To train (default:test):

$ python train.py --config BIRL --name <NAME> --render --num_envs 10

• --name # Experiment name (Replace <NAME> with q2 for Qmini), overrides settings in the config file
  • --config # Experiment configuration file (Default: 'config.Base'), overrides default configuration
  • --resume # Resume training from checkpoint (Default: test), requires specifying checkpoint 'path'
  • --render # Boolean flag (Default: False), force display off at all times
  • --fix_cam # Boolean flag (Default: False), fix camera view on the robot in environment 0
  • --horovod # Boolean flag (Default: False), enable Horovod multi-GPU training
  • --rl_device # RL device (Default: 'cuda:0'), supports formats like 'cpu'/'cuda:0'
  • --num_envs # Number of environments (Default: None), overrides config file settings
  • --seed # Random seed (Default: None), overrides config file settings
  • --max_iterations # Maximum number of iterations (Default: None), overrides config file settings

Tips

髋关节 YAW 轴的活动范围设定为-0.349到0.525弧度，这个数值既保证步态灵活性，又避免机械干涉。

Training New Policy

$ python train.py --config BIRL --name qmini_experiment

Evaluate Newly Trained Policy

$ python play.py --render --name qmini_experiment --time 10

Export Model for Deployment

$ python export_pt2onnx.py --name qmini_experiment

虽然核心控制基于深度学习，但底层电机控制仍需要精确的工程调优。

项目提供了PID参数优化工具，帮助减小仿真与实际机器人行为之间的差异：

优化底层控制参数

python tune_pid.py --mode real

基于官方项目结构进行定制

需要修改config文件、reward函数等核心模块

$ python train.py --config custom_config --name your_experiment