ROS 2 Gazebo 机器人仿真 Launch 文件源码与逻辑分析

代码分析

第一段：定义路径常量（机器人模型&仿真世界）

1. robot_name_in_model = "fishbot"：定义机器人在 Gazebo 中的实体名称，后续在 Gazebo 中生成机器人时，会用这个名称标识该机器人实体。
2. get_package_share_directory('fishbot_description')：ROS 2 的工具函数，作用是获取 fishbot_description 包的 share 目录的绝对路径（share 目录是 ROS 2 包中存放配置文件、模型、世界文件等资源的标准目录），避免硬编码路径（不同环境下包的安装路径不同，硬编码会导致路径错误）。
3. default_model_path：拼接得到机器人模型文件（fishbot.urdf.xacro）的绝对路径，注意文件格式是 .urdf.xacro（不是纯 .urdf），说明这是一个支持宏定义、参数化的 URDF 文件，需要先通过 xacro 工具解析为纯 URDF 格式才能被 ROS 2 识别。
4. default_world_path：拼接得到 Gazebo 仿真世界文件（custom_room.world）的绝对路径，这个文件定义了 Gazebo 中的仿真环境（如墙壁、地面、灯光等）。

第二段：声明 Launch 参数（模型路径）

action_declare_arg_mode_path = launch.actions.DeclareLaunchArgument(
    name='model',
    default_value=str(default_model_path),
    description='URDF 的绝对路径'
)

1. 这是 ROS 2 Launch 的参数声明动作（DeclareLaunchArgument），作用是为当前 Launch 文件定义一个可外部传入的参数 model。
2. 关键属性说明：
   • name='model'：参数名，外部启动该 Launch 文件时，可以通过 ros2 launch 包名 该 launch 文件名 model:=自定义模型路径 来覆盖默认值。
   • default_value=str(default_model_path)：参数默认值，即第一段中拼接的 fishbot.urdf.xacro 路径，不传入自定义参数时，使用该默认模型。
   • description：参数描述，用于说明该参数的作用，提高脚本可读性。
3. 核心目的：提高 Launch 文件的灵活性，无需修改 Launch 文件代码，即可切换不同的机器人模型。

第三段：生成机器人描述（解析 Xacro 为 URDF）

robot_description = launch_ros.parameter_descriptions.ParameterValue(
    launch.substitutions.Command(['xacro ', launch.substitutions.LaunchConfiguration('model')]),
    value_type=str
)

这是整个 Launch 文件的核心步骤之一，作用是解析 Xacro 文件，生成可供 ROS 2 使用的机器人描述（robot_description），拆解如下：

1. launch.substitutions.LaunchConfiguration('model')：获取第二段声明的 model 参数的值（默认值或外部传入值），即 Xacro 文件的路径。
2. launch.substitutions.Command([...])：ROS 2 的替换器，作用是在 Launch 文件执行时，运行一个系统命令，并获取命令的输出结果。这里的命令是 xacro [Xacro 文件路径]，对应终端中的 xacro fishbot.urdf.xacro 命令，用于将 Xacro 文件解析为纯 URDF 格式的字符串。
3. launch_ros.parameter_descriptions.ParameterValue(...)：将命令执行的输出（URDF 字符串）封装为 ROS 2 的参数值，指定 value_type=str（确保输出是字符串格式，符合 robot_description 的要求）。
4. 最终结果：robot_description 变量中存储了完整的、解析后的 URDF 机器人描述字符串，后续会传递给 robot_state_publisher 节点。

第四段：启动机器人状态发布节点（robot_state_publisher）

robot_state_publisher_node = launch_ros.actions.Node(
    package='robot_state_publisher',
    executable='robot_state_publisher',
    parameters=[{'robot_description': robot_description}]
)

1. launch_ros.actions.Node：ROS 2 Launch 中用于启动一个 ROS 2 节点的动作。
2. 节点配置说明：
   • package='robot_state_publisher'：节点所属的 ROS 2 包（核心功能包，无需自定义）。
   • executable='robot_state_publisher'：要运行的节点可执行文件名称。
   • parameters=[{'robot_description': robot_description}]：向节点传递参数，这里将第三段生成的 robot_description（URDF 字符串）作为参数传递给该节点。
3. robot_state_publisher 节点的核心作用：
   • 解析 robot_description 中的 URDF 模型，获取机器人的关节树结构。
   • 发布机器人的TF/TF2 变换（坐标变换）（如从基坐标系 base_link 到各个关节、传感器坐标系的变换），这是 ROS 2 中导航、感知、控制的基础（其他节点需要通过 TF 变换获取各部件的空间位置关系）。

第五段：包含并启动 Gazebo 仿真环境

launch_gazebo = launch.actions.IncludeLaunchDescription(
    PythonLaunchDescriptionSource([get_package_share_directory('gazebo_ros'), '/launch', '/gazebo.launch.py']),
    launch_arguments=[('world', default_world_path), ('verbose', 'true')]
)

1. launch.actions.IncludeLaunchDescription：ROS 2 Launch 的文件包含动作，作用是在当前 Launch 文件中嵌套执行另一个 Launch 文件，避免重复编写启动 Gazebo 的代码（gazebo_ros 包已经提供了成熟的 gazebo.launch.py）。
2. PythonLaunchDescriptionSource([...])：指定要包含的 Launch 文件的路径，这里通过 get_package_share_directory('gazebo_ros') 获取 gazebo_ros 包的路径，拼接得到 gazebo.launch.py（Gazebo 的核心启动文件）。
3. launch_arguments=[('world', default_world_path), ('verbose', 'true')]：向被包含的 gazebo.launch.py 传递参数：
   • world：指定 Gazebo 加载的仿真世界文件，即第一段中的 custom_room.world。
   • verbose='true'：开启 Gazebo 的详细输出模式，便于调试（在终端中打印更多 Gazebo 的运行日志）。
4. 执行结果：启动 Gazebo 仿真器，并加载 custom_room.world 定义的自定义环境，等待生成机器人实体。

第六段：在 Gazebo 中生成机器人实体（spawn_entity.py）

spawn_entity_node = launch_ros.actions.Node(
    package='gazebo_ros',
    executable='spawn_entity.py',
    arguments=['-topic', '/robot_description', '-entity', robot_name_in_model,]
)

1. 启动 gazebo_ros 包中的 spawn_entity.py 脚本节点，作用是将机器人模型发布到 Gazebo 仿真环境中，生成可交互的机器人实体。
2. arguments：向该节点传递命令行参数（对应终端运行 ros2 run gazebo_ros spawn_entity.py -h 看到的参数）：
   • -topic /robot_description：指定从 /robot_description 话题中获取机器人的 URDF 描述（robot_state_publisher 节点会发布该话题）。
   • -entity robot_name_in_model：指定机器人在 Gazebo 中的实体名称（即第一段定义的 fishbot）。
3. 执行结果：Gazebo 中会出现 fishbot 机器人模型，机器人被成功加载到仿真环境中，但此时还无法进行控制（需要激活控制器）。

第七段：定义控制器加载进程（3 个控制器）

load_joint_state_controller = launch.actions.ExecuteProcess(
    cmd=['ros2', 'control', 'load_controller', '--set-state', 'active', 'fishbot_joint_state_broadcaster'],
    output='screen'
)
load_fishbot_effort_controller = launch.actions.ExecuteProcess(
    cmd=['ros2', 'control', 'load_controller', '--set-state', 'active', 'fishbot_effort_controller'],
    output='screen'
)
load_fishbot_diff_drive_controller = launch.actions.ExecuteProcess(
    cmd=['ros2', 'control', 'load_controller', '--set-state', 'active', 'fishbot_diff_drive_controller'],
    output='screen'
)

1. launch.actions.ExecuteProcess：ROS 2 Launch 中用于**运行一个系统终端命令（非 ROS 2 节点）**的动作，这里用于执行 ros2 control 相关命令，加载并激活机器人控制器。
2. 核心命令：ros2 control load_controller --set-state active [控制器名称]，这是 ROS 2 控制框架（ros2_control）的终端命令，作用是从机器人的控制器配置中加载指定名称的控制器，并直接将其设置为激活状态（active）（控制器默认加载后是未激活状态，需要手动或自动激活才能工作）。
3. 三个控制器的作用说明：
   • fishbot_joint_state_broadcaster：关节状态广播器（核心必备），用于采集机器人所有关节的状态（位置、速度、力矩），并发布到 /joint_states 话题中，供 robot_state_publisher、RViz 等节点使用。
   • fishbot_effort_controller：力矩控制器，用于向机器人关节发送力矩指令，控制关节运动（该 Launch 文件中未实际执行激活，仅定义了进程）。
   • fishbot_diff_drive_controller：差速驱动控制器（核心运动控制器），用于实现机器人的差速驱动（左右轮转速控制，完成前进、转弯等动作），是移动机器人运动控制的核心。
4. output='screen'：将命令执行的输出日志打印到终端，便于调试（查看控制器是否加载成功、有无报错）。

第八段：返回 Launch 描述（组装所有动作，定义执行逻辑）

return launch.LaunchDescription([
    action_declare_arg_mode_path,
    robot_state_publisher_node,
    launch_gazebo,
    spawn_entity_node,
    launch.actions.RegisterEventHandler(
        event_handler=launch.event_handlers.OnProcessExit(
            target_action=spawn_entity_node,
            on_exit=[load_joint_state_controller],
        )
    ),
    launch.actions.RegisterEventHandler(
        event_handler=launch.event_handlers.OnProcessExit(
            target_action=load_joint_state_controller,
            on_exit=[load_fishbot_diff_drive_controller],
        )
    ),
])

这是 Launch 文件的最终返回结果，launch.LaunchDescription() 接收一个动作列表，定义了所有要执行的动作和执行逻辑，核心分为两部分：顺序执行的基础动作和事件驱动的有序控制器激活。

1. 基础动作（按列表顺序执行，无依赖）：
   • action_declare_arg_mode_path：先声明 model 参数。
   • robot_state_publisher_node：启动机器人状态发布节点。
   • launch_gazebo：启动 Gazebo 仿真环境。
   • spawn_entity_node：在 Gazebo 中生成机器人实体。
2. 事件驱动动作（RegisterEventHandler + OnProcessExit）：这是该 Launch 文件的亮点逻辑，解决了「控制器必须在机器人加载完成后才能激活」的依赖问题（如果直接顺序执行，可能出现机器人还没加载好，控制器就开始加载，导致加载失败）。
   • OnProcessExit：事件处理器，作用是监听指定目标动作（target_action）的进程退出事件（即目标动作执行完成、进程正常退出）。
   • 第一个事件监听：
     • target_action=spawn_entity_node：监听 spawn_entity_node（机器人生成）的进程退出。
     • on_exit=[load_joint_state_controller]：当机器人生成完成后，自动执行 load_joint_state_controller（激活关节状态广播器）。
   • 第二个事件监听：
     • target_action=load_joint_state_controller：监听关节状态广播器的加载完成事件。
     • on_exit=[load_fishbot_diff_drive_controller]：当关节状态广播器激活完成后，自动执行 load_fishbot_diff_drive_controller（激活差速驱动控制器）。
   • 最终控制器激活顺序（严格依赖，不会出错）：机器人生成完成 → 激活关节状态广播器 → 激活差速驱动控制器。
3. 注意：load_fishbot_effort_controller（力矩控制器）仅定义了进程，但未在 LaunchDescription 中添加执行逻辑，因此该控制器不会被自动激活（如需激活，可在第二个事件的 on_exit 中添加该进程，或新增一个事件监听）。

补充说明

1. 依赖条件：运行该 Launch 文件前，必须确保 fishbot_description 包已编译（colcon build --packages-select fishbot_description），且已执行 source install/setup.bash。
2. 常见报错：
   • 路径错误：get_package_share_directory 找不到 fishbot_description，大概率是包名拼写错误或未编译。
   • Xacro 解析错误：终端提示 xacro 命令错误，大概率是 fishbot.urdf.xacro 文件语法错误，或缺少依赖的宏定义。
   • 控制器加载失败：大概率是 fishbot 的 URDF 文件中未配置对应的 ros2_control 控制器（缺少 <ros2_control> 标签），或控制器名称拼写错误。
3. 扩展方向：如需添加 RViz 可视化，可在 LaunchDescription 中新增 rviz2 节点，指定配置文件路径。

总结

1. 该 Launch 文件的核心是一站式启动 fishbot 机器人的 Gazebo 仿真环境，并通过事件驱动实现控制器的有序自动激活，避免了手动执行多个终端命令的繁琐。
2. 关键技术点包括：Xacro 文件解析、Launch 参数声明、嵌套 Launch 文件、事件驱动（OnProcessExit）、ros2_control 控制器加载。
3. 核心执行流程：声明参数→启动状态发布节点→启动 Gazebo→生成机器人→按依赖激活控制器（关节状态广播器→差速驱动控制器）。