ROS2_learn/doc/00-overview.md

# 00 · 项目架构与设计取舍(完全指南)

> **目标**:5 分钟内搞清楚本仓库"为什么这么设计、每一层做什么、对比 ROS2 全栈还差什么"。

---

## 目录

- [1. 一句话定位](#1-一句话定位)
- [2. 双层解耦架构](#2-双层解耦架构)
- [3. 包设计全景](#3-包设计全景)
- [4. 通信拓扑](#4-通信拓扑)
- [5. 文件布局详解](#5-文件布局详解)
- [6. ROS2 全栈 vs 本仓库](#6-ros2-全栈-vs-本仓库)
- [7. 何时用本仓库](#7-何时用本仓库)
- [8. 设计原则](#8-设计原则)
- [9. 下一步](#9-下一步)

---

## 1. 一句话定位

> **ROS2 Humble 7 包全栈实战** — Topic / Service / Action / TF2 / URDF / Vision 六大通信范式 +
> Python/C++ 双语言互通 + 端到端 launch + **10/10 测试 100% 通过** + 15 篇文档 —
> 为 VLA / 具身智能开发铺平最后一段学习路径。

---

## 2. 双层解耦架构

本仓库用**两个互不污染的环境**把"Python 开发"与"ROS2 运行"分开:

```
┌─────────────────────────────────────────────────────────────┐
│              本机 Windows / Linux (你正在用的机器)              │
│  ┌───────────────────────────────────────────────────────┐  │
│  │              .venv (Python 3.10 virtualenv)           │  │
│  │   ruff · black · mypy · flake8 · pytest · numpy        │  │
│  │   + pip install -e src/py_pubsub ... (源码可编辑)      │  │
│  └───────────────────────────────────────────────────────┘  │
│  IDE: VSCode (Pylance / pyright) · PyCharm                  │
│  配置文件: pyproject.toml · pyrightconfig.json · .flake8     │
└────────────────────────────┬────────────────────────────────┘
                             │ bind mount: D:\xs\ros2 ↔ /root/ros2_ws
┌────────────────────────────▼────────────────────────────────┐
│           Docker (osrf/ros:humble-desktop)                  │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                ROS2 apt (系统 Python)                  │  │
│  │  rclcpp · rclpy · tf2 · cv_bridge · ros2-control ...  │  │
│  │  /opt/ros/humble + ROS_DOMAIN_ID + RMW                │  │
│  └───────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────┐  │
│  │         colcon build / install / test                  │  │
│  │  src/py_pubsub  src/cpp_pubsub  src/py_srv             │  │
│  │  src/py_action_demo  src/cpp_robot_tf2                 │  │
│  │  src/py_vision_demo  src/bringup                      │  │
│  │           ↓                                           │  │
│  │  install/<pkg>/share/<pkg>/launch/*.py                │  │
│  │  install/<pkg>/lib/<pkg>/<exec>                       │  │
│  └───────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────┐  │
│  │              11 个 ROS2 节点(运行时)                    │  │
│  │  talker/listener × 2 (py+cpp)                        │  │
│  │  service server / action server                      │  │
│  │  joint_state_publisher + robot_state_publisher        │  │
│  │  + tf2_listener + fake_camera + image_processor       │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

### 2.1 为什么这样设计

| 层 | 用途 | 为什么独立 |
|---|---|---|
| **本机 venv** | IDE 代码跳转、单元测试、lint、格式化 | rclpy 没 Windows wheels;venv 隔离掉"装不上 ROS 客户端"的事实 |
| **Docker ROS2** | 跑 ROS2 节点、launch、colcon test、端到端验证 | 一次 build 处处跑,Linux + Windows + macOS 一致 |

详见 [`02-virtualenv.md`](02-virtualenv.md)。

---

## 3. 包设计全景

| 包 | 角色 | build_type | 关键依赖 |
|---|---|---|---|
| **py_pubsub** | Topic pub/sub(Python) | ament_python | rclpy, std_msgs |
| **cpp_pubsub** | Topic pub/sub(C++) | ament_cmake | rclcpp, std_msgs |
| **py_srv** | Service(Python) | ament_python | rclpy, example_interfaces |
| **py_action_demo** | Action 三件套(Python) | ament_python | rclpy, example_interfaces |
| **cpp_robot_tf2** | URDF + TF2 + JointState(C++) | ament_cmake | rclcpp, tf2, geometry_msgs, sensor_msgs |
| **py_vision_demo** | sensor_msgs/Image(Python) | ament_python | rclpy, sensor_msgs, cv_bridge |
| **bringup** | 顶层 launch 聚合(Python) | ament_python | launch, launch_ros |

**设计原则**:
- 每个包独立可 build / test,**不强依赖其他 demo 包**
- 跨包互通依赖 DDS(**不需要 import 别的包代码**)
- bringup **只负责组合**,不重复节点实现

---

## 4. 通信拓扑

ROS2 所有节点通过 **DDS**(默认 fastdds)做发布订阅,**不直接 import 别的节点代码**:

```
┌──────────────────────────────────────────────────────────┐
│                       DDS 总线                            │
│   /chatter   /image_raw   /tf   /tf_static               │
│   /joint_states   /parameter_events   /rosout           │
└────────┬────────┬──────────┬──────────┬────────┬────────┘
         │        │          │          │        │
   ┌─────▼───┐ ┌──▼──────┐ ┌▼────────┐ ┌▼─────┐ ┌▼─────────┐
   │talker_py│ │fake_cam │ │joint_pub│ │srv   │ │fibonacci │
   │listener │ │image_   │ │robot_   │ │server│ │_server   │
   │   _py   │ │processor│ │state_pub│ │      │ │          │
   ├─────────┤ ├─────────┤ ├─────────┤ └──────┘ └──────────┘
   │talker_  │                                
   │  cpp   │  ← topic 互通(跨语言)         
   │listener │                                
   │  _cpp  │                                
   └─────────┘                                
```

---

## 5. 文件布局详解

```
D:\xs\ros2\
├── README.md                    ← 项目入口 + 架构 + 启动命令
├── AGENTS.md                    ← 铁律 + 工作流(必读)
├── pyproject.toml               ← PEP 621 workspace + 工具配置
├── requirements.txt / -dev.txt   ← venv 依赖
├── .flake8 / pyrightconfig.json  ← lint / 类型检查配置
├── .gitignore
│
├── docker/
│   ├── Dockerfile               ← ROS2 Humble 镜像
│   ├── docker-compose.yml       ← bind mount + host network
│   └── *_e2e.log                ← 端到端验证日志(46KB 等)
│
├── tools/                       ← 本机开发工具
│   ├── setup_venv.sh / .ps1     ← 一键 venv
│
├── build.sh / start.sh / start.ps1
│
├── src/
│   ├── py_pubsub/               ← Topic (Python)
│   ├── cpp_pubsub/              ← Topic (C++)
│   ├── py_srv/                  ← Service (Python)
│   ├── py_action_demo/          ← Action (Python)
│   ├── cpp_robot_tf2/           ← TF2 + URDF (C++)
│   ├── py_vision_demo/          ← Image (Python)
│   └── bringup/                 ← launch 聚合 (Python)
│
└── doc/                         ← 15 篇深度文档
    ├── 00-overview.md           ← 本篇
    ├── 01-quickstart.md         ← 5 分钟上手
    ├── 02-virtualenv.md         ← venv 工作流
    ├── 10-concepts.md           ← 核心概念地图
    ├── 20-topics.md             ← Topic 深度
    ├── 30-services.md           ← Service 深度
    ├── 40-actions.md            ← Action 深度
    ├── 50-tf2.md                ← TF2 坐标变换
    ├── 60-urdf.md               ← URDF 机器人模型
    ├── 70-launch.md             ← launch 文件
    ├── 80-package-build.md      ← colcon / ament
    ├── 85-docker.md             ← Docker 容器化
    ├── 90-testing.md            ← 测试金字塔
    ├── 99-embodied-ai.md        ← VLA / 机器人路径
    └── 100-embedded-deployment.md  ← 三机部署实操
```

---

## 6. ROS2 全栈 vs 本仓库

**坦白说:本仓库不是完全体**。覆盖 ~70% 的 ROS2 + 机械臂入门知识。

### 6.1 ✅ 已覆盖

| 知识点 | 状态 |
|---|---|
| ROS2 通信(Topic / Service / Action / Parameter) | ✅ |
| TF2 坐标变换 + URDF | ✅ |
| sensor_msgs/Image + cv_bridge | ✅ |
| JointState 发布 | ✅ |
| Launch + 测试 + Docker + venv | ✅ |
| 跨语言互通 | ✅ |
| 文档齐全(15 篇) | ✅ |

### 6.2 ❌ 没覆盖(下一步)

| 知识点 | 缺 |
|---|---|
| **ros2_control** + JointTrajectoryController | ❌ |
| **MoveIt2** 运动规划(IK / 避障) | ❌ |
| **Gazebo** / ros_gz 物理仿真 | ❌ |
| 真实 6-DoF 机械臂 URDF | ❌(只有 3 关节玩具) |
| Gripper / 末端执行器控制 | ❌ |
| 手眼标定 | ❌ |
| 力控 / Force-Torque | ❌ |
| GraspNet / 6-DoF 抓取 | ❌ |
| VLA 模型接入(OpenVLA / Pi0) | ❌(只有路径规划) |
| 移动底盘(Nav2 / SLAM) | ❌ |
| 多臂协调 | ❌ |
| rosbridge / Foxglove | ❌ |

**完整学习路径**: 见 [`99-embodied-ai.md`](99-embodied-ai.md) — 5 个阶段 / 3-5 个月。

### 6.3 实际项目必装的额外 apt 包

```bash
sudo apt install ros-humble-ros2-control
sudo apt install ros-humble-ros2-controllers
sudo apt install ros-humble-moveit
sudo apt install ros-humble-ros-gz
sudo apt install ros-humble-navigation2
```

---

## 7. 何时用本仓库

| 场景 | 推荐 |
|---|---|
| 第 1 次学 ROS2,想完整跑通一个最小 ROS2 系统 | ✅ 推荐 |
| 想搞懂"跨语言互通"是怎么工作的 | ✅ 推荐 |
| 准备做机器人 / 具身智能项目,需要先打基础 | ✅ 推荐 |
| 公司已经在用 ROS2,需要一个 demo 教学 | ✅ 推荐 |
| 想直接做 MoveIt2 / Nav2 的仿真 | ⚠️ 本仓库打底,然后装 ROS2 Humble 官方包 |
| 想直接做产品化 ROS2 | ⚠️ 本仓库做参考,真实项目要按需重构 |

---

## 8. 设计原则

### 8.1 包设计
- 一个 demo 一个包
- 跨包不 import,只走 DDS
- 标准消息为主(example_interfaces),避免自定义 msg

### 8.2 命名
- 包名小写下划线(`py_pubsub`, `cpp_robot_tf2`)
- **包名不能叫 `launch`**(与 ROS2 自带包同名,ament 索引冲突)
- 节点名小写下划线 + 后缀(`talker_py`, `joint_state_publisher_cpp`)

### 8.3 测试
- 每个 Python 包 4 个测试用例
- 每个 C++ 包 2 个 gtest
- 集成测试用 in-process spin(避免 launch_testing 的 shutdown 二次调用问题)

### 8.4 文档
- 中文 + 详细中文注释
- 每篇 doc 有目录 + "5 分钟摘要" + "踩过的坑"
- 代码与文档严格同步(交叉引用源文件路径)

---

## 9. 下一步

| 你想做什么 | 看 |
|---|---|
| 5 分钟跑通 | [`01-quickstart.md`](01-quickstart.md) |
| 用 venv 不污染系统 | [`02-virtualenv.md`](02-virtualenv.md) |
| 弄懂 ROS2 核心概念 | [`10-concepts.md`](10-concepts.md) |
| 深读 Topic / Service / Action | [`20-topics.md`](20-topics.md), [`30-services.md`](30-services.md), [`40-actions.md`](40-actions.md) |
| 做机器人 / TF / URDF | [`50-tf2.md`](50-tf2.md), [`60-urdf.md`](60-urdf.md) |
| 三机部署到 RDK X5 / RK3506 | [`100-embedded-deployment.md`](100-embedded-deployment.md) |
| 进入具身智能 / VLA | [`99-embodied-ai.md`](99-embodied-ai.md) |