548 lines
22 KiB
Markdown
548 lines
22 KiB
Markdown
# ROS2 学习套件 — 从零到具身智能 / VLA 完全体
|
||
|
||
> **如果你是 ROS2 完全的新手,不知道怎么开始 → [从零开始指南](#-从零开始-30-分钟跑通-hello-world)**
|
||
|
||
---
|
||
|
||
## 🆘 从零开始: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` → 回车),输入:
|
||
|
||
```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 克隆**
|
||
```powershell
|
||
cd D:\xs
|
||
git clone <仓库地址> ros2
|
||
cd D:\xs\ros2
|
||
```
|
||
|
||
**方式 B:下载 ZIP 解压**
|
||
|
||
把仓库下载下来,解压到任意位置。**真正的项目根目录是包含 `README.md` 和 `Makefile` 的那一层**,不是上层目录(里面还有 `src/`、`doc/`、`docker/` 这些子目录的)。
|
||
|
||
确认你在项目根目录:
|
||
```powershell
|
||
Get-ChildItem # 应该看到 AGENTS.md CHANGELOG.md docker doc Makefile README.md src
|
||
```
|
||
|
||
### 3. 打开 PowerShell 在项目根目录
|
||
|
||
**重要**:本节所有命令都在 **Windows PowerShell**(宿主机)执行,不是容器内。后面会有专门一节讲容器内命令。
|
||
|
||
```powershell
|
||
cd D:\xs\ros2
|
||
```
|
||
|
||
### 4. 构建 Docker 镜像(首次约 5-10 分钟)
|
||
|
||
**镜像是什么**:打包好的 Linux + ROS2 + 工具链的"操作系统模板"。本仓库基于 `osrf/ros:humble-desktop` 构建。
|
||
|
||
```powershell
|
||
docker build -t ros2-humble-dev:latest -f docker/Dockerfile .
|
||
```
|
||
|
||
**预期输出**:看到一长串 `---> Running in xxx`、`Successfully built xxx`(看不到具体行数是正常的,只看最后 `Successfully tagged ros2-humble-dev:latest`)。
|
||
|
||
**下载量**:首次约 3-5 GB(基础镜像 + 工具)。
|
||
|
||
### 5. 启动容器
|
||
|
||
容器 = 用镜像启动的"Linux 虚拟机实例"。本仓库的容器名是 `ros2_dev`。
|
||
|
||
**方式 A — 推荐(走 docker compose,跟 Makefile 等价)**
|
||
```powershell
|
||
docker compose -p ros2 -f docker/docker-compose.yml up -d
|
||
```
|
||
|
||
**方式 B — 手动 docker run**(等价;注意末尾的 `bash` 用来保活,**重要** ❗)
|
||
|
||
```powershell
|
||
docker run -d -it --name ros2_dev `
|
||
-v "${PWD}:/root/ros2_ws" `
|
||
--network ros2_net `
|
||
ros2-humble-dev:latest bash
|
||
```
|
||
|
||
> ❗ **一定要带末尾的 `bash`**: 否则容器启动后立刻 `Exited (0)`,因为基础镜像默认 ENTRYPOINT 跑 bash,无 tty 时立刻退出。
|
||
|
||
**预期输出**:一串 hash(容器 ID),没有报错就行。
|
||
|
||
**验证容器跑起来了**:
|
||
```powershell
|
||
docker ps
|
||
```
|
||
应该看到 `ros2_dev` 在列表里,`STATUS` 列显示 `Up`。
|
||
|
||
### 6. 进入容器(看到 root@xxx 就是成功了)
|
||
|
||
```powershell
|
||
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 就找不到 `ros2`、`colcon` 这些命令。
|
||
|
||
```bash
|
||
source /opt/ros/humble/setup.bash
|
||
```
|
||
|
||
**预期效果**:没有报错 = OK。
|
||
|
||
**怎么验证**:
|
||
```bash
|
||
ros2 --help | head -5 # 应该输出 ros2 CLI 用法
|
||
# 或
|
||
dpkg -l ros-humble-rclcpp | tail -1 # 应该看到已装的 ROS2 humble 版本行
|
||
```
|
||
|
||
**常见错误**:直接输入 `ros2` 提示 `command not found` → 说明你忘了 source。
|
||
|
||
**每次新开终端都要 source 一次**。嫌麻烦?把这两行加到容器用户的 `~/.bashrc`:
|
||
|
||
```bash
|
||
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 包列表)
|
||
```bash
|
||
cd /root/ros2_ws
|
||
bash scripts/build.sh
|
||
```
|
||
|
||
**方式 B — 手动**:
|
||
```bash
|
||
cd /root/ros2_ws
|
||
colcon build --symlink-install
|
||
```
|
||
|
||
**预期输出**:一堆 `Starting >>> xxx`、`Finished <<< xxx`,最后看到:
|
||
|
||
```
|
||
Summary: 12 packages finished [4 min 32 s]
|
||
```
|
||
|
||
**看到 "12 packages finished" 就成功了**。失败的话会有 `Failed <<< xxx`,先看下方"常见问题"。
|
||
|
||
### 9. 加载本项目环境 + 跑测试
|
||
|
||
**方式 A — 推荐**:用项目脚本
|
||
```bash
|
||
bash scripts/test.sh
|
||
```
|
||
|
||
**方式 B — 手动**:
|
||
```bash
|
||
source install/setup.bash
|
||
colcon test
|
||
```
|
||
|
||
**预期输出**(成功的话):
|
||
```
|
||
Summary: 12 packages finished [3 min 15 s]
|
||
```
|
||
|
||
**怎么确认 100% 通过**:
|
||
|
||
```bash
|
||
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
|
||
bash scripts/launch.sh pubsub_launch 30
|
||
# 第 2 个参数 = 运行时长(秒),空 = 一直跑
|
||
```
|
||
|
||
**方式 B — 手动**(跨语言 4 节点 Topic 互通)
|
||
```bash
|
||
source /opt/ros/humble/setup.bash
|
||
source /root/ros2_ws/install/setup.bash
|
||
ros2 launch bringup pubsub_launch.py
|
||
```
|
||
|
||
**预期输出**(每个终端都会一直打印,这是正常的):
|
||
```
|
||
[INFO] [py_publisher]: Publishing: "Hello World: 0"
|
||
[INFO] [py_publisher]: Publishing: "Hello World: 1"
|
||
...
|
||
[INFO] [chatter_listener]: I heard: Hello World: 0
|
||
...
|
||
```
|
||
|
||
**怎么验证 Python ↔ C++ 互通**:默认 launch 会同时启动 py + cpp 的 publisher 和 subscriber,你应该看到 4 个节点在互相通信。
|
||
|
||
**怎么停止**:按 `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.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 ...`
|
||
|
||
### ❌ 构建超时 / 网络问题
|
||
```
|
||
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.log` 或 `stderr.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.xml` 或 `build/<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 list`、`ros2 node info`、`rqt_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`](src/py_pubsub/README.md) | Topic 发布订阅、节点、launch 文件 |
|
||
| 2 | [`cpp_pubsub`](src/cpp_pubsub/README.md) | C++ 怎么写 ROS2 节点、跨语言互通 |
|
||
| 3 | [`py_srv`](src/py_srv/README.md) | Service 请求-响应(同步 RPC) |
|
||
| 4 | [`py_action_demo`](src/py_action_demo/README.md) | Action(带进度回调的长任务) |
|
||
|
||
### 第二梯队:进阶(做项目必备)
|
||
|
||
| 顺序 | 包 | 你将学到 |
|
||
|---|---|---|
|
||
| 5 | [`py_params`](src/py_params/README.md) | 参数系统(运行时改配置 + 校验回调) |
|
||
| 6 | [`cpp_custom_interface`](src/cpp_custom_interface/README.md) | 自定义 .msg/.srv/.action 接口 |
|
||
| 7 | [`py_vision_demo`](src/py_vision_demo/README.md) | 图像话题 + cv_bridge + OpenCV |
|
||
| 8 | [`cpp_robot_tf2`](src/cpp_robot_tf2/README.md) | TF2 坐标变换 + URDF 机械臂模型 |
|
||
|
||
### 第三梯队:深入(做生产级 / 部署级系统)
|
||
|
||
| 顺序 | 包 | 你将学到 |
|
||
|---|---|---|
|
||
| 9 | [`cpp_qos_demo`](src/cpp_qos_demo/README.md) | QoS 9 种组合(传输可靠性策略) |
|
||
| 10 | [`py_lifecycle_composable`](src/py_lifecycle_composable/README.md) | Lifecycle(节点生命周期管理) |
|
||
| 11 | [`py_overlay_dds`](src/py_overlay_dds/README.md) | DDS 配置 + colcon overlay |
|
||
| 12 | [`bringup`](src/bringup/README.md) | 跨包 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](doc/01-quickstart.md) | 已在"从零开始"一节读完(可跳读) |
|
||
| 2 | [doc/00-levels.md](doc/00-levels.md) | 想知道"学完这个下一步学什么" |
|
||
| 3 | [doc/10-concepts.md](doc/10-concepts.md) | 概念速查(Node/Topic/...) |
|
||
| 4 | [doc/20-topics.md](doc/20-topics.md) | 深入 Topic |
|
||
| 5 | [doc/30-services.md](doc/30-services.md) | 深入 Service |
|
||
| 6 | [doc/40-actions.md](doc/40-actions.md) | 深入 Action |
|
||
| 7 | [doc/50-tf2.md](doc/50-tf2.md) | 学 TF2 必读 |
|
||
| 8 | [doc/60-urdf.md](doc/60-urdf.md) | 学 URDF 必读 |
|
||
| 9 | [doc/70-launch.md](doc/70-launch.md) | 学 launch 必读 |
|
||
| 10 | [doc/80-package-build.md](doc/80-package-build.md) | 想自己创建 ROS2 包时读 |
|
||
| 11 | [doc/85-docker.md](doc/85-docker.md) | 想改 Docker 配置时读 |
|
||
| 12 | [doc/90-testing.md](doc/90-testing.md) | 想给代码加测试时读 |
|
||
| 13 | [doc/CODING_STYLE.md](doc/CODING_STYLE.md) | **写代码前必读** |
|
||
|
||
深度专题(按需读):
|
||
- [doc/15-params.md](doc/15-params.md) — 参数系统
|
||
- [doc/16-custom-interfaces.md](doc/16-custom-interfaces.md) — 自定义接口
|
||
- [doc/17-lifecycle.md](doc/17-lifecycle.md) — Lifecycle Node
|
||
- [doc/18-composable.md](doc/18-composable.md) — Composable Node
|
||
- [doc/19-qos.md](doc/19-qos.md) — QoS
|
||
- [doc/20-bag.md](doc/20-bag.md) — ros2 bag 数据记录
|
||
- [doc/21-overlay-dds.md](doc/21-overlay-dds.md) — DDS 配置
|
||
|
||
部署 / 进阶:
|
||
- [doc/00-overview.md](doc/00-overview.md) — 项目架构 + 设计取舍
|
||
- [doc/02-virtualenv.md](doc/02-virtualenv.md) — 本机 venv 工作流
|
||
- [doc/99-embodied-ai.md](doc/99-embodied-ai.md) — 具身智能 / VLA 路线图
|
||
- [doc/100-embedded-deployment.md](doc/100-embedded-deployment.md) — 三机部署(PC + RDK X5 + RK3506)
|
||
|
||
---
|
||
|
||
## 🏗 仓库结构(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.md` 和 `src/py_pubsub/py_pubsub/publisher_node.py`。
|
||
|
||
---
|
||
|
||
## 🔧 容器内常用命令速查
|
||
|
||
**进入容器**:
|
||
```powershell
|
||
# PowerShell(宿主机)
|
||
docker exec -it ros2_dev bash
|
||
```
|
||
|
||
**容器内**(Linux bash):
|
||
|
||
```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 # 回放数据
|
||
```
|
||
|
||
**退出容器**:`exit` 或 `Ctrl+D`。**容器还在跑,下次直接 `docker exec -it ros2_dev bash` 再进。**
|
||
|
||
**停容器**:
|
||
```powershell
|
||
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.md](doc/99-embodied-ai.md) 和 [doc/00-levels.md](doc/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 频道 |
|
||
|
||
---
|
||
|
||
## 🤝 致谢
|
||
|
||
- [ROS2 官方文档](https://docs.ros.org/en/humble/)
|
||
- [REP-2000: ROS 2 Design](https://www.ros.org/reps/rep-2002.html)
|
||
- [OSRF](https://www.openrobotics.org/) `osrf/ros:humble-desktop` 镜像
|
||
|
||
---
|
||
|
||
## 📜 项目元信息
|
||
|
||
| 文件 | 是什么 | 你要读吗 |
|
||
|---|---|---|
|
||
| [`CHANGELOG.md`](CHANGELOG.md) | 每次发布改了什么 | 想看版本历史 / 发版时 |
|
||
| [`CONTRIBUTING.md`](CONTRIBUTING.md) | 怎么贡献代码(PR 流程) | **只在你打算提 PR 时读** |
|
||
| [`LICENSE`](LICENSE) | MIT 协议 | 想二次发布时读 |
|
||
| [`pyproject.toml`](pyproject.toml) | PEP 621 包元数据 | 想 IDE 配置时 |
|
||
| [`AGENTS.md`](AGENTS.md) | 开发者铁律(给 AI Agent 看的) | **不要读**,这是给 AI 写代码时的规则 |
|
||
| [`scripts/`](scripts/README.md) | 容器内常用命令脚本(build/test/launch/clean/shell/e2e) | 推荐用 |
|
||
| [`.docs/bug_logs/`](.docs/bug_logs/2026-08-04_quickstart_audit.md) | 入门文档 bug 审计 + 修复历史 | 复盘 / 找历史坑时 |
|
||
|
||
---
|
||
|
||
**下一步** → 跑通上面的"从零开始:30 分钟跑通 Hello World",然后选 [第一梯队第 1 个包 py_pubsub](src/py_pubsub/README.md) 开始学。 |