Nav2 使用方式与典型场景

四、使用方式与典型场景

示例一：参数文件的关键片段

下面是从默认参数文件裁剪出的核心片段，字段名以所装发行版的官方参数文件为准：

controller_server:
  ros__parameters:
    controller_frequency: 20.0
    min_x_velocity_threshold: 0.001
    progress_checker_plugin: "progress_checker"
    goal_checker_plugins: ["general_goal_checker"]
    controller_plugins: ["FollowPath"]

    progress_checker:
      plugin: "nav2_controller::SimpleProgressChecker"
      required_movement_radius: 0.5
      movement_time_allowance: 10.0

    general_goal_checker:
      stateful: True
      plugin: "nav2_controller::SimpleGoalChecker"
      xy_goal_tolerance: 0.25
      yaw_goal_tolerance: 0.25

    FollowPath:
      plugin: "dwb_core::DWBLocalPlanner"
      max_vel_x: 0.6
      max_vel_theta: 1.0
      min_speed_xy: 0.0
      acc_lim_x: 1.0
      acc_lim_theta: 2.0
      vx_samples: 20
      vtheta_samples: 40
      prune_plan: true

local_costmap:
  local_costmap:
    ros__parameters:
      update_frequency: 5.0
      publish_frequency: 2.0
      global_frame: odom
      robot_base_frame: base_link
      rolling_window: true
      width: 3
      height: 3
      resolution: 0.05
      robot_radius: 0.22
      plugins: ["obstacle_layer", "inflation_layer"]
      inflation_layer:
        plugin: "nav2_costmap_2d::InflationLayer"
        cost_scaling_factor: 3.0
        inflation_radius: 0.55

planner_server:
  ros__parameters:
    expected_planner_frequency: 20.0
    planner_plugins: ["GridBased"]
    GridBased:
      plugin: "nav2_navfn_planner::NavfnPlanner"
      tolerance: 0.5
      use_astar: false

注意局部代价地图在 YAML 里是双层同名键，这是最容易写错的地方，结构错了参数不会报错，只会静默用默认值。

示例二：启动文件

import os

from ament_index_python.packages import get_package_share_directory
from launch import LaunchDescription
from launch.actions import IncludeLaunchDescription
from launch.launch_description_sources import PythonLaunchDescriptionSource


def generate_launch_description():
    nav2_bringup = get_package_share_directory("nav2_bringup")

    bringup = IncludeLaunchDescription(
        PythonLaunchDescriptionSource(
            os.path.join(nav2_bringup, "launch", "bringup_launch.py")
        ),
        launch_arguments={
            "map": "/home/robot/maps/warehouse.yaml",
            "use_sim_time": "false",
            "params_file": "/home/robot/config/nav2_params.yaml",
            "autostart": "true",
        }.items(),
    )

    return LaunchDescription([bringup])

autostart 会通过生命周期管理器自动完成配置与激活，省掉手动切换状态。调试阶段建议设成 false，方便逐个节点排查。

示例三：自定义行为树

<root main_tree_to_execute="MainTree">
  <BehaviorTree ID="MainTree">
    <RecoveryNode number_of_retries="6" name="NavigateRecovery">
      <PipelineSequence name="NavigateWithReplanning">
        <RateController hz="1.0">
          <ComputePathToPose goal="{goal}" path="{path}"
                             planner_id="GridBased"/>
        </RateController>
        <FollowPath path="{path}" controller_id="FollowPath"/>
      </PipelineSequence>
      <ReactiveFallback name="RecoveryFallback">
        <GoalUpdated/>
        <SequenceStar name="RecoveryActions">
          <ClearEntireCostmap name="ClearLocalCostmap"
            service_name="local_costmap/clear_entirely_local_costmap"/>
          <Spin spin_dist="1.57"/>
          <Wait wait_duration="5"/>
        </SequenceStar>
      </ReactiveFallback>
    </RecoveryNode>
  </BehaviorTree>
</root>

把 RateController 的频率从 1 Hz 提到更高，重规划更频繁、路径更贴合动态环境，代价是 CPU 占用上升。真机调试时这是最先要试的一个旋钮。

适合与不适合

• 适合：室内二维地图导航、差速与阿克曼底盘、激光雷达或深度相机做避障、需要成熟恢复逻辑的长期运行设备。
• 不适合：三维复杂地形（需要三维规划）、没有先验地图的完全未知环境（要配 SLAM）、需要厘米级对接精度的场景（末端通常还要加视觉伺服）、毫秒级高动态避障（代价地图的更新周期跟不上）。