IB-Robot 启动系统与故障排查实战指南：基于 robot_config 的 launch 编排、仿真后端分发与推理管线排障-平芜编程栈

具身智能
机器人
人工智能
大模型
模型推理服务
本地部署
计算机视觉
ROS

【免费下载链接】IB_Robot

Save the code of IB-Robot, an AI robot execution framework developed by openEuler Embedded for embodied intelligence scenarios. It includes references to the forked version of tensormsg, references to lerobot fork, code references to the lerobot_ros2:ros2_ws branch, as well as some code related to development usability.

项目地址：https://gitcode.com/openeuler/IB_Robot

点击查看免费下载

本文是一份面向 IB-Robot（openEuler Embedded 面向具身智能场景的 AI 机器人执行框架）开发者的启动与排障实战指南。核心场景是：通过src/robot_config/launch/robot.launch.py这一个统一入口，按需组合 30 个 launch builder 拉起 control / perception / simulation / execution / navigation / voice / recording / tracing 等各类节点，并在遇到配置校验失败、控制器不匹配、推理 pipeline 启动失败等典型故障时快速定位根因。读完本文，你将掌握 25 个 launch 参数的语义与默认值、三种仿真后端（gazebo / mujoco / mock）的分发机制、新增机器人与离线调试契约的完整流程，以及基于源码的故障排查方法。

何时需要阅读本文

需要选择正确的 launch builder 来组合启动节点（control / perception / simulation / execution / navigation / voice / recording / tracing 等）；
需要查阅robot.launch.py支持的 launch arguments 及默认值；
第一次启动系统、添加新机器人、调试契约合成时；
遇到配置校验失败、控制器不匹配、推理 pipeline 启动失败等问题需要排查时。

Launch 系统：单入口编排架构

IB-Robot 的启动系统以src/robot_config/launch/robot.launch.py为核心入口。该文件通过OpaqueFunction编排，在 launch 时动态加载机器人 YAML 配置，并直接调用launch_builders/目录下的构建函数生成节点；builder 之间无插件注册机制，是一组固定的 facade（门面模块），这意味着新增子系统必须显式挂载到编排器中，而不是通过注册表自动发现。

仿真平台则通过sim_backend.get_sim_backend(platform)分发到三种适配器之一。从 sim_backend/init.py 的源码可以看到注册表结构：

_BACKEND_REGISTRY: dict[str, type[SimBackendAdapter]] = { "gazebo": GazeboAdapter, "mock": MockAdapter, "mujoco": MujocoAdapter, }

get_backend_caps(platform)会在构建后端动作之前返回能力标志（provides_clock、needs_ros2_control），供 robot.launch.py 决定node_use_sim_time、auto_start_controllers与 ros2_control 的启停策略；未知平台会抛出ValueError并列出可用平台。此外，launch 编排中还有几个值得注意的 fail-fast 分支（同样位于robot.launch.py）：

benchmark target 会跳过 ros2_control、simulation backend 与 physical perception（打印[IBROBOT_BENCHMARK][SKIP]标记）；
配置了runtime.provider（如 so101_robot）时，硬件与控制器启动委托给机器人运行时单元，auto_start_controllers自动置为false；
控制器启动采用单控制器组 spawner 作为就绪屏障（_controller_readiness_barrier），后续的 perception、navigation、execution 等"控制相关动作"会挂到OnProcessExit事件上，等屏障退出成功后才启动。

Launch Builders（30 个）：按子系统分组的构建模块

src/robot_config/robot_config/launch_builders/下共 30 个 builder 模块，按职责可划分为以下分组：

分组	Builders
控制与描述	`control.py`（ros2_control 节点、controller spawners）、`description.py`（URDF xacro + 相机注入）、`hand_sources.py`（手部数据源 + profiles）
感知	`perception.py`（相机/激光雷达驱动、虚拟 relay）、`perception_models.py`（来自`perception_services.services`的 typed model-service 插件）、`camera_isp_overrides.py`（ISP 标定）
仿真	`simulation.py`（分发）、`sim_backend/`（gazebo / mujoco / mock 适配器）、`sim_peripheral_bridge.py`（ros_gz 桥）、`hardware_mock.py`（契约驱动的 mock）
推理与执行	`execution.py`（命名推理管线 + dispatch 路由）、`task_execution.py`（`task_executor_node`）
导航	`navigation.py`、`nav2.py`、`localization.py`（EKF + RTAB-Map）、`navigation_command.py`（typed command server）、`cmd_vel.py`（底盘桥）、`static_tf.py`、`fast_lio.py`
语音与音频	`audio_io.py`、`voice_asr.py`、`voice_tts.py`、`speech_direction.py`、`voice_nav.py`（ASR → Nav2 goal）
输出与可观测性	`recording.py`（continuous rosbag vs episodic recorder + rerun viewer）、`benchmark.py`、`semantic_mapping.py`、`tracing.py`（LTTng session）、`moveit.py`（move_group + RViz）

实际目录中还包括runtime.py（runtime provider 编排）、teleop.py、interaction_demo.py等，与robot.launch.py的launch_setup各节一一对应（见 robot.launch.py 的编排顺序：加载参数 → 解析 runtime target → 控制模式覆盖 → 控制节点 → 仿真节点 → 感知节点 → 遥操作 → 语音 → 导航 → 执行 → 记录 → tracing）。

Key Launch Arguments（25 个）：参数语义与默认值

robot.launch.py通过DeclareLaunchArgument声明 25 个 launch 参数（见 generate_launch_description）：

Argument	Purpose	Default
`robot_config`	配置名（不带 .yaml）	`so101_single_arm`
`config_path`	完整路径覆盖	`""`
`use_sim`	仿真标志（空则由 runtime target 推断）	`""`
`sim_platform`	覆盖`simulation.platform`（gazebo/mujoco/mock）	`""`
`runtime_target`	hardware / simulation / benchmark 覆盖	`""`
`auto_start_controllers`	启动时 spawn 控制器	`true`
`control_mode`	teleop / model_inference / moveit_planning（空 →`default_control_mode`）	`""`
`nav_stage`	mapping / navigation / grasp / hybrid	`""`
`hand_profile`	手部 profile 选择	`""`
`with_inference`	强制启用/禁用推理（空自动检测）	`""`
`inference_pipeline`	被覆盖的命名 pipeline ID	`""`
`inference_execution_mode`	monolithic / distributed	`""`
`with_moveit`	若 mode 名含 'moveit' 则自动检测	`""`
`with_navigation`	空 →`robot.navigation.enabled`	`""`
`navigation_mode`	full / odom_only / imu_only	`""`
`moveit_display`	RViz	`true`
`record`	Rosbag 录制	`false`
`record_mode`	continuous / episodic	`continuous`
`voice_asr_auto_start`	强制 ASR 启用 + continuous	`false`
`voice_asr_realtime_pre_roll_seconds`	ASR pre-roll	`""`
`with_embodied`	空 →`robot.embodied.enabled`	`""`
`with_perception`	空 →`robot.embodied.perception.enabled`	`""`
`record_visualizer`	none / rerun	`none`
`enable_tracing`	ros2_tracing / LTTng	`false`
`trace_session_name`	Trace session 名	（builder 默认）

几个关键语义需要结合源码理解：

use_sim与runtime_target的关系：use_sim为空时由 runtime_target.py 中的resolve_runtime_target决定（launch 覆盖 → YAMLruntime.target→ 历史use_sim回退 → 默认 hardware），且与显式use_sim做一致性 fail-fast 校验；benchmark +use_sim:=true仍是 benchmark，并跳过 ros2_control、仿真后端与物理感知。
inference_pipeline/inference_execution_mode必须成对使用：_apply_inference_cli_overrides（robot.launch.py）要求二者同时给定，且 pipeline ID 必须存在于control_modes.<mode>.inference.pipelines中，否则直接ValueError中止。
record_visualizer:=rerun会额外启动 Rerun sidecar，用于实时查看相机、关节与动作曲线（对应generate_rerun_viewer_node）。

常用启动模式：从标准仿真到业务组合

robot.launch.py的模块 docstring 给出了完整的启动示例，以下为最常用的模式：

# 标准仿真启动 ros2 launch robot_config robot.launch.py robot_config:=so101_single_arm use_sim:=true # Mock 后端（无硬件、无 Gazebo）：runtime target simulation + mock platform ros2 launch robot_config robot.launch.py robot_config:=so101_single_arm \ use_sim:=true sim_platform:=mock # 覆盖控制模式 ros2 launch robot_config robot.launch.py robot_config:=so101_single_arm \ control_mode:=moveit_planning # 移动底盘 + 导航阶段 ros2 launch robot_config robot.launch.py robot_config:=lekiwi_nav_grasp \ nav_stage:=grasp with_navigation:=true # 分段（episodic）录制 ros2 launch robot_config robot.launch.py control_mode:=teleop \ record:=true record_mode:=episodic # 分段录制 + Rerun 实时可视化 ros2 launch robot_config robot.launch.py robot_config:=so101_single_arm \ control_mode:=teleop record:=true record_mode:=episodic record_visualizer:=rerun # 真实硬件 ros2 launch robot_config robot.launch.py robot_config:=so101_single_arm use_sim:=false

注意两点运行前提：

必须设置ROS_DOMAIN_ID。工作区为避免与其他 ROS 2 系统冲突使用ROS_DOMAIN_ID=<ID>，启动前务必执行export ROS_DOMAIN_ID=<ID>；
清理残留。若遇到 "Controller already loaded" 错误，可运行仓库内scripts/cleanup_ros.sh清理后再启动。

so101_single_arm配置本身的runtime.provider: so101_robot走的是 SDK 模拟传输（simulation.platform: sdk），因此 Gazebo / MuJoCo / mock 均不支持于该 provider 路径——这是 so101_single_arm.yaml 中明确标注的约束。该配置同时是单臂应用的 SSOT 范本，包含control_modes（teleop / model_inference / moveit_planning 三种模式及其 inference 与 executor 配置）、voice_asr、voice_tts、embodied、contract、teleoperation、recording等完整段落。

添加新机器人：YAML 即 SSOT

新增一台机器人只需四个步骤，无需修改任何 Python 编排代码：

创建 YAML：config/robots/my_robot.yaml（单顶层键robot:）；
需要变体时用 overlay 继承：base_config: <base-name>（必须同目录），列表追加用__append__键；
定义name、joints、control_modes、peripherals、contract（按需追加voice_*/embodied/navigation段落）；
启动：ros2 launch robot_config robot.launch.py robot_config:=my_robot

overlay 合并与校验逻辑集中在 loader.py 的_deep_merge_config：__append__只允许出现在仅含该键的 dict 中且值为 list，base 中对应键必须是 list；跨目录、循环的 overlay 会被拒绝。路径解析优先级为config_path显式参数 →config_name→ROBOT_CONFIG环境变量 →ROBOT_NAME环境变量 → 默认so101_single_arm。

仓库src/robot_config/config/robots/下已有 30 余个现成配置可供参考，例如so101_dual_arm.yaml、lekiwi_nav_grasp.yaml、so101_pi05_ascend_310p_mock.yaml、franka_libero_evaluation.yaml等，覆盖单臂、双臂、移动底盘、昇腾 310P mock、benchmark 评测等场景。

调试契约：内存合成与离线检查

契约（Contract）在 launch 时内存合成（RobotConfig.to_contract()/build_contract_from_robot_config_dict()），不落盘、无磁盘缓存。前者是类型化路径（见 config.py），后者是 dict 路径（由 loader.py 转发到generators/contract.py）。可以离线检查合成结果：

# Offline inspection from robot_config.loader import load_robot_config rc = load_robot_config("so101_single_arm") contract = rc.to_contract() print(contract.rate_hz, [o.key for o in contract.observations])

Launch 日志中配置校验失败会 fail-fast 并给出具体原因（observation source 不在peripherals、inference 引用的模型 / pipeline 不存在、executor 类型非法等）。validate_config（loader.py）会返回错误列表，launch 内执行后在日志中逐条打印。
loader.robot_config_digest()（loader.py）对合并后的配置做指纹计算，可用于对比两份配置是否漂移——它刻意不是 YAML 文档的 digest，而是"封闭技能执行上下文"的指纹，因此 profile 选择等无关改动不会改变身份。

Troubleshooting：三类典型故障排查

问题一：launch 时配置校验失败

原因：SSOT YAML 违反校验规则（loader.validate_config在 launch 内执行，fail-fast）。

检查清单：

Observation 的source是否在peripherals中定义；
control_modes.<mode>.inference引用的模型 / pipeline 是否存在（由 inference_config.py 的parse_inference_config在 launch 构建前解析并校验，抛InferenceConfigError）；
Executor 类型是否为topic/benchmark，controller 名是否出现在ros2_control中；
Overlay 配置的base_config是否为同目录文件（跨目录、循环会被拒绝）。

额外经验：so101_single_arm.yaml中controller_startup_timeout支持按 profile 分别配置（sim 默认 120.0s、hardware 默认 30.0s），由_resolve_controller_startup_timeout（robot.launch.py）解析；launch 还会执行validate_runtime_resources与confirm_interactive_startup_p_pose等前置校验，模拟场景会起一个wait_for_controllers探针节点等待控制器就绪。

问题二：运行的控制器不对

原因：控制模式不匹配（每个 mode 的控制器集合来自 YAMLcontrol_modes.<mode>.controllers，launch 仅负责按control_mode选择对应集合）。

解决：

# For MoveIt / skills ros2 launch robot_config robot.launch.py control_mode:=moveit_planning # For policy inference ros2 launch robot_config robot.launch.py control_mode:=model_inference

参考映射关系：position controllers（topic executor）用于 teleop / model_inference；trajectory controllers（action executor，经运行时motion_server/task_dispatch）用于 moveit_planning；base_controller/base_velocity_controller用于 base_navigation。四种控制模式最终都汇聚到同一个ros2_control硬件接口上，只是 per-mode 控制器集合不同。需要留意的是：当前 generic launch 不再内置 planner——若请求 moveit 控制模式但robot.runtime.provider未设置，robot.launch.py 会直接抛RuntimeError拒绝启动不完整的运动栈。

问题三：推理 pipeline 启动失败

常见错误：

Manifest 加载失败——bundle 必须是 schema v3（inference_manifest/loader.py 的load_inference_manifest严格校验，含 artifact digest、语义绑定方向、action 输出绑定等），旧版本 manifest 会被ManifestValidationError拒绝；
Backend conformance 失败——deployment 的 runtime profile 与后端能力不匹配。例如 ascend 要求target.runtime=acl、artifacts 格式为om；backends/registry.py 中_validate_ascend明确要求target.runtime必须恰为'acl'（ABI 版本放在target.runtime_abi）；hisilicon 要求target.soc=sd3403且target.runtime=hisilicon-worker；
Scheduler 会话失败——session 化路径需先等待/inference/scheduler/ready就绪；重复请求会被IdempotencyLedger拒绝；
Distributed 模式无视频——检查 RTP 通道协商（VideoStreamNegotiator，见 compute_video_streams.py，负责 requirements 与VideoTransportCapabilities的匹配）与 keyframe 等待状态（WAITING_FOR_KEYFRAME）。