ROS2►核心

rcl_interfaces 源码详细分析

rcl_interfaces 源码详细分析

工作区路径：/home/cp/work2/ros2Learn/ros2_humble/src/ros2/rcl_interfaces
版本：1.2.2（各子包统一），构建类型 ament_cmake + rosidl，许可证 Apache 2.0。

rcl_interfaces 仓库不是运行时逻辑库，而是一组 ROS 2 接口定义包（.msg / .srv / .action）。源码经 rosidl_generate_interfaces 生成 C/C++/Python 等语言的 typesupport 代码，供 rcl、rclcpp、rclpy、rcl_action、component_manager 等上层库使用。可以把它理解为 ROS 2 客户端栈的**“协议契约层”**——定义参数、Action、Lifecycle、组件化、时钟等核心概念在线上如何表达。

1. 总体认识

1.1 仓库定位

特点 说明
纯接口 无业务 .c/.cpp 实现，只有 IDL 定义 + CMake 构建
QL1 除 test_msgs 外，各包均声明 Quality Level 1
被广泛依赖 几乎所有 ROS 2 核心包间接或直接依赖
设计文档驱动 接口语义来自 ROS 2 Design Articles

1.2 在 ROS 2 栈中的位置

flowchart TB
  subgraph apps [应用 / CLI]
    NODE[rclcpp Node]
    ROS2CLI[ros2 param / component]
    GAZEBO[Gazebo / 仿真 clock]
  end
  subgraph clients [客户端库]
    RCLCPP[rclcpp]
    RCLPY[rclpy]
    RCL[rcl]
    RCLACT[rcl_action]
    RCLLC[rcl_lifecycle]
  end
  subgraph iface [rcl_interfaces 仓库]
    RCLI[rcl_interfaces]
    ACT[action_msgs]
    LIFE[lifecycle_msgs]
    COMP[composition_interfaces]
    BUILTIN[builtin_interfaces]
    ROSGRAPH[rosgraph_msgs]
    STATS[statistics_msgs]
  end
  subgraph gen [代码生成]
    ROSIDL[rosidl_generate_interfaces]
    TS[typesupport C/C++/Python]
  end

  NODE --> RCLCPP --> RCLI & ACT & LIFE
  ROS2CLI --> COMP & RCLI
  GAZEBO --> ROSGRAPH
  RCL --> RCLI
  RCLACT --> ACT
  iface --> ROSIDL --> TS
  TS --> clients

2. 子包一览

仓库含 8 个独立 ROS 包（同一 git 仓库，colcon 分别编译）：

包名 版本 接口数量 职责
builtin_interfaces 1.2.2 2 msg OMG IDL 基础时间类型 Time / Duration
rcl_interfaces 1.2.2 11 msg + 6 srv 参数系统、日志 /rosout
action_msgs 1.2.2 3 msg + 1 srv Action 通用状态与 CancelGoal
lifecycle_msgs 1.2.2 4 msg + 4 srv Lifecycle 节点状态机
composition_interfaces 1.2.2 3 srv Composable Node 动态加载
rosgraph_msgs 1.2.2 1 msg 仿真时钟 /clock
statistics_msgs 1.2.2 3 msg Topic 统计指标
test_msgs 1.2.2 测试用 rosidl/typesupport 测试 fixture

目录结构：

1
2
3
4
5
6
7
8
9
10
11
rcl_interfaces/
├── README.md
├── LICENSE
├── builtin_interfaces/       # Time, Duration
├── rcl_interfaces/           # 参数 + Log ★ 核心
├── action_msgs/              # GoalInfo, GoalStatus, CancelGoal
├── lifecycle_msgs/           # State, Transition, ChangeState...
├── composition_interfaces/   # LoadNode, UnloadNode, ListNodes
├── rosgraph_msgs/            # Clock
├── statistics_msgs/          # MetricsMessage
└── test_msgs/                # 测试专用 msg/action

3. 构建机制

每个子包结构相同，以 rcl_interfaces 为例：

1
2
3
4
5
6
7
rosidl_generate_interfaces(${PROJECT_NAME}
  "msg/FloatingPointRange.msg"
  "msg/IntegerRange.msg"
  ...
  "srv/SetParameters.srv"
  DEPENDENCIES builtin_interfaces
)

构建流程：

1
2
3
4
5
.msg / .srv / .action
    → rosidl_adapter（转 IDL）
    → rosidl_generator_c / _cpp / _py ...
    → rosidl_typesupport_c / _cpp / _fastrtps / _introspection ...
    → 安装到 install/rcl_interfaces/{include,lib,share}

所有包均声明 <member_of_group>rosidl_interface_packages</member_of_group>，表示属于 ROS 接口包生态。

3.1 包间依赖

builtin_interfacesrcl_interfacesaction_msgslifecycle_msgscomposition_interfacesrosgraph_msgsstatistics_msgsunique_identifier_msgs
包 直接依赖
builtin_interfaces 无
rcl_interfaces builtin_interfaces
action_msgs builtin_interfaces, unique_identifier_msgs
lifecycle_msgs 无（自包含 enum）
composition_interfaces rcl_interfaces
rosgraph_msgs builtin_interfaces
statistics_msgs builtin_interfaces

4. builtin_interfaces — 基础时间类型

路径：builtin_interfaces/msg/

ROS 2 全栈最底层的时间/msg 类型，对应 OMG IDL PSM 中的 Time 和 Duration。

4.1 Time.msg

1
2
3
4
5
# The seconds component, valid over all int32 values.
int32 sec

# The nanoseconds component, valid in the range [0, 1e9)
uint32 nanosec
  • 可表示负时间（如 {sec: -2, nanosec: 300000000} = -1.7s）
  • 用于：std_msgs/Header.stamp、action_msgs/GoalInfo.stamp、参数事件时间戳等

4.2 Duration.msg

结构与 Time 相同，语义为时间间隔而非时间点。

4.3 消费者

消费者 用途
所有带 Header 的消息 std_msgs/Header.stamp
rcl/time.h ROS Time 与 RMW 时间转换
TF2 / 传感器消息 时间戳字段

builtin_interfaces 是 ROS 2 中使用最广泛的接口包之一，几乎所有消息类型都间接依赖它。

5. rcl_interfaces — 参数与日志

路径：rcl_interfaces/
这是仓库的核心包，定义 ROS 2 参数服务协议和 /rosout 日志消息。

5.1 参数系统架构

节点 namespace 下消息类型get_parametersset_parameterslist_parametersdescribe_parametersget_parameter_typesset_parameters_atomicallyparameter_eventsParameterValueParameterParameterEvent

每个节点在自身 namespace 下暴露标准服务（由 rclcpp/rclpy 自动创建）：

服务名 类型 功能
~/get_parameters GetParameters 按名读取参数值
~/set_parameters SetParameters 逐个设置，返回每项成败
~/set_parameters_atomically SetParametersAtomically 全部成功或全部失败
~/list_parameters ListParameters 按前缀递归列出
~/describe_parameters DescribeParameters 返回描述符（类型、范围、只读）
~/get_parameter_types GetParameterTypes 返回参数类型 enum

标准 Topic：

Topic 类型 功能
~/parameter_events ParameterEvent 参数增删改事件广播
~/parameter_event_descriptors ParameterEventDescriptors 仅描述符版（大参数场景）

README 中提到的 has_parameters 服务在 Humble 版接口文件中已不存在，以实际 .srv 文件为准。

5.2 参数值 — 变体类型设计

ParameterValue.msg 采用 tagged union（标记联合体） 模式：

1
2
3
4
5
6
7
8
9
10
11
uint8 type

bool bool_value
int64 integer_value
float64 double_value
string string_value
byte[] byte_array_value
bool[] bool_array_value
int64[] integer_array_value
float64[] double_array_value
string[] string_array_value

ParameterType.msg 定义 type 枚举：

常量 值 对应字段
PARAMETER_NOT_SET 0 未设置
PARAMETER_BOOL 1 bool_value
PARAMETER_INTEGER 2 integer_value
PARAMETER_DOUBLE 3 double_value
PARAMETER_STRING 4 string_value
PARAMETER_BYTE_ARRAY 5 byte_array_value
PARAMETER_BOOL_ARRAY 6 bool_array_value
PARAMETER_INTEGER_ARRAY 7 integer_array_value
PARAMETER_DOUBLE_ARRAY 8 double_array_value
PARAMETER_STRING_ARRAY 9 string_array_value

只有 type 对应的一个字段有效——这是 ROS 2 参数在 DDS 线上无 union 类型时的惯用设计。

5.3 参数描述符与约束

ParameterDescriptor.msg 携带元数据：

  • description / additional_constraints：人类可读说明
  • read_only：初始化后不可改
  • dynamic_typing：允许运行时改类型
  • floating_point_range / integer_range：取值范围与步长

FloatingPointRange.msg 示例：from_value、to_value、step 三者定义合法浮点参数空间。

5.4 参数事件

ParameterEvent.msg 在一次原子更新中，每个参数名只出现在三个列表之一：

1
2
3
4
5
builtin_interfaces/Time stamp
string node
Parameter[] new_parameters
Parameter[] changed_parameters
Parameter[] deleted_parameters

rclcpp 的 ParameterEventHandler 和 ros2 param listen 订阅此 topic 跟踪参数变化。

5.5 关键 Service 定义

GetParameters.srv：

1
2
3
string[] names          # 请求
---
ParameterValue[] values # 响应，顺序与 names 对应

SetParameters.srv：

1
2
3
Parameter[] parameters
---
SetParametersResult[] results   # 每项含 successful + reason

ListParameters.srv：

1
2
3
4
string[] prefixes
uint64 depth                    # 0 = DEPTH_RECURSIVE 无限递归
---
ListParametersResult result     # names[] + prefixes[]

SetParametersAtomically.srv：与 SetParameters 类似，但返回单个 SetParametersResult，任一失败则全部回滚。

5.6 Log.msg — /rosout

1
2
3
4
5
6
7
8
9
10
11
12
13
byte DEBUG=10
byte INFO=20
byte WARN=30
byte ERROR=40
byte FATAL=50

builtin_interfaces/Time stamp
uint8 level
string name
string msg
string file
string function
uint32 line
  • 日志级别与 Python logging / rcutils/logging.h 对齐
  • rcl/logging_rosout.c 将 RCUTILS 日志发布到 rosout topic，类型即此消息
  • 支持 ros2 run rqt_console 等工具订阅

5.7 ROS 1 桥接

mapping_rules.yaml 定义 rosgraph_msgs/Log → rcl_interfaces/Log 的字段映射，供 ros1_bridge 使用：

1
2
3
4
5
6
7
8
ros1_package_name: 'rosgraph_msgs'
ros1_message_name: 'Log'
ros2_package_name: 'rcl_interfaces'
ros2_message_name: 'Log'
fields_1_to_2:
  header.stamp: 'stamp'
  level: 'level'
  ...

6. action_msgs — Action 通用类型

路径：action_msgs/
定义所有 Action 共享的消息与服务，具体 Action（如 Fibonacci.action）由各功能包自行定义。

6.1 GoalInfo.msg

1
2
unique_identifier_msgs/UUID goal_id
builtin_interfaces/Time stamp
  • goal_id：128 位 UUID，全局唯一标识一个 goal
  • stamp：goal 被 server 接受的时间

6.2 GoalStatus.msg — 状态机

状态常量 值 含义
STATUS_UNKNOWN 0 未初始化
STATUS_ACCEPTED 1 已接受，等待执行
STATUS_EXECUTING 2 正在执行
STATUS_CANCELING 3 取消中
STATUS_SUCCEEDED 4 成功完成
STATUS_CANCELED 5 已取消
STATUS_ABORTED 6 server 中止

rcl_action 的 goal 状态机与此 enum 一一对应。

6.3 GoalStatusArray.msg

Action server 在 ~/action_name/_action/status topic 上发布，包含所有活跃 goal 的状态列表。

6.4 CancelGoal.srv

支持四种取消策略（goal_id + timestamp 组合）：

goal_id timestamp 行为
zero zero 取消所有 goal
zero 非 zero 取消该时间点之前接受的所有 goal
非 zero zero 取消指定 ID 的 goal
非 zero 非 zero 取消指定 ID + 该时间前的 goal

返回码：ERROR_NONE、ERROR_REJECTED、ERROR_UNKNOWN_GOAL_ID、ERROR_GOAL_TERMINATED。

6.5 与 Action 协议的关系

用户定义的 My.action 在底层会拆成多个 topic/service，action_msgs 提供元协议部分：

1
2
3
4
5
~/my_action/_action/send_goal      (service)
~/my_action/_action/cancel_goal    (CancelGoal.srv)  ← action_msgs
~/my_action/_action/get_result     (service)
~/my_action/_action/feedback       (topic)
~/my_action/_action/status         (GoalStatusArray) ← action_msgs

7. lifecycle_msgs — 生命周期节点

路径：lifecycle_msgs/
定义 Managed Node Lifecycle 的标准接口。

7.1 状态机

State.msg 定义 primary states 与 transition states：

Primary States（稳定态）：

ID 名称 含义
0 UNKNOWN 未设置
1 UNCONFIGURED 刚创建，未配置
2 INACTIVE 已配置，未激活
3 ACTIVE 正常运行
4 FINALIZED 即将销毁

Transition States（中间态）：CONFIGURING(10)、CLEANINGUP(11)、ACTIVATING(13)、DEACTIVATING(14) 等。

7.2 Transition.msg

定义标准转移 ID（0–8 为公开转移，10–62 为内部/回调结果）：

转移 ID 触发回调
CREATE 0 实例化
CONFIGURE 1 on_configure
CLEANUP 2 on_cleanup
ACTIVATE 3 on_activate
DEACTIVATE 4 on_deactivate
UNCONFIGURED_SHUTDOWN 5 on_shutdown
… … …

7.3 服务

服务 功能
ChangeState 请求状态转移
GetState 查询当前 primary state
GetAvailableStates 列出可达状态
GetAvailableTransitions 列出当前可用转移

7.4 TransitionEvent.msg

Lifecycle 节点在 ~/transition_event topic 发布状态变化：

1
2
3
4
uint64 timestamp
Transition transition
State start_state
State goal_state

rclcpp_lifecycle::LifecycleNode 和 ros2 lifecycle CLI 依赖这些接口。

8. composition_interfaces — 组件化节点

路径：composition_interfaces/
供 component_manager 和 ros2 component 动态加载/卸载 composable node。

8.1 LoadNode.srv

1
2
3
4
5
6
7
8
9
10
11
12
13
string package_name
string plugin_name
string node_name
string node_namespace
uint8 log_level
string[] remap_rules
rcl_interfaces/Parameter[] parameters
rcl_interfaces/Parameter[] extra_arguments
---
bool success
string error_message
string full_node_name
uint64 unique_id
  • plugin_name：如 rclcpp_components 注册的 TalkerComponent
  • 可携带 remap 规则和初始参数（复用 rcl_interfaces/Parameter）
  • 返回 unique_id 供后续 UnloadNode 使用

8.2 UnloadNode.srv / ListNodes.srv

服务 请求 响应
UnloadNode unique_id success, error_message
ListNodes 空 full_node_names[], unique_ids[]

8.3 消费者

  • rclcpp_components::ComponentManager
  • ros2 component load/unload/list
  • launch_ros 的 ComposableNodeContainer

9. rosgraph_msgs — 计算图时钟

路径：rosgraph_msgs/msg/Clock.msg

1
builtin_interfaces/Time clock
  • 仿真环境（Gazebo 等）在 /clock topic 发布此消息
  • rclcpp::TimeSource 订阅 /clock 驱动 ROS Time（sim time）
  • 与 wall time（系统时钟）相对，enable use_sim_time 时节点 timer 跟随仿真时间

关键消费者：rclcpp/src/rclcpp/time_source.cpp

10. statistics_msgs — Topic 统计

路径：statistics_msgs/

消息 职责
StatisticDataType.msg 统计类型 enum（mean、max、min、std_dev 等）
StatisticDataPoint.msg 单个统计值（type + float64 data）
MetricsMessage.msg 完整指标报文（来源、窗口、统计点数组）

MetricsMessage 结构：

  • measurement_source_name：节点/topic/进程名
  • metrics_source：指标名（如 message_age、subscription_period）
  • window_start / window_stop：统计窗口
  • statistics[]：数据点列表

消费者：rclcpp topic statistics 功能（libstatistics_collector），可选开启。

11. test_msgs — 测试专用

路径：test_msgs/

内容 用途
msg/Builtins.msg 覆盖各种 builtin 类型组合
action/NestedMessage.action 嵌套消息 Action 测试
include/test_msgs/*_fixtures.hpp C++ 测试 fixture
src/test_msgs/*_fixtures.py Python 测试 fixture

不应在应用代码中依赖——仅供 rosidl、rmw、rcl 测试使用。

12. 主要消费者映射

接口包 主要消费者 使用场景
builtin_interfaces 全栈 时间戳、Duration
rcl_interfaces rclcpp、rclpy、rcl/logging_rosout.c 参数 API、/rosout
action_msgs rcl_action、rclcpp_action Action cancel/status
lifecycle_msgs rcl_lifecycle、rclcpp_lifecycle 生命周期管理
composition_interfaces rclcpp_components、ros2component 动态组件
rosgraph_msgs rclcpp::TimeSource 仿真时间
statistics_msgs rclcpp topic statistics 性能监控

12.1 rcl 层直接使用

rcl 包在 package.xml 中依赖 rcl_interfaces，直接使用生成的 C 类型：

1
#include "rcl_interfaces/msg/log.h"

/rosout publisher 创建时使用 rosidl_typesupport_c__get_message_type_support_handle__rcl_interfaces__msg__Log()。

参数服务的实现不在 rcl 层，而在 rclcpp/rclpy 的 node_interfaces 中，但 wire 格式即本仓库定义的 srv/msg。

13. 参数分组规则

参数名采用类文件路径的分组语义（来自 README）：

  • 默认组：/
  • 嵌套组：/my_group/sub_group/param_name
  • 与节点 namespace 独立——参数名本身是全局字符串

ListParameters 的 prefixes + depth 控制递归深度，DEPTH_RECURSIVE=0 表示无限深度。

14. 设计特点小结

特点 说明
契约优先 接口即规范，改接口需跨版本协调
变体参数 ParameterValue 用 type tag + 多字段模拟 union
原子参数更新 ParameterEvent 三列表互斥；SetParametersAtomically 全成全败
Action 元协议 通用 status/cancel 与具体 action 类型分离
Lifecycle 标准化 状态/转移 ID 全局一致，跨语言互操作
组件化接口 LoadNode 直接复用 Parameter 类型
最小 rosgraph 仅 Clock 一条消息，保持计算图接口精简
无运行时代码 全部逻辑在消费者侧，本仓库只有 IDL

15. 与相邻包对比

包 类型 内容
rcl_interfaces 接口定义 ROS 客户端库内部协议
rcl C 运行时库 封装 rmw，使用 rcl_interfaces 类型
common_interfaces 接口定义 通用传感器/几何消息（sensor_msgs 等）
unique_identifier_msgs 接口定义 UUID（action_msgs 依赖）

16. 推荐阅读顺序

  1. rcl_interfaces/README.md — 参数 topic/service 命名约定
  2. ParameterValue.msg + ParameterType.msg — 理解参数类型系统
  3. GetParameters.srv / SetParameters.srv — 参数 RPC 协议
  4. action_msgs/GoalStatus.msg — Action 状态机
  5. lifecycle_msgs/State.msg + Transition.msg — 生命周期设计
  6. 消费者代码：
    • rclcpp/src/rclcpp/node_interfaces/parameters*.cpp — 参数服务实现
    • rcl/src/rcl/logging_rosout.c — Log 消息发布
    • rclcpp/src/rclcpp/time_source.cpp — Clock 订阅
  7. ROS 2 Design Articles — 参数、Action、Lifecycle 设计原文

17. 接口清单速查

17.1 rcl_interfaces 全部接口

Messages (11)：Parameter, ParameterValue, ParameterType, ParameterDescriptor, ParameterEvent, ParameterEventDescriptors, SetParametersResult, ListParametersResult, FloatingPointRange, IntegerRange, Log

Services (6)：GetParameters, SetParameters, SetParametersAtomically, ListParameters, DescribeParameters, GetParameterTypes

17.2 其他包

包 msg srv action
builtin_interfaces Time, Duration — —
action_msgs GoalInfo, GoalStatus, GoalStatusArray CancelGoal —
lifecycle_msgs State, Transition, TransitionDescription, TransitionEvent ChangeState, GetState, GetAvailableStates, GetAvailableTransitions —
composition_interfaces — LoadNode, UnloadNode, ListNodes —
rosgraph_msgs Clock — —
statistics_msgs MetricsMessage, StatisticDataPoint, StatisticDataType — —

文档基于 ROS 2 Humble 工作区中的 rcl_interfaces 1.2.2 源码（接口定义）分析生成。

文章互动

阅读 --

留言

0 条留言

正在加载留言…