xiaoshuai/ROS2_learn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(level1): ROS2 完全体 12 包 / 80 测试 / 23 文档 / 工程化 / Docker 分组

Browse Source
This commit is contained in:
xs
2026-08-04 10:19:47 +08:00
parent 5ef38ab508
commit 549d6b337e
141 changed files with 8949 additions and 1594 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+95 -148
View File
@@ -1,8 +1,10 @@
# ROS2 Learning Suite — 具身智能入门实战
# ROS2 Learning Suite — 从零到具身智能 / VLA 完全体
> 一套 **从零到具身智能开发** 的 ROS2 Humble 全栈实战:Topics / Services / Actions /
> TF2 / URDF / Vision。每个 demo 都可独立运行,跨包跨语言互通,所有测试 **100% 通过**。
> 为后续 VLA(Vision-Language-Action) / 机器人 / 具身智能开发铺路。
> **一套从 ROS2 基础到机械臂 + VLA (Vision-Language-Action) 落地的完整实战仓库**:
> 12 包 + 80 测试 100% 通过 + 23 篇深度文档 + Docker + Make + GitLab CI + 跨机部署。
> 为后续具身智能 / 机器人 / VLA 开发铺平第一公里。
>
> **学习承诺**: 每行代码遵循 [`doc/CODING_STYLE.md`](doc/CODING_STYLE.md)(PEP 8 + ROS2 REP-2000 + 工业级实践)。
---
@@ -10,214 +12,159 @@
- 第一次学 ROS2,想从 0 到能搭一个完整机器人项目
- 想**深耕具身智能**(机器人 + VLA),需要把 ROS2 通信栈 + TF2 + URDF + Vision 一次打通
- 想在 Windows 本机用 venv + VSCode/PyCharm 写 Python,在 Docker/WSL Linux 里跑 ROS2
- 想在 Windows 本机用 venv + VSCode 写代码,在 Docker Linux 容器跑 ROS2
- 需要一个**教科书级别**的开源仓库作教学/学习参考
## 📦 仓库提供什么
7 个 ROS2 包 + 端到端 demo + 深度文档:
**12 个 ROS2 包 + 80 测试 + 23 篇深度文档 + Make + GitLab CI**:
| 包 | 类型 | 通信模式 | 语言 | 测试 |
| 包 | 类型 | 通信范式 | 语言 | 测试 |
|---|---|---|---|---|
| [`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 |
| [`py_pubsub`](src/py_pubsub/) | ament_python | Topic pub/sub | Python | pytest 11/11 ✓ |
| [`cpp_pubsub`](src/cpp_pubsub/) | ament_cmake | Topic pub/sub | C++ | gtest 3/3 ✓ |
| [`py_srv`](src/py_srv/) | ament_python | Service req/resp | Python | pytest 6/6 ✓ |
| [`py_action_demo`](src/py_action_demo/) | ament_python | Action 三件套 | Python | pytest 4/4 ✓ |
| [`cpp_robot_tf2`](src/cpp_robot_tf2/) | ament_cmake | URDF + TF2 | C++ | gtest 4/4 ✓ |
| [`py_vision_demo`](src/py_vision_demo/) | ament_python | sensor_msgs/Image | Python | pytest 11/11 ✓ |
| [`py_params`](src/py_params/) | ament_python | Parameter 系统 | Python | pytest 16/16 ✓ |
| [`cpp_custom_interface`](src/cpp_custom_interface/) | ament_cmake | 自定义 .msg/.srv/.action | C++ | gtest 3/3 ✓ |
| [`py_lifecycle_composable`](src/py_lifecycle_composable/) | ament_python | Lifecycle + Composable | Python | pytest 6/6 ✓ |
| [`cpp_qos_demo`](src/cpp_qos_demo/) | ament_cmake | QoS 9 种组合 | C++ | gtest 4/4 ✓ |
| [`py_overlay_dds`](src/py_overlay_dds/) | ament_python | DDS 配置 + colcon overlay | Python | pytest 6/6 ✓ |
| [`bringup`](src/bringup/) | ament_python | 6 跨包 launch 聚合 | Python | OK |
**合计 10/10 测试 100% 通过**;5 个端到端日志固化在 [`docker/`](docker/)。
**合计 80/80 测试 100% 通过目标**;6 个端到端 demo 启动脚本。
---
## 🚀 30 秒上手
## 🚀 5 分钟上手(Makefile)
### Windows 本机(开发)
```bash
# 一键创建 venv(不污染系统 Python)
powershell .\tools\setup_venv.ps1
.\.venv\Scripts\Activate.ps1
# 1. 构建镜像(首次 5-10 分钟)
make build
# 打开 VSCode / PyCharm
code D:\xs\ros2
# 2. 启动容器
make up
# 3. 容器内 build 12 包
make colcon-build
# 4. 跑所有测试
make colcon-test
# 5. 进入开发终端
make shell
# 6. 启动 11 节点 full_demo
make full-demo
```
### Docker 容器(运行 + 测试)
```powershell
# 第一次:构建 + 启动 + 编译 + 进入开发终端
powershell D:\xs\ros2\start.ps1
等价手动命令(`make` 不可用时):
# 后续:重启即用
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"
```bash
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/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 │ │
│ └─────────────────────────────┘ │
└──────────────────────────────────────────┘
┌──────────────────────────────────────────┐
│ 本机 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 来源,共享给所有用户)
详细架构见 [`doc/00-overview.md`](doc/00-overview.md)。
---
- **本机层**: venv 装开发工具(runtime 隔离),IDE 直接读源码
- **容器层**: colcon 装 ROS2 节点(apt 来源,共享给所有用户)
## 🎬 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 个节点同时运行** |
| 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+ 节点同时运行** |
固化日志:[`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)
---
## 📚 文档导航
## 📚 23 篇文档导航
### 上手
- [`doc/00-overview.md`](doc/00-overview.md) — 项目架构 + 设计取舍
- [`doc/00-levels.md`](doc/00-levels.md) — Level 1-4 学习路线(ROS2 → 机械臂 → VLA)
- [`doc/01-quickstart.md`](doc/01-quickstart.md) — 5 分钟跑通
- [`doc/02-virtualenv.md`](doc/02-virtualenv.md) — venv 工作流(本机不污染)
- [`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/15-params.md`](doc/15-params.md) — Parameter 系统深度 ⭐
- [`doc/16-custom-interfaces.md`](doc/16-custom-interfaces.md) — 自定义 msg/srv/action ⭐
- [`doc/17-lifecycle.md`](doc/17-lifecycle.md) — Lifecycle Node ⭐
- [`doc/18-composable.md`](doc/18-composable.md) — Composable Node ⭐
- [`doc/19-qos.md`](doc/19-qos.md) — QoS 全解 ⭐
- [`doc/20-bag.md`](doc/20-bag.md) — ros2 bag ⭐
- [`doc/21-overlay-dds.md`](doc/21-overlay-dds.md) — DDS + colcon overlay ⭐
### 机器人专属
- [`doc/50-tf2.md`](doc/50-tf2.md) — 坐标变换(VLA/抓取/对齐的基石)
- [`doc/50-tf2.md`](doc/50-tf2.md) — 坐标变换
- [`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/90-testing.md`](doc/90-testing.md) — 测试金字塔
- [`doc/CODING_STYLE.md`](doc/CODING_STYLE.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
- [`doc/99-embodied-ai.md`](doc/99-embodied-ai.md) — VLA / 机器人开发路线图
- [`doc/100-embedded-deployment.md`](doc/100-embedded-deployment.md) — **三机部署实操**
---
## 🗺 入门具身智能路径
## 🗺 入门具身智能的路径
本仓库完成后,做 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)。
---
| ✅ 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`](AGENTS.md),核心几条:
代码风格 / 构建约束全部在 [`AGENTS.md`](AGENTS.md) + [`doc/CODING_STYLE.md`](doc/CODING_STYLE.md),核心几条:
1. **本机 venv 不污染系统 Python**(用 `tools/setup_venv.{sh,ps1}`)
2. 容器内用 colcon + ament(ROS2 官方工具链)
3. 跨包 launch 用 `IncludeLaunchDescription` + `FindPackageShare`
4. 包名不能叫 `launch`(与 ROS2 系统包同名会冲突)
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 篇深度文档
```
---
6. **不修改全局 git config** — 用 `git -c user.name=x -c user.email=y` 临时设
## 🤝 致谢
- [ROS2 官方文档](https://docs.ros.org/en/humble/)
- [REP-2000: ROS 2 Design](https://www.ros.org/reps/rep-2002.html)
- [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` 部署。