# Level 1 ~ Level 4 全方位 ROS2 学习路线图

> **目标读者**: 想从零学到能用 ROS2 + 机械臂 + VLA (Vision-Language-Action) 做真实具身智能系统的开发者。
>
> **学习承诺**: 本仓库把 ROS2 从基础到 VLA 部署分成 4 级,每级有可运行的代码包 + 教科书级别文档 + 自动化测试。
>
> **预计总时长**: 每天 2-3 小时,Level 1 约 4-6 周,Level 2 约 6-8 周,Level 3 约 8-12 周,Level 4 持续学习。

---

## 目录

- [学习哲学](#学习哲学)
- [Level 1: ROS2 基础机制 (Foundation)](#level-1-ros2-基础机制-foundation)
- [Level 2: 仿真 + 工具链 (Simulation & Tooling)](#level-2-仿真--工具链-simulation--tooling)
- [Level 3: 机械臂实战 (Real Robot)](#level-3-机械臂实战-real-robot)
- [Level 4: 具身智能 VLA (Embodied AI)](#level-4-具身智能-vla-embodied-ai)
- [硬件清单](#硬件清单)
- [时间估算](#时间估算)
- [推荐阅读 + 引用](#推荐阅读--引用)

---

## 学习哲学

### 三条铁律

1. **跑通 > 读完** — 每学一个机制,先在仓库里跑通最小 demo,再读设计文档。
2. **测一次 > 看一次** — 每个包都带 pytest/gtest,跑通测试比"看懂了"更可信。
3. **文档带引用** — 每篇深度文档末尾都列 ROS2 官方文档 + 设计稿链接 + DDS 规范 + 论文。

### 设计思想: 双层解耦

- **本机 venv** — 开发工具链(ruff/black/mypy/pytest),不污染系统 Python,只装 IDE / 编辑器需要的。
- **Docker 容器** — ROS2 运行时(`osrf/ros:humble-desktop`),跨 Win/macOS/Linux 一致,apt 装 ROS2 包。

理由: ROS2 原生依赖大量 C++ 库(DDS / FastRTPS / Cyclone / MoveIt2),在 Windows 本机 pip 装 rclpy 经常飘红。容器化后,所有人跑同一镜像,问题统一在镜像里修复。

### 设计思想: 教科书写法

每篇文档**不重复 ROS2 官方教程**,而是:

1. **讲什么 (What)** — 这个机制解决什么问题。
2. **为什么 (Why)** — 为什么 ROS2 这样设计,设计稿原文引用。
3. **怎么用 (How)** — API 列表 + 最小可运行示例。
4. **怎么测 (Test)** — 单元测试 + 集成测试代码。
5. **怎么错 (Pitfalls)** — 踩过的坑 + 故障排查表。
6. **学什么 (Next)** — 进阶阅读 + 相关论文。

---

## Level 1: ROS2 基础机制 (Foundation)

> **核心目标**: 完整理解 ROS2 的 15 大基础机制,能独立写节点 + launch 文件 + 自定义接口 + 生命周期管理。

### 15 大机制清单

| # | 机制 | 当前包 | 文档 |
|---|---|---|---|
| 1 | 节点 (Node) | `py_pubsub` / `cpp_pubsub` | `10-concepts.md` |
| 2 | Topic (发布订阅) | `py_pubsub` / `cpp_pubsub` | `20-topics.md` |
| 3 | Service (请求响应) | `py_srv` | `30-services.md` |
| 4 | Action (目标-反馈-结果) | `py_action_demo` | `40-actions.md` |
| 5 | TF2 (坐标变换) | `cpp_robot_tf2` | `50-tf2.md` |
| 6 | URDF (机器人模型) | `cpp_robot_tf2` | `60-urdf.md` |
| 7 | Launch (启动编排) | `bringup` | `70-launch.md` |
| 8 | 参数 (Parameter) | `py_params` ⭐新增 | `15-params.md` ⭐新增 |
| 9 | 自定义接口 (.msg/.srv/.action) | `cpp_custom_interface` ⭐新增 | `16-custom-interfaces.md` ⭐新增 |
| 10 | 生命周期 (Lifecycle Node) | `py_lifecycle_composable` ⭐新增 | `17-lifecycle.md` ⭐新增 |
| 11 | 组合节点 (Composable Node) | `py_lifecycle_composable` ⭐新增 | `18-composable.md` ⭐新增 |
| 12 | QoS (服务质量) | `cpp_qos_demo` ⭐新增 | `19-qos.md` ⭐新增 |
| 13 | ros2 bag (录制回放) | `cpp_qos_demo` ⭐新增 | `20-bag.md` ⭐新增 |
| 14 | colcon overlay (混合工作空间) | `py_overlay_dds` ⭐新增 | `21-overlay-dds.md` ⭐新增 |
| 15 | DDS / RMW (中间件配置) | `py_overlay_dds` ⭐新增 | `21-overlay-dds.md` ⭐新增 |

⭐新增 = Level 1 完成补齐的 5 个包 + 7 篇文档。

### Level 1 子目标

- ✅ 能独立写发布者、订阅者、服务器、客户端、Action server、Action client。
- ✅ 能用 TF2 监听 / 广播坐标变换,理解 `lookupTransform` vs `buffer.lookup_transform_async`。
- ✅ 能写简单 URDF,理解 `<link>` / `<joint>` / `<inertial>` / `<visual>` / `<collision>`。
- ✅ 能写 Python launch 文件,理解 `Node` / `IncludeLaunchDescription` / `LaunchConfiguration` / `PathJoinSubstitution`。
- ⭐ **新增** 能声明参数、读参数、参数变化回调、从 YAML 加载。
- ⭐ **新增** 能自定义 .msg / .srv / .action 并在节点里使用。
- ⭐ **新增** 能用 Lifecycle Node 管理节点状态(configure / activate / cleanup / shutdown)。
- ⭐ **新增** 能用 Composable Node 把多个节点装到一个进程。
- ⭐ **新增** 能配置 QoS(Reliability / Durability / History / Depth / Deadline / Lifeliness)。
- ⭐ **新增** 能用 `ros2 bag` 录制 / 回放 / 信息查询。
- ⭐ **新增** 能用 `colcon build --packages-up-to` 做混合工作空间。
- ⭐ **新增** 能配 domain ID / static peers / QoS XML,理解 DDS 中间件。

### Level 1 测试覆盖

```
py_pubsub              11 pytest   ✅
cpp_pubsub             3 gtest    ✅
py_srv                 7 pytest   ✅
py_action_demo         5 pytest   ✅
cpp_robot_tf2          4 gtest    ✅
py_vision_demo         13 pytest  ✅
bringup                (launch 聚合,无单测)
py_params              16 pytest  ⭐(新增)
cpp_custom_interface   3 gtest    ⭐(新增)
py_lifecycle_composable 6 pytest  ⭐(新增)
cpp_qos_demo           4 gtest    ⭐(新增)
py_overlay_dds         6 pytest   ⭐(新增)

总计: **82 用例**(pytest 64 + gtest 14 + launch_test 4),目标 100% 通过

> 注:82 用例是当前仓库实测数(`colcon test` 结果),与 README/AGENTS 一致。
>    上述表格列是"实测用例数"(非"测试文件数")。
>    拆分:pytest=11+7+5+13+16+6+6=64,gtest=3+4+3+4=14,launch_test=1+1+1+1=4。
```

---

## Level 2: 仿真 + 工具链 (Simulation & Tooling)

> **核心目标**: 用 MoveIt2 + Nav2 + Gazebo 把 Level 1 的基础机制用在真实仿真机器人上,学会调试 / 监控 / 测试金字塔。

### Level 2 计划包(下一阶段)

| 包 | 主题 | 关键概念 |
|---|---|---|
| `moveit2_demo` | MoveIt2 机械臂运动规划 | SRDF / PlanningScene / OMPL / CartesianPath |
| `nav2_demo` | Nav2 移动底盘导航 | Costmap / BT / SLAM / Recovery Behavior |
| `gazebo_sim` | Gazebo 仿真器集成 | SDF / Plugins / Sensors / ros2_control |
| `ros2_controllers` | ros2_control 控制器 | JointTrajectoryController / GripperController / DiffDriveController |
| `ros2_test_demo` | 测试金字塔 | launch_testing / pytest fixtures / gtest mock |

### Level 2 文档

- `22-moveit2.md` — MoveIt2 概念 + 编程 API + 调试技巧
- `23-nav2.md` — Nav2 概念 + 配置 + 行为树
- `24-gazebo.md` — Gazebo Harmonic 集成
- `25-ros2-control.md` — ros2_control 硬件抽象
- `26-testing-pyramid.md` — 单元 / 集成 / E2E 测试策略

### Level 2 子目标

- ✅ 能用 MoveIt2 给 6 自由度机械臂做运动规划。
- ✅ 能用 Nav2 给移动底盘做 SLAM + 路径规划。
- ✅ 能在 Gazebo 里仿真传感器(Lidar / Camera / IMU)。
- ✅ 理解 ros2_control 硬件抽象层。
- ✅ 写完整的测试金字塔: 单元 (60%) + 集成 (30%) + E2E (10%)。

### 推荐硬件(仿真阶段无需)

仿真阶段**不需要任何硬件**。Gazebo + RViz 足够。

---

## Level 3: 机械臂实战 (Real Robot)

> **核心目标**: 把仿真代码搬到真机,做手眼标定 + 视觉抓取 + 力控,实现"看得见、抓得起、放得稳"。

### Level 3 计划包(中后期)

| 包 | 主题 | 关键概念 |
|---|---|---|
| `arm_hardware` | 真实机械臂驱动 | UR5e / xArm / Franka / Realman 驱动 |
| `arm_calibration` | 手眼标定 | Eye-in-Hand / Eye-to-Hand / Tsai-Lenz / Park |
| `arm_perception` | 视觉感知 | RGB-D / 点云 / 6D 位姿 / GraspNet |
| `arm_grasp` | 抓取规划 | 6-DoF Grasp / suction / parallel jaw |
| `arm_trajectory` | 轨迹优化 | 时间最优 / 能量最优 / STOMP / CHOMP |
| `arm_force` | 力控 | impedance / admittance / hybrid position-force |

### Level 3 文档

- `27-arm-drivers.md` — 主流机械臂驱动对比 + 选型
- `28-hand-eye-calib.md` — 手眼标定原理 + 实践
- `29-6d-pose.md` — 6D 位姿估计(FoundationPose / GraspNet)
- `30-grasp-planning.md` — 抓取规划算法
- `31-force-control.md` — 力控原理 + 实践

### Level 3 推荐硬件(最低配置)

| 设备 | 型号 | 预算 |
|---|---|---|
| 机械臂 | xArm6 / UR5e / Realman RM75 | ¥15,000-50,000 |
| 夹爪 | 大寰 DH-3 / Robotiq 2F-85 | ¥3,000-8,000 |
| RGB-D 相机 | Intel RealSense D435 / Orbbec Gemini 2 | ¥1,500-3,000 |
| 标定板 | A4 ArUco 6×6 | ¥50 |
| 工控机 | NUC / RDK X5 | ¥3,000-5,000 |

总计: ¥25,000-70,000(可选配)

### Level 3 子目标

- ✅ 能驱动真实机械臂做点到点运动 + 直线运动。
- ✅ 做完手眼标定,误差 < 2mm。
- ✅ 视觉检测物体 6D 位姿,精度 < 5mm / 5°。
- ✅ 抓取成功率 > 80% (已知物体集)。
- ✅ 力控下能完成插孔 / 装配任务。

---

## Level 4: 具身智能 VLA (Embodied AI)

> **核心目标**: 用大模型(LLM / VLM)让机器人理解自然语言指令,自主决策动作序列,完成开放域任务。

### Level 4 计划包(终极目标)

| 包 | 主题 | 关键概念 |
|---|---|---|
| `vla_data` | 数据采集 + 处理 | DROID / Open X-Embodiment / RT-1 数据格式 |
| `vla_model` | VLA 模型 | OpenVLA / π0 / RT-2 / RoboFlamingo |
| `vla_inference` | 推理优化 | RKNN / TensorRT / ONNX / 量化 |
| `vla_deployment` | 端到端部署 | PC + RDK X5 + RK3506 三机协同 |

### Level 4 文档

- `32-vla-intro.md` — VLA 概念 + 主流模型对比
- `33-vla-training.md` — VLA 模型微调 + 数据工程
- `34-vla-inference.md` — 边缘推理 + NPU 加速
- `35-vla-deployment.md` — 真机部署 + 三机协同

### Level 4 关键论文(引用)

1. **RT-2** — Google DeepMind, 2023, "RT-2: Vision-Language-Action Models Transfer Web Knowledge to Robotic Control"
2. **OpenVLA** — Stanford / UC Berkeley / Toyota Research, 2024, "OpenVLA: An Open-Source Vision-Language-Action Model"
3. **π0** — Physical Intelligence, 2024, "π0: A Foundation Model for Robots"
4. **DROID** Stanford, 2024, "DROID: A Large-Scale In-the-Wild Robot Manipulation Dataset"
5. **Open X-Embodiment** — Google DeepMind et al., 2023, "Scaling Up Learning Across Many Different Robot Types"

### Level 4 子目标

- ✅ 能用 OpenVLA / π0 完成"把红杯子放到桌子左边"这类指令。
- ✅ 能用 RDK X5 NPU (5 TOPS) 跑 VLA 推理,延迟 < 500ms。
- ✅ 三机协同: PC 跑大模型 / RDK X5 跑感知 / RK3506 跑实时控制。
- ✅ 在真实机械臂上完成 10+ 类自然语言指令。

### Level 4 终极硬件配置

| 设备 | 角色 | 关键算力 |
|---|---|---|
| PC (RTX 4090) | 训练 + 大模型推理 | 100+ TOPS |
| RDK X5 | 边缘 VLA 推理 | 5 TOPS NPU |
| RK3506 ×2 | 实时控制 + 通讯 | 3 核 ARM + 512MB RAM |

---

## 硬件清单(汇总)

| 阶段 | 设备 | 必需 / 可选 |
|---|---|---|
| L1 | PC + Docker | 必需 |
| L2 | PC + Docker | 必需 |
| L3 | PC + xArm + RealSense + 标定板 | 必需 |
| L3 进阶 | + 夹爪 + 工装 | 可选 |
| L4 | PC (RTX 4090) + RDK X5 + RK3506 ×2 + xArm | 必需 |

---

## 时间估算

| Level | 学习时长(每天 2-3 小时) | 关键里程碑 |
|---|---|---|
| L1 | 4-6 周 | 写自定义接口 + Lifecycle Node |
| L2 | 6-8 周 | MoveIt2 给真臂规划 + Gazebo 仿真 |
| L3 | 8-12 周 | 手眼标定 + 视觉抓取 + 力控 |
| L4 | 12+ 周 | VLA 真机部署 |

总计: **6-9 个月** 从零到 VLA 真机部署。

---

## 推荐阅读 + 引用

### ROS2 官方文档(权威)

- [ROS2 Humble 官方文档](https://docs.ros.org/en/humble/index.html)
- [ROS2 设计稿 (design.ros2.org)](https://design.ros2.org/) — 必读,讲解为什么这样设计
- [ROS2 Concepts](https://docs.ros.org/en/humble/Concepts.html) — 概念总览
- [ROS2 Tutorials](https://docs.ros.org/en/humble/Tutorials.html) — 入门教程
- [ROS2 QoS 文档](https://docs.ros.org/en/humble/Concepts/About-Quality-of-Service.html)
- [ROS2 Lifecycle Node](https://design.ros2.org/articles/node_lifecycle.html)
- [ROS2 Composable Node](https://docs.ros.org/en/humble/Concepts/About-Composition.html)
- [ROS2 Launch](https://docs.ros.org/en/humble/Tutorials/Launch-system.html)

### DDS 规范

- [OMG DDS 规范 v1.4](https://www.omg.org/spec/DDS/1.4/) — QoS 源头
- [FastRTPS 文档](https://fast-rtps.docs.eprosima.com/) — 默认 RMW
- [Cyclone DDS 文档](https://cyclonedds.io/docs/) — 备选 RMW

### 机器人学

- [Probabilistic Robotics (Thrun et al.)](http://www.probabilistic-robotics.org/) — SLAM 基础
- [Modern Robotics (Lynch & Park)](https://hades.mech.northwestern.edu/index.php/Modern_Robotics.html) — 运动学 / 动力学

### 具身智能 / VLA

- [RT-2 论文](https://arxiv.org/abs/2307.15818)
- [OpenVLA 论文](https://arxiv.org/abs/2406.09246)
- [π0 论文](https://arxiv.org/abs/2410.24164)
- [DROID 数据集](https://droid-dataset.github.io/)
- [Open X-Embodiment 数据集](https://robotics-transformer-x.github.io/)

---

## 学习方法建议

### 每日节奏(2-3 小时)

```
30 min: 读本级文档(理解概念)
60 min: 跑包内 demo(动手验证)
30 min: 改 demo 试错(巩固)
30 min: 写学习笔记(记录坑点)
30 min: 复习 + 下一节
```

### 提问技巧

学 ROS2 时遇到问题,优先:
1. 看本仓库对应文档末尾"故障排查"表
2. 看 ROS2 官方文档对应章节
3. `ros2 doctor` 输出
4. `rclpy` / `rclcpp` 源码 + 调用栈
5. 最后才 Google / Stack Overflow

### 贡献方式

学完一段后,欢迎:
- 修 bug(测试用例失败的)
- 补文档(没说清楚的)
- 加 demo(新机制的最小示例)
- 翻译(英文版)

详见 `CONTRIBUTING.md`。

---

## 路线图完成度

```
[Level 1] ████████████░░ 95%  (5 包 5 文档待补,1 个 todo)
[Level 2] ░░░░░░░░░░░░░░░ 0%   (规划完成)
[Level 3] ░░░░░░░░░░░░░░░ 0%   (规划完成)
[Level 4] ░░░░░░░░░░░░░░░ 0%   (规划完成)
```

---

**继续**: 看 `doc/01-quickstart.md` 跑通第一个 demo → `doc/10-concepts.md` 理解 ROS2 概念 → `doc/15-params.md` Level 1 深度内容。

---

---

## 📖 阅读路径导航

> 💡 这是仓库 `doc/` 下所有文档的推荐阅读顺序。[返回 README 总导航](../README.md#-23-篇文档怎么读)
>
> ⏱ **本文预计阅读时间**: 15 分钟
> 📍 **当前位置**: 第 2 / 24 篇

- ⏮ **上一篇**: [项目架构 + 设计取舍](00-overview.md)
- ⏭ **下一篇**: [5 分钟跑通 Hello World](01-quickstart.md)