机器人 / 系统课时

整理导航 YAML 和启动参数

整理导航 YAML 和启动参数

同一套 Nav2 参数如果分别写在命令行、YAML 和启动脚本里,切换地图或仿真环境时很容易改漏。本篇以 ROS 2 Jazzy 为例,把节点参数、地图文件和启动开关整理到一个目录,用统一的 Launch 入口启动,并验证实际生效值。

学习目标

  • 区分地图 YAML、Nav2 节点参数 YAML 和 Launch 入参的职责。
  • 建立可复用的配置目录,集中管理地图、仿真时钟和自动激活开关。
  • 通过参数查询与生命周期状态确认启动配置确实生效。

明确各类参数的归属

Nav2 的 bringup_launch.py 接收以下真实启动参数。建议让地图位置和环境开关由 Launch 管理,把规划器、控制器、定位器及代价地图的细节留在 nav2_params.yaml 中。

参数 管理内容 本例设置
map 传给 Map Server 的地图元数据文件 maps/tb3_sandbox.yaml
params_file 各 Nav2 节点的 ROS 参数 config/nav2_params.yaml
use_sim_time 让节点使用仿真 /clock true
autostart 由 Lifecycle Manager 自动配置并激活节点 true
slam 是否启用 SLAM;关闭后走静态地图定位 False

不要在两个入口分别维护不同的地图路径:Jazzy 的官方启动脚本在指定 map 时,会将其作为 Map Server 的 yaml_filename。同样,不必在每个节点 YAML 中重复写一份 use_sim_time;本例通过官方 Launch 统一传入。相关入参可以在 Nav2 Jazzy 启动源码 中核对。

Nav2 启动参数与 YAML 的作用边界

复制并整理配置基线

前置条件是 Ubuntu 上已经安装 ROS 2 Jazzy 与 nav2_bringup。以下使用其自带的 TurtleBot3 沙盒地图演示;实际导航时,仿真世界必须与加载的地图匹配,并已有底盘、传感器和 TF 数据。

在终端执行:

bash
source /opt/ros/jazzy/setup.bash
set -e
ROOT="$HOME/nav2_demo"
SHARE="$(ros2 pkg prefix nav2_bringup)/share/nav2_bringup"
mkdir -p "$ROOT"/{config,launch,maps}
# 保留完整节点配置,并连同地图图像一起复制
cp "$SHARE/params/nav2_params.yaml" "$ROOT/config/"
cp "$SHARE/maps/tb3_sandbox.yaml" "$SHARE/maps/tb3_sandbox.pgm" "$ROOT/maps/"
printf 'READY: %s\n' "$ROOT"

预期输出:

text
READY: <PATH>

<PATH> 为实际的 $HOME/nav2_demo 绝对路径。地图 YAML 的 image: tb3_sandbox.pgm 相对于地图 YAML 所在目录解析,因此不能只复制 .yaml 而漏掉 .pgm。

在 config/nav2_params.yaml 中只调整所需节点的既有参数。以下为片段示例,依赖刚复制的完整配置文件,不能用它覆盖整个文件;帧名要和仿真发布的 TF 一致:

yaml
amcl:
  ros__parameters:
    base_frame_id: base_footprint
    odom_frame_id: odom
    global_frame_id: map

bt_navigator:
  ros__parameters:
    global_frame: map
    robot_base_frame: base_link

这两组配置分别属于 AMCL 和 BT Navigator;应在原文件对应节点内修改,而不是复制出重复的 amcl、bt_navigator 顶层键。规划器插件、局部与全局 Costmap 等其余配置继续保留在同一文件中。

编写统一 Launch 入口

新建 ~/nav2_demo/launch/nav2_stack.launch.py,使用文件位置推导项目根目录,不依赖运行命令时的当前工作目录。它只负责传递启动参数,不重复定义 Nav2 节点。

python
from pathlib import Path

from ament_index_python.packages import get_package_share_directory
from launch import LaunchDescription
from launch.actions import DeclareLaunchArgument, IncludeLaunchDescription
from launch.launch_description_sources import PythonLaunchDescriptionSource
from launch.substitutions import LaunchConfiguration

def generate_launch_description():
    # 以本文件为基准定位地图和参数,而非写死用户名
    root = Path(__file__).resolve().parent.parent
    upstream = Path(get_package_share_directory("nav2_bringup"))

    return LaunchDescription([
        DeclareLaunchArgument(
            "map", default_value=str(root / "maps" / "tb3_sandbox.yaml")
        ),
        DeclareLaunchArgument(
            "params_file", default_value=str(root / "config" / "nav2_params.yaml")
        ),
        DeclareLaunchArgument("use_sim_time", default_value="true"),
        DeclareLaunchArgument("autostart", default_value="true"),
        # 复用 Jazzy 官方入口,固定采用静态地图和 AMCL
        IncludeLaunchDescription(
            PythonLaunchDescriptionSource(
                str(upstream / "launch" / "bringup_launch.py")
            ),
            launch_arguments={
                "map": LaunchConfiguration("map"),
                "params_file": LaunchConfiguration("params_file"),
                "use_sim_time": LaunchConfiguration("use_sim_time"),
                "autostart": LaunchConfiguration("autostart"),
                "slam": "False",
                "use_localization": "True",
                "use_composition": "False",
            }.items(),
        ),
    ])

这里把 use_composition 设为 False 以便在调试阶段分别观察节点进程;功能正常后可按资源需求改为组合启动。更换地图时传 map:=... 即可,修改控制器参数则编辑 params_file 指向的完整 YAML。

启动并核对生效值

先启动与地图匹配的 Gazebo 仿真,并确认 /clock、激光、里程计及必要 TF 已由仿真或桥接节点提供。再执行:

bash
source /opt/ros/jazzy/setup.bash
cd "$HOME/nav2_demo/launch"
ros2 launch nav2_stack.launch.py use_sim_time:=true autostart:=true

预期结果:启动终端持续运行,Lifecycle Manager 尝试按顺序配置、激活定位和导航节点。日志时间、节点启动顺序与具体环境有关;这条命令不会启动 Gazebo 或生成地图。

在另一个已加载 Jazzy 环境的终端验证:

bash
source /opt/ros/jazzy/setup.bash
ros2 param get /amcl use_sim_time
ros2 lifecycle get /planner_server
ros2 param get /map_server yaml_filename

在上述依赖齐全且启动成功时,预期输出形如:

text
Boolean value is: True
active [3]
String value is: <PATH>/tb3_sandbox.yaml

最后一行的 <PATH> 是本机实际地图目录。active [3] 代表 Planner Server 已激活;它本身不证明机器人定位已经收敛,仍需在 RViz 检查地图、激光与位姿是否对齐。

排查覆盖与启动失败

按以下顺序核对配置,避免反复改动互不相关的参数:

  1. 地图无法加载:检查 map 是否指向真实的地图 YAML,以及其中 image 所引用的 .pgm 是否存在。不要只改 nav2_params.yaml 里的 yaml_filename,却在 Launch 中仍传入旧地图。
  2. 仿真时间不推进:查询 /amcl 的 use_sim_time 是否为 True,再确认 /clock 有消息;一个节点误用系统时间就可能造成 TF 时间戳不匹配。
  3. 节点停在 inactive:检查 autostart 是否为 true、Lifecycle Manager 是否报配置错误,再检查 map → odom → base_footprint → base_link 的实际 TF 链;不能用反复重启替代根因检查。

修改 YAML 后先做语法校验:

bash
python3 -c 'import sys, yaml; yaml.safe_load(open(sys.argv[1], encoding="utf-8")); print("YAML OK")' "$HOME/nav2_demo/config/nav2_params.yaml"

预期输出:

text
YAML OK

这个检查只能证明 YAML 能被解析,不能证明插件名和参数类型正确。最终仍以启动后的参数值、生命周期状态以及机器人在仿真中的实际导航行为为准。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

整理导航 YAML 和启动参数

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通