宇樹人形機器人全維度技術指南

宇樹人形機器人（如H1、G1等系列）是具備高自由度、精準運動控制的人形機器人平臺，以下從硬件配置、核心代碼框架、調試方法、二次開發接口四個維度展開，覆蓋從底層控制到上層應用的全鏈路技術細節。

注：以下內容基于宇樹官方公開技術文檔及通用開發規范，不同型號（如Unitree H1/Go1/A1）的細節會有差異，需結合對應型號的SDK適配。

一、硬件配置（以H1為例）

1. 核心硬件參數

2. 硬件連接邏輯

• 實時控制層 ：STM32運動控制板通過CAN總線連接所有伺服關節，負責毫秒級運動指令執行；
• 計算層 ：Jetson Orin通過以太網與運動控制板通信，處理感知、路徑規劃、行為決策；
• 感知層 ：相機/雷達數據直接接入Jetson，通過ROS/ROS2進行數據融合。

二、核心代碼框架

宇樹機器人的核心代碼基于 ROS2 Humble （部分老型號支持ROS1），分為「運動控制層」「感知層」「決策層」三大模塊，官方提供C++/Python SDK。

1. 代碼目錄結構（官方SDK）

unitree_sdk/
├── include/unitree_legged_sdk/  # 核心頭文件（關節控制、通信、枚舉）
├── lib/                         # 平臺庫文件（x86/ARM架構）
├── examples/                    # 示例代碼（站立、行走、避障）
├── config/                      # 機器人參數配置（關節限位、PID參數）
└── scripts/                     # Python輔助腳本（調試、數據采集）

2. 核心控制代碼示例（C++）

以下是最基礎的「機器人站立+步態控制」核心代碼，基于宇樹Legged SDK：

#include "unitree_legged_sdk/unitree_legged_sdk.h"
#include < iostream >
#include < unistd.h >

using namespace UNITREE_LEGGED_SDK;

class CustomController {
public:
    CustomController(): safe(LeggedType::H1), udp(8080, "192.168.123.161", 8082, sizeof(HighCmd), sizeof(HighState)) {
        udp.InitCmdData(cmd);  // 初始化控制指令
    }

    void Run() {
        udp.Recv();          // 接收機器人狀態
        udp.GetRecv(state);  // 獲取當前狀態（關節角度、IMU、力傳感器）

        // 1. 基礎配置：模式切換、速度設置
        cmd.mode = 0;        // 0:待機 1:站立 2:行走 3:奔跑
        cmd.gaitType = 0;    // 0:空步態 1:行走 2:小跑 3:奔跑
        cmd.speedLevel = 0;  // 速度等級（0-5）
        cmd.footRaiseHeight = 0.08;  // 抬腳高度（m）

        // 2. 站立指令（1秒后切換）
        static int count = 0;
        if (count > 100) {
            cmd.mode = 1;  // 切換到站立模式
        }
        count++;

        // 3. 發送指令
        udp.SetSend(cmd);
        udp.Send();
        usleep(10000);  // 10ms周期（與機器人通信頻率匹配）
    }

private:
    Safety safe;
    UDP udp;
    HighCmd cmd = {0};    // 高層控制指令（速度、步態、模式）
    HighState state = {0};// 高層狀態反饋（關節、IMU、電池）
};

int main() {
    CustomController ctrl;
    while (true) {
        ctrl.Run();
    }
    return 0;
}

3. 核心代碼關鍵說明

• 通信協議 ：宇樹機器人采用UDP/TCP通信，分為「高層指令（HighCmd）」和「底層指令（LowCmd）」：
  • HighCmd：控制整體運動（步態、速度、模式），適用于上層應用；
  • LowCmd：直接控制單個關節（角度、力矩、電流），適用于精細調試；
• 步態控制 ：內置行走、小跑、奔跑等步態算法，通過gaitType參數切換，無需自研；
• 安全機制 ：SDK內置碰撞檢測、關節限位、低電量保護，可通過Safety類配置閾值。

三、調試方法

1. 環境搭建調試

• 硬件連接 ：通過以太網直連機器人（默認IP：192.168.123.161），或通過WiFi接入機器人熱點；
• SDK驗證 ：運行官方example/walk示例，驗證通信是否正常，若無法通信：
  • 檢查PC與機器人的IP是否在同一網段；
  • 關閉防火墻/殺毒軟件；
  • 確認機器人已上電并進入「開發模式」（非默認的「演示模式」）；
• 依賴檢查 ：確保安裝ROS2 Humble、Eigen3、Boost等依賴，執行ldd libunitree_legged_sdk.so檢查庫依賴是否缺失。

2. 運動參數調試

（1）關節級調試（底層）

• 目標：校準關節零位、調整PID參數、測試力矩限制；
• 方法：
  1. 運行example/joint_control示例，發送單個關節的角度指令；
  2. 通過LowCmd設置關節目標角度（如cmd.motorCmd[0].q = 0.1），觀察實際反饋（state.motorState[0].q）；
  3. 調整config/pid_params.yaml中的關節PID參數，優化響應速度和穩定性。

（2）步態調試（高層）

• 目標：優化行走穩定性、調整速度/抬腳高度；
• 方法：
  1. 修改cmd.velocity（線速度，單位m/s）、cmd.yawSpeed（角速度，單位rad/s）；
  2. 調整footRaiseHeight（抬腳高度）和bodyHeight（機身高度），解決卡頓/打滑問題；
  3. 通過ros2 topic echo /unitree/high_state實時查看機器人狀態，分析步態異常原因（如IMU傾角過大、足力分布不均）。

（3）感知模塊調試

• 激光雷達/相機調試：
  1. 運行ros2 launch unitree_perception lidar.launch.py啟動感知節點；
  2. 通過RViz查看點云/深度圖像，驗證感知數據是否正常；
  3. 若數據缺失，檢查驅動是否加載（ls /dev/ttyUSB0）、權限是否足夠（sudo chmod 777 /dev/ttyUSB0）。

3. 故障排查調試

4. 工具輔助調試

• Unitree Console ：官方可視化工具，支持：
  • 實時監控關節角度、力矩、IMU數據；
  • 手動控制機器人運動（鍵鼠/手柄）；
  • 導出日志、校準傳感器；
• ROS2 Tools ：
  • ros2 topic echo：查看機器人狀態話題；
  • ros2 bag record：錄制運動數據，離線分析；
  • rqt_plot：繪制關節角度/力矩曲線，定位異常波動；
• 日志分析 ：機器人日志存儲在/var/log/unitree/，重點查看motion.log和comm.log，定位運動/通信錯誤。

四、二次開發接口

宇樹機器人提供多語言（C++/Python/ROS2）二次開發接口，覆蓋「運動控制」「感知數據」「行為擴展」三大類。

1. 核心接口列表（C++ SDK）

2. Python二次開發示例（簡易行走控制）

import time
from unitree_legged_sdk_python import HighCmd, HighState, UDP

# 初始化通信
udp = UDP(8080, "192.168.123.161", 8082, HighCmd, HighState)
cmd = HighCmd()
state = HighState()

# 初始化指令
cmd.mode = 0  # 待機模式
cmd.gaitType = 1  # 行走步態
cmd.speedLevel = 1  # 速度等級
cmd.footRaiseHeight = 0.08

# 主循環
count = 0
while True:
    # 接收狀態
    udp.recv()
    udp.getRecv(state)
    print(f"當前電池電壓：{state.batteryVoltage}V")

    # 1秒后切換到站立+行走
    if count > 100:
        cmd.mode = 2  # 行走模式
        cmd.velocity[0] = 0.2  # 前進速度0.2m/s
    count += 1

    # 發送指令
    udp.setSend(cmd)
    udp.send()
    time.sleep(0.01)  # 10ms周期

3. ROS2二次開發接口（話題/服務）

宇樹機器人已封裝ROS2接口，可直接通過話題/服務控制：

ROS2示例（發布行走指令）

import rclpy
from rclpy.node import Node
from unitree_msgs.msg import HighCmd

class WalkPublisher(Node):
    def __init__(self):
        super().__init__('walk_publisher')
        self.publisher_ = self.create_publisher(HighCmd, '/unitree/high_cmd', 10)
        timer_period = 0.01  # 10ms
        self.timer = self.create_timer(timer_period, self.timer_callback)
        self.count = 0

    def timer_callback(self):
        msg = HighCmd()
        msg.mode = 0 if self.count < 100 else 2  # 先待機，后行走
        msg.gait_type = 1
        msg.velocity[0] = 0.3  # 前進速度0.3m/s
        msg.foot_raise_height = 0.08
        self.publisher_.publish(msg)
        self.count += 1

def main(args=None):
    rclpy.init(args=args)
    walk_pub = WalkPublisher()
    rclpy.spin(walk_pub)
    walk_pub.destroy_node()
    rclpy.shutdown()

if __name__ == '__main__':
    main()

4. 自定義行為開發

若需擴展自定義功能（如抓取、避障、語音交互），可通過以下方式：

1. 感知融合 ：將激光雷達/相機數據輸入自研算法（如SLAM、目標檢測），輸出運動指令；
2. 行為封裝 ：將自定義動作（如揮手、彎腰）封裝為「動作庫」，通過cmd.customCmd參數觸發；
3. 接口擴展 ：基于宇樹SDK封裝HTTP/WebSocket接口，支持遠程控制（如手機APP、網頁端）。

五、注意事項

1. 安全規范 ：調試時務必在空曠場地進行，避免機器人傾倒傷人，建議先通過仿真環境（宇樹提供Gazebo仿真模型）驗證代碼；
2. 版本適配 ：不同型號的SDK不兼容（如H1和Go1的Cmd/State結構不同），需下載對應型號的SDK；
3. 權限管理 ：機器人默認有操作權限限制，需通過官方工具解鎖「開發者權限」才能修改底層參數；
4. 文檔參考 ：宇樹官方提供《Unitree Legged SDK開發手冊》《H1機器人硬件手冊》，包含完整API和參數說明，是二次開發的核心參考。

如需某一具體模塊（如力矩控制、SLAM集成、語音交互）的深度開發細節，可補充說明，我會針對性展開。

審核編輯 黃宇