本项目的主控板支持 Orange Pi 5 Plus（RK3588）与 RDK X5 两种硬件平台，分别对应 orangepi-build 与 x5-rdk-gen 两套镜像构建系统。前者基于 Armbian 构建框架，为 Orange Pi 系列板卡生成定制化 Linux 发行版；后者面向 D-Robotics RDK X5，通过 repo 管理内核、Bootloader 及官方 deb 包源码，一键输出带 RT 实时内核的 Ubuntu 22.04 镜像。完成镜像构建后，需将生成的 .img 文件烧录至 MicroSD 卡或板载存储，方可启动机器人主控系统。本文档面向高级开发者，系统阐述两套构建系统的工作流、关键配置与烧录方法，并给出故障排查指南。

Sources: readme_cn.md, README_CN.md, README_CN.md

硬件平台与镜像架构概览

首先对两款主控板的构建产出进行横向对比。Orange Pi 5 Plus 采用瑞芯微 RK3588 SoC，构建系统为 orangepi-build，默认支持 legacy（5.10）与 current（6.1）双内核分支，镜像输出位于 output/images/；RDK X5 采用 D-Robotics 自研 X5 芯片，构建系统为 x5-rdk-gen，默认同时编译标准内核 6.1.83 与 RT 内核 6.1.83-rt28，最终镜像输出至 deploy/ 目录。下表汇总了核心差异：

Sources: README_CN.md, README_CN.md, rockchip-rk3588.conf

整个镜像构建与烧录的宏观流程可由以下架构图表示。开发者主机运行 Ubuntu 22.04 x86_64，通过两套独立构建系统分别生成对应板卡的系统镜像，再借助通用烧录工具写入 MicroSD 卡，最终完成主控板上电启动。

graph TD
    A[开发者主机<br>Ubuntu 22.04 x86_64] -->|orangepi-build| B[Orange Pi 5 Plus 镜像<br>output/images/xxx.img]
    A -->|x5-rdk-gen| C[RDK X5 镜像<br>deploy/rdk-x5-ubuntu22-xxx.img]
    B --> D[BalenaEtcher / dd<br>烧录至 MicroSD]
    C --> D
    D --> E[主控板启动<br>进入 Ubuntu 22.04]

Sources: general.sh, build.sh

构建环境准备

无论使用哪套构建系统，主机环境均需满足以下基线：操作系统为 Ubuntu 22.04（Jammy）x86_64，具备 root/sudo 权限，建议预留 100 GB 以上可用磁盘空间（orangepi-build 因需缓存大量源码与交叉编译工具链，空间消耗更大），并确保网络可访问 Ubuntu 官方源、GitHub 及清华镜像。x5-rdk-gen 的 build.sh setup 子命令会自动安装 build-essential、debootstrap、qemu-user-static、apt-cacher-ng 等依赖，并下载 /opt/gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu 交叉编译工具链；orangepi-build 则在首次执行 ./build.sh 时通过 prepare_host_basic 函数检测并补全缺失工具。

Sources: README_CN.md, build.sh, build.sh

Orange Pi 5 Plus 镜像构建

进入 modules/atom01_firmware/orangepi-build 目录后，执行 ./build.sh 即可启动交互式构建向导。脚本首先提示选择板卡，对于 Atom01 机器人主控，应选择 robopi1（对应 Orange Pi 5 Plus 硬件变体）；若使用其他衍生板卡，可选择 robopi2（RK3588S CM5）或 robopi3。随后选择内核分支，项目推荐 current，以获取较新的内核特性与驱动支持。构建过程由 scripts/main.sh 统一编排，依次完成 U-Boot 编译、内核编译、rootfs debootstrap、软件包安装及镜像打包，最终产物为 output/images/ 下的 .img 文件。

Sources: README_CN.md, build.sh

若需启用实时内核，有两种技术路线。其一，在 external/config/templates/config-robopi1.conf 中将 build_rt_image 设为 "yes" 并选择 legacy 分支，此时构建系统会拉取 orange-pi-5.10-rk35xx-rt 内核源码并打包 RT 镜像；其二（项目推荐路线），先构建普通镜像，烧录启动后，再通过 atom01_deploy/assets/ 目录下的 linux-image-legacy-rockchip-rk3588_1.2.0_arm64.deb 等三个 deb 包安装 5.10 实时内核。后者更便于快速迭代，且已在部署框架中得到充分验证。

Sources: config-robopi1.conf, rockchip-rk3588.conf, README_CN.md

以下 Mermaid 流程图展示了 Orange Pi 5 Plus 的完整构建路径，从执行构建脚本到最终生成镜像文件，各阶段环环相扣：

flowchart LR
    A[./build.sh] --> B{选择板卡}
    B -->|robopi1| C[选择分支 current]
    C --> D[编译 U-Boot & 内核]
    D --> E[debootstrap rootfs]
    E --> F[安装 BSP 包与配置]
    F --> G[生成 output/images/xxx.img]

Sources: README_CN.md, debootstrap.sh

RDK X5 镜像构建

RDK X5 的构建入口为 modules/atom01_firmware/x5-rdk-gen/build.sh，采用子命令式驱动，支持全量构建与分步调试。最简用法为 sudo ./build.sh all，该命令依次执行 setup（环境初始化）、kernel（标准内核 + RT 内核）、bootloader（miniboot/uboot/nand_disk.img）、rootfs（Ubuntu samplefs）、debs（本地编译 17 个官方 deb 包）及 pack（分区、写入、生成 .img）。若已构建过 rootfs 且仅修改内核或软件包，可使用 sudo ./build.sh image 跳过环境与 rootfs 阶段，显著缩短迭代周期。

Sources: README_CN.md, build.sh

构建行为由 build_params/ 目录下的 .conf 文件控制，默认使用 ubuntu-22.04_desktop_rdk-x5_release.conf。该配置文件定义了镜像名称、Ubuntu 版本（Jammy）、samplefs 下载地址、预装 deb 包列表及 rootfs 目录。切换为 Server 版本或 Beta 通道时，只需通过 -c 参数指定对应配置即可，例如 sudo ./build.sh pack -c build_params/ubuntu-22.04_server_rdk-x5_release.conf。

Sources: build_params/ubuntu-22.04_desktop_rdk-x5_release.conf, README_CN.md

pack_image.sh 是镜像生成的核心脚本，其工作流程如下：首先解压 rootfs/samplefs*.tar.gz 到 deploy/rootfs/，随后调用 hobot_customize_rootfs.sh 完成主机名、SSH、NetworkManager、用户创建（默认用户 sunrise）等系统定制；接着合并安装 deb_packages/（官方预编译包）、third_packages/（用户自定义包）及 deploy/deb_pkgs/（本地编译包）中的所有 .deb；最后生成指向 Image-rt 的 boot.scr，创建分区表并写入 .img 文件。

Sources: pack_image.sh, hobot_customize_rootfs.sh, README_CN.md

RDK X5 构建流程的 Mermaid 时序图如下，展示了从开发者调用 build.sh all 到最终获得 .img 的完整调用链：

sequenceDiagram
    participant U as 开发者
    participant B as build.sh
    participant K as mk_kernel.sh
    participant D as mk_debs.sh
    participant P as pack_image.sh
    U->>B: sudo ./build.sh all
    B->>B: setup (依赖+工具链+repo sync)
    B->>K: kernel (Image + Image-rt)
    B->>B: bootloader (nand_disk.img)
    B->>B: rootfs (samplefs)
    B->>D: debs (17 packages)
    B->>P: pack (-l -c conf)
    P->>P: customize rootfs
    P->>P: install debs
    P->>P: create .img
    P-->>U: deploy/*.img

Sources: build.sh, README_CN.md

镜像烧录方法

构建完成后，得到的 .img 文件需写入启动介质。对于 Orange Pi 5 Plus 与 RDK X5，最通用的方式是通过 MicroSD 卡启动。orangepi-build 的构建脚本在日志末尾明确列出了四种烧录命令，其中推荐开发者使用 BalenaEtcher（跨平台图形工具）或 Linux 下的 dd 命令：对于压缩镜像可执行 zcat xxx.img.gz | pv | dd of=/dev/sdX bs=1M，对于未压缩镜像则执行 dd if=xxx.img of=/dev/sdX bs=1M。务必正确识别目标块设备（如 /dev/sdX），避免误写主机硬盘。

Sources: general.sh

Orange Pi 5 Plus 的详细烧录步骤亦可参考随仓库提供的官方用户手册 PDF《OrangePi_5_Plus_RK3588_用户手册_v2.1.pdf》第 118 页，该文档介绍了通过 SD 卡升级、Maskrom 模式烧录 eMMC 等多种方式。RDK X5 的镜像烧录方式与常规嵌入式板卡一致：将 .img 写入 MicroSD 卡后插入主板即可启动；若需烧录至板载 eMMC 或 NAND，请参阅 D-Robotics 官方硬件手册，通常需要配合 miniboot 与专用烧录工具完成。

Sources: README.md, README_CN.md

烧录完成后，将 MicroSD 卡插入主控板并上电。Orange Pi 5 Plus 默认用户名为 orangepi，RDK X5 默认用户名为 sunrise。首次启动建议通过串口或 HDMI 显示器确认内核日志无异常，随后检查网络接口与 SSH 服务是否正常，以便进行后续的 ROS2 部署与实时内核配置。

Sources: hobot_customize_rootfs.sh, README_CN.md, README_CN.md

构建流程深度解析

为了帮助高级开发者进行深度定制，本节对两套构建系统的内部阶段进行拆解。orangepi-build 属于 Armbian 衍生框架，其构建阶段可概括为：主机环境检查 → 板级配置加载（external/config/boards/robopi1.conf） → 内核与 U-Boot 源码下载/编译 → rootfs debootstrap（scripts/debootstrap.sh） → 软件包与 BSP 补丁注入 → 镜像分区与写入（scripts/debootstrap.sh 尾部调用 dd/parted 逻辑）。其中，板级设备树补丁存放在 external/patch/ 目录，例如 rk3588-orangepi-5-plus-robopi1.dts 关闭了部分未使用的 CAN、UART、PWM 节点，并启用了风扇 PWM 与 SPI Flash 分区，开发者可直接修改该文件以调整硬件使能状态。

Sources: build.sh, debootstrap.sh, rk3588-orangepi-5-plus-robopi1.dts

x5-rdk-gen 的构建粒度更细，且将源码与构建产物分离。source/ 目录通过 repo sync 拉取，包含 kernel/、kernel-rt/、bootloader/ 及各 hobot-* 软件包源码。mk_kernel.sh 与 mk_kernel_rt.sh 分别输出标准内核与 RT 内核到 deploy/kernel/；mk_debs.sh 依赖该目录下的 Image、dtb、modules 及 kernel_headers 来打包 hobot-boot、hobot-dtb、hobot-kernel-headers 等 deb；pack_image.sh 则负责最终集成。这种分层设计使得“仅修改内核配置后重新打包镜像”的迭代可在 10 分钟内完成，无需重复构建 rootfs。

Sources: mk_kernel.sh, READMErdk_CN.md, pack_image.sh

定制化与扩展

高级开发者往往需要在官方镜像基础上预装自定义软件或修改系统配置。x5-rdk-gen 提供了两条扩展路径：一是将外部 .deb 包放入 third_packages/ 目录，pack_image.sh 会自动识别并安装该目录下所有 deb，无需修改配置文件；二是直接编辑 hobot_customize_rootfs.sh，在 rootfs 解压后、deb 安装前插入自定义逻辑，例如修改默认密码、注入自启动服务或调整网络策略。需要特别注意的是，pack_image.sh 会合并 deb_packages/、third_packages/ 与 deploy/deb_pkgs/ 三个目录的全部 deb，同名包保留最新版本，若需排除某个包，必须将其从对应目录物理移除。

Sources: README_CN.md, hobot_customize_rootfs.sh

对于 Orange Pi 5 Plus，硬件层面的定制主要通过设备树（Device Tree）实现。external/patch/rk3588-orangepi-5-plus-robopi1.dts 在官方 rk3588-orangepi-5-plus.dtsi 基础上进行了板级裁剪：禁用了未使用的 can0、can1、pwm0/1/14 等节点以释放 GPIO，启用了 pwm-fan 温控风扇与 spi_flash 分区。若机器人后续迭代需要复用这些接口，开发者应在此 DTS 中将对应节点的 status 改为 "okay"，并重新编译内核与设备树。

Sources: rk3588-orangepi-5-plus-robopi1.dts

常见问题与排查

下表汇总了镜像构建与烧录过程中高频出现的问题及其根因与解决方案：

Sources: README_CN.md, build.sh

下一步

完成镜像烧录并确认主控板正常启动后，建议按照以下顺序继续后续工作：

1. 若使用 Orange Pi 5 Plus，请先安装实时内核 deb 包并配置 limits.conf，详情参见 部署架构与实时内核配置。
2. 若使用 RDK X5，镜像已内置 RT 内核，可直接进入 ROS2 环境搭建与传感器驱动集成阶段。
3. 在主控板系统就绪后，回到固件层面完成 USB2CAN 适配器的烧录与验证，参见 USB2CAN适配器固件开发。