# 镜像构建

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# 适用范围

本文适用于 Quectel PI RK3576 M2 板卡，项目名为 `QSM610ZAPWFPI`，以 Debian 根文件系统（`DEB`）固件为例。构建入口为 `quectel_build/compile/build.sh`，完整流程依次执行 `buildconfig`、`buildall` 和 `buildpackage`，烧录使用 SDK 根目录下的 `flash.sh`。

| **字段** | **M2 Debian 当前配置** |
| --- | --- |
| SoC | Rockchip RK3576 |
| 板型 | M2 |
| Project Name | `QSM610ZAPWFPI` |
| Build Type | `DEB` |
| Rootfs System | `debian` |
| Defconfig | `rockchip_rk3576_quectel_pi_m2_debian_defconfig` |
| Build Script | `build_quectel_pi_m2.sh` |

# 初始化构建环境

进入 RK3576 SDK 根目录，通过 `source` 加载统一构建脚本。该操作只在当前终端会话中注册构建函数；新开终端后需要重新执行。

```bash
cd ~/SMARC/RK3576_Linux6.1_BL01_v1.2.0
source quectel_build/compile/build.sh
```

加载成功后可使用以下命令：

| **命令** | **作用** |
| --- | --- |
| `buildconfig `<Project>` `<Version>` <STD\|DEB\|SEC> [SEC]` | 选择板型、根文件系统和 Secure Boot 组合并生成配置 |
| `buildall` | 根据当前配置执行完整固件编译 |
| `buildpackage` | 整理镜像并生成 Release 与 Factory 目录 |
| `buildconfig_verify` | 查看当前已生效的构建配置 |

M2 支持的主要组合如下：

| **参数** | **根文件系统** | **说明** |
| --- | --- | --- |
| `STD` | Buildroot | 使用 `quectel_pi_m2_rk3576_v0_defconfig` |
| `DEB` | Debian | 本文采用的普通 Debian 构建 |
| `SEC` | Debian | M2 单独传入 SEC 时等价于 Debian + Secure Boot 签名 |
| `DEB SEC` | Debian | 显式指定 Debian + Secure Boot 签名 |

# 配置 M2 Debian 固件

当前 M2 Debian 镜像使用以下配置命令：

```bash
buildconfig QSM610ZAPWFPI QSM610ZAPWFRD1A01_BD01BP01K0M01_QDP_LP6.1.118.01.001 DEB
```

配置成功后，脚本会识别板型与构建类型，生成 `quectel_build/config/quectel-buildconfig-gen.h` 和 `quectel_build/config/buildconfig.sh`。本次实测关键输出如下：

```
Project Name     = QSM610ZAPWFPI
Firmware Version = QSM610ZAPWFRD1A01_BD01BP01K0M01_QDP_LP6.1.118.01.001
Board            = M2
Build Type       = DEB
Defconfig        = rockchip_rk3576_quectel_pi_m2_debian_defconfig
Rootfs System    = debian
Build Script     = build_quectel_pi_m2.sh
Git Commit       = d97cfde78
```

需要复核配置时执行：

```bash
buildconfig_verify
```

# 整编固件

完成 `buildconfig` 后执行：

```bash
buildall
```

`buildall` 会先应用 M2 Debian defconfig，检查 Debian 构建前置条件，再执行完整镜像构建。构建成功后，中间产物位于 SDK 的 `rockdev/` 和 `output/` 等目录。完整编译耗时取决于主机性能和缓存状态。

# 打包固件

整编成功后执行：

```bash
buildpackage
```

打包前脚本会检查 `output/update/Image/update.img` 是否存在，以及 `rockdev/` 中是否有更新的分量镜像；如 `update.img` 缺失或已过期，会先重新生成。当前版本会在 `quectel_build/` 下生成两个同级目录：

| **输出目录** | **用途** |
| --- | --- |
| `QSM610ZAPWFRD1A01_BD01BP01K0M01_QDP_LP6.1.118.01.001/` | Release 发布包，不包含 `persist.img`、`nvdata1.img`、`nvdata2.img` |

打包内容来自 `rockdev/`、`output/update/Image/update.img` 和 `output/`。常见文件包括 `update.img`、`MiniLoaderAll.bin`、`uboot.img`、`boot.img`、`rootfs.img`、`parameter.txt`、`misc.img`、`recovery.img`、`oem.img` 和 `userdata.img`；实际文件集合以本次构建输出为准。

# 烧录 M2 固件

## Windows 烧录工具与 USB 驱动

在 Windows 主机上烧录 M2 固件时，可下载并使用以下工具。建议先安装 Rockchip USB 驱动，再连接设备并使用 RKDevTool 识别 Loader/MASKROM 设备和烧录镜像。

| **资源** | **用途** | **下载** |
| --- | --- | --- |
| `RKDevTool_zh.zip` | Windows 图形化烧录工具，用于识别 RK3576 Loader/MASKROM 设备并执行镜像烧录 | [下载 RKDevTool 中文版](<https://www.quectel.com.cn/wp-content/uploads/2026/08/RKDevTool_zh.zip>) |
| `DriverAssitant_v5.13.zip` | Rockchip USB 驱动安装工具，使 Windows 能正确识别 Loader/MASKROM 模式设备 | [下载 DriverAssitant v5.13](<https://www.quectel.com.cn/wp-content/uploads/2026/08/DriverAssitant_v5.13.zip>) |

**推荐顺序：** 解压并安装 `DriverAssitant_v5.13` 中的驱动，连接 M2 并进入 Loader 或 MASKROM 模式；确认 Windows 设备已被识别后，再打开 RKDevTool 选择对应固件进行烧录。Linux 主机仍可继续使用 SDK 自带的 `flash.sh` 和 `upgrade_tool` 流程。

确认 SDK 根目录中的 `tools/linux/Linux_Upgrade_Tool/Linux_Upgrade_Tool/upgrade_tool`、`rockdev/MiniLoaderAll.bin` 和待烧录的 `update.img` 已就绪，然后执行：

```bash
./flash.sh
```

默认烧录流程如下：

1. 检查 `update.img` 与分量镜像时间戳；仅在固件缺失或较旧时重新打包。

2. 尝试从固件 DTB 和 ADB 在线设备读取 compatible 信息，防止 SMARC 与 M2 固件混刷。

3. 检测 Loader 或 MASKROM 设备；若系统处于 ADB 在线状态，自动执行 `adb reboot loader`。

4. MASKROM 模式下先下载 Loader，Loader 模式下直接继续。

5. 调用 `upgrade_tool UF` 烧录完整 `update.img`。

6. 调用 `upgrade_tool RD` 请求设备重启。

`flash.sh` 支持以下参数：

| **参数** | **作用** |
| --- | --- |
| 无参数 | 按时间戳判断是否需要重新打包，然后烧录 |
| `-f` | 强制重新打包 `update.img` 后烧录 |
| `-n` | 跳过打包，直接烧录已有 `update.img` |
| `-e` | 烧录前擦除 Flash |
| `-y` | 跳过板型校验，仅在已人工确认固件与板卡完全匹配时使用 |
| `-h` | 显示帮助 |

# 推荐执行顺序

```bash
cd ~/SMARC/RK3576_Linux6.1_BL01_v1.2.0
source quectel_build/compile/build.sh
buildconfig QSM610ZAPWFPI QSM610ZAPWFRD1A01_BD01BP01K0M01_QDP_LP6.1.118.01.001 DEB
buildconfig_verify
buildall
buildpackage
./flash.sh
```

构建、打包和烧录必须按顺序执行。切换 Project、Firmware Version 或构建类型后，应重新运行 `buildconfig`，不要沿用旧的 `quectel_build/config/buildconfig.sh`。