# 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//share//launch/*.py │ │ │ │ install//lib// │ │ │ └───────────────────────────────────────────────────────┘ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ 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) |