机器人 / 系统课时
整理导航 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 启动源码 中核对。

复制并整理配置基线
前置条件是 Ubuntu 上已经安装 ROS 2 Jazzy 与 nav2_bringup。以下使用其自带的 TurtleBot3 沙盒地图演示;实际导航时,仿真世界必须与加载的地图匹配,并已有底盘、传感器和 TF 数据。
在终端执行:
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"预期输出:
READY: <PATH><PATH> 为实际的 $HOME/nav2_demo 绝对路径。地图 YAML 的 image: tb3_sandbox.pgm 相对于地图 YAML 所在目录解析,因此不能只复制 .yaml 而漏掉 .pgm。
在 config/nav2_params.yaml 中只调整所需节点的既有参数。以下为片段示例,依赖刚复制的完整配置文件,不能用它覆盖整个文件;帧名要和仿真发布的 TF 一致:
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 节点。
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 已由仿真或桥接节点提供。再执行:
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 环境的终端验证:
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在上述依赖齐全且启动成功时,预期输出形如:
Boolean value is: True
active [3]
String value is: <PATH>/tb3_sandbox.yaml最后一行的 <PATH> 是本机实际地图目录。active [3] 代表 Planner Server 已激活;它本身不证明机器人定位已经收敛,仍需在 RViz 检查地图、激光与位姿是否对齐。
排查覆盖与启动失败
按以下顺序核对配置,避免反复改动互不相关的参数:
- 地图无法加载:检查
map是否指向真实的地图 YAML,以及其中image所引用的.pgm是否存在。不要只改nav2_params.yaml里的yaml_filename,却在 Launch 中仍传入旧地图。 - 仿真时间不推进:查询
/amcl的use_sim_time是否为True,再确认/clock有消息;一个节点误用系统时间就可能造成 TF 时间戳不匹配。 - 节点停在 inactive:检查
autostart是否为true、Lifecycle Manager 是否报配置错误,再检查map → odom → base_footprint → base_link的实际 TF 链;不能用反复重启替代根因检查。
修改 YAML 后先做语法校验:
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"预期输出:
YAML OK这个检查只能证明 YAML 能被解析,不能证明插件名和参数类型正确。最终仍以启动后的参数值、生命周期状态以及机器人在仿真中的实际导航行为为准。