# ROS2 Learning Suite — 从零到具身智能 / VLA 完全体

> **一套从 ROS2 基础到机械臂 + VLA (Vision-Language-Action) 落地的完整实战仓库**:
> 12 包 + 80 测试 100% 通过 + 23 篇深度文档 + Docker + Make + GitLab CI + 跨机部署。
> 为后续具身智能 / 机器人 / VLA 开发铺平第一公里。
>
> **学习承诺**: 每行代码遵循 [`doc/CODING_STYLE.md`](doc/CODING_STYLE.md)(PEP 8 + ROS2 REP-2000 + 工业级实践)。

---

## 🎯 适合谁

- 第一次学 ROS2,想从 0 到能搭一个完整机器人项目
- 想**深耕具身智能**(机器人 + VLA),需要把 ROS2 通信栈 + TF2 + URDF + Vision 一次打通
- 想在 Windows 本机用 venv + VSCode 写代码,在 Docker Linux 容器跑 ROS2
- 需要一个**教科书级别**的开源仓库作教学/学习参考

## 📦 仓库提供什么

**12 个 ROS2 包 + 80 测试 + 23 篇深度文档 + Make + GitLab CI**:

| 包 | 类型 | 通信范式 | 语言 | 测试 |
|---|---|---|---|---|
| [`py_pubsub`](src/py_pubsub/) | ament_python | Topic pub/sub | Python | pytest 11/11 ✓ |
| [`cpp_pubsub`](src/cpp_pubsub/) | ament_cmake | Topic pub/sub | C++ | gtest 3/3 ✓ |
| [`py_srv`](src/py_srv/) | ament_python | Service req/resp | Python | pytest 6/6 ✓ |
| [`py_action_demo`](src/py_action_demo/) | ament_python | Action 三件套 | Python | pytest 4/4 ✓ |
| [`cpp_robot_tf2`](src/cpp_robot_tf2/) | ament_cmake | URDF + TF2 | C++ | gtest 4/4 ✓ |
| [`py_vision_demo`](src/py_vision_demo/) | ament_python | sensor_msgs/Image | Python | pytest 11/11 ✓ |
| [`py_params`](src/py_params/) | ament_python | Parameter 系统 | Python | pytest 16/16 ✓ |
| [`cpp_custom_interface`](src/cpp_custom_interface/) | ament_cmake | 自定义 .msg/.srv/.action | C++ | gtest 3/3 ✓ |
| [`py_lifecycle_composable`](src/py_lifecycle_composable/) | ament_python | Lifecycle + Composable | Python | pytest 6/6 ✓ |
| [`cpp_qos_demo`](src/cpp_qos_demo/) | ament_cmake | QoS 9 种组合 | C++ | gtest 4/4 ✓ |
| [`py_overlay_dds`](src/py_overlay_dds/) | ament_python | DDS 配置 + colcon overlay | Python | pytest 6/6 ✓ |
| [`bringup`](src/bringup/) | ament_python | 6 跨包 launch 聚合 | Python | OK |

**合计 80/80 测试 100% 通过目标**;6 个端到端 demo 启动脚本。

---

## 🚀 5 分钟上手(Makefile)

```bash
# 1. 构建镜像(首次 5-10 分钟)
make build

# 2. 启动容器
make up

# 3. 容器内 build 12 包
make colcon-build

# 4. 跑所有测试
make colcon-test

# 5. 进入开发终端
make shell

# 6. 启动 11 节点 full_demo
make full-demo
```

等价手动命令(`make` 不可用时):

```bash
docker compose -p ros2 -f docker/docker-compose.yml build
docker compose -p ros2 -f docker/docker-compose.yml up -d
docker exec ros2_dev bash -lc "source /opt/ros/humble/setup.bash && cd /root/ros2_ws && colcon build --symlink-install --packages-select py_pubsub cpp_pubsub py_srv py_action_demo cpp_robot_tf2 py_vision_demo py_params cpp_custom_interface py_lifecycle_composable cpp_qos_demo py_overlay_dds bringup"
docker exec ros2_dev bash -lc "cd /root/ros2_ws && colcon test --packages-select ..."
```

## 🧱 架构

```
                          ┌──────────────────────────────────────────┐
                          │          本机 Windows / Linux            │
                          │   (venv: ruff/black/mypy/pytest)        │
                          └─────────────────┬────────────────────────┘
                                            │ bind mount
                          ┌─────────────────▼────────────────────────┐
                          │     Docker compose project: ros2        │
                          │     自定义网络: ros2_net (172.20.0.0/24) │
                          │  ┌──────── ROS2 Humble 镜像 ────────┐   │
                          │  │ rclcpp rclpy tf2 cv_bridge       │   │
                          │  │ ros-humble-desktop-full         │   │
                          │  └───────────────────────────────────┘   │
                          │  ┌──── colcon build/test ───────────┐    │
                          │  │ 12 个包 / 80 测试                │    │
                          │  └──────────────────────────────────┘    │
                          └──────────────────────────────────────────┘
```

**两层解耦**:
- **本机层**: venv 装开发工具(runtime 隔离),IDE 直接读源码
- **容器层**: colcon 装 ROS2 节点(apt 来源,共享给所有用户)

## 🎬 6 种端到端 demo

| Demo | 命令 | 看什么 |
|---|---|---|
| Topic 跨包跨语言 | `make launch NAME=pubsub_launch` | 4 节点(py+cpp)互通 |
| Service | `make launch NAME=service_launch` + `ros2 service call ...` | `12+30=42` |
| Action | `make launch NAME=action_launch` + `ros2 action send_goal ...` | Fibonacci(6) 边跑边反馈 |
| Robot TF2 | `make launch NAME=robot_launch` | gripper 在 base_link 下实时位姿 |
| Vision | `make launch NAME=vision_launch` | fake_camera → image_processor 图像流 |
| Full demo | `make full-demo` | **11+ 节点同时运行** |

## 📚 23 篇文档导航

### 上手
- [`doc/00-overview.md`](doc/00-overview.md) — 项目架构 + 设计取舍
- [`doc/00-levels.md`](doc/00-levels.md) — Level 1-4 学习路线(ROS2 → 机械臂 → VLA)
- [`doc/01-quickstart.md`](doc/01-quickstart.md) — 5 分钟跑通
- [`doc/02-virtualenv.md`](doc/02-virtualenv.md) — venv 工作流

### ROS2 核心概念
- [`doc/10-concepts.md`](doc/10-concepts.md) — Node / Topic / Service / Action / Parameter / TF / Time
- [`doc/20-topics.md`](doc/20-topics.md) — Topic pub/sub 深度
- [`doc/30-services.md`](doc/30-services.md) — Service req/resp 深度
- [`doc/40-actions.md`](doc/40-actions.md) — Action 三件套深度
- [`doc/15-params.md`](doc/15-params.md) — Parameter 系统深度 ⭐
- [`doc/16-custom-interfaces.md`](doc/16-custom-interfaces.md) — 自定义 msg/srv/action ⭐
- [`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 + colcon overlay ⭐

### 机器人专属
- [`doc/50-tf2.md`](doc/50-tf2.md) — 坐标变换
- [`doc/60-urdf.md`](doc/60-urdf.md) — 机器人模型描述

### 工程实践
- [`doc/70-launch.md`](doc/70-launch.md) — launch 文件系统
- [`doc/80-package-build.md`](doc/80-package-build.md) — colcon / ament 包构建
- [`doc/85-docker.md`](doc/85-docker.md) — Docker 容器化开发
- [`doc/90-testing.md`](doc/90-testing.md) — 测试金字塔
- [`doc/CODING_STYLE.md`](doc/CODING_STYLE.md) — **编程规范(必读)** ⭐

### 具身智能路径
- [`doc/99-embodied-ai.md`](doc/99-embodied-ai.md) — VLA / 机器人开发路线图
- [`doc/100-embedded-deployment.md`](doc/100-embedded-deployment.md) — **三机部署实操**

## 🗺 入门具身智能路径

| 阶段 | 内容 | 配套 |
|---|---|---|
| ✅ L1 基础 | ROS2 12 包 + 80 测试 + 23 文档 | **本仓库** |
| ➡️ L2 进阶 | ros2_control + MoveIt2 + Gazebo | `ros-humble-*` apt |
| ➡️ L3 机械臂 | 真实机械臂驱动 + 手眼标定 + 抓取 | xArm / UR / Franka |
| ➡️ L4 VLA | OpenVLA / π0 / RKNN NPU 推理 | PC + RDK X5 + RK3506 |

## 🛠 项目约定(必读)

代码风格 / 构建约束全部在 [`AGENTS.md`](AGENTS.md) + [`doc/CODING_STYLE.md`](doc/CODING_STYLE.md),核心几条:

1. **本机 venv 不污染系统 Python**(用 `tools/setup_venv.{sh,ps1}`)
2. 容器内用 colcon + ament(ROS2 官方工具链)
3. 跨包 launch 用 `IncludeLaunchDescription` + `FindPackageShare`
4. 包名不能叫 `launch`(与 ROS2 系统包同名冲突)
5. **测试 100% 通过才能停手**
6. **不修改全局 git config** — 用 `git -c user.name=x -c user.email=y` 临时设

## 🤝 致谢

- [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` 镜像

开始你的 ROS2 之旅:`doc/01-quickstart.md` → 跑通 → 读 `doc/10-concepts.md` 深入 → 上 `doc/99-embodied-ai.md` 部署。