宇樹人形機(jī)器人全維度技術(shù)指南

宇樹人形機(jī)器人（如H1、G1等系列）是具備高自由度、精準(zhǔn)運動控制的人形機(jī)器人平臺，以下從硬件配置、核心代碼框架、調(diào)試方法、二次開發(fā)接口四個維度展開，覆蓋從底層控制到上層應(yīng)用的全鏈路技術(shù)細(xì)節(jié)。

注：以下內(nèi)容基于宇樹官方公開技術(shù)文檔及通用開發(fā)規(guī)范，不同型號（如Unitree H1/Go1/A1）的細(xì)節(jié)會有差異，需結(jié)合對應(yīng)型號的SDK適配。

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

1. 核心硬件參數(shù)

2. 硬件連接邏輯

• 實時控制層 ：STM32運動控制板通過CAN總線連接所有伺服關(guān)節(jié)，負(fù)責(zé)毫秒級運動指令執(zhí)行；
• 計算層 ：Jetson Orin通過以太網(wǎng)與運動控制板通信，處理感知、路徑規(guī)劃、行為決策；
• 感知層 ：相機(jī)/雷達(dá)數(shù)據(jù)直接接入Jetson，通過ROS/ROS2進(jìn)行數(shù)據(jù)融合。

二、核心代碼框架

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

1. 代碼目錄結(jié)構(gòu)（官方SDK）

unitree_sdk/
├── include/unitree_legged_sdk/  # 核心頭文件（關(guān)節(jié)控制、通信、枚舉）
├── lib/                         # 平臺庫文件（x86/ARM架構(gòu)）
├── examples/                    # 示例代碼（站立、行走、避障）
├── config/                      # 機(jī)器人參數(shù)配置（關(guān)節(jié)限位、PID參數(shù)）
└── scripts/                     # Python輔助腳本（調(diào)試、數(shù)據(jù)采集）

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

以下是最基礎(chǔ)的「機(jī)器人站立+步態(tài)控制」核心代碼，基于宇樹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();          // 接收機(jī)器人狀態(tài)
        udp.GetRecv(state);  // 獲取當(dāng)前狀態(tài)（關(guān)節(jié)角度、IMU、力傳感器）

        // 1. 基礎(chǔ)配置：模式切換、速度設(shè)置
        cmd.mode = 0;        // 0:待機(jī) 1:站立 2:行走 3:奔跑
        cmd.gaitType = 0;    // 0:空步態(tài) 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. 發(fā)送指令
        udp.SetSend(cmd);
        udp.Send();
        usleep(10000);  // 10ms周期（與機(jī)器人通信頻率匹配）
    }

private:
    Safety safe;
    UDP udp;
    HighCmd cmd = {0};    // 高層控制指令（速度、步態(tài)、模式）
    HighState state = {0};// 高層狀態(tài)反饋（關(guān)節(jié)、IMU、電池）
};

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

3. 核心代碼關(guān)鍵說明

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

三、調(diào)試方法

1. 環(huán)境搭建調(diào)試

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

2. 運動參數(shù)調(diào)試

（1）關(guān)節(jié)級調(diào)試（底層）

• 目標(biāo)：校準(zhǔn)關(guān)節(jié)零位、調(diào)整PID參數(shù)、測試力矩限制；
• 方法：
  1. 運行example/joint_control示例，發(fā)送單個關(guān)節(jié)的角度指令；
  2. 通過LowCmd設(shè)置關(guān)節(jié)目標(biāo)角度（如cmd.motorCmd[0].q = 0.1），觀察實際反饋（state.motorState[0].q）；
  3. 調(diào)整config/pid_params.yaml中的關(guān)節(jié)PID參數(shù)，優(yōu)化響應(yīng)速度和穩(wěn)定性。

（2）步態(tài)調(diào)試（高層）

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

（3）感知模塊調(diào)試

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

3. 故障排查調(diào)試

4. 工具輔助調(diào)試

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

四、二次開發(fā)接口

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

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

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

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  # 待機(jī)模式
cmd.gaitType = 1  # 行走步態(tài)
cmd.speedLevel = 1  # 速度等級
cmd.footRaiseHeight = 0.08

# 主循環(huán)
count = 0
while True:
    # 接收狀態(tài)
    udp.recv()
    udp.getRecv(state)
    print(f"當(dāng)前電池電壓：{state.batteryVoltage}V")

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

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

3. ROS2二次開發(fā)接口（話題/服務(wù)）

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

ROS2示例（發(fā)布行走指令）

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  # 先待機(jī)，后行走
        msg.gait_type = 1
        msg.velocity[0] = 0.3  # 前進(jìn)速度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. 自定義行為開發(fā)

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

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

五、注意事項

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

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

審核編輯 黃宇