机器人 / 系统课时

使用 YAML 加载节点参数

使用 YAML 加载节点参数

当同一个 ROS 2 节点需要在不同机器人或运行环境中使用不同配置时,可以把参数写进 YAML 文件,在启动时统一加载。本课使用 ROS 2 Jazzy 和 Python 编写一个最小节点,完成参数文件编写、命令行注入、节点读取及运行结果验证。

学习目标

  • 掌握 ROS 2 参数 YAML 的节点名称、ros__parameters 层级和数据类型规则。
  • 使用 --params-file 在节点启动时加载 YAML,并通过 rclpy 读取参数。
  • 使用 ros2 param get 核对实际参数值,定位文件未生效的常见原因。

编写符合 ROS 2 规范的 YAML

本例适用于 Ubuntu 24.04 与 ROS 2 Jazzy。假设一个传感器节点需要三个参数:设备名称、运行频率和启用状态。先在工作目录创建 params.yaml,保存以下内容。

yaml
config_reader:
  ros__parameters:
    device_name: "front_lidar"
    publish_rate_hz: 5.0
    enabled: true

这不是普通的扁平 YAML 配置,而是 ROS 2 规定的节点参数结构,包含三个层级。

  1. config_reader:目标节点名称。本例节点位于根命名空间,运行时完整名称为 /config_reader。
  2. ros__parameters:ROS 2 识别参数集合的固定字段,必须使用两个连续下划线,不能改写为 parameters。
  3. 参数键值:分别表示字符串、浮点数和布尔值,由 YAML 解析器推断类型。

这三个参数的实际含义如下。

参数 类型 示例值 用途
device_name string front_lidar 区分设备
publish_rate_hz double 5.0 指定目标频率,单位 Hz
enabled bool true 启用或停用功能

5.0 与 5 不能随意互换:前者通常解析为浮点数,后者解析为整数。如果节点声明的参数类型为浮点数,文件中使用整数可能引发类型不匹配。

YAML 使用空格缩进,示例采用每级两个空格。不要使用 Tab 缩进,也不要把 ros__parameters 写成与节点名称相同的层级。

在 Python 节点中声明并读取参数

为了不依赖已有工程,直接创建 config_reader.py,使用系统已安装的 rclpy 运行。这个节点负责声明三个参数、读取启动覆盖值,并在日志中打印结果。

python
import rclpy
from rclpy.node import Node
from rclpy.executors import ExternalShutdownException


class ConfigReader(Node):
    def __init__(self):
        super().__init__('config_reader')

        # 默认值仅在没有相应启动覆盖值时使用
        self.declare_parameter('device_name', 'default_sensor')
        self.declare_parameter('publish_rate_hz', 1.0)
        self.declare_parameter('enabled', False)

        name = self.get_parameter('device_name').value
        rate = self.get_parameter('publish_rate_hz').value
        enabled = self.get_parameter('enabled').value

        # 打印实际加载的参数,而不是写死的默认值
        self.get_logger().info(
            f'device_name={name}, publish_rate_hz={rate}, '
            f'enabled={enabled}'
        )


def main():
    rclpy.init()
    node = ConfigReader()
    try:
        # 保持节点运行,允许外部命令查询参数服务
        rclpy.spin(node)
    except (KeyboardInterrupt, ExternalShutdownException):
        pass
    finally:
        node.destroy_node()
        if rclpy.ok():
            rclpy.shutdown()


if __name__ == '__main__':
    main()

预期结果:代码能够声明三个参数,并在启动后打印实际读取值。程序通过 rclpy.spin() 持续运行,直到用户按 Ctrl+C 退出,因此可以在另一个终端查询其参数。

这里有两个容易混淆的 API。

  • declare_parameter('publish_rate_hz', 1.0):声明参数并提供默认值。在没有忽略覆盖值的情况下,启动时的同名 YAML 覆盖值会优先用于初始化。
  • get_parameter('publish_rate_hz').value:读取节点当前保存的参数值,而不是返回代码中填写的默认值。

本示例只演示配置读取,并未真正创建频率为 5 Hz 的发布定时器。如果业务需要按该频率发布消息,还应将读取到的频率转换为定时器周期,并检查频率是否大于零。

使用命令行加载参数文件

确认 config_reader.py 与 params.yaml 位于同一个工作目录。打开终端 A,加载 ROS 2 Jazzy 环境,然后执行脚本。

bash
source /opt/ros/jazzy/setup.bash
python3 config_reader.py --ros-args --params-file ./params.yaml

预期输出:

text
[INFO] [<TIME>] [config_reader]: device_name=front_lidar, publish_rate_hz=5.0, enabled=True

其中 <TIME> 表示实际运行时生成的日志时间戳,每次执行可能不同。

命令中的三个部分各有明确职责。

  • python3 config_reader.py:启动当前目录中的 Python 节点。
  • --ros-args:告诉 ROS 2,后面的选项属于 ROS 参数系统。
  • --params-file ./params.yaml:指定本次启动需要读取的参数文件。

如果节点已经注册为 ROS 2 功能包的可执行入口,同样可以把 --ros-args --params-file 放在 ros2 run 命令之后。

加载发生在节点启动过程中,不需要修改源代码里的默认值。由于 YAML 顶层名称与 ConfigReader 创建的节点名称一致,三个覆盖值能够匹配到对应声明。

验证节点实际接收的参数

不要仅凭启动命令没有报错就认定文件已经生效。保持终端 A 中的节点运行,打开终端 B,加载相同的 ROS 2 环境并查询参数。

bash
source /opt/ros/jazzy/setup.bash
ros2 param get /config_reader device_name
ros2 param get /config_reader publish_rate_hz
ros2 param get /config_reader enabled

预期输出:

text
String value is: front_lidar
Double value is: 5.0
Boolean value is: True

这三个结果分别证明字符串、浮点数和布尔参数都已在目标节点中声明并取得预期值。验证时应同时检查值与类型,例如 Double value is: 5.0 比单纯检查数字 5 更准确。

也可以使用 ros2 param list /config_reader 查看该节点全部已声明参数。输出通常还包含 ROS 2 自身管理的参数,不要求列表只有上面三个业务字段。

如果要进一步确认 YAML 确实覆盖了默认值,可以保留 Python 文件不变,暂时移除启动命令中的 --ros-args --params-file ./params.yaml 后重新运行。此时启动日志应显示 device_name=default_sensor、publish_rate_hz=1.0 和 enabled=False。两次结果不同,就能确认参数覆盖确实发生。

排查参数文件没有生效的问题

当启动后仍然读取到默认值,或者节点无法读取参数文件时,按照下面的顺序检查,避免同时修改多个位置而无法确定根因。

  1. 确认文件路径:./params.yaml 相对于当前终端工作目录解析,不是相对于 Python 源码所在目录自动解析。可以使用 pwd 和 ls -l ./params.yaml 检查文件位置,必要时改用绝对路径。
  2. 核对节点名称:本例的 YAML 使用 config_reader,节点实际名称是 /config_reader。如果节点被放入 /robot 命名空间,可以把 YAML 顶层键改成 /robot/config_reader,并使用对应完整名称查询。通过 ros2 node list 确认真实名称。
  3. 核对参数声明:若文件中增加 frame_id,但 Python 没有声明这一参数,在当前默认节点设置下它不会自动成为可读取的参数。应添加相应的 declare_parameter() 调用,或者在明确需要时采用自动声明机制。
  4. 检查类型与缩进:将 publish_rate_hz: 5 改成 publish_rate_hz: 5.0,保证与 Python 中的浮点默认值一致。检查 ros__parameters 拼写以及 YAML 中是否混入 Tab。
  5. 检查运行状态与通信域:查询参数时节点必须仍在运行。两个终端应使用相同的 ROS_DOMAIN_ID,并能通过 ROS 2 发现机制相互通信。如果节点不存在或发现失败,参数查询也无法成功。

另外,必须区分参数存储值与业务逻辑实际采用的值。本例只在构造函数中读取一次参数。如果以后通过 ros2 param set 修改运行中参数,ROS 2 参数服务中的值可能已改变,但先前保存到局部变量中的数值不会自动更新。需要动态调整定时器或其他业务行为时,应重新读取参数,或使用参数变更回调处理更新。

完成验证后,在终端 A 按 Ctrl+C 退出。此时应能明确区分 YAML 文件的静态配置、节点启动时的参数覆盖,以及节点运行中的参数查询:文件负责提供配置,节点声明决定可接受的参数,ros2 param get 则用于核实最终实际值。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 YAML 加载节点参数

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通