xsROS2 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 |
ament_python | Topic pub/sub | Python | pytest 4/4 ✓ |
cpp_pubsub |
ament_cmake | Topic pub/sub | C++ | gtest 2/2 ✓ |
py_srv |
ament_python | Service req/resp | Python | pytest 1/1 ✓ |
py_action_demo |
ament_python | Action 三件套 | Python | pytest 1/1 ✓ |
cpp_robot_tf2 |
ament_cmake | TF2 + URDF + JointState | C++ | gtest 2/2 ✓ |
py_vision_demo |
ament_python | sensor_msgs/Image | Python | pytest 2/2 ✓ |
bringup |
ament_python | launch 聚合 | Python | OK |
合计 10/10 测试 100% 通过;5 个端到端日志固化在 docker/。
🚀 30 秒上手
Windows 本机(开发)
# 一键创建 venv(不污染系统 Python)
powershell .\tools\setup_venv.ps1
.\.venv\Scripts\Activate.ps1
# 打开 VSCode / PyCharm
code D:\xs\ros2
Docker 容器(运行 + 测试)
# 第一次:构建 + 启动 + 编译 + 进入开发终端
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。
🎬 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/srv_e2e.log · docker/robot_e2e.log · docker/vision_e2e.log · docker/full_demo_e2e.log
📚 文档导航
上手
doc/00-overview.md— 项目架构 + 设计取舍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/50-tf2.md— 坐标变换(VLA/抓取/对齐的基石)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/99-embodied-ai.md— VLA / 机器人开发路线图(从本仓库出发到部署)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。
🛠 项目约定(必读)
代码风格 / 构建约束全部在 AGENTS.md,核心几条:
- 本机 venv 不污染系统 Python(用
tools/setup_venv.{sh,ps1}) - 容器内用 colcon + ament(ROS2 官方工具链)
- 跨包 launch 用
IncludeLaunchDescription+FindPackageShare - 包名不能叫
launch(与 ROS2 系统包同名会冲突) - 测试 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 之旅:doc/01-quickstart.md → 跑通 → 读 doc/10-concepts.md 深入 → 上 doc/99-embodied-ai.md 部署。