从零跑通Unitree Go2机器人ROS2控制：一份给新手的完整上手指南

【免费下载链接】go2_ros2_sdkUnofficial ROS2 SDK support for Unitree GO2 AIR/PRO/EDU项目地址: https://gitcode.com/gh_mirrors/go/go2_ros2_sdk

如果你刚把一台 Unitree Go2 四足机器人抱回家，大概很快会碰到这样的时刻：手机 App 里点点摇杆，看它走路、翻身、奔跑，确实很酷。但当你真正想做点"自己的事"——比如让它自己探索房间并画出一张地图、识别客厅里的沙发和茶几、或者编一段让它自动巡逻的程序时，App 的封闭接口就成了拦路虎。

这个项目要解决的，正是这个问题。go2_ros2_sdk是一个非官方的 ROS2 SDK，专门为 Unitree GO2 的 AIR / PRO / EDU 三个版本提供完整的 ROS2 生态接入：它能通过 Wi-Fi（WebRTC 协议）或网线（CycloneDDS 协议）把机器人"翻译"成 ROS2 世界里的标准接口，让你用一套成熟的生态工具去控制它、感知它、改造它。简而言之，它给 Go2 装上了一颗开放的大脑。🤖

它到底能帮你做什么？一句话说清楚

这个 SDK 的核心价值，是把 Go2 从"一个只有官方 App 能操控的玩具"变成"一个所有数据接口都开放的 ROS2 开发平台"。你不需要从零造轮子，也不需要逆向破解通信协议，装好之后开箱就能用。

拿几个关键能力来说：

• 实时数据同步：关节状态、IMU 姿态、脚底压力传感器（PRO/EDU 机型）、摄像头画面、激光雷达点云，全部以标准 ROS2 话题实时发布，频率足够支撑上层算法；
• 双协议自由切换：Wi-Fi 用 WebRTC，有线用 CycloneDDS，一条环境变量CONN_TYPE就能切换，场景不同选不同的连接方式；
• SLAM 建图 + Nav2 自主导航：直接集成slam_toolbox和nav2_bringup，启动即用，不需要自己拼装导航栈；
• 物体识别：内置基于 COCO 数据集的检测节点，可识别 80 多类常见物体，人物、家具、电器都不在话下；
• 多机协同：支持同时连接多台 Go2，用逗号分隔 IP 即可实现多机协作控制。

30 分钟跑通第一个"Hello World"：完整安装与启动指南

这一节我们走一遍从环境准备到机器人动起来的完整流程。你只需要一台装有 Ubuntu 22.04 的电脑（已安装 ROS2，Humble / Iron / Rolling 均可）、一个能与电脑同网的 Go2 机器人，以及一点耐心。

第一步：克隆项目并安装系统依赖

先在终端里创建工作区并克隆仓库，--recurse-submodules会把子模块一并拉下来，漏了它后面会缺文件：

mkdir -p ros2_ws && cd ros2_ws git clone --recurse-submodules https://gitcode.com/gh_mirrors/go/go2_ros2_sdk src

接着安装编译和运行所需的系统级依赖。这里的$ROS_DISTRO是 ROS2 版本名（比如humble），会由系统自动填充：

sudo apt install ros-$ROS_DISTRO-image-tools ros-$ROS_DISTRO-vision-msgs sudo apt install python3-pip clang portaudio19-dev

然后安装 Python 依赖。这一步要特别留意终端输出，任何一处 pip 安装失败都可能让对应功能不可用：

cd src pip install -r requirements.txt cd ..

第二步：构建整个工作区

先激活 ROS2 环境，用rosdep自动解析剩余依赖，再交给colcon build统一编译。整个过程会同时构建 SDK 主包、go2_interfaces消息定义、lidar_processor点云处理等若干子包：

source /opt/ros/$ROS_DISTRO/setup.bash rosdep install --from-paths src --ignore-src -r -y colcon build

如果顺利，install/目录里会出现全部可执行文件。构建报错时别慌，先看报错对应哪个包，常见原因集中在 Python 版本兼容上（见文末避坑清单）。

第三步：设置机器人 IP 并一键启动

启动前先用手机 App 把 Go2 切到 Wi-Fi 模式，并在 App 里查看它的 IP（路径大致是 设备 → 数据 → 自动检测 → STA 网络 wlan0）。然后激活环境、导出两个关键环境变量，一条 launch 命令带走所有节点：

source install/setup.bash export ROBOT_IP="你的机器人IP" export CONN_TYPE="webrtc" ros2 launch go2_robot_sdk robot.launch.py

这条命令背后其实串起了十几个节点：机器人驱动、状态发布器、激光雷达转点云、前视摄像头视频流、rviz2可视化界面、手柄遥控、SLAM 建图、Nav2 导航，还有 Foxglove 桥接服务。几秒之后 RViz 窗口弹出，雷达点云开始累积，约 4 秒后彩色摄像头画面出现——你的 Go2 已经在等你的手柄指令了。🎮

真实场景验证：让它先认识你家，再看见世界

场景一：给它画一张"家的地图"，然后自主导航

这是最能直观感受"它真的跑起来了"的演示。先用美纹胶带在地板上贴出一个机器人可以停靠的矩形区域，当作建图起点（官方把这里叫做 dock，相当于机器人的"出生点"）。在 RViz 左侧的 SlamToolbox 面板里点击Start At Dock，然后用手柄遥控它在房间里慢慢走一遍。你会看到地图实时生长：白色像素代表自由空间，黑色代表障碍物，灰色代表未知区域。

逛完一圈后，在面板里给地图起个名字（比如map_1），分别点击Save Map和Serialize Map，工作区里会生成map_1.yaml、map_1.pgm等 4 个文件。下次启动时，在Deserialize Map里填上地图名加载它，再用 RViz 上方的Nav2 Goal按钮在地图上点一个目标点，绿色箭头调整到达时的朝向，Go2 就会自己规划路径走过去。

这里有个必须记住的警告：导航前务必确认地图本身没问题、机器人的初始位置和朝向与地图对齐，否则路径规划器可能让机器人"穿墙而过"，在地板上留下一道道划痕。作者在文档里也自嘲地说：在你熟悉之前，最好跟着它走，发现它要做傻事就赶紧抱起来。

场景二：让它"看见"并识别周围的东西

SDK 内置的 COCO 物体检测器可以直接在另一个终端运行。注意第一次运行需要下载神经网络权重，会有一小段下载进度条，之后会缓存到本地：

ros2 run coco_detector coco_detector_node

打开另一个终端订阅检测结果话题，你会看到类似class_id: person、score: 0.9989的输出，还有物体中心在画面中的像素坐标——这些数据完全可以用来实现人员跟随：

ros2 topic echo /detected_objects

想直接看带框标注的画面，运行下面的命令即可弹出可视化窗口：

ros2 run image_tools showimage --ros-args -r /image:=/annotated_image

检测阈值默认是 0.9，如果误检太多，可以调高；想用 GPU 加速，把device参数改成cuda。检测结果、边界框、置信度都会通过Detection2DArray消息发布，接上你自己的逻辑就能做跟踪和避障。

从连不上到跑起来：避坑手册

整理几个新手最容易踩的坑，按出现频率排序：

Q1：启动后一直连不上机器人，怎么办？按顺序排查：① 确认机器人和电脑在同一个局域网；② 确认 IP 没写错，多个机器人用逗号分隔；③用 WebRTC 连接前必须关闭手机 App 的连接，两者抢连接会导致握手失败；④ 换有线连接，把CONN_TYPE改成cyclonedds再试。

Q2：pip install -r requirements.txt报错，尤其open3d装不上？大概率是你的 Python 版本太高。open3d目前不支持 Python 3.12，官方建议先建一个 Python 3.11 的venv虚拟环境再安装，别图省事直接跳过报错，否则后续点云、SLAM 功能都会悄悄失效。

Q3：手柄没反应？非 WSL2 环境先确认手柄驱动是否识别（ros2 run joy joy_enumerate_devices）。如果你在 WSL2 里跑 ROS2，还需要额外把 USB 设备共享进 WSL、编译带摇杆驱动的内核、并给/dev/input/event*添加当前用户的读写权限，这一步最容易被忽略。

Q4：建图质量差、导航撞墙？光照不足、玻璃和镜面反射都会污染雷达数据；机器人移动太快会让地图漂移。慢速多次扫描同一区域，必要时降低controller_frequency等控制频率参数（配置在go2_robot_sdk/config/nav2_params.yaml里），让规划器有足够的计算余量。

往深处走：二次开发从哪里入手

如果你不满足于开箱即用，这个项目的架构反而值得一读——它刻意采用了 Clean Architecture 分层设计，源码都放在go2_robot_sdk/go2_robot_sdk/下，按domain/（实体与业务规则）、application/（服务与用例）、infrastructure/（WebRTC 连接、传感器解码、ROS2 发布）、presentation/（驱动节点）四层划分。想扩展新传感器，就在infrastructure/sensors/加处理模块；想开发新算法，在domain/math/写计算、在application/services/接服务、最后通过 ROS2 话题暴露出来即可。

除此之外还有几个实用入口：

• Docker 一键部署：进入docker/目录，用ROBOT_IP=xxx CONN_TYPE=webrtc docker-compose up --build就能在容器里跑起来，适合不想污染宿主环境的用户；
• Foxglove 可视化：项目自带 Foxglove 桥接，安装 Foxglove Studio 后连接ws://localhost:8765，能获得比 RViz 更顺手的调试面板；
• WebRTC 指令接口：想让机器人开灯、播放声音这类非运动指令，可以直接往/webrtc_req话题发布WebRtcReq消息，不需要额外写代码；
• 3D 点云导出：设置MAP_SAVE=True和MAP_NAME=3d_map后，每隔 10 秒会往仓库根目录写一份.ply原始点云，适合做底层调试或给其他三维工具喂数据。

现在，就让它迈出第一步

从拆箱时的"只会听 App 的话"，到让它自己画出家的地图、认出客厅里的沙发、再跟着你走完一条走廊——中间隔着的，其实就是这几十条命令的距离。把仓库克隆下来，给它一块胶带贴出的起点，剩下的，交给时间和你的好奇心。Go2 已经站在那儿等你了，现在就去按下那条launch命令吧。🚀

【免费下载链接】go2_ros2_sdkUnofficial ROS2 SDK support for Unitree GO2 AIR/PRO/EDU项目地址: https://gitcode.com/gh_mirrors/go/go2_ros2_sdk