ROS2_learn/README.md

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

一套从 ROS2 基础到机械臂 + VLA (Vision-Language-Action) 落地的完整实战仓库: 12 包 + 80 测试 100% 通过 + 23 篇深度文档 + Docker + Make + GitLab CI + 跨机部署。 为后续具身智能 / 机器人 / VLA 开发铺平第一公里。

学习承诺: 每行代码遵循 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	ament_python	Topic pub/sub	Python	pytest 11/11 ✓
cpp_pubsub	ament_cmake	Topic pub/sub	C++	gtest 3/3 ✓
py_srv	ament_python	Service req/resp	Python	pytest 6/6 ✓
py_action_demo	ament_python	Action 三件套	Python	pytest 4/4 ✓
cpp_robot_tf2	ament_cmake	URDF + TF2	C++	gtest 4/4 ✓
py_vision_demo	ament_python	sensor_msgs/Image	Python	pytest 11/11 ✓
py_params	ament_python	Parameter 系统	Python	pytest 16/16 ✓
cpp_custom_interface	ament_cmake	自定义 .msg/.srv/.action	C++	gtest 3/3 ✓
py_lifecycle_composable	ament_python	Lifecycle + Composable	Python	pytest 6/6 ✓
cpp_qos_demo	ament_cmake	QoS 9 种组合	C++	gtest 4/4 ✓
py_overlay_dds	ament_python	DDS 配置 + colcon overlay	Python	pytest 6/6 ✓
bringup	ament_python	6 跨包 launch 聚合	Python	OK

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

---

🚀 5 分钟上手(Makefile)

# 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 不可用时):

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-levels.md — Level 1-4 学习路线(ROS2 → 机械臂 → VLA)
• doc/01-quickstart.md — 5 分钟跑通
• doc/02-virtualenv.md — venv 工作流

ROS2 核心概念

• doc/10-concepts.md — Node / Topic / Service / Action / Parameter / TF / Time
• doc/20-topics.md — Topic pub/sub 深度
• doc/30-services.md — Service req/resp 深度
• doc/40-actions.md — Action 三件套深度
• doc/15-params.md — Parameter 系统深度 ⭐
• doc/16-custom-interfaces.md — 自定义 msg/srv/action ⭐
• doc/17-lifecycle.md — Lifecycle Node ⭐
• doc/18-composable.md — Composable Node ⭐
• doc/19-qos.md — QoS 全解 ⭐
• doc/20-bag.md — ros2 bag ⭐
• doc/21-overlay-dds.md — DDS + colcon overlay ⭐

机器人专属

• doc/50-tf2.md — 坐标变换
• doc/60-urdf.md — 机器人模型描述

工程实践

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

具身智能路径

• doc/99-embodied-ai.md — VLA / 机器人开发路线图
• 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 + 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 官方文档
• REP-2000: ROS 2 Design
• OSRF osrf/ros:humble-desktop 镜像

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