atom01_firmware 是 ROBOTO_ORIGIN 人形机器人的固件及板卡镜像构建系统总仓库。它像一个"数字工厂"，将机器人底层通信、主控板操作系统、协处理器操作系统三个维度的工程代码整合在一起，通过 Git 子模块机制实现多仓库协同。对于初次接触的开发者，可以把本仓库理解为机器人"神经中枢"与"骨骼控制器"的软件源头——从 USB-CAN 通信适配器的微控制器固件，到运行在主控板上的完整 Linux 发行版镜像，所有基础软件都在这里诞生。

Sources: readme_cn.md

整体架构

本仓库采用三域架构设计，分别对应通信接口层、主控系统层和协处理系统层。这种分层让不同硬件平台可以由独立团队并行维护，同时通过统一的父仓库保证版本对齐。

graph TB
    subgraph atom01_firmware["atom01_firmware 父仓库"]
        direction TB
        A[Git 子模块管理]
    end
    
    subgraph comm["通信接口层"]
        B[roboto_usb2can<br/>USB 转 CAN 适配器固件]
    end
    
    subgraph mainctrl["主控系统层"]
        C[orangepi-build<br/>OrangePi Linux 镜像构建]
    end
    
    subgraph coproc["协处理系统层"]
        D[x5-rdk-gen<br/>RDK X5 Linux 镜像构建]
    end
    
    A --> B
    A --> C
    A --> D
    
    B -->|CAN 总线| E[机器人关节驱动器 / 传感器]
    C -->|RK3588 等 SoC| F[主控计算板]
    D -->|X5 平台| G[协处理 / AI 推理板]

上图展示了三个子模块在机器人系统中的角色划分：roboto_usb2can 是主机与 CAN 总线之间的"翻译官"，负责把 USB 数据包转成 CAN 帧；orangepi-build 为 RK 系列主控板生成定制 Linux 镜像；x5-rdk-gen 则为 RDK X5 平台提供带实时内核的 Ubuntu 系统。三者通过父仓库聚合，开发者可以一次性拉取全部源码。

Sources: readme_cn.md, .gitmodules

子系统速览

这三个子系统的构建复杂度逐级递增：USB2CAN 只需 Zephyr SDK 即可在数分钟内完成编译；OrangePi 构建需要 x86_64 宿主机和约 100GB 磁盘空间；RDK X5 镜像则涉及双内核编译、Deb 包本地构建和根文件系统组装，完整流程通常需要数小时。初学者建议从 USB2CAN 入手，逐步过渡到镜像构建。

Sources: roboto_usb2can/readme_cn.md, orangepi-build/README_CN.md, x5-rdk-gen/README_CN.md

仓库目录结构

atom01_firmware/
├── roboto_usb2can/          # USB 转 CAN 适配器固件源码
│   ├── src/                 # 主程序与 LED 控制
│   ├── boards/              # 板级设备树配置
│   ├── scripts/             # 上位机工具与 udev 规则
│   └── CMakeLists.txt       # Zephyr 构建入口
├── orangepi-build/          # OrangePi 镜像构建系统
│   ├── build.sh             # 主构建入口
│   ├── scripts/             # 编译、配置、打包脚本
│   └── external/            # 板卡配置与扩展
├── x5-rdk-gen/              # RDK X5 镜像构建系统
│   ├── build.sh             # 子命令式构建入口
│   ├── build_params/        # 桌面版/服务器版配置文件
│   ├── samplefs/            # Ubuntu rootfs 构建脚本
│   └── mk_kernel*.sh        # 标准内核 / RT 内核编译
├── readme_cn.md             # 中文总览（本文档来源）
├── readme.md                # 英文总览
└── .gitmodules              # 子模块声明

父仓库本身几乎不包含构建逻辑，真正的编译入口分散在三个子模块内部。这种设计保证了各子项目可以独立演进，同时通过 .gitmodules 锁定协作版本。

Sources: readme_cn.md

关联仓库

atom01_firmware 并非孤立存在，它是 ROBOTO_ORIGIN 生态中的基础软件层。理解它与上下游仓库的关系，有助于建立完整的开发视野：

固件与镜像工程师通常只需关注 Atom01_hardware 的接口定义，即可独立完成驱动适配；当镜像就绪后，再由 atom01_deploy 将 ROS2 节点、模型权重等上层应用注入系统。

Sources: readme_cn.md

快速开始

获取完整源码的最简单方式是使用递归克隆，因为三个子模块分别托管在独立仓库：

# 方式一：克隆时一并拉取子模块
git clone --recursive https://github.com/Roboparty/atom01_firmware.git

# 方式二：先克隆父仓库，再初始化子模块
git clone https://github.com/Roboparty/atom01_firmware.git
cd atom01_firmware
git submodule update --init --recursive

由于子模块体积较大（尤其是包含完整内核源码的 x5-rdk-gen/source/），首次同步可能需要较长时间。如果仅想查看文档或修改父仓库脚本，可以暂时跳过子模块初始化。

Sources: readme_cn.md

推荐阅读路径

如果你是第一次接触本仓库，建议按照以下顺序阅读文档，从具体到抽象、从独立到集成：

1. USB2CAN 适配器使用指南 —— 了解最轻量的固件组件，体验 Zephyr 编译与烧录流程。
2. OrangePi 镜像构建速览 —— 掌握镜像构建的基本概念，认识 Armbian 构建系统的配置与输出。
3. RDK X5 镜像构建速览 —— 深入双内核、Deb 包本地编译与根文件系统定制。
4. 深入理解各子系统 —— 在速览基础上，按需阅读 USB2CAN 固件核心、OrangePi 构建系统 或 RDK X5 镜像工程 系列文章。

这条路径遵循"先跑通一个设备，再理解整套构建系统"的认知规律，能有效降低初学者的信息过载。