机器人 / 系统课时
使用 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,保存以下内容。
config_reader:
ros__parameters:
device_name: "front_lidar"
publish_rate_hz: 5.0
enabled: true这不是普通的扁平 YAML 配置,而是 ROS 2 规定的节点参数结构,包含三个层级。
config_reader:目标节点名称。本例节点位于根命名空间,运行时完整名称为/config_reader。ros__parameters:ROS 2 识别参数集合的固定字段,必须使用两个连续下划线,不能改写为parameters。- 参数键值:分别表示字符串、浮点数和布尔值,由 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 运行。这个节点负责声明三个参数、读取启动覆盖值,并在日志中打印结果。
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 环境,然后执行脚本。
source /opt/ros/jazzy/setup.bash
python3 config_reader.py --ros-args --params-file ./params.yaml预期输出:
[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 环境并查询参数。
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预期输出:
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。两次结果不同,就能确认参数覆盖确实发生。
排查参数文件没有生效的问题
当启动后仍然读取到默认值,或者节点无法读取参数文件时,按照下面的顺序检查,避免同时修改多个位置而无法确定根因。
- 确认文件路径:
./params.yaml相对于当前终端工作目录解析,不是相对于 Python 源码所在目录自动解析。可以使用pwd和ls -l ./params.yaml检查文件位置,必要时改用绝对路径。 - 核对节点名称:本例的 YAML 使用
config_reader,节点实际名称是/config_reader。如果节点被放入/robot命名空间,可以把 YAML 顶层键改成/robot/config_reader,并使用对应完整名称查询。通过ros2 node list确认真实名称。 - 核对参数声明:若文件中增加
frame_id,但 Python 没有声明这一参数,在当前默认节点设置下它不会自动成为可读取的参数。应添加相应的declare_parameter()调用,或者在明确需要时采用自动声明机制。 - 检查类型与缩进:将
publish_rate_hz: 5改成publish_rate_hz: 5.0,保证与 Python 中的浮点默认值一致。检查ros__parameters拼写以及 YAML 中是否混入 Tab。 - 检查运行状态与通信域:查询参数时节点必须仍在运行。两个终端应使用相同的
ROS_DOMAIN_ID,并能通过 ROS 2 发现机制相互通信。如果节点不存在或发现失败,参数查询也无法成功。
另外,必须区分参数存储值与业务逻辑实际采用的值。本例只在构造函数中读取一次参数。如果以后通过 ros2 param set 修改运行中参数,ROS 2 参数服务中的值可能已改变,但先前保存到局部变量中的数值不会自动更新。需要动态调整定时器或其他业务行为时,应重新读取参数,或使用参数变更回调处理更新。
完成验证后,在终端 A 按 Ctrl+C 退出。此时应能明确区分 YAML 文件的静态配置、节点启动时的参数覆盖,以及节点运行中的参数查询:文件负责提供配置,节点声明决定可接受的参数,ros2 param get 则用于核实最终实际值。