ROS2 学习套件 — 从零到具身智能 / VLA 完全体

如果你是 ROS2 完全的新手,不知道怎么开始 → 从零开始指南


🆘 从零开始:30 分钟跑通 Hello World

如果你从来没接触过 ROS2,不知道"Docker 是什么"、"make 命令在哪"、不知道怎么开终端,按下面一步一步来。

0. 你需要准备什么?(只看这一节就够)

工具 是什么 怎么得到 大约多大
Docker Desktop 跑 Linux 虚拟机的工具(本仓库的核心运行环境) https://www.docker.com/products/docker-desktop/ 下载 Windows 版 ~1 GB
VSCode(可选) 编辑代码的编辑器 https://code.visualstudio.com/ ~300 MB
Git(可选) 下载本仓库代码 https://git-scm.com/ ~50 MB

你不需要装:Python、ROS2、Ubuntu、虚拟机、Linux。

磁盘空间:Docker 镜像约 5 GB,本仓库源代码 < 100 MB。建议预留 10 GB 空闲

操作系统支持:Windows 10/11 专业版 / 企业版 / 教育版都支持,Windows 11 家庭版也行(会自动装 WSL2)。具体安装教程见下方 "Docker Desktop 安装"。

1. 验证 Docker 是否能跑

打开 PowerShell(开始菜单 → 输入 powershell → 回车),输入:

docker version

看到类似这样的输出就 OK:

Client:
 Version:           24.0.7
 ...
Server:
 Engine:
  Version:          24.0.7
  ...

如果报错 "Cannot connect to Docker daemon":Docker Desktop 没启动。任务栏右下角找 Docker 图标(鲸鱼),右键 → "Docker Desktop is running" 出现才算 OK。

如果提示 "WSL2 not installed":Docker Desktop 会自动提示安装,按它的指引装完重启即可。

2. 下载 / 找到本仓库

方式 A:用 Git 克隆

cd D:\xs
git clone <仓库地址> ros2
cd D:\xs\ros2

方式 B:下载 ZIP 解压

把仓库下载下来,解压到任意位置。真正的项目根目录是包含 README.mdMakefile 的那一层,不是上层目录(里面还有 src/doc/docker/ 这些子目录的)。

确认你在项目根目录:

Get-ChildItem   # 应该看到 AGENTS.md  CHANGELOG.md  docker  doc  Makefile  README.md  src

3. 打开 PowerShell 在项目根目录

重要:本节所有命令都在 Windows PowerShell(宿主机)执行,不是容器内。后面会有专门一节讲容器内命令。

cd D:\xs\ros2

4. 构建 Docker 镜像(首次约 5-10 分钟)

镜像是什么:打包好的 Linux + ROS2 + 工具链的"操作系统模板"。本仓库基于 osrf/ros:humble-desktop 构建。

docker build -t ros2-humble-dev:latest -f docker/Dockerfile .

预期输出:看到一长串 ---> Running in xxxSuccessfully built xxx(看不到具体行数是正常的,只看最后 Successfully tagged ros2-humble-dev:latest)。

下载量:首次约 3-5 GB(基础镜像 + 工具)。

5. 启动容器

容器 = 用镜像启动的"Linux 虚拟机实例"。本仓库的容器名是 ros2_dev

方式 A — 推荐(走 docker compose,跟 Makefile 等价)

docker compose -p ros2 -f docker/docker-compose.yml up -d

方式 B — 手动 docker run(等价;注意末尾的 bash 用来保活,重要 )

docker run -d -it --name ros2_dev `
  -v "$(Get-Location):/root/ros2_ws" `
  --network ros2_net `
  ros2-humble-dev:latest bash

一定要带末尾的 bash: 否则容器启动后立刻 Exited (0),因为基础镜像默认 ENTRYPOINT 跑 bash,无 tty 时立刻退出。 挂载路径要用 $(Get-Location) 而不是 ${PWD}: PowerShell 里 ${PWD}docker run -v 这种被引号包裹的 bind mount 上偶尔会被吃掉,导致容器静默退出(docker ps 看不到)。$(Get-Location) 是更稳的写法。

预期输出:一串 hash(容器 ID),没有报错就行。

验证容器跑起来了:

docker ps

应该看到 ros2_dev 在列表里,STATUS 列显示 Up

6. 进入容器(看到 root@xxx 就是成功了)

docker exec -it ros2_dev bash

你应该看到类似:

root@abc123def456:/root/ros2_ws#

重要:从现在开始,所有命令都在 容器内(Linux)执行,不是 Windows PowerShell。

怎么退出容器? 输入 exit 或按 Ctrl+D。再进去就再执行 docker exec -it ros2_dev bash

7. 加载 ROS2 环境(每个新终端都要执行!)

为什么需要 source:ROS2 把可执行文件、库、环境变量放在 /opt/ros/humble/ 下,不 source 就找不到 ros2colcon 这些命令。

source /opt/ros/humble/setup.bash

预期效果:没有报错 = OK。

怎么验证:

ros2 --help | head -5                # 应该输出 ros2 CLI 用法
# 或
dpkg -l ros-humble-rclcpp | tail -1  # 应该看到已装的 ROS2 humble 版本行
# 或
colcon info --packages-up-to / 2>/dev/null | head -5  # 应该看到本工作空间元数据

常见错误:直接输入 ros2 提示 command not found → 说明你忘了 source。

每次新开终端都要 source 一次。嫌麻烦?把这两行加到容器用户的 ~/.bashrc:

echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
echo "source /root/ros2_ws/install/setup.bash" >> ~/.bashrc  # 这一行要等第 8 步做完才有 install/

8. 编译 12 个 ROS2 包(约 3-5 分钟)

colcon 是 ROS2 的官方编译工具(类似 make 但专为 ROS2 设计)。

方式 A — 推荐:用项目脚本(自带 source ROS2 + 12 包列表)

cd /root/ros2_ws
bash scripts/build.sh

方式 B — 手动( 必先 source ROS2):

cd /root/ros2_ws
source /opt/ros/humble/setup.bash    # ❗ 必先做!否则 C++ 包全挂(找不到 ament_cmake)
colcon build --symlink-install

source 是手动编译的前提:Dockerfile 把 source /opt/ros/humble/setup.bash 写在 ~/.bashrc, 但 docker exec ros2_dev bash -lc 'colcon build' 跑的是非交互 login shell(-l),不读 ~/.bashrc, CMake 会报 Could not find a package configuration file provided by "ament_cmake",所有 C++ 包 Failed。 脚本 scripts/build.sh 内部已 source,所以走方式 A 就不会踩这个坑。

预期输出:一堆 Starting >>> xxxFinished <<< xxx,最后看到:

Summary: 12 packages finished [4 min 32 s]

看到 "12 packages finished" 就成功了。失败的话会有 Failed <<< xxx,先看下方"常见问题"。

9. 加载本项目环境 + 跑测试

方式 A — 推荐:用项目脚本

bash scripts/test.sh

方式 B — 手动:

source install/setup.bash
colcon test

预期输出(成功的话):

Summary: 12 packages finished [3 min 15 s]

怎么确认 100% 通过:

colcon test-result --all

期望看到:

build/<package>/pytest.xml:  PASS
build/<package>/test_results/.../test_*.gtest.xml:  PASS

所有包都 PASS = 全绿。

10. 跑 Hello World(Topic 演示)

Topic 是什么:发布-订阅模式。一个节点(Publisher)发消息,另一个节点(Subscriber)收消息。这是 ROS2 最核心的通信方式。

打开第一个终端(容器内):

方式 A — 推荐:项目脚本(自带 source)

bash scripts/launch.sh pubsub_launch 30
# 第 2 个参数 = 运行时长(秒),空 = 一直跑

方式 B — 手动(跨语言 4 节点 Topic 互通)

source /opt/ros/humble/setup.bash
source /root/ros2_ws/install/setup.bash
ros2 launch bringup pubsub_launch.py

预期输出(每个终端都会一直打印,这是正常的):

[INFO] [launch]: Default logging verbosity is set to INFO
[INFO] [chatter_publisher-1]: process started with pid [2656]
[INFO] [chatter_publisher_cpp-2]: process started with pid [2658]
[INFO] [chatter_subscriber-3]: process started with pid [2660]
[INFO] [chatter_subscriber_cpp-4]: process started with pid [2662]
[chatter_publisher_cpp-2] [INFO] [...]: ChatterPublisher started: rate=2.00 Hz, topic="chatter"
[chatter_subscriber-3]    [INFO] [...]: recv #0: "Hello from PY, seq=0"
[chatter_subscriber_cpp-4] [INFO] [...]: recv #0: "Hello from C++, seq=0"
[chatter_subscriber-3]    [INFO] [...]: recv #1: "Hello from C++, seq=0"   ← 跨语言互通
[chatter_subscriber_cpp-4] [INFO] [...]: recv #1: "Hello from PY, seq=1"   ← 跨语言互通
...

怎么验证 Python ↔ C++ 互通:默认 launch 会同时启动 py + cpp 的 publisher 和 subscriber,你应该看到 4 个节点在互相通信(ros2 topic info /chatter -v 会显示 2 Publisher + 2 Subscription)。

怎么停止:按 Ctrl+C(Linux 终端的"取消运行"快捷键)。Ctrl+C 在 ROS2 节点运行时 = 优雅退出,不会损坏任何东西。

🎉 恭喜!

你已经跑通了 ROS2 的 Hello World。现在你可以:

  1. 继续学:打开下方"学完之后下一步做什么"选下一个包
  2. 玩参数:另开一个终端,输入 docker exec ros2_dev bash -lc "source /opt/ros/humble/setup.bash && source /root/ros2_ws/install/setup.bash && ros2 param set py_publisher publish_rate_hz 5.0",回到第一个终端你会看到消息频率从 1 Hz 变成 5 Hz
  3. 看节点关系图:输入 docker exec ros2_dev bash -lc "rqt_graph"(需要图形界面,详见 doc/85-docker.md)

📖 想看更详细的图文版 + Windows 截图?见 doc/01-quickstart.md(已读过的章节可跳读)。本节内容已覆盖 doc/01-quickstart 的核心流程。


🔧 常见问题(新手必看)

Docker Desktop 没启动

Cannot connect to the Docker daemon at unix:///var/run/docker.sock.

→ 启动 Docker Desktop(任务栏鲸鱼图标),等 30 秒。

容器名 ros2_dev 已存在

Error response from daemon: Conflict. The container name "/ros2_dev" is already in use.

→ 删掉旧容器: docker rm -f ros2_dev,再 docker run ...

ros2 topic info 显示 Publisher count: 4(应该是 2)

原因:bash scripts/launch.sh pubsub_launch forever 或多次调试后,ros2 launch fork 出的 chatter_publisher_* 子进程 reparent 到容器 PID 1,不再随 launch 主进程退出。下次启动 launch 又起 2 个,累计 4 个 Publisher。 解决:

docker exec ros2_dev bash /root/ros2_ws/scripts/clean_ros.sh
# 等价于 pkill -9 -f "ros2 launch" + pkill -9 -f chatter

docker compose up 网络冲突

Network ros2_ros2_net Error Error response from daemon:
invalid pool request: Pool overlaps with other one on this address space
failed to create network ros2_ros2_net

原因:compose project 名 ros2 让网络名前缀成 ros2_ros2_net,但仓库里手动(或上次启动)已经创建了 ros2_net(docker run 方式),子网 172.20.0.0/16 跟 compose 默认 172.20.0.0/24 重叠,daemon 拒绝。 解决 1(推荐):直接走"方式 B — 手动 docker run",绕开 compose:

docker rm -f ros2_dev
docker run -d -it --name ros2_dev -v "$(Get-Location):/root/ros2_ws" --network ros2_net ros2-humble-dev:latest bash

解决 2:先删旧网络再 compose up:

docker rm -f ros2_dev
docker network rm ros2_net
docker compose -p ros2 -f docker/docker-compose.yml up -d

构建超时 / 网络问题

failed to fetch ... context deadline exceeded

→ 重新 docker build -t ros2-humble-dev:latest -f docker/Dockerfile . (会自动重试)

编译失败

Failed <<< py_pubsub [1 min 30 s]

→ 看 build/<package>/ 下的 stdout.logstderr.log。最常见原因:漏装了某个 ROS2 包(ros-humble-xxx)。看错误信息里有没有 Could not find a package configuration file provided by "xxx"

测试失败

1 package had test failures: py_params

→ 看 build/<package>/pytest.xmlbuild/<package>/test_results/.../test_*.gtest.xml。常见原因:漏装 pytest-timeout、cv_bridge、image-transport 等。


📖 这是什么仓库?

一个教学级完全体 ROS2 学习项目,做完了可以直接做具身智能 / VLA 项目。

核心特点:

  • 12 个真实可运行的 ROS2 包,涵盖 ROS2 几乎所有核心机制
  • 82 个测试用例 100% 通过(64 pytest + 14 gtest + 4 launch_test,可运行、可验证、不踩坑)
  • 24 篇深度文档,从 Hello World 到三机部署
  • 跨语言互通(py ↔ cpp),贴近工业真实场景
  • Docker 容器化,Windows / Linux / Mac 都能跑

它不是:ROS2 官方文档翻译、API 速查表、"读完即懂" 的速成文档。


🎯 学完之后你能做什么?

学完本仓库 + 后续 Level 2/3/4 资料,你可以:

  1. 自己设计一个 ROS2 项目(Node / Topic / Service / Action / Parameter / TF / QoS 都会用)
  2. 调试 ROS2 通信问题(查 ros2 topic listros2 node inforqt_graph)
  3. 写自定义 .msg/.srv/.action 接口,跨语言互通
  4. 配置 DDS + 跨机器部署(知道 ROS_DOMAIN_ID / RMW_IMPLEMENTATION)
  5. 在机械臂 / 移动机器人 / VLA 项目里把 ROS2 作为通信底座

📚 12 包推荐学习顺序

不要按字母顺序学。按下面顺序,每个包约 1-3 小时(读 README + 看代码 + 改参数试效果)。

总计预计: 4-6 周(每天 2-3 小时)+ 24 篇深度文档 + 改 12 次代码 + 自己写 1 个 Service。

注:这是 doc/00-levels.md 跟 README 统一后的估算。纯跑通 = 1 天,纯读文档 = 7 天,真学懂 + 自己改 = 4-6 周。

第一梯队:必学(覆盖 80% 日常 ROS2 工作)

顺序 你将学到
1 py_pubsub Topic 发布订阅、节点、launch 文件
2 cpp_pubsub C++ 怎么写 ROS2 节点、跨语言互通
3 py_srv Service 请求-响应(同步 RPC)
4 py_action_demo Action(带进度回调的长任务)

第二梯队:进阶(做项目必备)

顺序 你将学到
5 py_params 参数系统(运行时改配置 + 校验回调)
6 cpp_custom_interface 自定义 .msg/.srv/.action 接口
7 py_vision_demo 图像话题 + cv_bridge + OpenCV
8 cpp_robot_tf2 TF2 坐标变换 + URDF 机械臂模型

第三梯队:深入(做生产级 / 部署级系统)

顺序 你将学到
9 cpp_qos_demo QoS 9 种组合(传输可靠性策略)
10 py_lifecycle_composable Lifecycle(节点生命周期管理)
11 py_overlay_dds DDS 配置 + colcon overlay
12 bringup 跨包 launch 聚合(多节点一键启动)

每个包怎么学(通用流程)

  1. 读包内 README.md(知道这个包做什么、关键概念)
  2. 看代码(先看 src/<包名>/ 下的 .py 或 .cpp,跟着注释读)
  3. 跑起来(ros2 launch <package> <launch.py>)
  4. 改参数试效果(ros2 param set <node> <param> <value>)
  5. 跑测试(colcon test --packages-select <package>)

📖 24 篇文档怎么读?

新手建议顺序:

顺序 文档 何时读
1 doc/01-quickstart.md 已在"从零开始"一节读完(可跳读)
2 doc/00-levels.md 想知道"学完这个下一步学什么"
3 doc/10-concepts.md 概念速查(Node/Topic/...)
4 doc/20-topics.md 深入 Topic
5 doc/30-services.md 深入 Service
6 doc/40-actions.md 深入 Action
7 doc/50-tf2.md 学 TF2 必读
8 doc/60-urdf.md 学 URDF 必读
9 doc/70-launch.md 学 launch 必读
10 doc/80-package-build.md 想自己创建 ROS2 包时读
11 doc/85-docker.md 想改 Docker 配置时读
12 doc/90-testing.md 想给代码加测试时读
13 doc/CODING_STYLE.md 写代码前必读

深度专题(按需读):

部署 / 进阶:


🏗 仓库结构(10 秒看懂)

D:\xs\ros2/                      ← 项目根目录(在这里开终端)
│
├── README.md                    ← 你正在读的文件
├── AGENTS.md                    ← 开发者铁律(写代码 / 调试日志放哪里)
├── Makefile                     ← 命令聚合(make build / make up / make shell 等)
│
├── docker/                      ← Docker 配置(ros2_dev 容器定义)
├── doc/                         ← 24 篇深度文档
├── tools/                       ← 本机 venv 脚本(本机开发工具隔离)
│
└── src/                         ← 12 个 ROS2 包(本仓库核心)
    ├── py_pubsub/               ← Python Topic 演示(最简单,新手必看)
    ├── cpp_pubsub/              ← C++ Topic 演示(跟 py_pubsub 互通)
    ├── py_srv/                  ← Service(请求-响应)
    ├── py_action_demo/          ← Action(带进度反馈的长任务)
    ├── cpp_robot_tf2/           ← TF2 坐标变换 + URDF 机械臂
    ├── py_vision_demo/          ← 图像(模拟相机 + OpenCV 处理)
    ├── py_params/               ← 参数系统(运行时改配置)
    ├── cpp_custom_interface/    ← 自定义 .msg/.srv/.action
    ├── py_lifecycle_composable/ ← Lifecycle Node
    ├── cpp_qos_demo/            ← QoS 9 种组合
    ├── py_overlay_dds/          ← DDS 配置 + 多机部署
    └── bringup/                 ← 跨包 launch 聚合(启动多个包)

新手第一天只需要打开: src/py_pubsub/README.mdsrc/py_pubsub/py_pubsub/publisher_node.py


🔧 容器内常用命令速查

进入容器:

# PowerShell(宿主机)
docker exec -it ros2_dev bash

容器内(Linux bash):

source /opt/ros/humble/setup.bash        # 加载 ROS2 环境(每次新终端都要)
source /root/ros2_ws/install/setup.bash   # 加载本项目编译产物(同上)

ros2 run <package> <executable>           # 跑节点,例:ros2 run py_pubsub chatter_publisher
ros2 launch <package> <launch.py>         # 跑 launch 文件
ros2 topic list                           # 列出所有话题
ros2 topic echo /chatter                  # 订阅看消息(按 Ctrl+C 退出)
ros2 node list                            # 列出所有节点
ros2 node info <node_name>                # 看某个节点的详细信息(话题/服务/参数)
ros2 param list <node_name>               # 看节点参数
ros2 param set <node> <param> <value>     # 改参数(运行时,例:ros2 param set py_publisher publish_rate_hz 5.0)
ros2 service list                         # 列出所有服务
ros2 service call <service_name> <req>    # 手动调用服务
ros2 action list                          # 列出所有 Action
ros2 bag record -a -o my_bag              # 录制所有话题数据
ros2 bag play my_bag                      # 回放数据

退出容器:exitCtrl+D容器还在跑,下次直接 docker exec -it ros2_dev bash 再进。

停容器:

docker stop ros2_dev       # 停止(不删除,下次 docker start)
docker rm -f ros2_dev      # 删除(下次要从头 docker run)

L1 基础完成清单(打勾用)

每学完一个包,把 [ ] 改成 [x],4 个维度独立勾:

[ ] py_pubsub       — 跑通 / 改过参数 / 改过代码 / 测过测试
[ ] cpp_pubsub      — 跑通 / 改过参数 / 改过代码 / 测过测试
[ ] py_srv          — 跑通 / 改过参数 / 改过代码 / 测过测试
[ ] py_action_demo  — 跑通 / 改过参数 / 改过代码 / 测过测试
[ ] py_params       — 跑通 / 改过参数 / 改过代码 / 测过测试
[ ] cpp_custom_interface — 跑通 / 改过参数 / 改过代码 / 测过测试
[ ] py_vision_demo  — 跑通 / 改过参数 / 改过代码 / 测过测试
[ ] cpp_robot_tf2   — 跑通 / 改过参数 / 改过代码 / 测过测试
[ ] cpp_qos_demo    — 跑通 / 改过参数 / 改过代码 / 测过测试
[ ] py_lifecycle_composable — 跑通 / 改过参数 / 改过代码 / 测过测试
[ ] py_overlay_dds  — 跑通 / 改过参数 / 改过代码 / 测过测试
[ ] bringup         — 跑通 / 改过参数 / 改过代码 / 测过测试

判定 "L1 完成": 12 × 4 = 48 个勾 ≥ 36 个(75%)。


🗺 学完之后下一步做什么?

阶段 内容 学完后能
L1 基础(本仓库) 12 包 + 78 测试 + 23 文档 自己设计 ROS2 项目
➡️ L2 进阶 ros2_control + MoveIt2 + Gazebo 仿真 控制真实机械臂 / 用仿真调参
➡️ L3 真实机器人 xArm / UR / Franka 驱动 上工业机械臂
➡️ L4 具身智能 / VLA OpenVLA / π0 / RKNN NPU 推理 让机器人理解自然语言指令

详见 doc/99-embodied-ai.mddoc/00-levels.md


📖 术语速查(给完全零基础的新手)

术语 一句话解释 生活化例子
Node(节点) 一个独立的运行程序(进程) 像手机里的每个 App
Topic(话题) 节点之间传递消息的"频道"(单向) 像广播电台,谁都可以订阅
Service(服务) 节点之间的"一问一答"调用(双向) 像打电话,问完必须等回答
Action(动作) 节点之间"长任务"调用,带进度回调 像外卖下单,可以取消 + 实时看进度
Parameter(参数) 节点的"配置项",可以运行时改 像手机设置里的开关
TF(坐标变换) 跟踪机器人各部件的空间位置关系 像人知道"我的手在身体左前方 30cm"
URDF 机器人的 3D 模型描述(关节 + 连杆) 像机器人的"骨骼图纸"
QoS 消息传输的"质量策略"(可靠 vs 实时) 像快递:顺丰可靠 vs 同城闪送快
Lifecycle 节点的"生命周期"管理(初始化 → 运行 → 关闭) 像手机 App 的启动 → 后台 → 退出
DDS 节点之间真正"传消息"的底层协议 像快递公司,Topic 是地址,DDS 是车
Launch 文件 一次性启动多个节点的"剧本" 像一键启动所有 App
Package(包) 一个独立的 ROS2 项目单元(代码 + 配置 + 依赖) 像 npm 包 / pip 包
colcon ROS2 官方编译工具(类似 make) 像 make,但专为 ROS2 设计
ROS_DOMAIN_ID 节点的"网络分组"(0-232),不同 ID 的节点互不可见 像不同的 WiFi 频道

🤝 致谢


📜 项目元信息

文件 是什么 你要读吗
CHANGELOG.md 每次发布改了什么 想看版本历史 / 发版时
CONTRIBUTING.md 怎么贡献代码(PR 流程) 只在你打算提 PR 时读
LICENSE MIT 协议 想二次发布时读
pyproject.toml PEP 621 包元数据 想 IDE 配置时
AGENTS.md 开发者铁律(给 AI Agent 看的) 不要读,这是给 AI 写代码时的规则
scripts/ 容器内常用命令脚本(build/test/launch/clean/shell/e2e) 推荐用
.docs/bug_logs/ 入门文档 bug 审计 + 修复历史 复盘 / 找历史坑时

下一步 → 跑通上面的"从零开始:30 分钟跑通 Hello World",然后选 第一梯队第 1 个包 py_pubsub 开始学。

S
Description
No description provided
Readme MIT 988 KiB
Languages
Python 63.2%
C++ 22.3%
Shell 5.2%
CMake 4.5%
Makefile 2.2%
Other 2.6%