在机器人开发中（比如机械手控制），经常需要运行时调整参数（如关节偏移量、滤波系数），而无需重启节点（重启会中断硬件通信，影响调试效率）。本文以「机械手关节偏移量动态调整」为例，从实际项目代码中拆解ROS2动态参数的完整实现流程，所有代码均来自真实的手套控制机械手项目。

一、场景背景

在手套控制机械手的场景中，每个关节（如大拇指旋转th_rot、掌指th_mcp）需要配置偏移量来校准物理误差。调试时需要实时修改这些偏移量，观察机械手运动效果，若每次修改都重启节点，会导致：

1. 硬件通信中断，机械手需要重新初始化；
2. 调试效率极低，无法快速验证参数效果。

ROS2的动态参数机制可以完美解决这个问题——运行时修改参数，节点实时生效。

以下是实现「关节偏移量动态修改」的核心代码，均来自实际的机械手控制节点：

步骤1：声明参数（含默认值）

在节点初始化时，先声明需要动态修改的参数（这里是12个关节的偏移量），并设置默认值。

def __init__(self):
    super().__init__("gloves_dexhand_control")
    
    # 1. 定义默认偏移量（根据机械手物理特性预设）
    default_joint_offsets = {
        "th_rot": 0.0,   "th_mcp": 0.0,   "th_dip": 0.0,
        "ff_spr": 0.0,   "ff_mcp": 0.0,    "ff_dip": -5.0,
        "mf_mcp": 0.0,  "mf_dip": -3.0,
        "rf_mcp": 0.0,   "rf_dip": -10.0,
        "lf_mcp": 0.0,   "lf_dip": 5.0
    }
    
    # 2. 初始化偏移量字典，声明ROS2参数（关键：支持动态修改）
    self.joint_offsets = {}
    for joint_name, default_offset in default_joint_offsets.items():
        # 声明参数：格式为「父参数.子参数」（嵌套参数），方便分类管理
        self.declare_parameter(f"joint_offsets.{joint_name}", default_offset)
        # 读取初始值
        self.joint_offsets[joint_name] = self.get_parameter(
            f"joint_offsets.{joint_name}"
        ).get_parameter_value().double_value
    
    # ========== 注册参数回调函数 ==========
    self.add_on_set_parameters_callback(self.parameter_callback)

关键说明：

• 参数命名使用「嵌套格式」joint_offsets.th_rot，而非扁平的th_rot_offset，便于分类管理（比如后续可新增filter_params.kalman_noise等参数）；
• declare_parameter是ROS2参数声明的核心API，第一个参数是参数名，第二个是默认值；
• 声明后，参数会被ROS2参数服务器管理，支持运行时修改。

步骤2：编写参数回调函数

当外部修改参数时，ROS2会触发该回调函数，我们需要在这里完成：参数合法性校验、参数值更新。

def parameter_callback(self, params):
    """动态参数回调：支持运行时修改 joint_offsets"""
    success = True
    for param in params:
        # 1. 过滤仅处理joint_offsets相关参数
        if param.name.startswith("joint_offsets."):
            # 提取关节名
            joint_name = param.name.split(".", 1)[1]
            
            # 2. 合法性校验：仅处理已声明的关节名
            if joint_name in self.joint_offsets:
                # 3. 范围保护，防止参数错误导致硬件损坏
                if abs(param.value) > 360:
                    return SetParametersResult(
                        successful=False, 
                        reason=f"{joint_name} 偏移量过大(>{360})，有效值范围±360°"
                    )
                # 4. 更新本地参数值（实时生效）
                self.joint_offsets[joint_name] = float(param.value)
                self.get_logger().info(f"参数更新: {joint_name} offset = {param.value:.2f}°")
            else:
                return SetParametersResult(
                    successful=False, 
                    reason=f"未知关节: {joint_name}，仅支持{list(self.joint_offsets.keys())}"
                )
    # 返回成功结果，ROS2会确认参数修改生效
    return SetParametersResult(successful=success)

关键说明：

• 回调函数的入参params是「待修改的参数列表」（支持批量修改）；
• 必须返回SetParametersResult：告知ROS2参数是否修改成功（失败时会拒绝参数更新）；
• 增加范围校验：防止错误的参数值（如偏移量999°）导致机械手运动异常；
• 日志输出：方便调试时确认参数是否更新成功。

步骤3：运行时读取最新参数值

参数修改后，在业务逻辑中读取self.joint_offsets即可获取最新值（无需重启节点）。

def gloves_joint_callback(self, msg: JointState):
    # ... 省略其他逻辑 ...
    
    # 实时读取最新的关节偏移量
    for joint_name in self.joint_offsets.keys():
        # 读取动态修改后的参数值
        self.joint_offsets[joint_name] = self.get_parameter(
            f"joint_offsets.{joint_name}"
        ).get_parameter_value().double_value
    
    # 叠加偏移量到关节指令中
    for joint_name, offset_value in self.joint_offsets.items():
        if joint_name in filtered_command:
            filtered_command[joint_name] += offset_value
            self.get_logger().debug(
                f"{joint_name}：原始值={filtered_command[joint_name]-offset_value:.1f}° → 叠加offset后={filtered_command[joint_name]:.1f}°"
            )
    
    # ... 发送指令到机械手硬件 ...

关键说明：

• 在业务回调中，每次都读取self.joint_offsets，确保使用的是最新的参数值；

二、动态修改参数的3种方法

实现上述代码后，可通过以下3种方式修改参数，均无需重启节点：

方法1：命令行修改（最常用）

使用ros2 param set命令，格式：

# 修改单个参数：大拇指掌指关节偏移量为10°
ros2 param set /gloves_dexhand_control joint_offsets.th_mcp 10.0

# 查看当前参数值
ros2 param get /gloves_dexhand_control joint_offsets.th_mcp

# 查看所有参数
ros2 param list /gloves_dexhand_control

效果：执行命令后，节点日志会输出参数更新: th_mcp offset = 10.00°，且机械手的th_mcp关节指令会立即叠加10°偏移。

方法2：使用rqt工具（可视化操作）

ROS2提供可视化工具rqt_reconfigure（需安装），适合调试时快速调整：

# 安装工具
sudo apt install ros-humble-rqt-reconfigure

# 启动工具
rqt_reconfigure

操作步骤：

1. 选择节点/gloves_dexhand_control；
2. 找到joint_offsets分类下的关节名；
3. 拖动滑块/输入数值，实时修改参数（无需敲命令）。

方法3：代码中主动修改（程序内动态调整）

若需要在代码中根据逻辑自动修改参数（如根据传感器数据调整偏移量），可调用ROS2的参数API：

# 示例：在代码中修改th_rot的偏移量为5.0°
from rclpy.parameter import Parameter

# 构造参数对象
param = Parameter(
    name="joint_offsets.th_rot",
    value=5.0
)
# 设置参数（会触发parameter_callback回调）
self.set_parameters([param])

三、关键注意事项

1. 线程安全

如果参数被多线程访问（如回调函数+定时器），需加锁保护：

# 初始化时创建锁
self.param_lock = threading.Lock()

# 在回调函数中更新参数时加锁
def parameter_callback(self, params):
    with self.param_lock:
        # ... 参数更新逻辑 ...

# 在业务逻辑中读取参数时加锁
def gloves_joint_callback(self, msg: JointState):
    with self.param_lock:
        offset = self.joint_offsets["th_mcp"]

2. 参数类型一致性

声明参数时用double_value（浮点型），修改时需保持类型一致（如避免传入字符串），否则会触发类型错误。

3. 批量修改参数

回调函数支持批量修改参数，只需遍历params列表即可（本文示例已支持）。

4. 节点启动时传入参数

除了运行时修改，也可在启动节点时传入参数（覆盖默认值）：

ros2 run your_package your_node --ros-args -p joint_offsets.th_mcp:=5.0 -p joint_offsets.th_dip:=-8.0

总结

ROS2动态参数的核心实现流程可总结为：

1. declare_parameter：声明参数（含默认值）；
2. add_on_set_parameters_callback：注册参数回调函数；
3. 回调函数中：校验参数+更新本地变量；
4. 业务逻辑中：读取本地变量（实时生效）。

该机制在机器人开发中非常实用，除了关节偏移量，还可用于：

• 滤波系数（如卡尔曼滤波的噪声方差）；
• 控制模式参数（如阻抗控制的刚度）；
• 传感器校准参数（如触觉传感器的阈值）。

通过动态参数，可大幅提升机器人调试效率，避免频繁重启节点导致的硬件中断问题。