Foxy 迁移指南

从 ROS 2 Foxy 迁移到 Galactic 带来了大量稳定性改进，此处不逐一展开。

NavigateToPose 动作反馈更新

NavigateToPose 动作反馈有两项改进：

• distance_remaining 现在会积分路径位姿，以报告准确的剩余距离。此前，该字段报告的是当前位姿与目标位姿之间的欧几里得距离。
• 新增了 estimated_time_remaining 字段。该字段通过将剩余距离除以当前速度来报告预计剩余时间。

NavigateToPose BT 节点接口变更

NavigateToPose 的输入端口已改为 PoseStamped，而不是 Point 和 Quaternion。

更多信息请参阅 bt_navigate_to_pose_action。

新增 NavigateThroughPoses 和 ComputePathThroughPoses 动作

与 NavigateToPose 类似，新增了 NavigateThroughPoses 动作。该动作并非前往单个目标位置，而是允许用户在起始位姿与最终位姿之间指定若干必须经过的中间位姿，使路径能够依次穿过这些位姿。新的 ComputePathThroughPoses 动作已添加到 planner_server，用于通过 N 个 goal_poses 处理这些请求。

ComputePathThroughPoses 动作服务器接收一组 N 个待到达的目标点，分别规划经过每个位姿的路径，再将各段路径拼接起来供导航使用。控制器和导航器不了解所生成路径的语义，因此机器人在接近这些目标时不会停止或减速，而是会像通过路径上的其他普通点一样连续经过每个位姿。与 SmacPlanner 配合使用时，该功能可用于生成完全满足运动学可行性、穿过位姿约束的轨迹。

如果你希望在每个目标位姿处停下，可以考虑改用 waypoint follower（航点跟随器），它会在每个位姿处停下，并允许用户选择性地在每个位姿处执行任务插件。

ComputePathToPose BT 节点接口变更

新增了 start 输入端口，通过该端口可以选择请求从 start 到 goal 的路径，而不是从机器人当前位置到 goal 的路径。

更多信息请参阅 bt_compute_path_to_pose_action。

ComputePathToPose 动作接口变更

• 目标位姿字段 pose 已更名为 goal。
• 新增了 PoseStamped 类型的 start 字段。
• 新增了布尔字段 use_start。

这两个新增字段用于在 use_start 为 true 时，可选择请求从 start 到 goal 的路径，而不是从机器人当前位置到 goal 的路径。Planner Server 也做了相应的修改。

BackUp BT 节点接口变更

backup_dist 和 backup_speed 输入端口都应为正值，分别表示向后倒退的距离和机器人向后倒退的速度。

BackUp 恢复接口变更

BackUp 恢复目标中的 speed 应为正值，表示向后倒退的速度。 BackUp 恢复目标中的 target.x 应为正值，表示向后倒退的距离。 在这两种情况下，负值都会被静默取反。

Nav2 控制器和目标检查器插件接口变更

从此 PR 2247 开始，controller 插件现在会在 computeAndPublishVelocity() 中获取当前导航任务所用目标检查器的指针。目的是让控制器能够访问目标完成的预测性检查，以及目标检查器插件的状态信息。

goal_checker 插件还新增了一个 getTolerances() 方法。该方法供目标检查器的调用方获取目标检查器在目标点处要考虑的容差信息。pose 和 velocity 的每个字段表示在判定目标完成时，每个维度允许的最大误差。对于平移容差（X 和 Y 分量的组合），X 和 Y 都会填入该容差值，因为它是该维度上的最大容差（假设另一个维度没有误差）。如果目标检查器对某个维度没有设置容差，则使用 numeric_limits<double> lowest() 的值代替。

FollowPath 的 goal_checker_id 属性

例如：对于某些特定的导航运动，你可以使用比常规运动所用的默认目标检查器更精确的目标检查器。

<FollowPath path="{path}" controller_id="FollowPath" goal_checker_id="precise_goal_checker" server_name="FollowPath" server_timeout="10"/>

• 此前通过 goal_checker_plugin 参数声明 controller_server 目标检查器的用法已被废弃并移除。

• controller_server 参数现在支持声明目标检查器列表 goal_checker_plugins，并为其指定唯一的标识符名称，就像控制器和规划器插件分别使用 FollowPath 和 GridBased 一样。

• 当 controller_server 参数配置中定义了多个检查器时，必须指定所选的目标检查器。如果 controller_server 中只配置了一个 goal_checker，则即使未显式指定，也会默认选中它。

下面展示了 controller_server 节点的 goal_checker 配置示例。

controller_server:
  ros__parameters:
      goal_checker_plugins: ["general_goal_checker", "precise_goal_checker"]
      precise_goal_checker:
          plugin: "nav2_controller::SimpleGoalChecker"
          xy_goal_tolerance: 0.25
         yaw_goal_tolerance: 0.25
      general_goal_checker:
          plugin: "nav2_controller::SimpleGoalChecker"
          xy_goal_tolerance: 0.25

Groot 支持

现在可以使用 Groot 对行为树进行实时监控和编辑，还支持通过新的目标请求动态切换 bt-xml 文件。上述功能默认启用，且不破坏任何现有 API。

新插件（New Plugins）

nav2_waypoint_follower 包含一个动作服务器，接收要跟随的航点列表并按顺序依次跟随。在某些场景下，我们可能希望机器人在到达航点时执行一些特定任务。为此，nav2_core 中新增了通用插件接口 WaypointTaskExecutor。用户可以继承该接口来实现自定义插件，在到达航点时执行所需的具体任务。

nav2_waypoint_follower 中提供了几个示例实现。WaitAtWaypoint 和 PhotoAtWaypoint 作为运行时加载的插件包含在 nav2_waypoint_follower 中。WaitAtWaypoint 让机器人在到达航点时暂停指定的毫秒数；PhotoAtWaypoint 则在到达航点时拍照，并将照片保存到指定目录，照片格式可通过参数配置，支持 png、jpeg、jpg 等主流图像格式，默认格式为 png。

通过 nav2_bringup/params/nav2_param.yaml 加载此类插件时，需要指定插件的名称、类型及其使用的参数。

waypoint_follower:
  ros__parameters:
    loop_rate: 20
    stop_on_failure: false
    waypoint_task_executor_plugin: "wait_at_waypoint"
      wait_at_waypoint:
        plugin: "nav2_waypoint_follower::WaitAtWaypoint"
        enabled: True
        waypoint_pause_duration: 0

原始 GitHub 议题：

• WaypointTaskExecutor
• WaitAtWaypoint
• PhotoAtWaypoint
• InputAtWaypoint

代价地图过滤器（Costmap Filters）

Galactic 版本引入了一个新概念——代价地图过滤器（Costmap Filters），用于实现与空间标注对象的交互（关于该概念的更多信息请参阅核心概念页面）。代价地图过滤器作为代价地图插件运行，作用在常规插件所在的代价地图之上。为了生成过滤后的代价地图并改变机器人在标注区域内的行为，过滤器插件会读取过滤掩码（filter mask）的数据，并将其线性转换为过滤器空间中的特征图（feature map）。特征图的内容可以是区域的可通过性、以 m/s 为单位的最大速度限制、以度为单位的机器人期望方向等。插件算法会综合使用特征图、地图/代价地图、传感器数据和当前机器人位置，对最终的代价地图和机器人行为进行更新。

在架构上，代价地图过滤器由 CostmapFilter 类组成，该基类为其子类过滤器插件提供了许多公共功能：

• KeepoutFilter：禁入/安全区域过滤器插件。
• SpeedFilter：慢速/限速区域过滤器。
• 工业场景中的优先车道（preferred lanes）。该插件由 KeepoutFilter 覆盖（更多细节请参阅相应 PR 中的讨论）。

每个代价地图过滤器都会订阅过滤器信息话题（由 Costmap Filter Info Publisher Server 发布），该话题包含所加载代价地图过滤器的全部必要信息；同时还会订阅过滤掩码话题。SpeedFilter 还会向控制器（Controller）发布最大速度限制消息，以确保机器人不会超过给定限制。

该概念的高层设计详见此处。代价地图过滤器的功能在议题 #1263 中进行了讨论，并由 PR #1882 实现。以下教程：禁入区过滤器（Keepout Filter） 和速度过滤器（Speed Filter） 将帮助你快速上手 KeepoutFilter 和 SpeedFilter。

SmacPlanner

新增了 nav2_smac_planner 包，包含 4 或 8 邻接的 2D A*、基于 Dubins 和 Reed-Shepp 曲线的带平滑 Hybrid-A*、多分辨率查询等功能。

nav2_smac_planner 包实现了优化的模板化 A搜索算法，可为多种类型的机器人平台创建多个基于 A 的规划器。SmacPlanner2D 实现了代价感知（cost-aware）A规划器，支持差速驱动和全向驱动机器人。SmacPlanner 插件实现了 Hybrid-A 规划器，支持汽车、类汽车和阿克曼（Ackermann）车型。该插件也适用于曲率受限的规划场景，例如在机器人高速行驶时规划路径，确保机器人不会翻车或失控打滑。

SmacPlanner 完整实现了论文《Practical Search Techniques in Path Planning for Autonomous Driving》中提出的 Hybrid-A* 规划器，包括混合搜索、CG 平滑、解析扩展和启发式函数。

ThetaStarPlanner

新增了 nav2_theta_star_planner 包，包含针对 2D 地图的 4 或 8 邻接 Theta* 实现。

该包实现了 Theta* 路径规划器的优化版本（具体为 Lazy Theta* P 变体），可为差速驱动和全向机器人规划任意角度的路径，同时考虑代价地图中的代价值。该插件适用于希望以更高频率规划路径、但不需要拐角处路径极其平滑的场景——这种平滑处理可以交给局部规划器/控制器来完成。

RegulatedPurePursuitController

新增了 nav2_regulated_pure_pursuit_controller 包，包含 Pure Pursuit 算法的一种新变体。它还支持启用标准 Pure Pursuit 和自适应 Pure Pursuit（Adaptive Pure Pursuit）变体的配置。

该变体专门面向服务/工业机器人的需求：

• 根据路径曲率调节线速度，有助于减少在盲区弯道高速行驶时的超调，使运行更安全。
• 与目前可用的其他 Pure Pursuit 变体相比，能更好地跟踪路径。
• 内置在靠近障碍物时减速的启发式策略，当附近可能存在碰撞风险时，机器人会自动减速。
• 实现了自适应前瞻点（Adaptive lookahead point）特性，前瞻距离按速度进行缩放，从而在更宽的速度范围内保持稳定的行为。

该变体的功能不止上述这些，以上仅为总体介绍。更多信息请参阅该包的 README。

Costmap2D 中 current_ 的用法

在 Costmap2D 中，current_ 在 ROS 1 中用于表示代价地图图层是否仍然启用并正在积极处理数据。只有在传感器未达到预期更新频率、导致数据过期或收不到消息的情况下，它才会被置为 false，充当导航传感器停止发布时的故障保护机制。

在 Galactic 中，这一行为保持不变，但新增了额外的功能：当代价地图因清除操作或其他导航恢复行为而被重置时，current_ 也会被置为 false。这使得机器人在重置后代价地图至少更新一次之前，不会生成规划或执行控制。这样可以避免在代价地图完全为空时生成路径或执行控制（可能导致碰撞）——例如清除代价地图后立即请求运行算法的情况。

参数中的标准时间单位

为严格遵循 REP-103 规定的 SI 单位制，以下节点已修改为在所有参数中统一使用秒。每个节点名称下列出了从毫秒改为秒的参数。

• lifecycle manager

  • bond_timeout_ms 变为 bond_timeout，单位改为秒

• smac planner

  • max_planning_time_ms 变为 max_planning_time，单位改为秒

• map saver

  • save_map_timeout，单位为秒

光线追踪参数（Ray Tracing Parameters）

光线追踪功能新增了一个最小范围参数，光线追踪从该范围开始清除障碍物，以避免错误地清除离机器人太近的障碍物。该问题在 ROS Answers 中有所提及。现有参数 raytrace_range 已更名为 raytrace_max_range，以准确反映其作用。更名后的参数及其所属插件如下所示，相关更改由该拉取请求 引入。

• obstacle_layer 插件

  • raytrace_min_range 控制光线追踪从代价地图中清除障碍物的最小范围

  • raytrace_max_range 控制光线追踪从代价地图中清除障碍物的最大范围

• voxel_layer 插件

  • raytrace_min_range 控制光线追踪从代价地图中清除障碍物的最小范围

  • raytrace_max_range 控制光线追踪从代价地图中清除障碍物的最大范围

障碍物标记参数（Obstacle Marking Parameters）

障碍物标记功能新增了一个最小范围参数，从该范围开始在代价地图上标记障碍物，以防止因噪声和错误测量而在代价地图中新增障碍物。此修改与光线追踪参数的更改相关。更名的参数、新增的参数及其所属插件如下所示。

• obstacle_layer 插件

  • obstacle_min_range 控制障碍物在代价地图上被标记的最小范围

  • obstacle_max_range 控制障碍物在代价地图上被标记的最大范围

• voxel_layer 插件

  • obstacle_min_range 控制障碍物在代价地图上被标记的最小范围

  • obstacle_max_range 控制障碍物在代价地图上被标记的最大范围

恢复动作变更（Recovery Action Changes）

恢复动作 Spin 和 BackUp 已修改：如果恢复动作因潜在碰撞而中止，将正确返回 FAILURE。此前这些动作总是错误地返回 SUCCESS。此更改会影响下游的动作客户端，例如默认行为树。相关更改由该拉取请求 1855 引入。

默认行为树变更（Default Behavior Tree Changes）

默认行为树（BT）navigate_w_replanning_and_recovery.xml 已更新，支持在恢复行为之间进行重新规划。此更改由该 PR 1855 引入。此外，由于与更新后的默认 BT 功能相似，备选 BT navigate_w_replanning_and_round_robin_recovery.xml 已被移除。

NavFn 规划器参数

NavFn 规划器的 3 个参数（tolerance、use_astar 和 allow_unknown）现在支持在运行时重新配置。此更改由该拉取请求 2181 引入。

新增 ClearCostmapExceptRegion 和 ClearCostmapAroundRobot BT 节点

ClearEntireCostmap 动作节点已经存在，但调用 Costmap 2D 对应服务 (local_or_global)_costmap/clear_except_(local_or_global)_costmap 和 clear_around_(local_or_global)_costmap 的 ClearCostmapExceptRegion 和 ClearCostmapAroundRobot BT 节点此前缺失，现已以类似方式实现。它们都暴露了一个 reset_distance 输入端口。更多信息请参阅 bt_clear_costmap_except_region_action 和 bt_clear_entire_costmap_around_robot_action。此更改由该拉取请求 2204 引入。

新的行为树节点（New Behavior Tree Nodes）

新增了多个行为树节点，可以使用 BehaviorTree.CPP v3 在运行时动态加载。 完整列表请参阅 nav2_behavior_tree 包，当前可用的行为树插件及其描述请参阅插件（Plugins）。 这些插件在 nav2_bt_navigator 中被设为默认插件，但可以通过 bt_plugins 参数覆盖，以加入你自己的自定义插件。

原始 GitHub 议题：

• SingleTrigger
• PlannerSelector
• ControllerSelector
• GoalCheckerSelector
• NavigateThroughPoses
• RemovePassedGoals
• ComputePathThroughPoses

此外，行为树节点已被修改为包含各自独立的本地执行器（executor），用于处理动作、话题、服务等，以确保各行为树节点彼此独立（例如，在一个 BT 节点中 spin 不会触发另一个节点中的回调）。

sensor_msgs/PointCloud 到 sensor_msgs/PointCloud2 的变更

由于 sensor_msgs/PointCloud 已被弃用，发布 sensor_msgs/PointCloud 的话题已统一转换为 sensor_msgs/PointCloud2。受影响的话题及其详细信息如下所列。

• nav2_costmap_2d 包 voxel_layer 插件中的 clearing_endpoints 话题
• nav2_costmap_2d 包 costmap_2d_cloud 节点中的 voxel_marked_cloud 和 voxel_unknown_cloud 话题
• dwb_core 包 publisher.cpp 的 cost_cloud 话题

这些更改由拉取请求 2263 引入。

Controller Server 新参数 failure_tolerance

Controller Server 新增了参数 failure_tolerance，用于在控制器插件异常时容忍而不立即报错。该参数类似于 ROS 1 Navigation 中的 controller_patience。详细描述请参阅 configuring_controller_server。 此更改由该拉取请求 2264 引入。

移除的 BT XML Launch 配置

用于通过 CLI 设置行为树 XML 文件的 launch Python 配置已被移除，改为使用 YAML 文件来设置该值。如果在较大的部署中 yaml 文件的 path 不一致，可以在父级 launch 文件中使用 RewrittenYaml 工具，借助 get_shared_package_path() 目录查找器重新映射默认的 XML 路径（或者沿用之前 python3 的方式）。

地图订阅 QoS 的 launch 配置也已移除，请改用参数文件进行设置。 此更改由该拉取请求 2295 引入。

Nav2 RViz 面板动作反馈信息

Nav2 RViz 面板现在会显示由 nav2_msgs/NavigateToPose 和 nav2_msgs/NavigateThroughPoses 动作发布的反馈信息。 用户可以直接在 RViz 面板中查看预计到达时间、距目标的剩余距离、导航开始以来经过的时间，以及单次导航动作期间执行的恢复次数等信息。 此功能由该拉取请求 2338 引入。