init: ROS2 learning suite

2026-08-03 18:09:35 +08:00
commit 5ef38ab508
95 changed files with 13322 additions and 0 deletions
@@ -0,0 +1,270 @@
+# 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) |