参数服务：把配置参数从代码里拉出来

01先动手感受：亲手调一调这三个参数

这一节不用敲任何命令——下面是一个跑在页面里的 param_sensor 模拟器。三个滑块，就是真实节点的三个参数（发布周期、报警阈值、使能开关），你拖动它们，右侧日志会立刻响应。先玩两分钟，你就会明白参数到底解决了什么问题，再去实验箱跑真节点。

▲ 调 publish_period 看日志节奏（0.02s 最快、10s 最慢）；关掉 sensor_enabled 看采样停止；点越界测试看回调如何拒绝。这些现象稍后在真实节点上会一模一样复现。

02问题引入：改一个数字为什么这么贵

刚才你在页面上拖滑块，改一个值的代价是零。但在没有参数系统之前，同样的事有多贵？

换个生活的说法：阈值写死在代码里，就像把功放音量旋钮焊死在机箱里——想调个音量，得拆机、改电路、再装回去。参数系统则是把旋钮装回面板：设备不用停，伸手一拧就行。（这里的"旋钮"就是参数，只不过它的"拧"是在命令行里发一条 ros2 param set。）

图 10-1 · 同样是把报警阈值从 500 改成 600：硬编码走完全程 vs 参数化一条命令

03核心原理：声明 → 读取 → 设置，与两次校验

图 10-2 · 参数服务解剖图：三条路（declare 登记 / get 读取 / set 写入）汇入同一个参数注册表，只有写入路必须过回调闸门

一次 param set 的完整数据流

图 10-3 · 一次 param set 的完整数据流：请求经参数服务转交回调闸门，校验通过才落到业务逻辑

两层约束：描述符（静态）与回调（动态）

# 声明时附带描述符：自描述 + 可视化元数据
from rcl_interfaces.msg import ParameterDescriptor, FloatingPointRange

period_desc = ParameterDescriptor(
    description='MQ5 数据发布周期（秒），越小采样越快。',
    floating_point_range=[
        FloatingPointRange(from_value=0.02, to_value=10.0, step=0.01)
    ]
)
self.declare_parameter('publish_period', 1.0, period_desc)   # 第三参即描述符

04实验步骤：读源码 → 跑节点 → 九步联调

这一节把"读代码"和"动手跑"合在一起：先看源码的三站结构（知道每个参数在哪被消费），再启动节点验证（看参数变成日志），最后九步 CLI 联调（把声明、读取、校验、热生效、持久化全走一遍）。

第 1 步 · 先看源码：param_sensor_node 的三站结构

源码位于 ros_sensor/ros_sensor/param_sensor_node.py（与 EXP-06 的 gas_sensor_node 同目录，from .common import read_mq5_once 复用真实读取）。按数据流分三站读：

第一站 · __init__：声明、读取、接线

# 来源：param_sensor_node.py __init__（声明 → 读取 → 发布器/定时器）
self.declare_parameter('publish_period', 1.0)        # ① 声明：名字+默认值，1.0 同时定型为 double
self.declare_parameter('sensor_enabled', True)        #     True → bool；'x' 才是 str
self.declare_parameter('alarm_threshold_ppm', 500.0)  #     声明即登记进"参数注册表"（图 10-2）

self.publish_period = float(self.get_parameter('publish_period').value)     # ② 读取：注册表 → 成员变量
self.sensor_enabled = bool(self.get_parameter('sensor_enabled').value)   #     启动时读一次缓存
self.alarm_threshold = float(self.get_parameter('alarm_threshold_ppm').value)

self.pub = self.create_publisher(Float32, '/gas_sensor', qos)   # ③ 接线：与实验6完全一致
self.timer = self.create_timer(self.publish_period, self.timer_cb)   #     周期就是参数本身

第二站 · timer_cb：参数怎样控制行为

# 来源：param_sensor_node.py timer_cb（使能开关 + 阈值报警两处消费参数）
def timer_cb(self):
    if not self.sensor_enabled:          # 消费点①：使能开关——false 时直接返回，
        return                           #   定时器仍在走，只是采样被"跳过"（功耗极低）
    raw, v, ppm, err = read_mq5_once()   # 复用实验6 的真实 MQ5 读取
    msg = Float32(); msg.data = float(ppm)
    self.pub.publish(msg)
    if ppm >= self.alarm_threshold:      # 消费点②：阈值判断——参数一改，下一拍就用新值
        self.get_logger().warn(f'[报警] ppm={ppm:.2f} >= {self.alarm_threshold}ppm')
    else:
        self.get_logger().info(f'raw={raw} voltage={v:.3f}V ppm={ppm:.2f}')

第三站 · 回调：校验 → 应用 → 回执

# __init__ 末尾注册（必须先导入：from rcl_interfaces.msg import SetParametersResult）
self.add_on_set_parameters_callback(self.on_parameters_set)

def _recreate_timer(self):
    """按新的发布周期重建定时器 —— 参数真正改变行为的关键一步"""
    self.destroy_timer(self.timer)
    self.timer = self.create_timer(self.publish_period, self.timer_cb)

def on_parameters_set(self, params):
    """params: 本次被修改的参数列表（可能一次多个）"""
    for p in params:
        if p.name == 'publish_period':
            if p.value < 0.02 or p.value > 10.0:        # ① 校验：范围外一票否决
                return SetParametersResult(successful=False,
                    reason=f'publish_period 必须在 [0.02, 10.0] 内，收到: {p.value}')
            self.publish_period = float(p.value)           # ② 应用：更新变量
            self._recreate_timer()                      #    + 重建定时器（行为才变）
            self.get_logger().info(f'发布周期已更新: {self.publish_period} s')
        elif p.name == 'sensor_enabled':
            self.sensor_enabled = bool(p.value)
        elif p.name == 'alarm_threshold_ppm':
            if p.value < 0.0:
                return SetParametersResult(successful=False, reason='报警阈值不能为负数')
            self.alarm_threshold = float(p.value)
    return SetParametersResult(successful=True)          # ③ 回执：每个出口都必须返回

第 2 步 · 启动节点：看参数变成日志

源码看懂了，打开终端实际跑一遍。先确认每个参数在真实节点上的表现，再进入命令行联调。

cd ~/ros2_ws
colcon build --packages-select ros_sensor
source install/setup.bash

ros2 run ros_sensor param_sensor

ros2 param list

ros2 param get /param_sensor publish_period
ros2 run ros_sensor param_sensor --ros-args -p publish_period:=0.1 -p alarm_threshold_ppm:=100.0

第 3 步 · 九步 CLI 联调：把参数系统走一遍

前面已经验证了"参数在册"和"启动覆盖"。这一步把剩下的环节补齐——描述符、热生效、越界被拒、开关控制、持久化，每一步都有明确的观测点。前提：第 1 步的回调版代码已编译，终端 B 的节点保持运行。

ros2 param describe /param_sensor publish_period

ros2 param set /param_sensor publish_period 0.2
ros2 param set /param_sensor publish_period 100.0
ros2 param set /param_sensor sensor_enabled false
ros2 param set /param_sensor sensor_enabled true

ros2 param dump /param_sensor > param_sensor.yaml
cat param_sensor.yaml
ros2 run ros_sensor param_sensor --ros-args --params-file ./param_sensor.yaml

05注意事项与验收清单

06本课总结与思考题