零基础用ROS2控制Unitree Go2机器人：完整指南与实战演练

零基础用ROS2控制Unitree Go2机器人：完整指南与实战演练

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

把一只 Unitree Go2 四足机器人接入 ROS2 生态，听起来像是个硬核工程师的专属任务。但在 go2_ros2_sdk 这个开源项目出现之前，你确实只能被困在厂商 App 和私有协议里：想在 RViz 里看实时点云？想用一行命令让机器狗站起来、打招呼、跳个舞？想同时指挥三台狗协同作业？这些都变成了"想想就好"的奢望。

这个项目专门为 GO2 的 AIR / PRO / EDU 三个版本提供了完整的 ROS2 SDK 支持，通过 WebRTC（Wi-Fi）和 CycloneDDS（以太网）两种协议打通机器人与标准 ROS2 工具链。你不需要懂机器人底层通信细节，也不需要逆向厂商协议，克隆仓库、装好依赖、跑一条启动命令，就能收获一套实时关节状态、IMU、摄像头、激光雷达点云，外加 SLAM 建图、自主导航、物体识别、语音合成全家桶。本文就带你从零开始，完成一次从"连不上"到"自主导航"的完整实战。

30秒看懂它：这是什么，能做什么，适合谁

先别急着看代码，用三句话建立认知：

一句话概括价值：它把"机器狗"变成了一台标准的 ROS2 传感器平台，让生态里现成的工具（RViz、slam_toolbox、Nav2、Foxglove）全部直接可用。

整个项目采用 Clean Architecture 分层设计，代码组织清晰，想二次开发的用户也能快速找到切入点：

• 领域层go2_robot_sdk/domain/：业务实体与命令常量，比如robot_commands.py里定义了全部运动指令 ID
• 应用层go2_robot_sdk/application/：控制与数据服务
• 基础设施层go2_robot_sdk/infrastructure/：WebRTC 连接、传感器解码、ROS2 发布
• 展示层go2_robot_sdk/presentation/：入口节点go2_driver_node.py

第一步：环境准备，5 分钟搭好开发台

前提条件：一台 Ubuntu 22.04 电脑，装有 ROS2（Iron / Humble / Rolling 均可），一只设置成 Wi-Fi 模式的 Go2 机器人（IP 可在手机 App 的 Device → Data 里查到，找 STA Network: wlan0 那一栏）。

打开终端，按顺序执行：

# 1. 创建工作空间并克隆项目（含子模块，务必加 --recurse-submodules） mkdir -p ros2_ws cd ros2_ws git clone --recurse-submodules https://gitcode.com/gh_mirrors/go/go2_ros2_sdk.git src

# 2. 安装 ROS 系统级依赖 sudo apt install ros-$ROS_DISTRO-image-tools ros-$ROS_DISTRO-vision-msgs

# 3. 安装 Python 依赖（进入 src 目录后执行） sudo apt install python3-pip clang portaudio19-dev cd src pip install -r requirements.txt cd ..

这一步应看到什么：pip install无报错地跑完。这里要特别提醒：如果pip install中途报错，后面很多功能会悄悄失效。比如 open3d 目前还不支持 Python 3.12，如果你用的是新版 Python，需要先建一个 3.11 的venv再装。

接着构建工作空间：

# 4. 构建（确保已安装 rosdep） source /opt/ros/$ROS_DISTRO/setup.bash rosdep install --from-paths src --ignore-src -r -y colcon build

这一步应看到什么：colcon build结束后出现Finished <<< go2_robot_sdk之类的成功提示。

💡 想省事也可以走 Docker 路线：仓库的docker/目录已备好镜像配置，一条docker-compose up --build就能起来，环境变量ROBOT_IP和CONN_TYPE照常传即可。

第二步：首次运行，一条命令唤醒机器狗

构建完成后的启动极其简单，核心就三行：

# 设置机器人 IP（多台机器人用逗号分隔） export ROBOT_IP="192.168.1.100" # 选择连接方式：webrtc（Wi-Fi）或 cyclonedds（以太网） export CONN_TYPE="webrtc" # 加载环境并一键启动 source install/setup.bash ros2 launch go2_robot_sdk robot.launch.py

这一步应看到什么：RViz 窗口弹出、激光雷达点云开始累积、前视彩色摄像头画面大约 4 秒后出现、机器狗静静等待你的手柄指令。如果你用的是 Xbox 手柄，插上就能操控它在家里的地面上走动，同时收集建图数据。

这一条命令背后其实拉起了一整队节点，robot.launch.py（位于 launch/robot.launch.py）会同时启动：

启动时如果你觉得 RViz 画面信息太多，可以先在左侧面板关掉Map话题，视野会清爽很多。

第三步：完整闭环，从建图到自主导航

现在进入本文的重头戏——让机器狗真正"认识"你的房间，并自己走过去。

3.1 生成你的第一张地图

1. 在地板上用胶带贴一个"停靠矩形"作为起始点标记
2. 在 RViz 左侧的 SlamToolbox 插件里点Start At Dock，让机器人锁定初始位姿
3. 用手柄遥控它慢慢探索房间（白色像素=自由空间，黑色=障碍，灰色=未知）
4. 探索完成后，在Save Map输入文件名并保存，再在Serialize Map输入同名并序列化

这一步应看到什么：工作空间里多出 4 个文件——map_1.yaml（地图元数据）、map_1.pgm（栅格图像）、map_1.data和map_1.posegraph（SLAM 位姿图）。下次启动系统时，通过Deserialize Map加载这张地图，就能接着补全或直接使用。

3.2 下达第一个自主导航目标

加载地图后，RViz 的 Navigation 2 插件会显示Navigation: active / Localization: inactive，点开Deserialize Map载入你的地图文件（无需带扩展名）。

然后用 RViz 菜单里的Nav2 Goal，鼠标点选一个目标位置——松开前的绿色箭头用来设定机器狗到达后的朝向角。按下后，你就拥有了第一台会自己认路的机器狗。

⚠️ 导航前务必确认两件事：机器狗相对于地图的初始朝向正确；地图本身没有严重畸变（尤其是长走廊，容易让规划器"穿墙"，在墙上留下划痕）。新手期建议全程跟着它，发现苗头不对就及时抱起来。

3.3 点云数据的备份开关

想留存原始激光雷达数据做底层调试？启动前导出两个变量即可：

export MAP_SAVE=True export MAP_NAME="3d_map"

系统会每 10 秒把点云以.ply格式存到仓库根目录。注意这不是 Nav2 地图，而是原始 LIDAR 数据转储，适合做算法验证。

进阶玩法一：让机器狗"看见"世界（物体识别）

导航只是移动，识别才是感知。启动主系统几秒后，摄像头数据就绪，另开终端运行：

source install/setup.bash ros2 run coco_detector coco_detector_node

这一步应看到什么：第一次运行会下载 PyTorch 的神经网络权重（有进度条，之后会缓存）。然后在第三个终端查看检测结果：

ros2 topic echo /detected_objects

输出里能看到class_id: person（人物）、score: 0.9989（置信度 0~1），以及bbox:center:x/y（目标中心像素坐标）。想看带标注框的视频流？

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

我能用它做什么：这些坐标数据完全够你写一个"人物跟随"逻辑——让机器狗锁定画面中的person，用目标中心偏移量反推速度指令。检测器还支持参数调优：

ros2 run coco_detector coco_detector_node --ros-args \ -p publish_annotated_image:=False \ -p device:=cuda \ -p detection_threshold:=0.7

detection_threshold默认 0.9，值越大误检越少；device默认 cpu，有 NVIDIA 显卡可以换cuda提速。识别模块源码在 coco_detector/coco_detector/coco_detector_node.py。

进阶玩法二：让机器狗"开口说话"（语音合成）

仓库内置了一个独立的语音包 speech_processor/，支持 ElevenLabs / Google / Amazon / OpenAI 四家 TTS 服务商。启动时通过环境变量注入 API Key：

export ELEVENLABS_API_KEY="你的密钥"

启动后向 TTS 话题发一条字符串，机器狗就会开口：

ros2 topic pub /tts_input std_msgs/msg/String "data: '你好，我是Go2机器人'" --once

实现里内置了音频缓存（同样的文本不重复请求 API）、本地播放开关和 chunk 流式播放，具体参数在 speech_processor/speech_processor/tts_node.py 的TTSConfig里可调。

进阶玩法三：多机器人协同，一只变一群

如果你手里不止一台 Go2，协同控制只需要改一行环境变量：

export ROBOT_IP="192.168.1.101,192.168.1.102,192.168.1.103" export CONN_TYPE="webrtc" ros2 launch go2_robot_sdk robot.launch.py

系统会自动识别为多机模式，每台机器人的话题加robot0/、robot1/前缀，分别发布robot{i}/joint_states、robot{i}/odom、robot{i}/imu等，RViz 也会切换到multi_robot_conf.rviz视图，URDF 换成 urdf/multi_go2.urdf。多机话题映射逻辑集中在 go2_robot_sdk/presentation/go2_driver_node.py。

进阶玩法四：用 WebRTC 话题遥控非移动动作

想开灯、放音乐、做花式动作？这些不走速度指令，而是通过/webrtc_req话题发送：

# 发送挥手动作（api_id=1016 对应 Hello） ros2 topic pub /webrtc_req go2_interfaces/msg/WebRtcReq \ "{api_id: 1016, topic: 'rt/api/sport/request'}" --once

所有可用的动作指令 ID 都集中定义在 go2_robot_sdk/domain/constants/robot_commands.py，从基础动作到高难度玩法应有尽有：

用同一机制还能做避障开关（api_id: 1004+OBSTACLES_AVOID话题），控制逻辑见 go2_robot_sdk/application/services/robot_control_service.py。

新手最容易踩的 3 个坑

坑 1：连不上机器人

最常见原因：手机 App 还占着连接。WebRTC 协议同一时间只允许一个客户端，先关掉手机 App 再连。另外确认电脑和机器人在同一网段，Wi-Fi 建议用 5GHz 频段降低延迟。有网线条件时直接切CONN_TYPE="cyclonedds"走以太网，稳定性最好。

坑 2：地图越建越歪 / 导航穿墙

九成情况是这三件事之一：地图本身错了、机器人相对地图的初始位姿错了、控制回路过载。仓库在 config/nav2_params.yaml 里已经把controller_frequency（3.0）和expected_planner_frequency（1.0）设得很保守，来防止"原地转圈"这类过载故障，所以先别乱调，优先检查前两项。

坑 3：关节模型"抽搐"或延迟

这是新固件（v1.1.7）的已知现象：激光雷达流已提升到 7Hz，但关节状态仍以 1Hz 到达，所以 URDF 模型更新会有明显延迟感。属于预期行为，社区正在找解决方案，不影响其他功能使用。

症状排查对照表

再往前走一步：可视化与二次开发

Foxglove 高级可视化

除了 RViz，你还能用 Foxglove Studio 获得更现代的调试界面：

sudo snap install foxglove-studio

打开后点击Open Connection，选择Foxglove WebSocket，默认地址ws://localhost:8765直接连接。配合robot.launch.py自动拉起的 foxglove_bridge，无需额外配置。

给机器狗接新"器官"

想加新传感器或算法？Clean Architecture 的分层让扩展路径非常清晰：

1. 新传感器：在go2_robot_sdk/infrastructure/sensors/创建处理模块，实现标准数据接口，再接入主驱动节点
2. 新算法：在go2_robot_sdk/domain/math/写数学逻辑，在application/services/落地业务，最后用 ROS2 话题暴露
3. 改外观：仓库自带三套 URDF——基础款 urdf/go2.urdf、增强款 urdf/go2_on_steroids.urdf、带 RealSense 的 urdf/go2_with_realsense.urdf，模型资源在 meshes/ 和 dae/

自定义动作与参数

所有机器人配置参数（IP、Token、连接方式、是否开视频/解码雷达/避障）都通过环境变量和 ROS2 参数传入，核心配置类在 go2_robot_sdk/domain/entities/robot_config.py，建图参数在 config/mapper_params_online_async.yaml，手柄映射在 config/joystick.yaml。

资源导航

把本文用到的所有关键资源汇总在这，方便你随取随用：

你的下一步行动清单

现在，轮到你了。按这个顺序动手，最快 30 分钟就能收获第一份成就感：

1. 今晚：克隆仓库、跑通pip install和colcon build
2. 明天：把机器人设成 Wi-Fi 模式，查到 IP，跑robot.launch.py，用手柄遛一次狗
3. 周末：完成第一次 SLAM 建图，保存地图，下达第一个自主导航目标
4. 下周：跑通物体识别，试试让它跟踪"person"，再试试/webrtc_req让狗挥手打招呼

这只机器狗能做的不止是行走。当你把它接进 ROS2 生态的那一刻，它就变成了一个开放平台——建图、导航、感知、语音、多机协同，全部由你定义。从今天这第一步开始，让想象落地成真。🤖

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