atom01_firmware 并非一个单体式构建系统，而是一个采用 Git 子模块联邦（Submodule Federation） 策略的元仓库。它通过 .gitmodules 将三个异构的固件与镜像构建系统锁定在同一基准线上：面向主机-机器人通信接口的 roboto_usb2can、面向 RK3588 计算平台的 orangepi-build，以及面向 RDK X5 计算平台的 x5-rdk-gen。元仓库本身不提供顶层构建编排脚本，而是以版本契约为核心，确保在任意历史提交点上，各子模块的代码状态均可完整复现。这种设计的根本意图是将嵌入式通信固件、板卡镜像生成与主机端工具链解耦，使各域专家能够独立迭代，同时通过子模块指针保证系统级一致性。 Sources: .gitmodules, readme_cn.md

以下架构图展示了元仓库、三个子模块、目标硬件与主机工具之间的整体关系。其中 atom01_firmware 作为版本聚合点，向下锁定三个子模块的精确提交；各子模块则分别向 MCU、OrangePi SBC 与 RDK X5 SBC 交付固件或镜像，同时 roboto_usb2can 还反向向开发主机提供 USB 即插即用的 CAN 接口能力。

graph TB
    subgraph atom01_firmware["atom01_firmware（元仓库）"]
        direction TB
        GM[.gitmodules<br/>版本契约]
        RM[readme_cn.md<br/>集成说明]
    end

    subgraph submodules["Git 子模块"]
        direction LR
        USB[roboto_usb2can<br/>USB-CAN 桥接固件]
        OPB[orangepi-build<br/>OrangePi 镜像构建]
        X5[x5-rdk-gen<br/>RDK X5 镜像构建]
    end

    HW_CAN[机器人 CAN 总线]
    HW_OP[OrangePi SBC<br/>RK3588]
    HW_X5[RDK X5 SBC]

    atom01_firmware -->|锁定版本| submodules
    USB -->|CAN 帧转发| HW_CAN
    OPB -->|eMMC/SD 镜像| HW_OP
    X5 -->|eMMC/SD 镜像| HW_X5

    HOST[开发主机]
    USB -.->|PyUSB 主机工具<br/>udev 免驱规则| HOST

三个子模块在构建范式、输出形态与目标硬件上存在本质差异，因此集成策略必须尊重各自的工程惯例，而非强行统一构建抽象。roboto_usb2can 基于 Zephyr RTOS 与 cannectivity 协议栈，输出为单片 MCU 固件（.bin），并附带基于 pyusb 的跨平台主机工具及 udev 规则，实现 USB 插入即用的 CAN 接口抽象；orangepi-build 继承 Armbian 构建框架，通过 build.sh 编译 U-Boot、内核与根文件系统，支持 robopi1、robopi2、robopi3 三种自定义板卡配置，其内核采用 legacy/current/develop 多分支策略；x5-rdk-gen 则采用 D-Robotics 官方 SDK 的 repo-manifest 模式，通过 build.sh 的 setup/kernel/bootloader/rootfs/debs/pack 子命令串行构建，最终基于 Ubuntu samplefs 叠加本地 deb 包生成可烧录镜像。三者的构建产物——MCU 固件、ARM64 Linux 镜像、ARM64 Linux 镜像——在物理上互不依赖，但在功能上共同构成机器人的“通信-计算”底座。 Sources: roboto_usb2can.h, roboto_usb2can_tool.py, 99-roboto-usb2can.rules, robopi1.conf, build.sh

针对两个计算平台，机器人专属软件的集成采用了两种截然不同的模式。对于 OrangePi，集成采用 运行时 APT 源注入 策略：在 orangepi-build/scripts/general.sh 的镜像打包阶段，若构建配置中启用 BUILD_ROBOPARTY_PACKAGES=yes，脚本将首先根据 BOARD 变量（robopi1、robopi2 或 robopi3）确定对应的 APT 发行版代号与待安装包名（当前统一为 roboto-all），随后向镜像内写入 GPG 公钥与私有源列表 roboparty.list，最终在 chroot 环境中执行 apt-get install。该机制将机器人业务层软件与基础镜像构建解耦，使业务包可通过独立的 APT 仓库异步迭代，无需重新编译内核。此外，distributions.sh 与 main.sh 中保留了 bms-daemon 的本地 deb 安装与编译钩子（当前以注释形式存在），展示了从“外部 APT 依赖”回退到“本地源码编译”的二级集成路径，为后续硬实时或离线场景预留了扩展接口。 Sources: general.sh, distributions.sh, main.sh

对于 RDK X5，集成逻辑则采用 根文件系统 deb 覆盖 策略。x5-rdk-gen/pack_image.sh 在镜像打包阶段，除了将官方 RDK_DEB_PKG_LIST 中指定的基础 deb 包复制到 /app/hobot_debs 外，还会额外扫描 deploy/deb_pkgs 目录，将用户或 CI 预编译的第三方 deb 包合并进同一目录，随后调用 install_packages 函数在 chroot 环境中批量安装。与 OrangePi 的在线 APT 模式不同，RDK X5 的集成完全离线完成，所有依赖必须在构建主机上预先解决并以 deb 形式落地。hobot_customize_rootfs.sh 则提供了根文件系统级的基础定制，包括主机名、SSH 配置、用户创建、NetworkManager 策略及 fake-hwclock 初始化，确保镜像出厂即具备机器人场景所需的运行环境。这种“samplefs + 本地 deb 叠加”的策略更适合对网络不可达的嵌入式部署环境。 Sources: pack_image.sh, hobot_customize_rootfs.sh

roboto_usb2can 作为横跨“嵌入式端—主机端”的组件，其集成策略不仅包含 MCU 固件本身，还涵盖主机侧的即插即用生态。固件端实现了兼容 candleLight 的 gs_usb 协议，并通过 MSOS 2.0 描述符提供 Windows WinUSB 免驱支持；主机端则提供基于 libusb/pyusb 的 Python 工具 roboto_usb2can_tool.py，支持双通道 CAN 收发、位时序配置及帧解析。为进一步降低使用门槛，仓库内置 99-roboto-usb2can.rules udev 规则，将 VID=0x1D50, PID=0x606F 的 USB 设备权限映射至 plugdev 组，实现 Linux 下的非 root 访问。GitHub Actions 工作流同时自动化了 Zephyr 固件编译与 Windows EXE 打包，确保每次代码推送都能产出跨平台可用的发布产物。这种“固件-驱动-工具-CI”四位一体的设计，使 USB2CAN 模块成为机器人 CAN 总线的透明延伸。 Sources: roboto_usb2can.h, roboto_usb2can_tool.py, 99-roboto-usb2can.rules, zephyr-build.yml, build-tool-exe.yml

flowchart LR
    subgraph MCU["roboto_usb2can 固件端"]
        Z[Zephyr RTOS]
        GS[gs_usb 协议栈]
        CAN[CAN 控制器]
    end

    subgraph HOST["主机端"]
        USB[USB 总线]
        UD[udev 规则<br/>MODE=0666]
        PY[roboto_usb2can_tool.py<br/>PyUSB / Tkinter GUI]
        EXE[Windows EXE<br/>GitHub Actions 产出]
    end

    MCU <-->|USB Bulk EP| HOST
    CAN -->|CAN_H/L| ROBOT[机器人 CAN 网络]

在多仓库协作的固件工程中，版本漂移是导致系统级故障的首要原因。atom01_firmware 通过 Git 子模块的 SHA-1 指针解决这一问题：.gitmodules 定义了三个远程仓库的 URL 与本地路径，而父仓库的每次提交都精确记录子模块的当前快照。开发者只需执行 git submodule update --init --recursive，即可在任意历史时刻重建完全一致的固件基线。与单体式仓库相比，子模块联邦策略的权衡在于：本地开发者需要熟悉 git submodule 的工作流（如 detached HEAD 状态、同步顺序），且跨子模块的原子提交较为繁琐；但其收益是显著的——各子模块可保持独立的 Issue 追踪、PR 流程与版本标签，OrangePi 的 Armbian 基线升级、RDK X5 的 SDK 迭代、USB2CAN 的 Zephyr 版本迁移均可在不相互阻塞的情况下推进。对于机器人这种长周期、多硬件并行的项目，该策略在工程可维护性与系统可复现性之间取得了最优平衡。 Sources: .gitmodules, readme_cn.md

当前项目的发布策略是 分布式产物模型：每个子模块通过自身的 GitHub Actions 工作流独立产出 release 资产。roboto_usb2can 在推送至 main 分支时触发 zephyr-build.yml，使用 west build 编译并上传 .bin 固件；同时 build-tool-exe.yml 在 Windows runner 上将主机工具打包为独立 .exe。orangepi-build 与 x5-rdk-gen 虽未在元仓库内配置 Actions，但二者均通过本地 build.sh 脚本生成可烧录镜像，镜像文件存放于各自子模块的 Release 页面。元仓库不介入具体的编译过程，也不提供统一的 release 打包脚本；开发者需根据目标硬件选择进入对应子模块目录执行构建。这种去中心化的流水线设计降低了 CI 的耦合度，但要求维护者在发布大版本时，手动确认各子模块产物的版本对齐关系，并在 atom01_firmware 的父仓库中打上一个聚合标签，以记录该次发布所依赖的全部子模块指针。 Sources: zephyr-build.yml, build-tool-exe.yml, build.sh, readme_cn.md

flowchart LR
    A[开发者] -->|git submodule update| B[atom01_firmware]
    B --> C{选择目标域}
    C -->|USB2CAN| D[cd roboto_usb2can]
    D --> E[west build -b roboto_usb2can]
    E --> F[Release: .bin + .exe]
    C -->|OrangePi| G[cd orangepi-build]
    G --> H[./build.sh BOARD=robopi*]
    H --> I[Release: .img]
    C -->|RDK X5| J[cd x5-rdk-gen]
    J --> K[./build.sh image]
    K --> L[Release: .img]

基于上述集成架构，新增机器人业务软件或硬件适配时应遵循以下扩展路径。对于 OrangePi 平台，若业务包已发布至私有 APT 仓库，仅需在构建配置中设置 BUILD_ROBOPARTY_PACKAGES=yes 并确保 roboparty_dist 与板卡匹配；若需离线集成或修改内核模块，可参考 bms-daemon 的注释化 hook，在 main.sh 中添加本地编译步骤，并在 distributions.sh 中执行 install_deb_chroot。对于 RDK X5 平台，推荐将第三方 deb 包预先放入 deploy/deb_pkgs，由 pack_image.sh 自动合并安装；若需修改根文件系统基础环境（如新增默认用户组、预置 systemd 服务），则直接扩展 hobot_customize_rootfs.sh。对于 roboto_usb2can，固件功能扩展遵循标准 Zephyr 应用开发流程，主机工具扩展则修改 roboto_usb2can_tool.py 并确保 requirements.txt 同步更新。所有扩展在提交时均应在父仓库更新子模块指针，以固化集成状态。 Sources: general.sh, distributions.sh, main.sh, pack_image.sh, hobot_customize_rootfs.sh, roboto_usb2can_tool.py

本页从架构层面阐释了机器人系统固件的集成策略与协作模式。若您希望深入某一具体子模块的实现细节，可按以下路径继续阅读：USB2CAN 固件的核心协议实现与硬件抽象请参阅 Zephyr RTOS 与 USB 协议栈 与 CAN 总线监控与错误保护机制；OrangePi 构建系统的脚本编排与板卡配置请参阅 构建流程与脚本编排 与 板卡配置与内核编译；RDK X5 的全量构建命令、双内核编译与 deb 管理请参阅 全量构建与子命令解析 与 Deb 包本地编译与依赖管理。此外，子模块的版本协同机制在 多仓库协同与子模块管理 中有更详细的 Git 操作说明。