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

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

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

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

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

2. 硬件連接邏輯

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

二、核心代碼框架

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

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

unitree_sdk/
├── include/unitree_legged_sdk/  # 核心頭文件（關(guān)節(jié)控制、通信、枚舉）
├── lib/                         # 平臺(tái)庫(kù)文件（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)控制」核心代碼，基于宇樹(shù)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;  // 速度等級(jí)（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)鍵說(shuō)明

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

三、調(diào)試方法

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

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

2. 運(yùn)動(dòng)參數(shù)調(diào)試

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

• 目標(biāo)：校準(zhǔn)關(guān)節(jié)零位、調(diào)整PID參數(shù)、測(cè)試力矩限制；
• 方法：
  1. 運(yùn)行example/joint_control示例，發(fā)送單個(gè)關(guān)節(jié)的角度指令；
  2. 通過(guò)LowCmd設(shè)置關(guān)節(jié)目標(biāo)角度（如cmd.motorCmd[0].q = 0.1），觀察實(shí)際反饋（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ī)身高度），解決卡頓/打滑問(wèn)題；
  3. 通過(guò)ros2 topic echo /unitree/high_state實(shí)時(shí)查看機(jī)器人狀態(tài)，分析步態(tài)異常原因（如IMU傾角過(guò)大、足力分布不均）。

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

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

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

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

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

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

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

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

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

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  # 速度等級(jí)
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二次開(kāi)發(fā)接口（話題/服務(wù)）

宇樹(shù)機(jī)器人已封裝ROS2接口，可直接通過(guò)話題/服務(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. 自定義行為開(kāi)發(fā)

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

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

五、注意事項(xiàng)

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

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

審核編輯 黃宇