xsROS2 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 / Timedoc/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,核心几条:
- 本机 venv 不污染系统 Python(用
tools/setup_venv.{sh,ps1}) - 容器内用 colcon + ament(ROS2 官方工具链)
- 跨包 launch 用
IncludeLaunchDescription+FindPackageShare - 包名不能叫
launch(与 ROS2 系统包同名冲突) - 测试 100% 通过才能停手
- 不修改全局 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 部署。