ros2-engineering-skills

全面的 ROS 2 工程指南，涵盖工作空间设置、节点架构、 通信模式（具有 QoS 的主题/服务/操作）、生命周期和组件节点， 发射组合、tf2/URDF、ros2_control 硬件接口、实时约束、 Nav2、MoveIt 2、感知管道、模拟 (Gazebo/Isaac Sim)、安全 (SROS2/DDS)、 微型 ROS (MCU/RTOS)、多机器人系统（车队管理/Open-RMF）、 测试、调试、部署和 ROS 1 迁移。 每当用户处理 ROS 2 代码、包、启动文件、URDF/xacro、 DDS 配置、ros2_control、Nav2、MoveIt 2 或任何机器人中间件任务 涉及rclcpp、rclpy、colcon、ament、rosbag2、ros2 CLI工具、Gazebo/Isaac Sim、 micro-ROS、SROS2 或多机器人协调。还触发 ROS 1 到 ROS 2 的迁移， 交叉编译、基于 Docker 的 ROS 2 工作流程以及机器人的 CI/CD。

## 概述（中文）

全面的 ROS 2 工程指南，涵盖工作空间设置、节点架构、
通信模式（具有 QoS 的主题/服务/操作）、生命周期和组件节点，
发射组合、tf2/URDF、ros2_control 硬件接口、实时约束、
Nav2、MoveIt 2、感知管道、模拟 (Gazebo/Isaac Sim)、安全 (SROS2/DDS)、
微型 ROS (MCU/RTOS)、多机器人系统（车队管理/Open-RMF）、
测试、调试、部署和 ROS 1 迁移。
每当用户处理 ROS 2 代码、包、启动文件、URDF/xacro、
DDS 配置、ros2_control、Nav2、MoveIt 2 或任何机器人中间件任务
涉及rclcpp、rclpy、colcon、ament、rosbag2、ros2 CLI工具、Gazebo/Isaac Sim、
micro-ROS、SROS2 或多机器人协调。还触发 ROS 1 到 ROS 2 的迁移，
交叉编译、基于 Docker 的 ROS 2 工作流程以及机器人的 CI/CD。

## 原文

# ROS 2 Engineering Skills

A progressive-disclosure skill for ROS 2 development — from first workspace to
production fleet deployment. Each section below gives you the essential decision
framework; detailed patterns, code templates, and anti-patterns live in the
`references/` directory. Read the relevant reference file before writing code.

## How to use this skill

1. Identify what the user is building (see Decision Router below).
2. Read the matching `references/*.md` file for detailed guidance.
3. Apply the Core Engineering Principles in every piece of code you generate.
4. When multiple domains intersect (e.g. Nav2 + ros2_control), read both files.

## Decision router

| User is doing...                                  | Read                              |
|---------------------------------------------------|-----------------------------------|
| Creating a workspace, package, or build config    | `references/workspace-build.md`   |
| Writing nodes, executors, callback groups         | `references/nodes-executors.md`   |
| Topics, services, actions, custom interfaces, QoS | `references/communication.md`     |
| Lifecycle nodes, component loading, composition   | `references/lifecycle-components.md` |
| Launch files, conditional logic, event handlers   | `references/launch-system.md`     |
| tf2, URDF, xacro, robot_state_publisher           | `references/tf2-urdf.md`         |
| ros2_control, hardware interfaces, controllers    | `references/hardware-interface.md` |
| Real-time constraints, PREEMPT_RT, memory, jitter | `references/realtime.md`         |
| Nav2, SLAM, costmaps, behavior trees              | `references/navigation.md`       |
| MoveIt 2, planning scene, grasp pipelines         | `references/manipulation.md`     |
| Camera, LiDAR, PCL, cv_bridge, depth processing   | `references/perception.md`       |
| Unit tests, integration tests, launch_testing, CI | `references/testing.md`          |
| ros2 doctor, tracing, profiling, rosbag2          | `references/debugging.md`        |
| Docker, cross-compile, fleet deployment, OTA      | `references/deployment.md`       |
| Gazebo, Isaac Sim, sim-to-real, use_sim_time      | `references/simulation.md`       |
| SROS2, DDS security, certificates, supply chain   | `references/security.md`         |
| micro-ROS, MCU/RTOS, XRCE-DDS, rclc              | `references/micro-ros.md`        |
| Multi-robot fleet, Open-RMF, DDS discovery scale  | `references/multi-robot.md`      |
| Message types, units, covariance, frame conventions | `references/message-types.md`    |
| ROS 1 migration, ros1_bridge, hybrid operation    | `references/migration-ros1.md`   |

When a task spans multiple domains, read all relevant files and reconcile
conflicting recommendations by favoring safety, then determinism, then simplicity.

**Cross-cutting concern — Security:** Security is not isolated to `references/security.md`.
Every domain should consider its security implications: hardware interfaces need safe
shutdown on auth failure, DDS topics may need encryption, deployment images need supply
chain verification, and fleet communication must use TLS. When reviewing code in any
domain, check whether the data path crosses a trust boundary.

## Core engineering principles

These apply to every ROS 2 artifact you produce, regardless of domain.

### 1. Distro awareness

Always ask which ROS 2 distribution the user targets. Key differences:

| Feature                   | Foxy (**EOL**)       | Humble (LTS)       | Jazzy (LTS)        | Kilted (non-LTS)   | Rolling            |
|---------------------------|----------------------|--------------------|--------------------|--------------------|--------------------|
| EOL                       | Jun 2023 (**ended**) | May 2027           | May 2029           | Nov 2025           | Rolling            |
| Ubuntu                    | 20.04               | 22.04              | 24.04              | 24.04              | Latest             |
| Default DDS               | Fast DDS             | Fast DDS           | Fast DDS           | Fast DDS           | Fast DDS           |
| Zenoh support             | —                    | —                  | —                  | Tier 1             | Tier 1             |
| Type description support  | No                   | No                 | Yes                | Yes                | Yes                |
| Service introspection     | No                   | No                 | Yes                | Yes                | Yes                |
| EventsExecutor            | No                   | No                 | Experimental       | Stable (+ rclpy)   | Stable (+ rclpy)   |
| Default bag format        | sqlite3              | sqlite3            | MCAP               | MCAP               | MCAP               |
| ros2_control interface    | N/A (separate)       | 2.x                | 4.x                | 4.x                | Latest             |
| CMake recommendation      | ament_target_deps    | ament_target_deps  | either             | target_link_libs   | target_link_libs   |

When the user does not specify, default to the latest LTS (Jazzy).
Pin the exact distro in Dockerfile, CI, and documentation so builds are reproducible.

### 2. C++ vs Python decision

Choose the language based on the node's role, not personal preference.

**Use rclcpp (C++) when:**
- The node sits in a control loop running ≥100 Hz
- Deterministic memory allocation matters (real-time path)
- The node is a hardware driver or controller plugin
- Intra-process zero-copy communication is required

**Use rclpy (Python) when:**
- The node is orchestration, monitoring, or parameter management
- Rapid prototyping with frequent iteration
- Heavy use of ML frameworks (PyTorch, TensorFlow) that are Python-native
- The node does not sit in a latency-critical path

**Mixed stacks are normal.** A typical robot has C++ drivers/controllers and Python
orchestration/monitoring. Note: `component_container` (composition) only loads
C++ components via pluginlib. Python nodes run as separate processes, but can
share a launch file and communicate via zero-overhead intra-host DDS.

**Intra-process communication** works for any nodes sharing a process — not only
composable components. Any nodes instantiated in the same process with
`use_intra_process_comms(true)` can use zero-copy transfer.

### 3. Package structure conventions

Every package should follow this layout. Consistency across a workspace reduces
onboarding time and makes CI scripts portable.

```
my_package/
├── CMakeLists.txt          # or setup.py for pure Python
├── package.xml             # format 3, with <depend> tags
├── config/
│   └── params.yaml         # default parameters
├── launch/
│   └── bringup.launch.py   # Python launch file
├── include/my_package/     # C++ public headers (if library)
├── src/                    # C++ source files
├── my_package/             # Python modules (if ament_python or mixed)
├── test/                   # gtest, pytest, launch_testing
├── urdf/                   # URDF/xacro (if applicable)
├── msg/ srv/ action/       # custom interfaces (dedicated _interfaces package preferred)
└── README.md
```

Separate interface definitions into a `*_interfaces` package so downstream
packages can depend on interfaces without pulling in implementation.

### 4. Parameter discipline

- Declare every parameter with a type, description, range, and default
  in the node constructor — never use undeclared parameters.
- Use `ParameterDescriptor` with