# ROS2 Learning Suite — 具身智能入门实战 > 一套 **从零到具身智能开发** 的 ROS2 Humble 全栈实战:Topics / Services / Actions / > TF2 / URDF / Vision。每个 demo 都可独立运行,跨包跨语言互通,所有测试 **100% 通过**。 > 为后续 VLA(Vision-Language-Action) / 机器人 / 具身智能开发铺路。 --- ## 🎯 适合谁 - 第一次学 ROS2,想从 0 到能搭一个完整机器人项目 - 想**深耕具身智能**(机器人 + VLA),需要把 ROS2 通信栈 + TF2 + URDF + Vision 一次打通 - 想在 Windows 本机用 venv + VSCode/PyCharm 写 Python,在 Docker/WSL Linux 里跑 ROS2 ## 📦 仓库提供什么 7 个 ROS2 包 + 端到端 demo + 深度文档: | 包 | 类型 | 通信模式 | 语言 | 测试 | |---|---|---|---|---| | [`py_pubsub`](src/py_pubsub/) | ament_python | Topic pub/sub | Python | pytest 4/4 ✓ | | [`cpp_pubsub`](src/cpp_pubsub/) | ament_cmake | Topic pub/sub | C++ | gtest 2/2 ✓ | | [`py_srv`](src/py_srv/) | ament_python | Service req/resp | Python | pytest 1/1 ✓ | | [`py_action_demo`](src/py_action_demo/) | ament_python | Action 三件套 | Python | pytest 1/1 ✓ | | [`cpp_robot_tf2`](src/cpp_robot_tf2/) | ament_cmake | TF2 + URDF + JointState | C++ | gtest 2/2 ✓ | | [`py_vision_demo`](src/py_vision_demo/) | ament_python | sensor_msgs/Image | Python | pytest 2/2 ✓ | | [`bringup`](src/bringup/) | ament_python | launch 聚合 | Python | OK | **合计 10/10 测试 100% 通过**;5 个端到端日志固化在 [`docker/`](docker/)。 --- ## 🚀 30 秒上手 ### Windows 本机(开发) ```bash # 一键创建 venv(不污染系统 Python) powershell .\tools\setup_venv.ps1 .\.venv\Scripts\Activate.ps1 # 打开 VSCode / PyCharm code D:\xs\ros2 ``` ### Docker 容器(运行 + 测试) ```powershell # 第一次:构建 + 启动 + 编译 + 进入开发终端 powershell D:\xs\ros2\start.ps1 # 后续:重启即用 docker compose -f D:\xs\ros2\docker\docker-compose.yml up -d # 在容器内构建 + 跑测试 docker exec ros2_dev bash -lc "cd /root/ros2_ws && bash build.sh" docker exec ros2_dev bash -lc "source /opt/ros/humble/setup.bash && cd /root/ros2_ws && colcon test --packages-select py_pubsub cpp_pubsub py_srv py_action_demo cpp_robot_tf2 py_vision_demo bringup" ``` --- ## 🧱 架构 ``` ┌──────────────────────────────────────────┐ │ 本机 Windows / Linux │ │ (venv: ruff/black/mypy/pytest/numpy) │ └─────────────────┬────────────────────────┘ │ 共享源码目录 (bind mount) ┌─────────────────▼────────────────────────┐ │ Docker (osrf/ros:humble-desktop) │ │ ┌────────── ROS2 apt ───────────┐ │ │ │ rclcpp rclpy tf2 cv_bridge │ │ │ │ ros-humble-desktop-full │ │ │ └───────────────────────────────┘ │ │ ┌──── colcon build/test ───────┐ │ │ │ py_pubsub cpp_pubsub │ │ │ │ py_srv py_action_demo │ │ │ │ cpp_robot_tf2 py_vision_demo│ │ │ │ bringup │ │ │ └─────────────────────────────┘ │ └──────────────────────────────────────────┘ ``` **两层解耦**: - **本机层**:venv 装开发工具(runtime 隔离),IDE 直接读源码 - **容器层**:colcon 装 ROS2 节点(apt 来源,共享给所有用户) 详细架构见 [`doc/00-overview.md`](doc/00-overview.md)。 --- ## 🎬 6 种端到端 demo | Demo | 命令 | 看什么 | |---|---|---| | Topic 跨包跨语言 | `ros2 launch bringup pubsub_launch.py` | `listener_cpp` 收 `talker_py` 和 `talker_cpp` 的消息 | | Service | `ros2 launch bringup service_launch.py` + `ros2 service call /add_two_ints ...` | `12+30=42` | | Action | `ros2 launch bringup action_launch.py` + `ros2 action send_goal /fibonacci ...` | Fibonacci(6) 边跑边反馈 | | Robot TF2 | `ros2 launch bringup robot_launch.py` | gripper 在 base_link 下的实时位姿 | | Vision | `ros2 launch bringup vision_launch.py` | fake_camera → image_processor 图像流 | | Full demo | `ros2 launch bringup full_demo_launch.py` | **11 个节点同时运行** | 固化日志:[`docker/bringup_e2e.log`](docker/bringup_e2e.log) · [`docker/srv_e2e.log`](docker/srv_e2e.log) · [`docker/robot_e2e.log`](docker/robot_e2e.log) · [`docker/vision_e2e.log`](docker/vision_e2e.log) · [`docker/full_demo_e2e.log`](docker/full_demo_e2e.log) --- ## 📚 文档导航 ### 上手 - [`doc/00-overview.md`](doc/00-overview.md) — 项目架构 + 设计取舍 - [`doc/01-quickstart.md`](doc/01-quickstart.md) — 5 分钟跑通 - [`doc/02-virtualenv.md`](doc/02-virtualenv.md) — venv 工作流(本机不污染) ### ROS2 核心概念 - [`doc/10-concepts.md`](doc/10-concepts.md) — Node / Topic / Service / Action / Parameter / TF / Time - [`doc/20-topics.md`](doc/20-topics.md) — Topic pub/sub 深度 - [`doc/30-services.md`](doc/30-services.md) — Service req/resp 深度 - [`doc/40-actions.md`](doc/40-actions.md) — Action 三件套深度 ### 机器人专属 - [`doc/50-tf2.md`](doc/50-tf2.md) — 坐标变换(VLA/抓取/对齐的基石) - [`doc/60-urdf.md`](doc/60-urdf.md) — 机器人模型描述 ### 工程实践 - [`doc/70-launch.md`](doc/70-launch.md) — launch 文件系统 - [`doc/80-package-build.md`](doc/80-package-build.md) — colcon / ament 包构建 - [`doc/85-docker.md`](doc/85-docker.md) — Docker 容器化开发 ### 开发 & 测试 - [`doc/90-testing.md`](doc/90-testing.md) — 单元/集成/端到端测试策略 ### 具身智能路径 - [`doc/99-embodied-ai.md`](doc/99-embodied-ai.md) — **VLA / 机器人开发路线图**(从本仓库出发到部署) - [`doc/100-embedded-deployment.md`](doc/100-embedded-deployment.md) — **三机部署实操**:PC + RDK X5 + RK3506 × 2 --- ## 🗺 入门具身智能的路径 本仓库完成后,做 VLA / 机器人开发的下一步: | 阶段 | 内容 | 配套技术 | |---|---|---| | ✅ 已有 | Topic / Service / Action / TF2 / URDF / 视觉 | **本仓库** | | ➡️ 下一步 | ros2_control | ros-humble-ros2-control + ros-humble-ros2-controllers | | ➡️ 下一步 | MoveIt2 机械臂规划 | ros-humble-moveit | | ➡️ 下一步 | Nav2 移动底盘导航 | ros-humble-navigation2 | | ➡️ 下一步 | Gazebo / Ignition 仿真 | ros-humble-ros-gz | | ➡️ 下一步 | rosbridge / Foxglove | rosbridge_suite,foxglove_bridge | | ➡️ 下一步 | VLA 模型接入 | OpenVLA / RT-2 / Pi0;ros2 服务 + TF + Image 输入 | | ➡️ 下一步 | 真机部署(PC + RDK X5 + RK3506) | 见 `doc/100-embedded-deployment.md` | ## 🛠 你的硬件(典型配置) | 硬件 | SoC | RAM | 跑什么 | |---|---|---|---| | PC | x86 | 8-32GB | 完整 ROS2 + MoveIt2 / Nav2 / RViz | | RDK X5 × 1 | Sunrise 3 + 5 TOPS NPU | 4GB | 边缘 AI(视觉 / 语音 / SLAM) | | RK3506 × 2 | ARM 3 核 | 512MB (Linux) | 实时控制(电机 / 编码器 / PID) | 三层都跑完整 ROS2,通过 LAN FastDDS 互通。**详细部署见 [`doc/100-embedded-deployment.md`](doc/100-embedded-deployment.md)**。 详见 [`doc/99-embodied-ai.md`](doc/99-embodied-ai.md)。 --- ## 🛠 项目约定(必读) 代码风格 / 构建约束全部在 [`AGENTS.md`](AGENTS.md),核心几条: 1. **本机 venv 不污染系统 Python**(用 `tools/setup_venv.{sh,ps1}`) 2. 容器内用 colcon + ament(ROS2 官方工具链) 3. 跨包 launch 用 `IncludeLaunchDescription` + `FindPackageShare` 4. 包名不能叫 `launch`(与 ROS2 系统包同名会冲突) 5. **测试 100% 通过才能停手** --- ## 📁 目录速览 ``` D:\xs\ros2\ ├── README.md ← 本文件 ├── AGENTS.md ← 铁律 + 工作流约定 ├── pyproject.toml ← PEP 621 workspace 元数据(IDE 入口) ├── requirements*.txt ← venv 依赖 ├── .flake8 / pyrightconfig.json ← lint / 类型检查配置 │ ├── docker/ │ ├── Dockerfile ← ROS2 Humble 镜像 │ ├── docker-compose.yml ← 容器编排 │ ├── bringup_e2e.log ← 端到端日志(已固化) │ ├── srv_e2e.log │ ├── robot_e2e.log │ ├── vision_e2e.log │ └── full_demo_e2e.log │ ├── tools/ │ ├── setup_venv.sh ← Linux/WSL/Docker 一键 venv │ └── setup_venv.ps1 ← Windows 一键 venv │ ├── build.sh / start.sh / start.ps1 ← 容器内构建 / 一键启动 │ ├── src/ │ ├── py_pubsub/ ← Topic pub/sub (Python) │ ├── cpp_pubsub/ ← Topic pub/sub (C++) │ ├── py_srv/ ← Service (Python) │ ├── py_action_demo/ ← Action (Python) │ ├── cpp_robot_tf2/ ← TF2 + URDF + JointState (C++) │ ├── py_vision_demo/ ← sensor_msgs/Image (Python) │ └── bringup/ ← 顶层 launch 聚合 (Python) │ └── doc/ ← 12 篇深度文档 ``` --- ## 🤝 致谢 - [ROS2 官方文档](https://docs.ros.org/en/humble/) - [OSRF](https://www.openrobotics.org/) `osrf/ros:humble-desktop` 镜像 - [鱼香 ROS](https://fishros.org/) 中文教程 开始你的 ROS2 之旅:`doc/01-quickstart.md` → 跑通 → 读 `doc/10-concepts.md` 深入 → 上 `doc/99-embodied-ai.md` 部署。