Launch 构建器

相关源码文件

以下文件被用作生成此 wiki 页面的上下文：

本页面详述 robot.launch.py 如何编排机器人系统的各个子图，包括控制、描述、感知、导航、遥操作、录制、追踪与语音。它解释每个 launch 构建器模块在基于单一事实源（SSOT）YAML 配置组装完整 ROS 2 launch 描述中的角色。

Launch 构建器模块概览

robot_config.launch_builders 包包含基于机器人 YAML 配置生成 ROS 2 launch 组件的模块 src/robot_config/robot_config/launch_builders/init.py:1-9。每个模块聚焦一个特定子系统：

控制子图

control.py 模块是搭建机器人控制系统的核心。它生成 ros2_control 节点与控制器 spawner，并执行关节配置校验 src/robot_config/robot_config/launch_builders/control.py:1-7。

ros2_control 节点生成

ros2_control 节点负责管理机器人的硬件接口与控制器。generate_ros2_control_nodes 函数（未完整展示，但由 __init__.py 中的 generate_ros2_control_nodes 暗示 src/robot_config/robot_config/launch_builders/init.py:64）通常会为 ros2_control 创建一个 Node action。

控制器 Spawner 创建

控制器使用 controller_manager 的 spawner 可执行文件生成。generate_controller_spawners 函数（由 __init__.py 中的 generate_controller_spawners 暗示 src/robot_config/robot_config/launch_builders/init.py:65）会创建 Node action 来加载并启动已配置的控制器。

关节配置校验

启动前，validate_joint_config 函数 src/robot_config/robot_config/launch_builders/control.py:28 确保机器人 YAML 中定义的关节配置有效。这防止了因错误关节定义导致的运行时错误。

运行时资源校验

validate_runtime_resources 函数 src/robot_config/robot_config/launch_builders/control.py:64-139 检查真实硬件资源（如串口）的冲突，防止多个组件尝试使用同一个独占资源。这对物理机器人部署至关重要。

来源：src/robot_config/robot_config/launch_builders/control.py:1-162, src/robot_config/robot_config/launch_builders/init.py:64-68

描述子图

description.py 模块负责从 YAML 配置生成机器人的统一机器人描述格式（URDF）src/robot_config/robot_config/launch_builders/description.py:1-3。这包括处理 xacro 文件与动态注入相机描述。

基于 Xacro 的 URDF 生成

generate_robot_description 函数 src/robot_config/robot_config/launch_builders/init.py:62 接收机器人配置并生成完整 URDF。该过程包括：

  1. Xacro 处理：展开基础 URDF 文件中定义的 xacro 宏。

  2. 动态相机注入：_build_cameras_urdf_from_yaml 函数 src/robot_config/robot_config/launch_builders/description.py:61-178 基于机器人 YAML 的 peripherals 节动态添加相机 link、joint 与 Gazebo 传感器定义。这确保相机在仿真与可视化中都正确呈现在机器人模型中。

模型生成偏移

_get_model_spawn_offset 函数 src/robot_config/robot_config/launch_builders/description.py:25-47 从 YAML 的 simulation.robot_spawn 节获取机器人的生成位置。该偏移对于在 URDF 中正确定位 parent="world" 相机至关重要。

来源：src/robot_config/robot_config/launch_builders/description.py:1-178, src/robot_config/robot_config/launch_builders/init.py:62

感知子图

perception.py 模块负责启动机器人传感器（主要是相机与 LiDAR）相关的节点 src/robot_config/robot_config/launch_builders/perception.py:1-8。

相机驱动节点

generate_camera_nodes 函数 src/robot_config/robot_config/launch_builders/perception.py:25-147 基于机器人 YAML 中的 peripherals 配置为各类相机驱动创建 Node action。

LiDAR 驱动节点

generate_lidar_nodes 函数（由 __init__.py 中的 generate_lidar_nodes 暗示 src/robot_config/robot_config/launch_builders/init.py:71）会类似地为 LiDAR 传感器创建 Node action。

静态 TF 发布器

generate_tf_nodes 函数（由 __init__.py 中的 generate_tf_nodes 暗示 src/robot_config/robot_config/launch_builders/init.py:72）负责发布外围设备坐标系的静态变换，确保传感器与机器人之间正确的空间关系。

虚拟相机中继

generate_virtual_camera_relays 函数（由 __init__.py 中的 generate_virtual_camera_relays 暗示 src/robot_config/robot_config/launch_builders/init.py:73）处理虚拟相机，可能用于特定仿真或测试场景。

来源：src/robot_config/robot_config/launch_builders/perception.py:1-178, src/robot_config/robot_config/launch_builders/init.py:70-74

仿真子图

simulation.py 模块及其后端适配器管理仿真环境。它支持多种仿真平台，如 Gazebo 与 MuJoCo。

仿真后端适配器

robot_config.launch_builders.sim_backend 包为不同仿真平台提供适配器 src/robot_config/robot_config/launch_builders/sim_backend/init.py。

仿真数据流

仿真后端适配器确保来自仿真器的传感器数据正确发布到 ROS topic，且控制命令被发送到仿真机器人。

Gazebo 数据流

Title: Gazebo Simulation Data Flow

        graph TD
    subgraph "Gazebo Simulation"
        GZ_WORLD["Gazebo World"] --> GZ_SENSOR_TOPICS["Gazebo Sensor Topics (e.g., /camera/top_camera/image)"]
    end

    subgraph "ROS 2 System"
        GZ_SENSOR_TOPICS --> BRIDGE_NODE["ros_gz_bridge bridge_node (YAML Config)"]
        BRIDGE_NODE --> ROS_CONTRACT_TOPICS["ROS Contract Topics (e.g., /camera/top/image_raw)"]
        ROS_CONTRACT_TOPICS --> PERCEPTION_NODES["Perception Nodes"]
        ROS_CONTRACT_TOPICS --> INFERENCE_SERVICE["Inference Service"]
        ACTION_DISPATCH["Action Dispatch"] --> ROS2_CONTROL_NODE["ros2_control_node (Gazebo Hardware Interface)"]
        ROS2_CONTROL_NODE --> GZ_WORLD
    end

    style GZ_WORLD fill:#f9f,stroke:#333,stroke-width:2px
    style GZ_SENSOR_TOPICS fill:#bbf,stroke:#333,stroke-width:2px
    style BRIDGE_NODE fill:#ccf,stroke:#333,stroke-width:2px
    style ROS_CONTRACT_TOPICS fill:#cfc,stroke:#333,stroke-width:2px
    style PERCEPTION_NODES fill:#ffc,stroke:#333,stroke-width:2px
    style INFERENCE_SERVICE fill:#fcf,stroke:#333,stroke-width:2px
    style ACTION_DISPATCH fill:#fcc,stroke:#333,stroke-width:2px
    style ROS2_CONTROL_NODE fill:#cff,stroke:#333,stroke-width:2px

来源：src/robot_config/robot_config/launch_builders/sim_backend/gazebo_adapter.py:1-152, src/robot_config/robot_config/launch_builders/sim_peripheral_bridge.py:1-183

MuJoCo 数据流

Title: MuJoCo Simulation Data Flow

        graph TD
    subgraph "MuJoCo Simulation"
        MUJOCO_SIM["MuJoCo Simulator"] --> MUJOCO_ROS2_CONTROL_NODE["mujoco_ros2_control ros2_control_node"]
    end

    subgraph "ROS 2 System"
        MUJOCO_ROS2_CONTROL_NODE --> ROS_CONTRACT_TOPICS["ROS Contract Topics (e.g., /camera/top/image_raw)"]
        ROS_CONTRACT_TOPICS --> PERCEPTION_NODES["Perception Nodes"]
        ROS_CONTRACT_TOPICS --> INFERENCE_SERVICE["Inference Service"]
        ACTION_DISPATCH["Action Dispatch"] --> MUJOCO_ROS2_CONTROL_NODE
    end

    style MUJOCO_SIM fill:#f9f,stroke:#333,stroke-width:2px
    style MUJOCO_ROS2_CONTROL_NODE fill:#cff,stroke:#333,stroke-width:2px
    style ROS_CONTRACT_TOPICS fill:#cfc,stroke:#333,stroke-width:2px
    style PERCEPTION_NODES fill:#ffc,stroke:#333,stroke-width:2px
    style INFERENCE_SERVICE fill:#fcf,stroke:#333,stroke-width:2px
    style ACTION_DISPATCH fill:#fcc,stroke:#333,stroke-width:2px

来源：src/robot_config/robot_config/launch_builders/sim_backend/mujoco_adapter.py:1-125

硬件 Mock 数据流

Title: Hardware Mock Data Flow

        graph TD
    subgraph "Hardware Mock"
        CONTRACT_MOCK_NODE["hardware_mock.contract_mock Node"]
        CONTRACT_MOCK_NODE -- "Publishes Image / JointState" --> ROS_OBSERVATION_TOPICS["ROS Observation Topics"]
        ROS_ACTION_TOPICS["ROS Action Topics"] -- "Subscribes Float64MultiArray" --> CONTRACT_MOCK_NODE
        CONTRACT_MOCK_NODE -- "Updates internal JointModel" --> CONTRACT_MOCK_NODE
        CONTRACT_MOCK_NODE -- "Immediately publishes /joint_states" --> ROS_OBSERVATION_TOPICS
    end

    subgraph "ROS 2 System"
        ROS_OBSERVATION_TOPICS --> INFERENCE_SERVICE["Inference Service"]
        INFERENCE_SERVICE --> ACTION_DISPATCH["Action Dispatch"]
        ACTION_DISPATCH --> ROS_ACTION_TOPICS
    end

    style CONTRACT_MOCK_NODE fill:#ccf,stroke:#333,stroke-width:2px
    style ROS_OBSERVATION_TOPICS fill:#cfc,stroke:#333,stroke-width:2px
    style ROS_ACTION_TOPICS fill:#fcc,stroke:#333,stroke-width:2px
    style INFERENCE_SERVICE fill:#fcf,stroke:#333,stroke-width:2px
    style ACTION_DISPATCH fill:#fcc,stroke:#333,stroke-width:2px

来源：src/hardware_mock/README.md:199-200, src/hardware_mock/README.md:145-158, src/hardware_mock/README.md:25-27

来源：src/robot_config/robot_config/launch_builders/sim_backend/gazebo_adapter.py:1-152, src/robot_config/robot_config/launch_builders/sim_backend/mujoco_adapter.py:1-125, src/robot_config/robot_config/launch_builders/sim_backend/mock_adapter.py, src/hardware_mock/README.md:1-279, src/robot_config/test/test_sim_backend.py:1-184, src/robot_config/robot_config/launch_builders/sim_peripheral_bridge.py:1-183

导航子图

navigation.py 模块负责启动 Nav2 栈及相关组件。generate_navigation_nodes 函数（由 __init__.py 中的 generate_navigation_nodes 暗示 src/robot_config/robot_config/launch_builders/init.py:85）会配置并启动必要的 Nav2 节点、参数与控制器。这包括在机器人配置指定时与 FAST-LIO/Livox 等 LiDAR 系统的集成。

来源：src/robot_config/robot_config/launch_builders/init.py:85

遥操作子图

遥操作子图通过机器人 YAML 的 teleoperation 节配置。control.py 模块的 validate_runtime_resources 函数 src/robot_config/robot_config/launch_builders/control.py:92-115 检查遥操作设备（如游戏手柄或主臂）使用的独占资源。遥操作节点的实际启动由专用构建器处理（未在提供的代码片段中明确展示，但由 teleoperation 配置暗示）。

来源：src/robot_config/robot_config/launch_builders/control.py:92-115

录制子图

录制子图由 dataset_tools 包（特别是 episode_recorder）管理。虽然它不是 robot_config 中的直接 launch 构建器，但 dataset_tools 内的 policy_eval.py 模块演示了如何回放与处理录制数据（rosbag）以进行策略评估 src/dataset_tools/dataset_tools/policy_eval.py:1-9。这暗示录制功能将作为更广泛系统的一部分启动。

来源：src/dataset_tools/dataset_tools/policy_eval.py:1-201, src/dataset_tools/test/test_policy_eval.py:1-202

追踪子图

追踪子图未在提供的 launch 构建器片段中明确详述，但它是系统用于性能分析与调试的核心组件。它涉及启动收集与可视化追踪数据的节点或工具。

语音子图

语音子图包括自动语音识别（ASR）、文本转语音（TTS）与语音方向组件。

语音 ASR

voice_asr.py 模块生成 ASR 节点 src/robot_config/robot_config/launch_builders/voice_asr.py:1-191。

语音 TTS

generate_voice_tts_nodes 函数（由 __init__.py 中的 generate_voice_tts_nodes 暗示 src/robot_config/robot_config/launch_builders/init.py:50）会为文本转语音功能创建节点。

语音方向

generate_speech_direction_actions 函数（由 __init__.py 中的 generate_speech_direction_actions 暗示 src/robot_config/robot_config/launch_builders/init.py:55）会启动与判定语音方向相关的节点。

来源：src/robot_config/robot_config/launch_builders/voice_asr.py:1-191, src/robot_config/robot_config/launch_builders/init.py:48-56