15 KiB
15 KiB
00 · 项目架构与设计取舍(完全指南)
目标:5 分钟内搞清楚本仓库"为什么这么设计、每一层做什么、对比 ROS2 全栈还差什么"。
目录
1. 一句话定位
ROS2 Humble 12 包全栈实战 — Topic / Service / Action / TF2 / URDF / Vision 六大通信范式 + Python/C++ 双语言互通 + 端到端 launch + 82/82 测试 100% 通过 + 24 篇文档 — 为 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/py_params │ │
│ │ src/cpp_custom_interface src/py_lifecycle_composable │ │
│ │ src/cpp_qos_demo src/py_overlay_dds src/bringup │ │
│ │ ↓ │ │
│ │ install/<pkg>/share/<pkg>/launch/*.py │ │
│ │ install/<pkg>/lib/<pkg>/<exec> │ │
│ └───────────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ 11 个 ROS2 节点(运行时) │ │
│ │ chatter_publisher/subscriber × 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。
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 |
| py_params | 参数系统 + 校验回调(Python) | ament_python | rclpy, rcl_interfaces |
| cpp_custom_interface | 自定义 .msg/.srv/.action(C++) | ament_cmake | rclcpp, rclcpp_action, rosidl_default_generators |
| py_lifecycle_composable | Lifecycle + Composable(Python) | ament_python | rclpy, lifecycle_msgs |
| cpp_qos_demo | QoS 9 种组合(C++) | ament_cmake | rclcpp, std_msgs |
| py_overlay_dds | DDS 配置 + colcon overlay(Python) | ament_python | rclpy, launch |
| 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 │
└────────┬────────┬──────────┬──────────┬────────┬────────┘
│ │ │ │ │
┌─────▼───┐ ┌──▼──────┐ ┌▼────────┐ ┌▼─────┐ ┌▼─────────┐
│chatter_ │ │fake_cam │ │joint_ │ │add_ │ │fibonacci │
│publish_ │ │image_ │ │state_ │ │two_ │ │_action_ │
│er_py │ │processor│ │publisher│ │ints_ │ │server │
├─────────┤ ├─────────┤ ├─────────┤ │server│ └──────────┘
│chatter_ │
│publish_ │ ← topic 互通(跨语言)
│er_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/ ← 12 个 ROS2 包 + 4 个 L2 占位
│ ├── 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)
│ ├── py_params/ ← ⭐ 参数系统 (Python)
│ ├── cpp_custom_interface/ ← ⭐ 自定义 msg/srv/action (C++)
│ ├── py_lifecycle_composable/ ← ⭐ Lifecycle + Composable (Python)
│ ├── cpp_qos_demo/ ← ⭐ QoS 9 种组合 (C++)
│ ├── py_overlay_dds/ ← ⭐ DDS 配置 + colcon overlay (Python)
│ ├── bringup/ ← launch 聚合 (Python)
│ ├── gazebo_sim/ ← ⚪ L2 占位(待 Gazebo)
│ ├── moveit2_demo/ ← ⚪ L2 占位(待 MoveIt2)
│ ├── nav2_demo/ ← ⚪ L2 占位(待 Nav2)
│ └── ros2_control_demo/ ← ⚪ L2 占位(待 ros2_control)
│
└── 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) | ✅ |
| 自定义 .msg/.srv/.action + rosidl 编译 | ✅ |
| QoS 9 种组合(RELIABLE / BEST_EFFORT / TRANSIENT_LOCAL ...) | ✅ |
| Lifecycle Node(unconfigured → active → finalized) | ✅ |
| TF2 坐标变换 + URDF | ✅ |
| sensor_msgs/Image + cv_bridge | ✅ |
| JointState 发布 | ✅ |
| DDS 配置 + colcon overlay + 多机部署 | ✅ |
| Launch + 测试 + Docker + venv | ✅ |
| 跨语言互通(py ↔ cpp) | ✅ |
| 文档齐全(24 篇) | ✅ |
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 — 5 个阶段 / 3-5 个月。
6.3 实际项目必装的额外 apt 包
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 测试
- 12 包 / 82 用例(64 pytest + 14 gtest + 4 launch_test),100% 通过
- Python 包 6 ~ 16 个 pytest 不等(深度按包而定)
- C++ 包 3 ~ 4 个 gtest + launch_test
- 集成测试用 in-process spin(避免 launch_testing 的 shutdown 二次调用问题)
8.4 文档
- 中文 + 详细中文注释
- 每篇 doc 有目录 + "5 分钟摘要" + "踩过的坑"
- 代码与文档严格同步(交叉引用源文件路径)
9. 下一步
| 你想做什么 | 看 |
|---|---|
| 5 分钟跑通 | 01-quickstart.md |
| 用 venv 不污染系统 | 02-virtualenv.md |
| 弄懂 ROS2 核心概念 | 10-concepts.md |
| 深读 Topic / Service / Action | 20-topics.md, 30-services.md, 40-actions.md |
| 做机器人 / TF / URDF | 50-tf2.md, 60-urdf.md |
| 三机部署到 RDK X5 / RK3506 | 100-embedded-deployment.md |
| 进入具身智能 / VLA | 99-embodied-ai.md |
📖 阅读路径导航
💡 这是仓库
doc/下所有文档的推荐阅读顺序。返回 README 总导航⏱ 本文预计阅读时间: 20 分钟 📍 当前位置: 第 1 / 24 篇
- ⏭ 下一篇: 5 分钟跑通 Hello World