Iron 迁移指南

从 ROS 2 Iron 迁移到 Jazzy 时，引入了大量稳定性改进，此处不一一赘述。

BehaviorTree.CPP 升级到 4.5+ 版本

版本从 3.8 升级到 4.5 后，用户需要相应更新 XML 和源代码。

更多细节请参阅此页面，主要变化如下：

• XML 必须更改。这个 python 脚本可以提供帮助。
• SubTrees 的语法已经改变，请改用 SubTreePlus 语法。
• 如果你创建了自定义的 ControlNode 或 DecoratorNode，你必须处理子节点返回 BT::NodeStatus::SKIPPED 的情况。

为命令新增 TwistStamped 选项

新增参数 enable_stamped_cmd_vel，适用于所有 cmd_vel 及相关话题的发布器和订阅器。开启后可用 TwistStamped 消息替代 Twist 消息，使速度命令附带坐标系和时间戳信息。该参数目前默认为 false 以保持向后兼容，但后续计划与 Gazebo、ROS 2 Control 等项目协同，将 TwistStamped 设为默认行为。

在碰撞监控器中新增 VelocityPolygon

PR #3708 在碰撞监控器（Collision Monitor）中新增了 VelocityPolygon 类型，允许用户设置多个多边形来覆盖不同速度范围内的机器人轮廓。例如，可为旋转、前进或后退分别配置不同多边形。碰撞监控器会根据机器人当前速度匹配相应的子多边形，用于碰撞检查。教程请参阅配置带 VelocityPolygon 的碰撞监控器。

更改碰撞监控器中多边形点参数的格式

PR #4020 将 Polygon points 参数的格式从 vector<double> 改为 string，使碰撞监控器（Collision Monitor）和 Costmap_2D 之间的多边形描述更加统一。现在可用字符串定义多边形顶点，结构为 vector<vector<double>>，例如 "[[p1.x, p1.y], [p2.x, p2.y], [p3.x, p3.y],...]"，至少需描述 4 个点。方形多边形示例如下：

PolygonFront:
  type: "polygon"
  points: "[[0.3, 0.3], [0.3, -0.3], [0.0, -0.3], [0.0, 0.3]]"
  action_type: "none"
  min_points: 4
  visualize: True
  polygon_pub_topic: "polygon_front"

引入软实时动作服务器

PR #3914 为控制器服务器（Controller Server）添加了软实时优先级，以更好地保障时间敏感代码的资源供给。Simple Action Server 新增 realtime 输入字段，并通过 Controller Server 的 use_realtime_priority 参数暴露。开启后，控制器的执行线程会获得比系统其他部分更高的优先级，以满足调度截止时间要求。使用该功能需在 /etc/security/limits.conf 中添加以下内容，授予用户空间提升优先级的权限。目前仅在 Controller Server 中启用（其执行线程对调度优先级敏感），但将来如有需要也可扩展到其他线程。

<username> soft rtprio 99
<username> hard rtprio 99

碰撞监控器和速度平滑器（Velocity Smoother）也新增了 use_realtime_priority 参数。

opennav_coverage 项目

新增元包（metapackage）：opennav_coverage，其中包含完整的覆盖（coverage）导航器插件、行为树节点、行为树演示，以及基于 Fields2Cover 的覆盖规划服务器。更多详情请参阅该项目。长期计划是纳入 Nav2，但 Fields2Cover 尚有一些功能缺失，需待其补齐后才能集成到主项目中。

如果你希望直接在 Nav2 中看到覆盖规划，请考虑为此处描述的尚待实现的功能做出贡献。

opennav_docking 项目

新增元包：opennav_docking，其中包含完整的自动充电停靠框架、行为树节点、插件和演示，能够以通用、可复用的方式为各类机器人对接各类充电桩。该项目已直接集成到 Nav2 技术栈中（即 nav2_docking）。

使用教程请参阅使用停靠功能（Docking）。感谢 NVIDIA 赞助此包。

引入新的多机器人 Bringup 启动

PR #3572 引入了新的 tb3 多机器人 bringup 方式。仿真中使用 cloned_tb3_simulation_launch.py 启动文件，通过 nav2_multirobot_param_all.yaml 中的相同参数启动多个机器人，各机器人通过 Launch 参数中指定的命名空间实现隔离。原有的 multi_tb3_simulation_launch.py 被 unique_tb3_simulation_launch.py 取代，后者可用 nav2_multirobot_params_<N>.yaml 配置文件启动多个独立的机器人实例。

Voxel 和障碍物图层的新选项

PR #3612 为 Voxel 和障碍物图层的 combination_method 参数新增了 MaxWithoutUnknownOverwrite 选项，用于确保静态地图作为信息的主要来源，有效防止机器人穿过静态地图中不存在的区域。

use_interpolation RPP 参数已弃用

经过大量用户的多轮测试，现已弃用 use_interpolation 参数——该功能始终默认开启且无法禁用。在所有场景下，它都能有效改善速度平滑度和整体跟踪质量。

MPPI Goal Critic 的变更

MPPI Goal critic 的公式已调整，使其在接近目标时更好地保持速度，而非过早大幅减速。同时改进了权重的利用方式，使减速程度的调节更加自然。此变更涉及将 threshold_to_consider 调整为与预测时域（例如 samples dt max speed）一致，使 goal critic 和 path follower critic 之间能够平滑交接，无需减速。

MPPI Path Angle Critic 的变更

MPPI 的 Path Angle critic 新增了 mode 设置，可根据机器人期望的行为特征调整策略。此前它会惩罚与机器人前进朝向偏差较大的路径朝向，以引导机器人在路径方向急剧变化处及时转向。这仍是默认行为（mode: 0），但现在还支持其他模式。

mode: 1：根据前进朝向或相反朝向（用于倒车）设置路径相对方向的惩罚，使对称机器人能在某一方向不可取时实现真正的双向运动。它仅依据路径相对于机器人的点来决定激励哪个方向。

mode: 2：当路径来自 Smac 规划器或平滑器服务器算法（运动学可行路径）时，改用路径本身的朝向。这样遵循的是全局规划的朝向，而不仅仅基于路径的相对点。对于高度受限环境中的非圆形机器人尤为有用——在这些环境中改变方向的机会有限，必须遵循全局路径的朝向才能以所需朝向到达目标。

MPPI 方向性路径处理的变更

MPPI 的 Path Align Critic 和 Path Handler 现在可以选择利用路径的朝向信息，仅在可行规划器请求时才强制控制器改变方向。当 enforce_path_inversion 为 true 时，路径处理器会将路径修剪到方向首次改变的位置，强制控制器规划到反转点，待进入容差范围后再设置路径的其余部分。Path Align Critic 还包含参数 use_path_orientations，可与之配合使用，激励对齐包含朝向信息的路径——在请求时更好地实现路径反转，同时在未请求时不执行反转。

完整信息请参阅 MPPI 的配置指南。

新增 MPPI Cost Critic

与 ObstacleCritic 类似，CostCritic 是另一种避障 critic 替代方案，适用于 ObstacleCritic 效果不理想的场景。该 critic 使用代价地图中的膨胀代价（inflated cost）来评分，而非像 ObstaclesCritic 那样使用到障碍物的距离。详情请参阅配置指南。

MPPI 加速

Jazzy 中的新特性：经过数周的优化工作，MPPI 速度提升了 45%。

移动错误码枚举

PR #3693 将枚举错误码从目标（goal）部分移到结果（result）部分。

参数文件中的替换（substitution）

参数文件中启用了替换（substitution）。例如，你可以这样写：

bt_navigator:
  ros__parameters:
    default_nav_to_pose_bt_xml: $(find-pkg-share my_package)/behavior_tree/my_nav_to_pose_bt.xml

关于替换语法的更多信息，请参阅此处。

允许行为服务器插件访问动作结果

PR #3704 允许行为服务器插件访问和修改动作结果。

Smac 规划器调试参数更名

debug_visualizations 取代了 Hybrid-A* 中的 viz_expansions 参数，以反映现在还会发布足迹调试信息。

Smac 规划器接近目标时的捷径（shortcutting）解决方案

PR #3962 在 Humble 中 analytic_expansion_max_length 的基础上新增了参数 analytic_expansion_max_cost 和 analytic_expansion_max_cost_override，进一步限制接近目标时靠近障碍物的路径捷径。其中最大代价参数（默认 200）用于判断扩展是否比预期更靠近障碍物。当扩展距离目标非常近且 analytic_expansion_max_cost_override 为 false 时，可能覆盖此约束——这是为了在必要时找到可行的路径解。该 PR 还引入了额外的解析扩展评分逻辑和边缘情况处理，通过类似的启发式函数来提高路径质量。

新增 GPS 航点跟随服务器

此 PR #2814 为 nav2_waypoint_follower 新增了 follow_gps_waypoints 动作服务器。该服务器接受一组 GPS 目标（而非笛卡尔坐标目标），并支持 nav2_waypoint_follower 的所有其他功能。配套教程见 navigation2_tutorials 的 PR 70，可在本网站的 General Tutorials 目录中找到。

Smac Planner Hybrid-A* 新特性

新增特性包括 allow_primitive_interpolation（允许在搜索集合中加入更多基元）、use_quadratic_cost_penalty（影响遍历和启发式函数中的代价惩罚顺序），以及 downsample_obstacle_heuristic（可选不对障碍物启发式的代价地图进行降采样）。默认行为保持不变。如需使用这些新特性，请参阅 Smac Planner Hybrid-A* 的配置指南。

nav2_collision_monitor 中的新节点：Collision Detector

此 PR #3500 为 nav2_collision_monitor 引入了新节点：碰撞检测器（Collision Detector）。其工作原理与碰撞监控器（Collision Monitor）类似，但不会影响机器人速度。它仅通过 collision_detector_state 话题发布消息，报告在配置的多边形内是否检测到来自配置数据源的数据，供外部模块使用（例如在碰撞时切换 LED 或触发声音警报）。

在碰撞监控器/检测器中动态启用/禁用数据源和多边形

此 PR #3825 新增了在碰撞监控器/检测器（Collision Monitor/Detector）中动态启用/禁用数据源和多边形的能力。

暴露动作服务器的结果超时

此 PR #3787 为所有具有动作服务器的节点暴露了结果超时参数。原因是 rcl 的PR #1012 引入了一项变更：如果结果未在 10 秒内产生，动作服务器将丢弃目标句柄（此前默认值为 15 分钟）。由于 Nav2 中某些动作可能需要超过 10 秒才能完成，用户现可通过 action_server_result_timeout 参数设置该值——在 bt_navigators 和 waypoint_follower 中默认为 15 分钟，在其他节点中默认为 10 秒。

RewrittenYaml 可以向 YAML 添加新参数

Nav2 launch 脚本中广泛使用的 RewrittenYaml 现在不仅能替换原始 YAML 中已有的 ROS 参数，还能添加 YAML 中不存在的新参数。当然，这些参数必须在目标 ROS 节点中声明，否则运行时不会处理。此时参数应以点分隔的绝对路径表示。例如，FollowPath 节点的 prune_distance 参数重写在 RewrittenYaml() 的 param_rewrites 字典中写为 'controller_server.ros__parameters.FollowPath.prune_distance': '1.0'。该变更随 PR #3785 引入。

Simple Commander API 支持多机器人命名空间

Simple Navigator API 现在通过构造函数中的 namespace 字段支持多机器人命名空间，可指定某个机器人或系统的 Nav2 技术栈命名空间。详见此 PR。

更改 wait_action 节点中 duration 的类型

此 PR #3871 将 wait_action 节点中 duration 变量的类型从 int 改为 double，使 wait_action 支持浮点值。

所需变换不可用时代价地图激活失败

此 PR #3866 为代价地图新增了参数 initial_transform_timeout。如果在此超时时间内，机器人基坐标系（base frame）到全局坐标系的变换仍不可用，代价地图的激活将失败。

子树获得共享资源

PR #3911 赋予 BT.CPP 中所有子树与主树相同的共享资源（节点、共享超时等）。

碰撞监控器：新增看门狗机制（默认阻塞行为）

PR #3880 新增了基于 source_timeout 参数的看门狗机制：如果数据源尚未发布数据，或在 source_timeout 参数设定的时间内未收到新数据，或无法将数据变换到基坐标系，则会停止机器人。source_timeout 参数现在可以按数据源单独设置：如果某个数据源未设置 source_timeout，则使用节点的 source_timeout 参数值。

此外，可以通过设置 source_timeout: 0.0 来禁用此看门狗机制。

BtActionServer：使用原生库 haltTree()

PR #3950 将原先通过 BehaviorTreeEngine::haltAllActions 暂停行为树节点的方式，改为使用 BT.CPP 的原生方法 haltTree()。

此前，动作完成时仅活动的行为树节点会被暂停。变更后，所有行为树节点的 halt() 方法都会被调用。这对于需要在 halt() 中执行清理操作的场景（例如离开时关灯）非常方便。

同时还更新了 nav2_behavior_tree::BtActionServer::haltTree() 以使用相同方法。该方法在 Nav2 内部暂未使用，但对于外部用户（例如希望在抢占时暂停整棵行为树的用户）很有用。

从 2 个行为树节点中移除全局坐标系

从 RemovePassedGoals 和 GoalReached 行为树节点中移除了全局坐标系（Global Frame），改用目标消息头（headers）的 frame_id 进行变换。

引入 CostmapUpdate.msg

PR #3965 引入了新消息类型 CostmapUpdate.msg，作为 Costmap.msg 的增量更新消息。此前每条消息都发送整个代价地图，而 CostmapUpdate.msg 只包含自上次更新以来发生变化的代价地图区域。Costmap.msg 仅在开始时发送一次，之后发送 CostmapUpdate.msg，类似于 OccupancyGrid.msg 和 OccupancyGridUpdate.msg 的行为模式。

要激活此功能，必须将 Costmap2D ROS 参数 always_send_full_costmap 设置为 false。

要订阅 Costmap.msg 和 CostmapUpdate.msg，建议使用 CostmapSubscriber 类。

整个技术栈使用节点时钟

整个技术栈不再使用墙钟定时器（wall timer）或墙钟频率（wall rate），改用节点时钟。当 use_sim_time 为 true 时使用 ROS Time（仿真时钟），否则使用稳态时钟（steady clock）。

新的优雅运动控制器（Graceful Motion Controller）

PR #4021 为差速驱动机器人引入了一种新型控制器，它基于位姿跟随的运动学控制律，可生成平滑舒适的轨迹。

更多信息请参阅 configuring_graceful_motion_controller。

BT Navigator 中的插件库仅包含自定义节点

Jazzy 中的新特性：plugin_lib_names 参数现在会隐式包含所有 Nav2 行为树节点，用户只需指定额外自定义的行为树插件即可。

用于选择规划器、控制器、目标检查器、进度检查器和平滑器的新 RViz 插件

PR #4091 新增了一个 RViz 插件，用于实时选择规划器、控制器、目标检查器、进度检查器和平滑器。

该插件旨在方便开发人员对配置进行快速集成测试，而后再将机器人部署到实际应用中。

为实现组件的动态选择，所有相关行为树选择器节点均已被启用，并更新到了所有关联的行为树节点。

此处可以看到该插件的工作演示：

GIF 中可以看到两个 controller_id：FollowPath 和 HighSpeedFollowPath，默认使用行为树中定义的那个。其中 FollowPath 是默认的 controller_id，两者的区别在于 HighSpeedFollowPath 的最大速度更高，这在 GIF 中可以清楚看到。

警告：如果某个服务器不可用，则该特定组件的下拉列表将为空。

RPP 新增可选的 interpolate_curvature_after_goal 行为，并修复 use_rotate_to_heading 与 allow_reversing 之间的冲突

PR #4140 新增了可选参数 interpolate_curvature_after_goal（默认 false），用于在目标点之后激活胡萝卜点（carrot）的插值，保持恒定的曲率前瞻距离，避免在路径末端生成角速度时出现不稳定。用于线速度计算的胡萝卜点保持不变。

插值基于路径最后两个位姿构成的向量朝向。因此当 interpolate_curvature_after_goal 为 true 时，长度为 1 的路径会被拒绝。该参数仅在 use_fixed_curvature_lookahead: true 时生效。

此外，use_rotate_to_heading 和 allow_reversing 之间的冲突已修复，现在 use_rotate_to_heading 可以在倒车时使用。

GlobalPlanner 的取消检查接口

PR #4148 为 GlobalPlanner 引入了新接口，允许取消当前的规划任务。此前即使目标已取消，规划器仍会继续规划；现在规划器可以检查目标是否已取消，并在取消时终止规划。GlobalPlanner::createPlan 的新接口：

virtual nav_msgs::msg::Path createPlan(
  const geometry_msgs::msg::PoseStamped & start,
  const geometry_msgs::msg::PoseStamped & goal,
  std::function<bool()> cancel_checker)

该接口已在技术栈中的所有规划器上实现，可参考它们了解 cancel_checker 的用法示例（只需调用 cancel_checker() 即可）。Smac 和 Theta* 规划器新增了参数 terminal_checking_interval，表示以迭代次数为单位的取消或超时检查间隔。

BtActionServer/BtNavigator 新参数

PR #4209 引入了布尔参数 always_reload_bt_xml：无论当前活动的 XML 是什么，都会重新加载所请求的行为树 XML 描述。这样在开发行为树 XML 期间无需重启动作服务器。

碰撞监控器新参数

PR #4207 引入了一个新的布尔参数 polygon_subscribe_transient_local（默认值为 false），用于设置多边形话题或足迹话题订阅的 QoS 持久性（durability）。

控制器新的优雅取消 API

PR #4136 为控制器引入了优雅取消 API。此前目标被取消时，控制器会立即停止机器人；新 API 允许控制器以更平滑的方式停车。该 API 已在 RegulatedPurePursuitController 中实现，新增参数 cancel_deceleration——目标取消时，控制器会以恒定减速度在继续跟踪路径的同时减速停车，而非急停。该 API 后续将推广到所有有加速度限制的控制器。

插件命名标准化为双冒号（::）

PR #4220 将整个 Navigation2 包中的插件命名标准化为使用双冒号（::），取代了之前混用的斜杠（/）和双冒号。受影响的插件包括：

• Behavior Server：nav2_behaviors::Spin、nav2_behaviors::BackUp、nav2_behaviors::DriveOnHeading、nav2_behaviors::Wait、nav2_behaviors::AssistedTeleop
• Planner Server：nav2_navfn_planner::NavfnPlanner、nav2_smac_planner::SmacPlanner2D、nav2_smac_planner::SmacPlannerHybrid、nav2_theta_star_planner::ThetaStarPlanner
• Controller Server：nav2_regulated_pure_pursuit_controller::RegulatedPurePursuitController、nav2_dwb_controller::DWBLocalPlanner
• BT Navigator：nav2_bt_navigator::NavigateToPoseNavigator、nav2_bt_navigator::NavigateThroughPosesNavigator

碰撞监控器：圆形多边形的动态半径

PR #4226 为圆形多边形引入了参数 <polygon_name>.polygon_sub_topic。若未设置 <polygon_name>.radius，碰撞监控器节点会订阅话题 <polygon_name>.polygon_sub_topic（消息类型为 std_msgs/msg/Float32），并根据接收到的消息动态更新圆形多边形的半径。

Static Layer：新参数 footprint_clearing_enabled

PR #4282 为静态图层引入了 footprint_clearing_enabled 参数，工作方式与障碍物图层和体素图层中的同名参数类似。设为 true 时，静态图层会清除机器人足迹内的代价地图栅格。默认值为 false，以保持原有行为。

生命周期节点：新增 bond_heartbeat_period 参数（并允许禁用 bond 机制）

PR #4342 为生命周期节点新增了参数 bond_heartbeat_period，用于自定义 bond 机制的发布周期（在 /bond 话题上）。默认值为 0.1 秒。小于或等于 0.0 时禁用。

Rotation Shim 控制器：新参数 rotate_to_goal_heading

PR #4332 为 rotation shim 控制器引入了 rotate_to_goal_heading 参数，允许在达到 XY 目标容差时重新接管控制，朝目标朝向进行旋转。有些控制器内部已实现此功能，但对于其他控制器来说，这是一个实用的选项。

MPPI 控制器：新增加速度约束

PR #4352 为 MPPI 控制器新增了参数 ax_max、ax_min、ay_max、az_max。这些参数将使 MPPI 控制器能够在指定的加速度约束内生成局部轨迹。

RegulatedPurePursuit 控制器（RPP）：新参数 use_cancel_deceleration

PR #4441 为 regulated pure pursuit 控制器新增了参数 use_cancel_deceleration。该参数使控制器在目标被取消时，能够使用恒定减速度优雅地停止机器人，而不是立即停止。

清除传入位姿周围的代价地图

在 PR #5309 中，nav2_costmap_2d 包新增了一个服务，用于清除传入位姿周围的代价地图。

nav2_behavior_tree 包中的清除代价地图插件（clear costmap plugin）也新增了一个服务客户端。

这在以下场景中特别有用：由于目标位置的代价地图数据过时（通常在障碍物/光线追踪范围之外，且通常是由已经移走的动态障碍物造成）而导致规划器失败。这与清除整个代价地图的恢复行为不同——该功能支持定向清除，从而保留有用的地图数据。

RViz 可视化展示了在期望的目标位置清除过时代价的示例，此前这会导致 SMAC 等规划器规划失败。

下面是一个在行为树中使用 ClearCostmapAroundPose 的示例：当规划器无法计算路径时，清除目标位姿周围的代价地图。

<RateController hz="1.0">
  <RecoveryNode number_of_retries="1" name="ComputePathToPose">
      <ComputePathToPose goal="{goal}" path="{path}" planner_id="{selected_planner}" error_code_id="{compute_path_error_code}" error_msg="{compute_path_error_msg}"/>
      <ClearCostmapAroundPose name="ClearCostmapAroundPose-Context" service_name="global_costmap/clear_around_pose_global_costmap" pose="{goal}" reset_distance="5.0"/>
  </RecoveryNode>
</RateController>