本页面向初次接触 ROBOTO_ORIGIN 固件模块的开发者，提供仓库整体结构的鸟瞰视图、环境准备步骤，以及三个子模块的最快上手路径。阅读完本文后，你将能够克隆完整仓库、理解各模块的职责边界，并执行第一个构建或烧录命令。

仓库架构概览

atom01_firmware 是一个多仓库协同的固件聚合模块，内部通过 Git 子模块管理三个独立演进的项目：面向通信接口的 roboto_usb2can、面向主控板卡的 orangepi-build，以及面向机器人计算平台的 x5-rdk-gen。三者在物理上解耦，在功能上形成从底层总线适配到上层系统镜像的完整工具链。下图中，开发者工作站作为统一的构建入口，根据目标硬件的不同，分别流向 Zephyr 固件编译、OrangePi 镜像构建或 RDK X5 系统生成三条产出管线。

graph TB
    A[开发者工作站<br/>Ubuntu 22.04 x86_64] --> B[roboto_usb2can]
    A --> C[orangepi-build]
    A --> D[x5-rdk-gen]
    B --> B1[Zephyr RTOS 固件<br/>STM32G431]
    C --> C1[OrangePi Linux 镜像<br/>RK3588 等]
    D --> D1[RDK X5 Ubuntu 镜像<br/>双内核 + Deb 包]

Sources: readme_cn.md, .gitmodules

环境准备：克隆仓库

由于本仓库使用 Git 子模块引用外部项目，首次克隆时必须携带 --recursive 参数，否则子模块目录将为空。

git clone --recursive https://github.com/Roboparty/atom01_firmware.git
cd atom01_firmware

如果已经以普通方式克隆，可通过以下命令补全子模块：

git submodule update --init --recursive

当前仓库包含的子模块定义如下：

Sources: readme_cn.md, .gitmodules

项目目录结构

克隆完成后，你的工作区将呈现如下目录布局。建议初学者先熟悉一级目录的边界，再按需深入具体子模块。

atom01_firmware/
├── .gitmodules              # 子模块配置
├── readme.md                # 英文总览
├── readme_cn.md             # 中文总览
├── roboto_usb2can/          # USB2CAN 固件（Zephyr RTOS）
│   ├── west.yml             # West 工作区清单
│   ├── CMakeLists.txt       # Zephyr 应用构建配置
│   ├── boards/              # 板级设备树与引脚配置
│   ├── src/                 # 固件源码（main.c / led.c）
│   └── scripts/             # 上位机工具与测试脚本
├── orangepi-build/          # OrangePi 镜像构建系统
│   ├── build.sh             # 主构建入口（交互式菜单）
│   ├── scripts/             # 编译、打包、配置脚本
│   └── external/            # 板卡配置与扩展
└── x5-rdk-gen/              # RDK X5 镜像构建系统
    ├── build.sh             # 子命令式构建入口
    ├── build_params/        # 构建配置文件（desktop/server）
    ├── mk_kernel.sh         # 标准内核编译
    ├── mk_kernel_rt.sh      # RT 实时内核编译
    └── samplefs/            # Ubuntu rootfs 构建目录

Sources: readme_cn.md

子模块快速上手路径

以下分三条并行路径介绍各子模块的最快启动方式。你可以根据当前手头的硬件与开发任务，选择对应的路径切入。

路径 A：USB2CAN 固件（无需编译，直接烧录）

如果你手头已有 roboto_usb2can 硬件，最快的方式是下载预编译固件并直接烧录，无需搭建 Zephyr 编译环境。前往该子模块的 Release 页面下载 roboto_usb2can_xxx.bin，随后使用 STM32CubeProgrammer 或 west flash 完成烧录。若你希望从源码编译，需先安装 Zephyr SDK，并将本项目置于 Zephyr 的 samples/ 目录下，配置好包含 cannectivity 模块的 West 工作区后，执行 west build -b roboto_usb2can 即可完成编译。

Sources: roboto_usb2can/readme_cn.md, roboto_usb2can/west.yml

路径 B：OrangePi 镜像构建（交互式菜单）

orangepi-build 采用交互式菜单驱动，只需运行主脚本并按提示选择板卡与目标即可。脚本启动后会依次引导你选择目标板卡（固件 01/02/03 分别对应 robopi1 / robopi2 / robopi3）、内核分支及镜像类型，随后自动完成内核编译、rootfs 构建与镜像打包。该构建系统底层由 scripts/main.sh 进行任务编排，scripts/compilation.sh 负责核心编译逻辑。

cd orangepi-build
./build.sh

Sources: orangepi-build/README_CN.md, orangepi-build/build.sh

路径 C：RDK X5 镜像构建（子命令式流程）

x5-rdk-gen 采用子命令式设计，支持一键全量构建与分步执行两种模式。首次构建推荐运行全量命令 sudo ./build.sh all，该命令将自动完成环境初始化、标准内核与 RT 实时内核编译、Bootloader 构建、Ubuntu rootfs 生成、本地 deb 包编译及最终镜像打包。如果你只想在已有 rootfs 的基础上快速重建镜像，可使用 sudo ./build.sh image 跳过 rootfs 构建步骤。

各子命令的对应关系如下：

Sources: x5-rdk-gen/README_CN.md, x5-rdk-gen/build.sh

快速开始流程图

下图展示了从克隆仓库到产出构建成果的完整决策路径，帮助你根据目标硬件快速定位应执行的命令。

flowchart TD
    A[克隆仓库<br/>git clone --recursive] --> B{目标硬件?}
    B -->|USB2CAN 适配器| C[下载 bin 固件<br/>或 west build -b roboto_usb2can]
    B -->|OrangePi 板卡| D[cd orangepi-build<br/>./build.sh]
    B -->|RDK X5 平台| E[cd x5-rdk-gen<br/>sudo ./build.sh all]
    C --> F[west flash 烧录]
    D --> G[选择板卡与镜像类型<br/>自动构建]
    E --> H[生成 .img 镜像文件]

Sources: readme_cn.md

系统要求速查

在深入各子模块之前，请确认你的开发工作站满足以下基本要求：

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

下一步阅读建议

完成环境准备并执行第一条构建命令后，你可以根据兴趣沿着以下路径继续深入：

• 若正在调试机器人 CAN 总线通信，请继续阅读 USB2CAN 适配器使用指南，了解 LED 状态含义、SocketCAN 配置及上位机工具用法。
• 若需要定制 OrangePi 板卡镜像，请前往 OrangePi 镜像构建速览，掌握板卡配置、内核参数调整与扩展机制。
• 若负责 RDK X5 计算平台的系统定制，请阅读 RDK X5 镜像构建速览，理解双内核编译、deb 包管理与镜像打包流程。
• 若希望从源码层面理解 USB2CAN 固件的实现细节，可深入 USB2CAN 固件核心 系列章节，从 硬件架构与接口规范 开始。