入门宇树机器人开发：从SDK源码探索到实战操作

 

 

一、宇树 SDK2 整体介绍

 

宇树机器人（Unitree）作为全球领先的四足机器人研发企业，其推出的unitree_sdk2是面向旗下 Go2、H1、B2 等系列机器人的第二代软件开发工具包。该 SDK 提供了丰富的接口和示例代码，支持开发者快速实现机器人控制、状态获取、传感器数据处理等功能，是入门宇树机器人开发的核心工具。

 

 

 

unitree_sdk2的核心优势在于：

 

 

•跨平台支持：兼容 x86_64 和 aarch64 架构的 Ubuntu 20.04 系统

 

 

•多机器人适配：统一接口支持 Go2、H1、B2 等多款机器人

 

 

•功能全面：涵盖运动控制、状态监测、视频流获取、语音交互等能力

 

 

•易于扩展：提供 CMake 集成示例，方便开发者搭建自定义项目

 

 

官方文档中心（Unitree Document Center）提供了更详细的技术文档，建议作为开发过程中的重要参考。

 

 

二、SDK 目录结构与核心功能

 

1. 目录结构解析

 

unitree_sdk2的源码结构清晰，主要包含以下核心目录：

 

 

•  
•  
•  
•  
•  
•  
•  
•  
•  
•  

unitree_sdk2/├── example/               # 示例代码目录│   ├── go2/               # Go2机器人示例│   ├── h1/                # H1机器人示例│   ├── b2/                # B2机器人示例│   ├── state_machine/     # 状态机控制示例│   └── wireless_controller/ # 无线控制器示例├── include/               # 头文件目录│   └── unitree/robot/     # 机器人控制核心接口└── README.md              # 环境配置与编译说明

2. 核心功能点

 

从示例代码中可以梳理出 SDK 的核心功能：

 

 

（1）基础控制功能

 

•运动控制：支持机器人站立（StandUp()）、下蹲（StandDown()）、移动（Move(vx, vy, vw)）等动作

 

 

•步态切换：通过SwitchGait()实现不同运动模式（如慢走、快跑、爬楼梯）的切换

 

 

•速度控制：通过SpeedLevel()调整运动速度等级

 

 

（2）状态获取功能

 

•机器人状态：通过RobotStateClient获取关节角度、IMU 数据、电池状态等

 

 

•服务状态：通过ServiceList()查询当前激活的服务列表及运行状态

 

 

•传感器数据：支持获取摄像头图像（VideoClient）、超声波等传感器数据

 

 

（3）高级功能

 

•轨迹跟踪：通过TrajectoryFollow实现预设路径的精确跟踪

 

 

•低电平控制：直接操作关节电机，实现高精度位置 / 力控制

 

 

•语音交互：通过VuiClient控制机器人的语音交互模块

 

 

（4）开发辅助功能

 

•日志系统：支持自定义日志输出路径和格式

 

 

•参数配置：通过 YAML 文件加载机器人控制参数

 

 

•线程管理：提供周期性控制线程封装，简化实时控制逻辑

 

 

三、环境搭建步骤

 

1. 系统要求

 

•操作系统：Ubuntu 20.04 LTS

 

 

•架构：x86_64（开发机）或 aarch64（机器人本体）

 

 

•编译器：GCC 9.4.0

 

 

2. 依赖安装

 

执行以下命令安装必要依赖：

 

 

•  
•  

apt-get updateapt-get install -y cmake g++ build-essential libyaml-cpp-dev libeigen3-dev libboost-all-dev libspdlog-dev libfmt-dev

3. 编译与安装

 

（1）编译示例代码

 

•  
•  
•  
•  

mkdir buildcd buildcmake ..make

（2）安装 SDK 到系统目录

 

•  
•  
•  
•  
•  

# 安装到默认路径sudo make install# 或指定安装路径cmake .. -DCMAKE_INSTALL_PREFIX=/opt/unitree_roboticssudo make install

（3）项目集成

 

参考example/cmake_sample中的配置，在自定义项目的CMakeLists.txt中通过以下方式引入 SDK：

 

 

•  
•  

find_package(unitree_sdk2 REQUIRED)target_link_libraries(your_project unitree_sdk2)

四、常见问题与解决方法

 

1. 编译错误

 

•问题：CMake版本不足

 

 

解决：升级 CMake 至 3.10 以上版本：sudo apt-get install cmake --upgrade

 

 

•问题：依赖库缺失

 

 

解决：检查是否已安装所有依赖，特别是libyaml-cpp-dev和libeigen3-dev

 

 

2. 运行时错误

 

•问题：networkInterface参数缺失

 

 

解决：运行示例时需指定网络接口（如 eth0），例如：./go2_robot_state_client eth0

 

 

•问题：API 版本不匹配

 

 

解决：检查客户端与服务器的 API 版本是否一致，通过GetApiVersion()和GetServerApiVersion()验证

 

 

•问题：服务调用失败

 

 

解决：确保机器人已启动对应服务，可通过ServiceList()查询服务状态

 

 

3. 硬件相关问题

 

•问题：H1 机器人关节跟踪实验失败

 

 

解决：必须先将机器人悬挂起来再运行测试，避免硬件损坏

 

 

•问题：运动指令无响应

 

 

解决：检查机器人是否处于正确模式（如运动模式需先激活sport_mode）

 

 

五、入门实战建议

 

1.从示例开始：先运行基础示例（如go2_stand_example），熟悉机器人控制流程

 

 

2.调试工具：利用示例中的日志输出和状态打印功能，理解数据流向

 

 

3.模块化学习：

 

 

◦运动控制：重点研究go2_sport_client.cpp

 

 

◦状态获取：分析go2_robot_state_client.cpp

 

 

◦低电平控制：参考h1/low_level目录下的示例

 

 

1.渐进式开发：先基于现有接口实现简单功能，再逐步深入到自定义控制算法

 

 

宇树 SDK2 为开发者提供了通往机器人开发的便捷路径，无论是高校科研、企业应用还是个人兴趣，都能通过这个工具包快速实现创意。动手实践是最好的学习方式，不妨从编译第一个示例开始，开启你的机器人开发之旅吧！