开发指南概述

相关源文件

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

本页面为参与 IB-Robot 代码库开发的开发者提供实用指南。内容涵盖环境配置、IDE 设置、构建系统使用、调试技术和验证工作流程。有关初始设置说明，请参阅 入门指南。有关特定包的开发详情，请参考 包参考。

开发环境架构

IB-Robot 开发环境由三个集成层组成：带有 ROS 2 系统站点包的 Python 虚拟环境、带有工作区特定 mixin 的 colcon 构建系统，以及用于 IntelliSense 和调试的 VS Code 配置。

        graph TB
    subgraph "Layer 1: Environment Setup"
        SETUP["setup.sh<br/>Environment Initialization"]

        subgraph "Conda Detection"
            CONDA_CHECK["check_conda()<br/>CONDA_PREFIX detection"]
            CONDA_BLOCK["Exit with error<br/>if Conda active"]
        end

        subgraph "Git Submodule Management"
            SUBMOD_DETECT["Check .git directories<br/>libs/lerobot, src/pymoveit2"]
            SUBMOD_PROMPT["Interactive selection<br/>All/LeRobot/PyMoveIt2/Individual"]
            SUBMOD_UPDATE["git submodule update<br/>--init --recursive"]
        end

        subgraph "Python venv Creation"
            VENV_CREATE["python3 -m venv<br/>--system-site-packages"]
            VENV_DEPS["pip install requirements<br/>numpy<2, setuptools<80"]
            LEROBOT_INSTALL["pip install -e libs/lerobot"]
            HW_DEPS["pip install pyserial<br/>feetech-servo-sdk"]
        end

        SETUP --> CONDA_CHECK
        CONDA_CHECK --> CONDA_BLOCK
        CONDA_CHECK --> SUBMOD_DETECT
        SUBMOD_DETECT --> SUBMOD_PROMPT
        SUBMOD_PROMPT --> SUBMOD_UPDATE
        SUBMOD_UPDATE --> VENV_CREATE
        VENV_CREATE --> VENV_DEPS
        VENV_DEPS --> LEROBOT_INSTALL
        LEROBOT_INSTALL --> HW_DEPS
    end

    subgraph "Layer 2: Build System"
        COLCON[".colcon/defaults.yaml<br/>merge-install: true"]

        subgraph "Mixin Definitions"
            MIXIN_INDEX[".colcon/mixin/index.yaml"]
            MIXIN_BUILD[".colcon/mixin/build.mixin.yaml"]

            DEBUG_MIXIN["debug mixin<br/>CMAKE_BUILD_TYPE=Debug"]
            RELEASE_MIXIN["release mixin<br/>CMAKE_BUILD_TYPE=Release"]
            DEV_MIXIN["dev mixin<br/>symlink-install + Debug"]
            PROD_MIXIN["prod mixin<br/>Release + no testing"]
        end

        MIXIN_INDEX --> MIXIN_BUILD
        MIXIN_BUILD --> DEBUG_MIXIN
        MIXIN_BUILD --> RELEASE_MIXIN
        MIXIN_BUILD --> DEV_MIXIN
        MIXIN_BUILD --> PROD_MIXIN
    end

    subgraph "Layer 3: VS Code Integration"
        SETTINGS[".vscode/settings.json<br/>Python interpreter + paths"]
        TASKS[".vscode/tasks.json<br/>colcon build tasks"]
        LAUNCH[".vscode/launch.json<br/>Debug configurations"]
        EXTENSIONS[".vscode/extensions.json<br/>Recommended tools"]

        CPP_PROPS[".vscode/c_cpp_properties.json<br/>C++ IntelliSense"]
    end

    HW_DEPS -.->|provides Python env| SETTINGS
    COLCON -.->|used by| TASKS
    MIXIN_BUILD -.->|applied in| TASKS
    SETTINGS -.->|configures| LAUNCH

来源: scripts/setup.sh:1-307, .vscode/settings.json:1-33, .colcon/defaults.yaml:1-23, .colcon/mixin/build.mixin.yaml:1-19, .vscode/tasks.json:1-26

Python 虚拟环境配置

工作区使用启用了 --system-site-packages 的 Python 虚拟环境，以便在隔离项目依赖的同时访问 ROS 2 系统安装的 rclpy。

关键依赖项

包

版本约束

原因

numpy

<2

ROS 2 Humble 组件需要 NumPy 1.x API

setuptools

>=71,<80

平衡 LeRobot 需求与 colcon 兼容性

lerobot

可编辑安装

开发修改 立即生效

pyserial

最新版本

Feetech 舵机 通信

feetech-servo-sdk

最新版本

SO-101 硬件 接口

scipy

最新版本

四元数/旋转 矩阵转换

gitlint

最新版本

提交消息 验证

设置流程

虚拟环境由 scripts/setup.sh:216-278 创建：

# Create venv with system site packages
python3 -m venv --system-site-packages venv

# Activate and install dependencies
source venv/bin/activate
pip install --upgrade pip
pip install "numpy<2"
pip install "setuptools<80" "setuptools>=71"
pip install -e libs/lerobot
pip install pyserial feetech-servo-sdk scipy
pip install gitlint
gitlint install-hook

Conda 冲突检测

如果检测到 Conda 环境处于活动状态，设置脚本将阻止执行 scripts/setup.sh:25-33：

check_conda() {
    if [[ -n "${CONDA_PREFIX}" ]]; then
        log_error "Active Conda environment detected"
        log_warn "Conda environments conflict with ROS 2 Python libraries"
        exit 1
    fi
}

原因：Conda 的包隔离可能会覆盖 ROS 2 系统包，导致 rclpy 和 tf2_ros 的导入冲突。

来源: scripts/setup.sh:216-278, scripts/setup.sh:25-33

Git 子模块管理

工作区包含 .gitmodules:1-11 中定义的两个子模块：

子模块

路径

用途

lerobot_ros2

libs/lerobot

带有 ROS 2 集成的 LeRobot 库

pymoveit2

src/pymoveit2

MoveIt 2 的 Python API

交互式初始化

设置脚本提供选择性子模块初始化 scripts/setup.sh:38-135：

        graph LR
    START["setup.sh execution"]
    CHECK{"Submodules<br/>initialized?"}

    PROMPT_UPDATE["Prompt: Update all?"]
    UPDATE_ALL["git submodule update<br/>--init --recursive"]

    PROMPT_SELECT["Menu:<br/>1. All<br/>2. LeRobot only<br/>3. PyMoveIt2 only<br/>4. Individual<br/>0. Skip"]

    INIT_ALL["Initialize all submodules"]
    INIT_LEROBOT["Initialize libs/lerobot"]
    INIT_PYMOVEIT["Initialize src/pymoveit2"]
    INIT_CUSTOM["Interactive per-submodule"]

    START --> CHECK
    CHECK -->|All exist| PROMPT_UPDATE
    CHECK -->|Some missing| PROMPT_SELECT

    PROMPT_UPDATE -->|Yes| UPDATE_ALL
    PROMPT_UPDATE -->|No| SKIP

    PROMPT_SELECT -->|1| INIT_ALL
    PROMPT_SELECT -->|2| INIT_LEROBOT
    PROMPT_SELECT -->|3| INIT_PYMOVEIT
    PROMPT_SELECT -->|4| INIT_CUSTOM
    PROMPT_SELECT -->|0| SKIP

    SKIP["Continue without update"]

开发者 Fork 配置

对于拥有个人 fork 的贡献者，设置脚本可以重新配置远程仓库 scripts/setup.sh:137-177：

# Prompts for GitCode username
# Sets: origin → user's fork
#       upstream → original repository
git remote set-url origin git@gitcode.com:${USERNAME}/IB_Robot.git
git remote add upstream git@atomgit.com:openeuler/IB_Robot.git

# Also configures submodule fork
cd libs/lerobot
git remote set-url origin git@gitcode.com:${USERNAME}/lerobot_ros2.git
git remote add upstream <original-lerobot-url>

来源: .gitmodules:1-11, scripts/setup.sh:38-177

VS Code 配置

工作区设置架构

.vscode/settings.json:1-33 文件配置 Python IntelliSense 和 ROS 2 集成：

        graph TB
    subgraph "Python Configuration"
        INTERP["defaultInterpreterPath<br/>workspaceFolder/venv/bin/python3"]

        ANALYSIS_PATHS["python.analysis.extraPaths"]
        AUTOCOMPLETE_PATHS["python.autoComplete.extraPaths"]

        PATH_LEROBOT["libs/lerobot/src"]
        PATH_SRC["src"]
        PATH_ROS_LIB["/opt/ros/humble/lib/python3.10/site-packages"]
        PATH_ROS_LOCAL["/opt/ros/humble/local/lib/python3.10/dist-packages"]
        PATH_VENV["venv/lib/python3.10/site-packages"]
    end

    subgraph "Terminal Environment"
        TERM_ENV["terminal.integrated.env.linux"]
        PYTHONPATH["PYTHONPATH environment variable"]
    end

    subgraph "File Associations"
        REPOS_YAML["*.repos files → YAML"]
    end

    subgraph "Search Exclusions"
        EXCLUDE_BUILD["build/"]
        EXCLUDE_INSTALL["install/"]
        EXCLUDE_LOG["log/"]
        EXCLUDE_VENV["venv/"]
    end

    subgraph "ROS Integration"
        ROS_DISTRO["ros.distro: humble"]
        ROS_SETUP["ros.setupSource<br/>/opt/ros/humble/setup.sh"]
    end

    INTERP --> ANALYSIS_PATHS
    INTERP --> AUTOCOMPLETE_PATHS

    ANALYSIS_PATHS --> PATH_LEROBOT
    ANALYSIS_PATHS --> PATH_SRC
    ANALYSIS_PATHS --> PATH_ROS_LIB
    ANALYSIS_PATHS --> PATH_ROS_LOCAL
    ANALYSIS_PATHS --> PATH_VENV

    AUTOCOMPLETE_PATHS --> PATH_LEROBOT
    AUTOCOMPLETE_PATHS --> PATH_SRC
    AUTOCOMPLETE_PATHS --> PATH_ROS_LIB

关键配置值：

设置

值

用途

python.defaultInterpreterPath

${workspaceFolder}/venv/bin/python3

使用工作区 venv

python.analysis.extraPaths

LeRobot, src, ROS 路径

启用导入解析

terminal.integrated.env.linux.PYTHONPATH

合并路径

确保终端使用正确的导入

ros.distro

humble

RDE 扩展 ROS 版本

search.exclude

build/, install/, log/, venv/

改善搜索性能

推荐扩展

.vscode/extensions.json:1-13 列出了必要的扩展：

扩展 ID

用途

ms-python.python

Python 语言支持和 调试

ms-vscode.cpptools

C++ IntelliSense（用于 ros2_control 插件）

vadimcn.vscode-lldb

C++ LLDB 调试器

ms-vscode.cmake-tools

CMake 集成

redhat.vscode-yaml

YAML 模式验证

Ranch-Hand-Robotics.rde-pack

ROS 开发环境包

anthropic.claude-code

可选 AI 助手

C++ IntelliSense 配置

.vscode/c_cpp_properties.json:1-17 配置 C++ 语言功能：

{
    "configurations": [
        {
            "name": "ROS2-Humble",
            "includePath": [
                "${workspaceFolder}/**",
                "/opt/ros/humble/include/**",
                "/usr/include/**"
            ],
            "cppStandard": "c++17",
            "intelliSenseMode": "linux-gcc-x64"
        }
    ]
}

来源: .vscode/settings.json:1-33, .vscode/extensions.json:1-13, .vscode/c_cpp_properties.json:1-17

构建系统和 Mixin

Colcon 工作区默认设置

.colcon/defaults.yaml:1-23 设置工作区范围的构建行为：

build:
  merge-install: true  # Single install/ directory
  event-handlers:
    - console_cohesion+  # Grouped output per package
  base-paths:
    - src

为什么使用 ``merge-install``：所有包合并到单个 install/ 目录树中，而不是单独的 install/<package> 目录。这简化了环境加载（一个 setup.bash 而不是多个），并减少磁盘使用。

Mixin 系统架构

Mixin 系统通过 .colcon/mixin/build.mixin.yaml:1-19 提供可重用的构建配置：

        graph TB
    subgraph "Build Mode Mixins"
        DEBUG["debug<br/>CMAKE_BUILD_TYPE=Debug<br/>COMPILE_COMMANDS=ON"]
        RELEASE["release<br/>CMAKE_BUILD_TYPE=Release<br/>COMPILE_COMMANDS=ON"]
        REL_DEB["rel-with-deb-info<br/>CMAKE_BUILD_TYPE=RelWithDebInfo"]
    end

    subgraph "Testing Mixins"
        TEST["test<br/>BUILD_TESTING=ON"]
        NO_TEST["no-test<br/>BUILD_TESTING=OFF"]
        LINT["lint<br/>BUILD_TESTING=ON<br/>AMENT_LINT_AUTO=ON"]
    end

    subgraph "Workflow Mixins"
        DEV["dev<br/>symlink-install: true<br/>Debug + no testing"]
        PROD["prod<br/>Release + no testing<br/>TRACETOOLS_DISABLED=ON"]
    end

    USAGE["colcon build --mixin dev"]

    USAGE -.->|applies| DEV
    DEV -.->|combines| DEBUG
    DEV -.->|combines| NO_TEST

常用构建命令

命令

用例

colcon build --mixin dev

开发：调试符号、符号链接安装、快速迭代

colcon build --mixin release

性能测试：优化代码、构建较慢

colcon build --mixin prod

生产部署：Release + 无测试 + 无追踪

colcon build --mixin debug test

带调试的测试：调试符号 + 测试目标

colcon build --packages-select <pkg>

单个包：仅构建指定的包及其依赖

colcon build --packages-up-to <pkg>

包及其依赖：构建目标包及所有上游依赖

VS Code 构建任务

.vscode/tasks.json:1-26 定义了两个构建任务：

{
    "tasks": [
        {
            "label": "colcon build",
            "command": "source /opt/ros/humble/setup.sh && source venv/bin/activate && colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release",
            "group": {"kind": "build", "isDefault": true}
        },
        {
            "label": "colcon build selected",
            "command": "colcon build --packages-select ${relativeFileDirname}"
        }
    ]
}

用法：

  • Ctrl+Shift+B 触发默认的 “colcon build” 任务

  • “colcon build selected” 仅构建包含当前文件的包

来源: .colcon/defaults.yaml:1-23, .colcon/mixin/build.mixin.yaml:1-19, .vscode/tasks.json:1-26

调试配置

Python 节点调试

.vscode/launch.json:1-28 提供两个 Python 调试配置：

配置 1：调试当前文件

{
    "name": "ROS2: Debug Python Node (Current File)",
    "type": "python",
    "request": "launch",
    "program": "${file}",
    "console": "integratedTerminal",
    "env": {
        "PYTHONPATH": "libs/lerobot_ros2:venv/lib/python3.10/site-packages:/opt/ros/humble/lib/python3.10/site-packages"
    }
}

用法：打开任意 Python 节点文件，按 F5 直接调试。

配置 2：特定节点（action_dispatcher_node）

{
    "name": "ROS2: Action Dispatcher Node",
    "type": "python",
    "request": "launch",
    "program": "src/action_dispatch/action_dispatch/action_dispatcher_node.py",
    "args": ["--ros-args", "-p", "robot_name:=test_single_arm_single_cam"],
    "env": {
        "PYTHONPATH": "libs/lerobot_ros2:venv/lib/python3.10/site-packages:/opt/ros/humble/lib/python3.10/site-packages"
    }
}

用法：从调试下拉菜单中选择 “ROS2: Action Dispatcher Node”，按 F5。

调试工作流程

        graph LR
    OPEN["Open Python node file"]
    SET_BP["Set breakpoints"]
    SELECT["Select debug configuration"]
    LAUNCH["Press F5"]

    DEBUG["Debugger attaches"]
    INTERACT["Inspect variables<br/>Step through code<br/>Evaluate expressions"]

    OPEN --> SET_BP
    SET_BP --> SELECT
    SELECT --> LAUNCH
    LAUNCH --> DEBUG
    DEBUG --> INTERACT

C++ 调试

对于 C++ 节点（例如 robot_hardware 中的硬件插件）：

  1. 使用调试符号构建：colcon build --mixin debug

  2. 生成编译命令：由 mixin 自动启用

  3. 使用 vadimcn.vscode-lldb 扩展进行调试

  4. 附加到运行中的进程或通过 launch.json 启动

来源: .vscode/launch.json:1-28

配置验证

validate_config.py 脚本

scripts/validate_config.py:1-351 强制执行机器人配置文件之间的一致性：

        graph TB
    START["validate_config.py"]

    subgraph "Step 1: Load robot_config"
        LOAD_ROBOT["Load YAML<br/>so101_single_arm.yaml"]
        EXTRACT_JOINTS["Extract joints.arm<br/>joints.gripper<br/>joints.all"]
        VALIDATE_UNION{"arm ∪ gripper<br/>== all?"}
    end

    subgraph "Step 2: Resolve Controllers"
        RESOLVE_PATH["Resolve $(find package)<br/>from ros2_control.controllers_config"]
        LOAD_CTRL["Load controllers YAML"]
    end

    subgraph "Step 3: Validate Controllers"
        CHECK_ARM_POS["arm_position_controller<br/>joints == arm"]
        CHECK_ARM_TRAJ["arm_trajectory_controller<br/>joints == arm"]
        CHECK_GRIP_POS["gripper_position_controller<br/>joints == gripper"]
        CHECK_GRIP_TRAJ["gripper_trajectory_controller<br/>joints == gripper"]
        CHECK_JS_BROAD["joint_state_broadcaster<br/>joints == all"]
    end

    subgraph "Step 4: Validate MoveIt"
        LOAD_MOVEIT["Load moveit_controllers.yaml"]
        CHECK_MOVEIT_ARM["arm_trajectory_controller<br/>joints == arm"]
        CHECK_MOVEIT_GRIP["gripper_trajectory_controller<br/>joints == gripper"]
    end

    SUMMARY["Print summary:<br/>Errors + Warnings"]
    EXIT{"Errors?"}

    START --> LOAD_ROBOT
    LOAD_ROBOT --> EXTRACT_JOINTS
    EXTRACT_JOINTS --> VALIDATE_UNION
    VALIDATE_UNION -->|Warning if mismatch| RESOLVE_PATH

    RESOLVE_PATH --> LOAD_CTRL
    LOAD_CTRL --> CHECK_ARM_POS
    CHECK_ARM_POS --> CHECK_ARM_TRAJ
    CHECK_ARM_TRAJ --> CHECK_GRIP_POS
    CHECK_GRIP_POS --> CHECK_GRIP_TRAJ
    CHECK_GRIP_TRAJ --> CHECK_JS_BROAD

    CHECK_JS_BROAD --> LOAD_MOVEIT
    LOAD_MOVEIT --> CHECK_MOVEIT_ARM
    CHECK_MOVEIT_ARM --> CHECK_MOVEIT_GRIP

    CHECK_MOVEIT_GRIP --> SUMMARY
    SUMMARY --> EXIT
    EXIT -->|Yes| FAIL["Exit code 1"]
    EXIT -->|No| SUCCESS["Exit code 0"]

执行的验证检查

配置文件

检查的控制器

预期关节

controllers.yaml

arm_position_controller

joints.arm

controllers.yaml

arm_trajectory_controller

joints.arm

controllers.yaml

gripper_position_controller

joints.gripper

controllers.yaml

gripper_trajectory_controller

joints.gripper

controllers.yaml

joint_state_broadcaster

joints.all

moveit_controllers.yaml

arm_trajectory_controller

joints.arm

moveit_controllers.yaml

gripper_trajectory_controller

joints.gripper

运行验证

# Default: validate src/robot_config/config/robots/so101_single_arm.yaml
python scripts/validate_config.py

# Verbose output
python scripts/validate_config.py --verbose

# Custom robot config
python scripts/validate_config.py --robot-config path/to/robot.yaml

# Specify MoveIt config explicitly
python scripts/validate_config.py --moveit-config path/to/moveit_controllers.yaml

CI/CD 集成

退出代码：- 0：所有验证通过 - 1：发现配置错误 - 2：文件未找到或解析错误

在 CI 中使用：

- name: Validate Configuration
  run: python scripts/validate_config.py
  # Fails build if exit code != 0

来源: scripts/validate_config.py:1-351

贡献工作流程

Git 提交规范

工作区使用 gitlint 进行提交消息验证，由 scripts/setup.sh:264-268 安装：

pip install gitlint
gitlint install-hook  # Installs pre-commit hook

提交消息格式 （由 gitlint 强制执行）：

<type>(<scope>): <subject>

<body>

<footer>

示例：

feat(inference): add distributed execution mode

Implement device-edge-cloud architecture for compute offloading.
TensorPreprocessor runs on robot CPU, PureInferenceEngine on GPU server.

Closes #42

开发周期

        graph TB
    FORK["Fork repository<br/>on GitCode"]
    CLONE["Clone your fork"]
    SETUP["Run setup.sh"]

    BRANCH["Create feature branch<br/>git checkout -b feat/xyz"]
    CODE["Make changes"]
    TEST["Test locally"]

    VALIDATE["Run validate_config.py"]
    LINT["Lint checks (gitlint)"]
    COMMIT["git commit -m 'feat: ...'"]

    PUSH["git push origin feat/xyz"]
    PR["Create Pull Request"]

    FORK --> CLONE
    CLONE --> SETUP
    SETUP --> BRANCH
    BRANCH --> CODE
    CODE --> TEST
    TEST --> VALIDATE
    VALIDATE --> LINT
    LINT --> COMMIT
    COMMIT --> PUSH
    PUSH --> PR

    PR -.->|Review feedback| CODE

分支命名约定

前缀

用途

示例

feat/

新功能

feat/add-depth-camera-support

fix/

错误修复

fix/action-queue-overflow

refactor/

代码重构

refactor/split-preprocessor-module

docs/

文档

docs/update-inference-guide

test/

测试添加

test/add-temporal-smoother-tests

提交前检查清单

推送前：

  1. 构建通过：colcon build --mixin dev

  2. 配置有效：python scripts/validate_config.py

  3. 测试通过：colcon test --packages-select <modified-packages>

  4. 代码格式化：遵循 ROS 2 Python 风格指南

  5. 提交消息：遵循 gitlint 约定

  6. 子模块更新：如果修改了子模块，单独提交子模块更新

来源: scripts/setup.sh:264-268

快速参考

环境激活

# Source ROS 2
source /opt/ros/humble/setup.sh

# Activate venv
source venv/bin/activate

# Source workspace
source install/setup.bash

常用开发命令

任务

命令

完整构建

colcon build --mixin dev

单个包

colcon build --packages-select robot_config

清理构建

rm -rf build/ install/ log/ && colcon build --mixin dev

运行验证

python scripts/validate_config.py --verbose

更新子模块

git submodule update --remote --merge

格式化 Python

black src/<package>/<package>/*.py （如已配置）

列出包

colcon list

故障排除

问题

解决方案

rclpy 导入错误

确保使用 --system-site-packages 创建 venv

NumPy 版本冲突

在 venv 中执行 pip install "numpy<2"

子模块未初始化

git submodule update --init --recursive

VS Code 无法找到导入

检查 .vscode/settings.json extraPaths

构建失败并出现 mixin 错误

确保 .colcon/mixin/ 文件存在

配置验证失败

检查 YAML 文件中的关节定义是否一致

来源: scripts/setup.sh:1-307, .vscode/settings.json:1-33, .colcon/mixin/build.mixin.yaml:1-19