入门指南概述

前置条件

系统要求

IB-Robot 在三平台协同工作流上开发和测试：

组件	要求
Operating Systems	Ubuntu 22.04 (Host/Sim), openEuler Embedded 24.03 (Edge), OpenHarmony 5.1 (Edge)
ROS Version	ROS 2 Humble Hawksbill
Python	System Python 3.10+ (openEuler uses 3.11, OpenHarmony uses 3.12)
Conda	配置前必须停用，避免库冲突

关键要求：配置流程使用 Python virtual environment (venv) 将机器学习依赖，PyTorch、LeRobot，与系统包隔离。在激活的 Conda 环境中运行 setup 或 build scripts 会导致动态库冲突，尤其是 libstdc++ 和 NumPy 版本。setup.sh 脚本会显式设置 PYTHONNOUSERSITE=1，确保环境干净。

来源：scripts/setup.sh:68-82, scripts/setup/platforms/openeuler-embedded-24.03.sh:114-116, scripts/setup/platforms/openharmony-5.1.0-musl.sh:22-26

快速开始工作流

下图展示从克隆仓库到运行系统的完整流程：

图：初始配置与启动流程

        graph TB
    Clone["git clone IB_Robot"] --> CheckConda{"Conda active?"}
    CheckConda -->|Yes| DeactivateConda["conda deactivate"]
    CheckConda -->|No| RunSetup
    DeactivateConda --> RunSetup["./scripts/setup.sh"]
    
    RunSetup --> SubmoduleInit["update_submodules (submodules.sh)"]
    SubmoduleInit --> CreateVenv["ensure_workspace_venv (rosdep.sh)"]
    CreateVenv --> InstallDeps["ensure_rosdep (rosdep.sh)"]
    InstallDeps --> ApplyPatches["lerobot_patches.sh"]
    ApplyPatches --> GenerateShrc["Generate .shrc_local"]
    
    GenerateShrc --> SourceEnv["source .shrc_local"]
    SourceEnv --> RunBuild["./scripts/build.sh"]
    
    RunBuild --> ColconBuild["colcon build --mixin dev"]
    
    ColconBuild --> LaunchSim["ros2 launch robot_config robot.launch.py"]
    LaunchSim --> SystemRunning["Robot System Running"]
    
    style RunSetup fill:#e3f2fd
    style RunBuild fill:#fff9c4
    style LaunchSim fill:#c8e6c9

来源：scripts/setup.sh:119-128, scripts/setup/submodules.sh:36-41, scripts/setup/rosdep.sh:79-85, scripts/build.sh:132-147

分步配置

1. 克隆仓库

git clone https://atomgit.com/openeuler/IB_Robot.git
cd IB_Robot

2. 运行初始配置

执行 setup script 初始化开发环境：

./scripts/setup.sh

setup.sh 脚本会自动执行以下操作：

子模块与依赖管理

脚本通过 git submodule sync 和 update 处理仓库同步。它使用安装在 venv 内的 workspace-local rosdep 实例管理系统依赖。在 openEuler 上，它会配置 ROS_OS_OVERRIDE=rhel:8 以保持兼容。

来源：scripts/setup/submodules.sh:43-45, scripts/setup/rosdep.sh:105-112, scripts/setup/platforms/openeuler-embedded-24.03.sh:11-12

LeRobot Patch 应用

IB-Robot 为 libs/lerobot 子模块维护 patch stack，以确保它兼容 ROS 2 和特定硬件平台。lerobot_patches.sh 脚本使用 lerobot_resolve_active.py 从 INDEX.yaml 识别正确 tag，并基于平台 profile，例如 core、ros、hardware，应用 patches。

来源：scripts/setup/lerobot_patches.sh:6-19, scripts/setup/README.md:21-34, scripts/setup/platforms/ubuntu-22.04.sh:6-8

Tracing 基础设施

配置流程会自动安装 LTTng 和 tracing 依赖。在 Ubuntu 上，它安装 lttng-tools 和 babeltrace2；在 openEuler 上，它通过 extras repository 处理 python3-lttngust。

来源：scripts/setup/platforms/ubuntu-22.04.sh:33-35, scripts/setup/platforms/openeuler-embedded-24.03.sh:147-154

3. 构建工作空间

使用提供的 wrapper script 编译 ROS 2 packages：

./scripts/build.sh --mixin dev

build.sh 脚本会验证 colcon 可从 workspace venv 导入，检查 libs/lerobot 的 Python 版本兼容性，要求 Python >= 3.10，并安装缺失的运行时依赖，如 pyserial 或 sherpa-onnx。

来源：scripts/build.sh:149-161, scripts/build.sh:163-190, scripts/build.sh:203-208

首次启动

启动仿真

要验证安装，请在仿真中启动机器人：

ros2 launch robot_config robot.launch.py \
    robot_config:=so101_single_arm \
    use_sim:=true

图：robot.launch.py 执行流程

该图将高层启动流程映射到 robot_config 包中定义的代码实体和硬件接口逻辑。

        graph TB
    LaunchFile["robot.launch.py"] --> LoadConfig["robot_config/config/robots/so101_single_arm.yaml"]
    LoadConfig --> ParseParams["robot_config.launch_utils"]
    
    ParseParams --> BuilderSelect{"Builder Dispatch"}
    
    BuilderSelect --> ControlBuilder["ros2_control_node"]
    BuilderSelect --> SimBuilder["gz_ros2_control"]
    BuilderSelect --> PeripheralBuilder["usb_cam_node"]
    
    ControlBuilder --> HWPlugin{"Hardware Plugin"}
    HWPlugin -->|use_sim:=true| GzPlugin["gz_ros2_control/GazeboSimSystem"]
    HWPlugin -->|use_sim:=false| RealHW["so101_hardware/SO101HardwareInterface"]
    
    BuilderSelect --> InferenceCheck{"with_inference?"}
    InferenceCheck -->|true| InferenceNodes["lerobot_policy_node"]
    
    style LoadConfig fill:#e3f2fd
    style ControlBuilder fill:#fff9c4
    style SimBuilder fill:#c8e6c9

来源：scripts/setup/platforms/openeuler-embedded-24.03.sh:131-132, scripts/build.sh:152-153

Package 参考概览

工作空间按功能层组织：

Package	角色
`robot_config`	中央配置、URDFs 和统一 launch 入口。
`tensormsg`	ROS messages 与 ML tensors 之间的双向转换。
`inference_service`	管理 policy 执行，LeRobot/ACT/Diffusion/VLA。
`action_dispatch`	Temporal smoothing 和 command queue 管理。
`voice_asr_service`	基于 `sherpa-onnx` 的语音命令接口。

来源：scripts/build.sh:9, scripts/build.sh:152-153

下一步

详细环境配置：深入排障或手动配置见环境配置。
构建配置：在项目构建中了解不同 build mixins，release、debug、asan。
核心概念：在核心概念中理解契约驱动设计和单一事实源。

来源：scripts/build.sh:41-49