使用旋转 Shim 控制器（Rotation Shim Controller）

• 概述
• 什么是旋转 Shim 控制器？
• 配置旋转 Shim 控制器
• 配置主控制器
• 演示执行

概述

本教程介绍如何为机器人配置 RotationShimController，使其在开始跟随路径前先原位旋转到路径方向。内容涵盖该控制器的作用、配置方法、与主控制器的配合使用，并给出实际示例。

阅读本教程前，建议先完成快速入门，尤其是刚接触 ROS 和 Nav2 的用户。需安装包含该软件包的最新版 Nav2/ROS 2。

什么是旋转 Shim 控制器？

该控制器最初是为了解决 TEB 和 DWB 的一些意外行为而开发的，但适用于任何希望具备原位旋转能力的控制器插件。由于弹性带（elastic band）方法的限制，TEB 在路径起始方向与当前航向相差较大时，倾向于让机器人以小角度不断来回摆动，行为不太可预期。DWB 虽然可以通过调参实现各种行为，但将其调校为优秀的路径跟随器后，往往在新路径起始航向偏差较大时过渡不够平滑——两者总有权衡。让 TEB 和 DWB 先有个好的起点再开始跟随路径，能显著降低调校难度，也使运行效果更加直观。

需要注意的是，该控制器并非必须与其他插件搭配使用。许多用户不使用它也能取得很好的效果。但如果机器人在开始路径跟随（或其他任务）前需要先原位旋转，那么使用它会更加合适。

nav2_rotation_shim_controller 会检测机器人当前航向与新收到路径起始方向之间的角度差。如果差值在阈值范围内，直接将请求传递给 primary_controller 执行；如果超出阈值，则控制机器人原位旋转，直到朝向路径方向。一旦进入容差范围，即将控制权从旋转 Shim 控制器移交给主控制器插件，由主插件接管后续任务，实现平滑交接。

RotationShimController 最适合用于：

• 可以原位旋转的机器人，例如差速（differential）和全向（omnidirectional）机器人。
• 在开始跟随一条与当前航向差异较大的新路径时倾向于先原位旋转，或者控制器调校后难以完成紧密旋转的场景。
• 使用非运动学可行（non-kinematically feasible）的规划器时，例如 NavFn、Theta或 Smac 2D。运动学可行规划器（如 Smac Hybrid-A 和 State Lattice）会从机器人实际起始航向开始搜索，其路径受物理约束保证可行驶，因此无需旋转。

注意：Regulated Pure Pursuit 内置了此功能，因此无需与 RPP 搭配使用。但它适用于所有其他控制器。参见插件获取当前控制器插件的完整列表。

配置旋转 Shim 控制器

该控制器之所以称为 shim（垫片），是因为它位于主控制器插件与控制器服务器之间。它接收命令并进行预处理——先将机器人旋转到目标航向，满足条件后再将控制权移交给主插件，充当简单的透传层。

因此，它的配置方式与其他插件类似。下面的代码块中，RotationShimController 已被添加为控制器服务器的路径跟随插件，其内部参数从 angular_dist_threshold 到 max_angular_accel 依次配置。

controller_server:
  ros__parameters:
    controller_frequency: 20.0
    min_x_velocity_threshold: 0.001
    min_y_velocity_threshold: 0.5
    min_theta_velocity_threshold: 0.001
    progress_checker_plugins: ["progress_checker"] # progress_checker_plugin: "progress_checker" For Humble and older
    goal_checker_plugins: ["goal_checker"]
    controller_plugins: ["FollowPath"]
    progress_checker:
      plugin: "nav2_controller::SimpleProgressChecker"
      required_movement_radius: 0.5
      movement_time_allowance: 10.0
    goal_checker:
      plugin: "nav2_controller::SimpleGoalChecker"
      xy_goal_tolerance: 0.25
      yaw_goal_tolerance: 0.25
      stateful: True
    FollowPath:
      plugin: "nav2_rotation_shim_controller::RotationShimController"
      angular_dist_threshold: 0.785
      forward_sampling_distance: 0.5
      rotate_to_heading_angular_vel: 1.8
      max_angular_accel: 3.2
      max_cost_threshold: 254.0
      simulate_ahead_time: 1.0

旋转 Shim 控制器非常简单，只有少量参数控制其启用条件。

• angular_dist_threshold：触发旋转行为时，机器人当前航向与近似路径航向之间的角距离（弧度）。一旦进入该阈值范围内，控制权即移交给主控制器插件。
• forward_sampling_distance：机器人前方距离（米），用于在路径上选取一个点来近似路径的起始航向，类似于「前瞻」（lookahead）点。
• rotate_to_heading_angular_vel：行为启用时，机器人旋转到目标航向的角速度（rad/s）。
• max_angular_accel：行为启用时，机器人旋转到目标航向的角加速度（rad/s/s）。
• max_cost_threshold：用于检测碰撞的最大足迹代价（footprint cost）阈值。默认 254.0，即 LETHAL_OBSTACLE（致命障碍物）。
• simulate_ahead_time：前向投影旋转命令以检查碰撞的时间（秒）。

配置主控制器

RotationShimController 还有一个上面未提到的参数：primary_controller。该参数指定应用中实际使用的主要控制器类型。 下面的示例展示了将主控制器设置为 DWB 的配置（为简洁起见，省略了进度检查器和目标检查器）。

controller_server:
  ros__parameters:
    controller_frequency: 20.0
    min_x_velocity_threshold: 0.001
    min_y_velocity_threshold: 0.5
    min_theta_velocity_threshold: 0.001
    controller_plugins: ["FollowPath"]
    FollowPath:
      plugin: "nav2_rotation_shim_controller::RotationShimController"
      angular_dist_threshold: 0.785
      forward_sampling_distance: 0.5
      rotate_to_heading_angular_vel: 1.8
      max_angular_accel: 3.2
      max_cost_threshold: 254.0
      simulate_ahead_time: 1.0
      primary_controller:
        plugin: "dwb_core::DWBLocalPlanner"
        # DWB parameters
        ...
        ...
        ...

演示执行