本文采用知识共享署名 4.0 国际许可协议进行许可，转载时请注明原文链接，图片在使用时请保留全部内容，可适当缩放并在引用处附上图片所在的文章链接。

[TOC]

RCL = ROS Client

RMW = ROS Middleware

rosidl = ROS Interface Definition Language （接口语言定义）

1
2
3
4
5
6
7
8
9

rclcpp / rclpy
      ↓
     rcl
      ↓
     rmw  ← 抽象接口层
      ↓
rmw_fastrtps_cpp / rmw_cyclonedds_cpp / ...
      ↓
   Fast DDS / Cyclone DDS / ...

1
2
3
4
5
6
7

rclcpp::Publisher<T>::publish(msg)
↓
rcl_publish(...)
↓
rmw_publish(...)
↓
fastdds_writer->write(...)

内部API架构

ROS Interface Definition Language

rosidl 是 ROS 2 中用来 定义消息（msg）、服务（srv）、动作（action）接口的标准机制。它支持生成跨多种编程语言（C/C++/Python/Java等）的接口代码。

工作流程

1. 定义接口 例如：

   1 2	std_msgs/String.msg string data

2. 用 rosidl 工具解析并生成目标语言的代码 CMake 中配置 rosidl_generate_interfaces()，自动生成对应语言的支持文件。

3. ament_export_dependencies(rosidl_default_runtime) : 告诉其他依赖这个包的下游包，它们在构建时也需要依赖 rosidl_default_runtime

   rosidl_default_runtime 是一个 虚拟依赖包，内部包含了所有目标语言所需的运行时支持，比如：

   • rosidl_runtime_c : C 语言的消息运行时支持 用 rcl 层处理 msg/srv

   • rosidl_runtime_cpp: C++ 消息支持结构 rclcpp 节点用自定义消息

   • rosidl_runtime_py: Python 动态导入支持 rclpy 使用消息时

   • builtin_interfaces ： ROS 2 标准内建消息类型集合，类似于 ROS 1 中的 std_msgs 基础支持包。

     • builtin_interfaces/Time：表示 ROS 时间
     • builtin_interfaces/Duration：表示时间间隔
     • builtin_interfaces/String, Bool, Int32 等都在 std_msgs，但 Time/Duration 是内建的，直接由中间件支持。

   • unique_identifier_msgs ：用于表示唯一 ID 的标准消息类型包，常用于 action、跟踪、标识对象等。

     • unique_identifier_msgs/UUID：标准 UUID 表示（16字节）

       1	uint8[16] uuid

4. 在应用中引用 在 C++ 中使用 std_msgs::msg::String，或 Python 中使用 std_msgs.msg.String。

🎯 rosidl 的设计目标：

• ✅ 支持多种语言（C、C++、Python、Java等）
• ✅ 支持多种类型支持库（type support：FastRTPS、Connext、Cyclone DDS 等）
• ✅ 模块化生成器架构（便于扩展新语言/类型支持）

ROS 2 rcl 层：核心功能与能力综述

rcl (ROS Client Library) 是 ROS 2 客户端库架构中的核心抽象层，它提供了一套C 语言 API，旨在为所有上层语言客户端库（如 rclcpp 和 rclpy）提供统一、稳定且隔离于底层通信中间件（DDS）的接口。rcl 的存在是实现 ROS 2 跨语言和模块化设计的关键。

rcl 的功能可以归纳为以下五个核心模块：

1. 上下文和初始化管理 (Context and Initialization)

rcl 是 ROS 2 进程的起点，负责建立和管理整个运行环境的状态。

• 环境构建： rcl_init 是核心的初始化函数。它接收命令行参数，处理 ROS 2 的特殊参数和重映射规则，并完成运行环境的设置。
• 状态容器： rcl_context_t 结构体承载着 ROS 2 运行环境的全部状态，包括初始化选项、参数解析结果和当前 ROS 2 实例的状态等。
• 资源清理： rcl_shutdown 负责在进程结束时优雅地清理和终止 rcl 上下文，释放所有相关资源。

2. 节点管理 (Node Management)

rcl 提供了创建和管理 ROS 2 基本通信单元——节点的机制。

• 节点实体： rcl_node_t 是承载一个 ROS 2 节点实体的 C 结构体。它包含节点的名称、命名空间、日志配置等元数据信息。
• 节点注册： rcl_node_init 用于初始化一个节点实例，并将其注册到 ROS 2 图 (Graph) 中，使其能够被其他节点发现和通信。

3. 通信原语 (Communication Primitives)

这是 rcl 最核心的能力，它抽象并提供了 ROS 2 中所有的基础通信模式。

4. 等待与并发 (Waiting and Concurrency)

为了实现高效的事件驱动编程，rcl 提供了等待多个并发事件的机制。

• 事件集合： rcl_wait_set_t 是核心的等待集结构。它允许单个线程同时监听多个通信事件（如订阅数据到达、服务请求、定时器到期等）。
• 阻塞等待： rcl_wait 函数是阻塞式的。它会暂停执行，直到等待集中至少有一个事件发生。这是上层 rclcpp 执行器 (Executor) 实现高效并发的基础。

5. RMW 抽象和 DDS 解耦

rcl 扮演了 ROS 2 客户端和通信中间件之间的关键桥梁，是实现通信模块化和可插拔性的基石。

• 中间件接口： rcl 内部调用 RMW (ROS Middleware Interface) 层的 API。RMW 负责将 rcl 的通用请求（例如，创建一个话题订阅）转化为特定 DDS 实现（如 Fast RTPS, Cyclone DDS）的 API 调用。
• 隔离效应： 这种设计使得 rcl 的用户（以及上层的 rclcpp 开发者）无需关心底层使用的是哪种 DDS。开发者只需要编写一次代码，就可以在不同的通信中间件上运行。

Topic 发送驱动的任务调度过程

整个过程可以被分解为以下六个主要阶段：/

阶段 1：消息到达 (Message Arrival)

1. 发布 (Publish)：某个节点使用其发布者 (rclcpp::Publisher) 向特定 Topic 发送一条消息。
2. RMW 传输：消息被 ROS 2 的中间件层 (RMW) 传输到接收节点。
3. 底层标记就绪：消息到达接收节点的底层 RMW 订阅句柄（Subscription Handle）。RMW 层将该订阅句柄标记为**“就绪”**（Ready），意味着它有待处理的数据。

阶段 2：等待集阻塞与唤醒 (Wait Set Blocking and Wakeup)

执行器的大部分时间都阻塞在 rcl_wait() 调用中。

1. 阻塞 (rcl_wait())：执行器线程在 Executor::wait_for_work() 函数内部调用底层 rcl_wait()，等待任何一个可等待实体（包括订阅、定时器、守护条件等）就绪。
2. 唤醒 (Wakeup)：当消息到达后，RMW 层标记底层订阅句柄就绪。rcl_wait() 接收到信号（通常通过系统级的 I/O 多路复用机制，如 epoll 或 poll），从而解除阻塞并返回。

阶段 3：执行器发现就绪实体 (Executor Discovers Ready Entity)

rcl_wait() 返回后，执行器开始查找是哪个实体导致了唤醒。

1. 清除空句柄：执行器首先调用 memory_strategy_->remove_null_handles()，检查等待集中哪些句柄真的有事件发生，并清理掉虚假唤醒（spurious wakeup）或已失效的句柄。
2. 获取下一个可执行实体 (get_next_ready_executable)：执行器进入 Executor::get_next_ready_executable() 循环，查找可执行实体。对于 Topic 首发的情况，它会：
   • 跳过定时器：首先检查定时器（因为定时器有最高的调度优先级），如果定时器没到期则跳过。
   • 检查订阅者：调用 memory_strategy_->get_next_subscription()。内存策略会检查等待集中就绪的订阅句柄，并将其封装成一个 AnyExecutable 结构体。
3. 识别回调组和互斥性：
   • AnyExecutable 现在包含了就绪的订阅者、其所在的回调组以及关联的节点信息。
   • 执行器检查该回调组的类型：
     • 如果回调组是 MutuallyExclusive（互斥）：执行器会通过原子操作将其内部的 can_be_taken_from 标志设置为 false。这会阻止任何其他线程从该组中取出任务，直到当前任务完成。
     • 如果是 Reentrant（可重入）：不做限制。

阶段 4：执行回调 (execute_any_executable)

找到任务后，执行器进入 Executor::execute_any_executable()。

1. 分派给线程：对于 SingleThreadedExecutor，它会在主线程上立即执行。对于 MultiThreadedExecutor，它会将 AnyExecutable 放入一个队列，并由线程池中的一个空闲工作线程取出执行。
2. 消息接收 (execute_subscription)：执行 Executor::execute_subscription() 函数：
   • 它调用订阅者的 take_type_erased()（或 take_serialized / take_loaned_message）方法，从 RMW 层拉取 (Pull) 消息数据。
   • 成功拉取消息后，订阅句柄在 RMW 层再次变回“未就绪”状态。
3. 用户回调执行：一旦获得消息，订阅者句柄就会调用用户的回调函数 (subscription->handle_message(...))，传入拉取到的消息数据。
4. 计算阻塞：用户回调开始执行。回调的执行时间是任务调度的主要瓶颈：如果回调运行时间过长，它会占用执行器线程，并可能阻塞其他事件。

阶段 5：回调组解锁与清理

用户回调函数执行完毕后，执行器完成收尾工作：

1. 回调组解锁：
   • 如果该回调组是互斥的，执行器会通过原子操作将回调组的 can_be_taken_from 标志重置回 true。这使得该组中的其他就绪任务现在可以被其他线程获取。
2. 清理消息：如果消息是借出 (LoanedMessage) 的，则将其归还。

阶段 6：通知与下一轮循环

1. 触发中断条件：执行器会调用 interrupt_guard_condition_.trigger()。
2. 目的：这个触发操作是为了唤醒所有可能阻塞在 rcl_wait() 中的其他执行器线程（特别是在多线程执行器中），通知它们：
   • 回调组已被释放（有新的工作可用）。
   • 需要重新计算最短的定时器超时时间（如果回调修改了定时器）。
3. 下一轮：执行器线程（无论是主线程还是线程池中的工作线程）完成当前任务后，会返回 spin() 循环的起始，重新开始下一轮 等待-发现-执行 的调度过程。

总结：

Topic 消息的调度是一个典型的事件驱动流程：消息的到达触发了阻塞的等待集，执行器被唤醒并拉取消息，最终在合适的线程（受回调组规则约束）上执行用户回调。回调组和 原子锁 是实现并发性和线程安全的关键，而 rcl_wait() 则是实现效率的核心。

rcl

下面我结合 ROS2 官方文档、社区资料，以及你给出的 rcl 仓库（humble 分支）来给你比较系统、深入地介绍一下 rcl（ROS Client Library core / ROS 客户端库核心）的功能、定位、模块结构、设计原则以及在 ROS2 架构中的角色。

如果你后来还想深入源码（某个模块、接口、实现细节）我也可以陪你一起看。

一、rcl 在 ROS2 架构中的位置与角色

1. 为什么要有 rcl？

• 在 ROS1 中，不同语言（C++、Python 等）的客户端库（roscpp、rospy）几乎是各自实现的，很多功能在各个语言库里重复实现，导致行为不一致、维护成本高。
• ROS2 的目标之一是语言无关、功能一致。于是引入一个公共的、语言中立的核心客户端库层，即 rcl，用 C 语言（或 C 接口）实现 ROS 的核心功能，让各语言客户端库（如 rclcpp、rclpy、rclc、rclrs 等）去调用它，从而保证行为一致性、减少重复实现。 docs.ros.org+2index.ros.org+2
• rcl 本身并不直接依赖特定中间件（DDS 实现等），它会通过更下层的 rmw（ROS Middleware Interface）来调用具体中间件提供者。换句话说，rcl 是介于 语言客户端库（如 rclcpp、rclpy）和 rmw / DDS 实现 之间的一层抽象。 docs.ros.org+2index.ros.org+2

所以在 ROS2 的调用栈里，可以抽象为：

1
2
3
4

用户代码（用 rclcpp, rclpy, rclrs 等）  
→ rcl （核心 C 接口实现公共行为）  
→ rmw 接口（中间件抽象层）  
→ 具体中间件实现（如 rmw_fastrtps, rmw_cyclonedds, etc.）

rcl 还负责管理 ROS 图（graph）、节点、主题、服务、生命周期、参数、定时器等基本概念的公共逻辑。

2. 在 rcl 仓库中的组成

在你给的仓库 https://github.com/ros2/rcl/tree/humble 中，可以看到它包含多个子包 / 子目录：

• rcl：核心包，实现主要的 ROS 客户端功能
• rcl_action：Action 的支持
• rcl_lifecycle：节点生命周期管理
• rcl_yaml_param_parser：用 YAML 解析 ROS 参数文件
• 以及一些元数据（如 CMakeLists、README 等） GitHub

也就是说，除了基本的 publisher/subscription、服务 / 客户端、节点管理，那些扩展机制（action、生命周期、参数 YAML 解析等）都被划分为子模块，以保持核心的清晰和模块化。

二、rcl 的主要功能 / 模块

下面我按功能模块来拆解 rcl 支持的特性，以及核心 API 的作用：

下面我分别稍微展开一些关键模块的细节。

2.1 初始化 / 支持结构

• rcl_init()：在使用 ROS 通信资源之前，必须进行初始化。rcl 会处理启动参数（例如 remapping、ROS_DOMAIN_ID、日志级别等）并设置内部结构。
• rcl_init_options_t：初始化时可以指定内存分配器、域 ID（domain_id）、上下文、是否要捕获 SIGINT 等。
• rcl_shutdown()：关闭 ROS 通信，清理资源。
• 这些结构使得多个节点可以在同一个进程中共存（即可以有多个 node 实例共用一个 rcl 上下文）或者在不同上下文中分开。

2.2 Node 管理

Node 是 ROS 的基本参与者概念。rcl 在这一层管理节点的生命周期与属性。

• rcl_node_init()：初始化节点，需要指定节点名称、命名空间、节点选项（可以包含 remapping 规则、记分 allocators 等）
• rcl_node_fini()：析构节点，释放其资源
• 节点可以进行重映射（remap rules）以改变 topic / service / 参数名字
• 节点名称与命名空间的标准化、检查合法性、命名冲突处理等逻辑都在这里统一进行

2.3 Publisher / Subscription

这是 ROS 通信的基础。

• 在 rcl 层，是通过调用底层的 rmw 接口来创建 publisher / subscription。rcl 层必须把客户端库层（rclcpp / rclpy）传入的 QoS 设置、消息类型信息、topic 名称等翻译成 rmw 层可识别的形式
• rcl_publisher_init()、rcl_subscription_init()：初始化对应结构
• 发布消息：rcl_publish()、序列化、传递给 rmw 层
• 接收消息：rcl 会配合 rcl_wait() / rcl_wait_set_t 等机制，以轮询方式等待新的消息到来，然后从底层拿消息、触发回调
• 支持多种 QoS 策略（例如可靠 / 最佳努力、历史深度、延迟 / 丢失策略等），这些在 rcl 层统一处理或检查一致性

2.4 服务 / 客户端

ROS 的请求-响应机制：

• 客户端（Client）发起请求，请求被发送到服务端（Service），然后服务端返回响应
• 在 rcl 层，rcl_client_init() / rcl_service_init() 用于初始化客户端 / 服务端
• 客户端可以通过 rcl_send_request() 发请求；服务端则 rcl_take_request() 提取请求、处理、再 rcl_send_response()
• rcl 层还负责管理请求 ID、内存管理、请求超时、并发、队列深度等控制逻辑

2.5 Timer / Wait Set / 回调触发机制

ROS 节点不仅仅响应消息，还可能有定时任务、事件触发等。

• rcl 提供 rcl_timer_t：可注册定时器，每当定时器触发时，将对应回调排入待执行队列。
• rcl 引入 Wait Set 机制，即 rcl_wait_set_t，它封装了一系列等待条件（subscription 可读、service 请求、客户端响应、定时器触发、guard conditions 等），rcl 会把它们包装在一个统一的等待集合里，然后调用 rcl_wait()（通常底层对应系统调用 / 中间件等待）来等待多个事件中的任意一个发生
• 当 rcl_wait() 返回后，rcl 会遍历 wait set 中每一个触发事件（subscription、timer、service 等），对它们分别做 take / invoke 回调 /发送响应等操作
• 这个设计使得 ROS 节点内部可以使用统一的等待 / 调度机制，不必为每一种事件类型写不同的等待逻辑

2.6 Graph / Introspection 支持

为了支持运行时监控、节点拓扑查看、主题 / 节点 /连接状态，rcl 提供一些接口：

• rcl_get_topic_names_and_types()：返回系统中所有 topic 名字 + 类型
• rcl_count_publishers() / rcl_count_subscribers()：查询某个 topic 上的 publisher / subscriber 数量
• Graph changes 事件：当网络拓扑（节点加入 / 退出 / 主题连接变化）发生时，可以触发“graph event”，让客户端库层（如 rclcpp）有机会收到通知或更新其本地缓存
• 这些功能使得客户端层可以构建更高级的 introspection、可视化工具（如 ros2 topic list、ros2 node list 等命令）

2.7 参数系统

参数是 ROS 节点中非常常用的机制，用于节点配置（例如控制频率、阈值等）。

• rcl 支持统一的参数接口：rcl_set_parameter()、rcl_get_parameter()、rcl_set_parameters()（批量设置）、参数回调（当某些参数被更改时触发）
• 参数验证、类型约束、参数命名的规则检查等逻辑都在 rcl 层实现
• 还支持将参数从 YAML 文件加载（借助 rcl_yaml_param_parser）
• 这样，不论在 C++、Python、Rust 等客户端库中操作参数，都能获得一致的行为

2.8 生命周期节点

这是 ROS2 的一种可控节点机制（状态机式管理节点生命周期状态）。

• 在 rcl_lifecycle 子包中，rcl 提供对以下状态的支持：如 unconfigured、inactive、active、finalized、shutting_down 等
• 提供切换状态的机制（configuration、activation、deactivation、shutdown、cleanup 等）
• 允许节点在不同状态阶段初始化/释放资源、对外服务 / topic 发布行为限制等
• 客户端库（如 rclcpp 的 rclcpp_lifecycle）会在此基础上给出更友好接口

2.9 Action 支持

Action 是一种比服务更复杂、可反馈、可取消、可预占的交互机制。rcl 在其子包 rcl_action 中提供支持。

• rcl_action 提供目标 (Goal) 接口、反馈 (Feedback)、结果 (Result) 的抽象
• 支持取消目标（preemption）、超时、多个并发目标、状态跟踪（accepted, executing, canceled, succeeded 等）
• 将复杂的状态机、消息流、回调逻辑整合在 rcl 层，使得客户端库可以较为简单地封装 action 接口

2.10 YAML 参数解析

• rcl_yaml_param_parser 子模块负责把 YAML 文件（通常是 ROS 的参数配置文件 / launch 文件中指定的参数）解析成内部 rcl 参数结构
• 它处理 YAML 中的节点名、命名空间、类型、默认值、参数 validation 规则等

三、设计原则与特色

在理解 rcl 的功能之外，理解其设计思想与特性也很重要：

1. 语言中立 / 接口统一 rcl 使用纯 C 接口，这样各种语言（C++、Python、Rust、C# 等）都可以比较容易地包装绑定。通过统一的核心层，不同语言的客户端库行为更一致。 docs.ros.org+2docs.ros.org+2
2. 中间件无关 rcl 自己并不直接依赖特定的中间件（如 Fast DDS、Cyclone DDS 等）。它通过 rmw 接口抽象中间件层（ROS Middleware Interface）。这样 ROS2 可以支持多种 DDS 实现，而且用户代码无需修改。 docs.ros.org+2index.ros.org+2
3. 模块化 / 可扩展 将常见但复杂的机制（如生命周期、action、参数 YAML 解析）拆为子模块，不让核心变得过于臃肿。 这样也使得未来扩展更方便，比如如果要添加新的交互机制，就可以作为插件 / 子模块扩展。
4. 统一错误管理 / 内存管理 所有模块通常都会使用统一的 allocator（内存分配器）、错误码体系、初始化 / 清理规范等，以保证资源安全、避免泄漏、保证一致性。
5. 等待 / 回调驱动模型 rcl 的 event / wait set / 回调触发机制设计，使得节点可以统一地等待多个事件（消息、定时器、服务等），简化客户端库层（语言层）设计。
6. 高度抽象但不过度封装 rcl 一方面提供较高层次的、统一的 ROS 概念（节点、topic、service、action、参数等），另一方面它保留一定的灵活性，不把所有操作都封死，以便高级用户或语言客户端可以对某些行为做优化或扩展。

四、rcl 在 Humble 版本中的特点 & 注意事项

（基于你提供的 humble 分支仓库）

• rcl 在 Humble 中仍然继承上述核心设计，并继续被用于 ROS2 Humble 发布版本
• 一些模块（如 rcl_action、rcl_lifecycle、rcl_yaml_param_parser）在这个分支里是并列子包，清晰分隔
• 在 rcl_action 模块中，有质量声明（Quality Declaration）来表明其代码质量、性能测试要求等。 GitHub
• rcl 包在 ROS2 项目中是 质量等级 1（Quality Level 1） 的包（High quality / production-level） index.ros.org+1
• 代码库中已有很多测试、性能验证、静态分析工具支持，以保证稳定性
• Humble 分支可能针对新的特性、bug 修复有增量改动（包括内存安全、边界条件处理等），而这些改动都是在 rcl 的公共逻辑层进行的
• 在 rcl 的仓库里，你可以看到各子模块的实现细节（头文件、C 源代码）——如果你愿意，我们可以一起挑一个模块看它的具体实现。

五、举例：用 rcl（经 rclcpp / rclpy ）的流程（简化视角）

为了更好理解 rcl 功能在实际使用时是如何被客户端库调用的，下面给一个典型的流程（以 “发布-订阅” 为例）：

1. 客户端库（rclcpp）调用 rcl_init() 初始化上下文。
2. rclcpp 调用 rcl_node_init() 初始化一个 node。
3. rclcpp 构造一个 publisher，内部调用 rcl_publisher_init()，rcl 会根据给定 topic 名称、消息类型、QoS 等初始化 publisher，并注册到底层 rmw。
4. rclcpp 构造一个 subscription，内部调用 rcl_subscription_init()，同样设置 topic / QoS / 回调。
5. 在执行阶段，rclcpp 启动一个 spin loop —— 本质上会调用 rcl_wait()（或封装好的 spin 函数），等待 subscription 可读 / 定时器 / service 等事件。
6. 当消息到达时，底层 rmw 通知，rcl 的 wait set 触发 subscription，可调用 rcl_take() 拿消息数据，反序列化、封装，然后把它交给 rclcpp 的回调函数。
7. 如果发布，rclcpp 将消息序列化传入 rcl 的 rcl_publish()，再经由 rmw 传出去。
8. 最终，节点退出时，rclcpp 会调用 rcl_shutdown() / rcl_node_fini() / rcl_publisher_fini() / rcl_subscription_fini() 等清理资源。

这样，客户端库层无需关心具体中间件、等待机制、序列化细节、错误管理等，都由 rcl 层统一处理。

六、rcl 的限制 / 注意点 /挑战

虽然 rcl 做得很优秀，但在实践中也有一些需要注意或限制的地方：

• rcl 抽象层设计需要兼顾灵活性与封装，有时某些极端或性能敏感需求可能绕过 rcl（但这破坏了跨语言一致性）
• 在高性能场景下，序列化 / 反序列化、回调调度、内存分配、等待机制等都可能成为瓶颈。客户端库有时候需要做优化（例如内存池、零拷贝）
• rcl 的错误管理 / 生命周期管理比较严格，使用者需要理解其初始化 / 清理顺序，避免资源泄漏或未定义行为
• 客户端库必须严格按照 rcl 的契约（API 约定）来使用，否则可能引起兼容性 / 稳定性问题
• 部分中间件特性（如某些 DDS vendor 的特殊扩展）可能超出 rcl 抽象层能力，需要在更底层（rmw 或 vendor 接口层）做扩展

🌟 rcl_action —— Action 客户端/服务支持层

一、背景与作用

ROS 2 的 Action 是一种比 Service 更复杂的交互机制：

• Service：一次请求 + 一次响应，适合短任务。
• Action：适合执行时间较长、可反馈、可取消的任务（例如“导航到目标点”、“机械臂移动”）。

rcl_action 是 Action 在 rcl 层 的实现，封装了 Action 协议的状态管理、通信（goal、feedback、result、cancel）、与底层 rmw 层交互等。

上层（如 rclcpp_action / rclpy.action）会基于它实现更友好的类接口。

二、rcl_action 架构与组成

源码路径：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

rcl/rcl_action/
├── include/rcl_action/
│   ├── action_client.h
│   ├── action_server.h
│   ├── graph.h
│   ├── goal_handle.h
│   ├── types.h
│   ├── visibility_control.h
│   └── ...
├── src/rcl_action/
│   ├── action_client.c
│   ├── action_server.c
│   ├── graph.c
│   ├── goal_handle.c
│   └── ...

主要模块：

三、Action 通信机制（在 rcl 层）

Action 通信是通过多个 topic + service 组合实现的：

rcl_action 负责：

• 建立这些通信通道；
• 处理消息序列化 / 反序列化；
• 维护 goal 状态；
• 调度反馈与结果；
• 处理 goal 的取消、超时、完成等逻辑。

四、核心结构与 API

1. Action Client

文件：rcl_action/action_client.h

主要接口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

rcl_ret_t rcl_action_client_init(
  rcl_action_client_t * action_client,
  const rcl_node_t * node,
  const rosidl_action_type_support_t * type_support,
  const char * action_name,
  const rcl_action_client_options_t * options);

rcl_ret_t rcl_action_send_goal_request(
  const rcl_action_client_t * action_client,
  const void * ros_goal_request,
  int64_t * sequence_number);

• rcl_action_client_init()：初始化客户端，绑定节点与 action 名称。
• rcl_action_send_goal_request()：发送一个目标请求（GoalRequest）。
• rcl_action_take_goal_response()：接收服务端返回的 goal_id（是否被接受）。
• rcl_action_take_feedback()：取 feedback topic 中的新反馈。
• rcl_action_send_cancel_request()：发送取消请求。
• rcl_action_take_result_response()：获取任务结果。

客户端通常维护：

• 多个待完成 goal；
• 每个 goal 的状态；
• 对应的 sequence number。

2. Action Server

文件：rcl_action/action_server.h

主要接口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

rcl_ret_t rcl_action_server_init(
  rcl_action_server_t * action_server,
  const rcl_node_t * node,
  const rosidl_action_type_support_t * type_support,
  const char * action_name,
  const rcl_action_server_options_t * options);

rcl_ret_t rcl_action_take_goal_request(...);
rcl_ret_t rcl_action_send_goal_response(...);
rcl_ret_t rcl_action_publish_feedback(...);
rcl_ret_t rcl_action_publish_status(...);
rcl_ret_t rcl_action_send_result_response(...);

• 服务器负责：
  • 接收 goal 请求，决定接受 / 拒绝；
  • 维护每个 goal 的状态机（通过 rcl_action_goal_handle_t）；
  • 持续发布 feedback；
  • 最终发布 result；
  • 处理 cancel 请求。

3. Goal Handle

文件：goal_handle.h

1
2
3
4
5
6
7

rcl_action_goal_handle_t * rcl_action_accept_new_goal(
  rcl_action_server_t * action_server,
  const rcl_action_goal_info_t * goal_info);

rcl_ret_t rcl_action_update_goal_state(
  rcl_action_goal_handle_t * goal_handle,
  rcl_action_goal_state_t goal_state);

• goal_handle 封装一个目标的生命周期状态机。

• 状态包括：

  1 2 3 4 5 6

  RCL_ACTION_GOAL_STATE_ACCEPTED RCL_ACTION_GOAL_STATE_EXECUTING RCL_ACTION_GOAL_STATE_CANCELING RCL_ACTION_GOAL_STATE_SUCCEEDED RCL_ACTION_GOAL_STATE_CANCELED RCL_ACTION_GOAL_STATE_ABORTED

• 可以更新状态、查询状态、触发状态变更事件。

4. Graph

提供 introspection 接口：

1
2
3
4

rcl_ret_t rcl_action_get_names_and_types(
  const rcl_node_t * node,
  rcl_allocator_t allocator,
  rcl_names_and_types_t * action_names_and_types);

用于查询当前系统中有哪些 action 可用。

5. Options / QoS

客户端和服务端都可以设置：

• QoS（可靠性、历史深度）
• allocator
• timeout
• introspection 选项

五、调用流程总结

客户端：

1. rcl_action_client_init()
2. rcl_action_send_goal_request() → 得到 goal_id
3. rcl_action_take_goal_response() → 接收是否被接受
4. 循环：
   • rcl_action_take_feedback() 获取反馈
5. rcl_action_take_result_response() 获取结果
6. 可随时调用 rcl_action_send_cancel_request()

服务端：

1. rcl_action_server_init()
2. rcl_action_take_goal_request() → 生成 goal_handle
3. rcl_action_publish_feedback() / rcl_action_publish_status()
4. 完成后 rcl_action_send_result_response()

六、总结特点

✅ 完整封装 Action 协议 ✅ 状态机驱动 ✅ 支持多 goal 并发 ✅ 支持 cancel / feedback / result ✅ 与 rmw 层解耦 ✅ 上层语言库调用方便（如 rclcpp_action）

🌟 rcl_lifecycle —— 节点生命周期管理层

一、背景与作用

在 ROS 2 中，Lifecycle Node 是一种有状态节点，提供标准的状态机来管理节点的启动、激活、停止、清理过程。

目的：

• 清晰控制资源初始化/释放；
• 在不同状态下限定节点行为；
• 便于系统管理（如启动/暂停模块、自动重启等）。

rcl_lifecycle 是在 rcl 层实现的生命周期状态机与通信机制。

上层：rclcpp_lifecycle::LifecycleNode 调用 rcl_lifecycle 接口。

二、状态机设计

标准状态：

1

Unconfigured → Inactive → Active → Finalized

事件与转换：

每个转换可触发用户回调（例如 on_configure(), on_activate()）。

三、组成模块

源码路径：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

rcl/rcl_lifecycle/
├── include/rcl_lifecycle/
│   ├── lifecycle.h
│   ├── state.h
│   ├── transition.h
│   ├── transition_map.h
│   └── ...
├── src/rcl_lifecycle/
│   ├── lifecycle.c
│   ├── state.c
│   ├── transition.c
│   ├── transition_map.c

主要模块：

四、核心数据结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

typedef struct rcl_lifecycle_state_t {
  unsigned int id;
  const char * label;
} rcl_lifecycle_state_t;

typedef struct rcl_lifecycle_transition_t {
  unsigned int id;
  const char * label;
  rcl_lifecycle_state_t * start;
  rcl_lifecycle_state_t * goal;
} rcl_lifecycle_transition_t;

typedef struct rcl_lifecycle_state_machine_t {
  rcl_lifecycle_state_t * current_state;
  rcl_lifecycle_transition_map_t transition_map;
} rcl_lifecycle_state_machine_t;

五、关键 API

初始化与状态机创建

1
2
3
4
5

rcl_ret_t rcl_lifecycle_state_machine_init(
  rcl_lifecycle_state_machine_t * state_machine,
  const rcl_node_t * node,
  const rcl_clock_t * clock,
  const rcl_lifecycle_state_machine_options_t * options);

状态转换

1
2
3

rcl_ret_t rcl_lifecycle_trigger_transition_by_label(
  rcl_lifecycle_state_machine_t * state_machine,
  const char * transition_label);

查询状态

1
2

const rcl_lifecycle_state_t * rcl_lifecycle_get_current_state(
  const rcl_lifecycle_state_machine_t * state_machine);

发布状态 / 通知

生命周期节点会自动发布当前状态、可用转换等信息（topic 名称如 /node_name/transition_event）。

六、生命周期节点行为

典型流程：

1. 节点初始化（Unconfigured）
2. 调用 configure() → 初始化资源 → Inactive
3. 调用 activate() → 激活发布者、定时器 → Active
4. 调用 deactivate() → 暂停行为 → Inactive
5. 调用 cleanup() → 释放资源 → Unconfigured
6. 调用 shutdown() → Finalized

只有 Active 状态下节点会正常执行主逻辑（如发布数据）。

七、特点

✅ 明确状态机，规范节点生命周期 ✅ 每个状态有用户回调 ✅ 自动发布状态变化，支持远程控制 ✅ 与 rcl、rmw 解耦 ✅ 方便系统监控和管理

✅ 总结对比