Flash 烧写工具（1 拖 N）（跨平台）

资源

下载

概述

AmebaFlash 是面向 Realtek Ameba 系列 SoC 开发的跨平台量产烧录工具，支持通过 LOGUART/USB 接口同时烧录多台 Ameba 设备。工具同时提供命令行模式与图形界面模式。

功能	说明
1 拖 N 固件烧录	向 NOR Flash、NAND Flash 或 RAM 烧写单个或多个二进制固件，指定 N (N >= 1)个串口，同时烧录 N 台设备。
Flash 擦除	擦除指定地址范围（命令行模式支持）或整片 Flash。
WiFi MAC 读取	无需完整烧录流程，直接读取设备 WiFi MAC 地址（命令行模式支持）。

备注

1 拖 N 并行烧录功能自 v1.1.0 起支持。

软件环境

Flash 烧写工具支持以下操作系统：

Windows 7 及更高版本
Ubuntu 及其他 Linux 发行版

工具及其支持文件位于 SDK 目录结构中。

文件	位置	说明
`AmebaFlash.py`	`{SDK}/tools/ameba/Flash/AmebaFlash.py`	基于 Python 的跨平台命令行工具。需要 Python 3.8+ 及 `{SDK}/tools/requirements.txt`中的依赖库。运行方式：`AmebaFlash.py <参数>`。
`AmebaMPFlashGUI.py`	`{SDK}/tools/ameba/Flash/AmebaMPFlashGUI.py`	基于 Python 的跨平台图形界面工具，依赖库安装需求同上。运行方式：`AmebaMPFlashGUI.py`。
`AmebaFlash.exe`	`{SDK}/tools/ameba/Flash/dist/AmebaFlash.exe`	Windows 独立可执行文件，无需安装 Python。由 PyInstaller（`--onefile` 模式）打包，首次启动因运行时解压到临时目录可能较慢。
`AmebaMPFlashGUI.exe`	`{SDK}/tools/ameba/Flash/dist/AmebaMPFlashGUI.exe`	图形界面版 Windows 独立可执行文件，无需安装 Python。由 PyInstaller 打包，首次启动因运行时解压到临时目录可能较慢。
设备 Profile 文件（`.rdev` 文件）	`{SDK}/tools/ameba/Flash/Devices/Profiles/`	各芯片型号的设备配置文件，定义 Flash 布局、固件地址、波特率等参数，通过 `--profile` 指定。

安装 Python 依赖（仅 AmebaFlash.py / AmebaMPFlashGUI.py 需要）：

pip3 install -r {SDK}/tools/requirements.txt

备注

本文档中使用 ``{AmebaFlash}`` 作为 {SDK}/tools/ameba/Flash/ 的简写。
使用 LOGUART 模式烧录前，需在主机上安装 USB 转串口适配器驱动（如 PL2303GC），请从适配器厂商官网获取驱动。
请勿随意修改或删除 Devices/Floaders/ 目录中的 floader_ameba*.bin 文件，它们是工具与设备通信所需的 Flashloader 文件。
对于支持 USB 下载的设备（如 RTL8721Dx、RTL8730E），仅在 Windows 7 上需要安装 USB CDC-ACM 驱动。驱动位于 {SDK}/tools/ameba/ImageTool/RtkUsbCdcAcmSetup.INF。

硬件环境

硬件设置：各型号可支持的烧录端口可参考下载方式，接线拓扑请参考硬件设置。
进入烧录模式：请参考设备进入烧录模式。
自动烧录方案: 产线如果有自动烧录设计需求，请参考自动烧录方案。

命令行模式

Flash 烧录

命令行烧录只需执行一条下载命令，工具即自动完成设备检测、Flashloader 加载、固件烧写与校验等流程，将固件烧录到目标设备的 Flash 或 RAM 中，全程无需手动干预。该方式便于集成到实际使用环境的自动化流程（如产线批量烧录、CI/CD 自动烧录）中。

命令格式

AmebaFlash.py --download --baudrate <波特率> --profile <profile> --port <端口> \
    (--image <固件> --start-address <起始地址> [--end-address <结束地址>] | --image-dir <固件目录>) [--chip-erase]

必选参数

以下参数在烧录、擦除和 WiFi MAC 读取操作中均为必选。

-b / --baudrate <value>

设置串口通信波特率。

--baudrate 1500000

支持的波特率： 115200, 128000, 153600, 230400, 380400, 460800, 500000, 921600, 1000000, 1382400, 1444400, 1500000, 2000000, 3000000

-f / --profile <path>

设备配置文件（.rdev 格式）路径。Profile 文件定义了目标芯片的参数，包括 Flash 布局、存储配置和握手波特率等。

Profile 文件位于工具目录下的 Devices/Profiles/ 文件夹。

--profile Devices/Profiles/RTL8721Dx.rdev

-p / --port <port1> [port2 ...]

目标板的串口号。指定多个串口可启用 1 拖 N 并行烧录（v1.1.0 起支持）。

--port COM3                    # 单设备
--port COM3 COM4 COM5          # 1 拖 3 并行

小技巧

在 Linux 上，可使用 ls /dev/tty* 查看可用串口。

固件来源

烧录工具支持两种固件来源，分别对应 合并 image 与 分离 image 两种烧录方式。二者通过 --image 和 --image-dir 两个互斥参数选择，每次烧录只能使用其中之一。

两种方式的烧录结果一致，区别在于参数、使用场景与灵活性，可参考下表按需选择：

固件来源	分离 image	合并 image
参数	`-r` / `--image-dir <directory>`	`-i` / `--image <path>` `-a` / `--start-address <hex>` `-n` / `--end-address <hex>`（仅 NAND flash 烧录时必需）
说明	指定包含所有固件文件的目录路径。工具按 Profile 中预定义的固件布局自动匹配文件名，并依次烧录到各自地址，无需手动指定地址。	将编译产物中已合并所有分区的单个固件（如 `image_all.bin`）烧录到 `--start-address` 指定的起始地址；地址需与该合并固件的预期基地址一致。
优点	地址由 Profile 自动匹配，无需手动指定；可直接与 SDK 编译固件对接，无需合并，灵活更新或替换单个分区，便于开发调试。	仅需一个文件，命令简单；适合量产烧录、整机出厂与版本固化等需要固定整片固件的场景。
缺点	依赖目录内文件名与 Profile 严格匹配；如果单个分区固件有更新需单独烧录，则需编辑 Profile 指定只烧录该分区，配置相对繁琐。	需手动指定起始地址（`--start-address`）； NAND flash 还需指定结束地址（`--end-address`）。

备注

使用 --image-dir 时，目录中的文件名必须与 Profile 中预定义的固件名称完全一致。

Linux *.dtb 文件除外，但是指定目录中仅允许存在一个 .dtb 文件。

小技巧

量产与整机出厂烧录推荐使用 合并 image，流程固定、不易出错。
开发调试或仅更新部分分区时推荐使用 分离 image，无需关心各分区地址。

备注

使用 合并 image 方式（--image）烧录时，可启用 SplitSingleImageByLayout 跳过合并固件中无实际意义的 0xFF 填充以节省烧录时间；烧录 NAND Flash 时必须启用该功能。详见按 Profile 布局拆分单固件。

启用该功能时，请 务必选用与合并固件（如 image_all.bin）实际布局一致的 Profile (不一定是官方自带的默认 Profile)。工具会依据所选 Profile 的分区对合并固件进行切分；若 Profile 布局与固件合并时的分区布局不一致，将导致切分边界错位、烧录数据错误。

烧录命令示例

配置好所有必选参数后，追加 --download/-d 即可触发烧录，该参数无需跟随任何值。

单个固件示例：

AmebaFlash.py --download \
    --baudrate 1500000 \
    --profile Devices/Profiles/RTL8721Dx.rdev \
    --image D:/Images/image_dp/image_all.bin \
    --start-address 0x08000000 \
    --port COM3

[2026-07-07 16:28:47.929][I] [main]AmebaFlash Version: 1.1.8.1
[2026-07-07 16:28:47.929][I] [main]Settings path: E:\git_repo\meta_tools\flash1\Settings.json
[2026-07-07 16:28:47.930][I] [main]Device profile: .\Devices\Profiles\RTL8721Dx.rdev
[2026-07-07 16:28:47.966][I] [main]Device profile .\Devices\Profiles\RTL8721Dx.rdev loaded
[2026-07-07 16:28:47.966][I] [main]Memory type derived from device profile: 1
[2026-07-07 16:28:47.966][I] [main]Serial port: ['COM3']
[2026-07-07 16:28:47.967][I] [main]Baudrate: 1500000
[2026-07-07 16:28:47.967][I] [main]Image info:
[2026-07-07 16:28:47.967][I] [main]> Image: D:\Images\image_dp\image_all.bin
[2026-07-07 16:28:47.967][I] [main]> StartAddress: 134217728
[2026-07-07 16:28:47.968][I] [main]> EndAddress: 136314880
[2026-07-07 16:28:47.968][I] [main]> MemoryType: 1
[2026-07-07 16:28:47.968][I] [main]> FullErase: False
[2026-07-07 16:28:47.968][I] [main]> Mandatory: True
[2026-07-07 16:28:47.968][I] [main]> Description: image_all.bin
[2026-07-07 16:28:47.968][I] [main]Chip erase: False
[2026-07-07 16:28:47.969][I] [main]Settings path: E:\git_repo\meta_tools\flash1\Settings.json
[2026-07-07 16:28:48.134][I] [COM3]Check supported flash size...
[2026-07-07 16:28:48.697][I] [COM3]Current supported flash size >16MB
[2026-07-07 16:28:48.697][I] [COM3]Device info:
[2026-07-07 16:28:48.697][I] [COM3]* DID: 0x6845
[2026-07-07 16:28:48.698][I] [COM3]* ImageType: 0x0001
[2026-07-07 16:28:48.698][I] [COM3]* CmdSetVersion: 2.0
[2026-07-07 16:28:48.698][I] [COM3]* MemoryType: NOR
[2026-07-07 16:28:48.698][I] [COM3]* FlashMID: C8
[2026-07-07 16:28:48.698][I] [COM3]* FlashDID: 0x4019
[2026-07-07 16:28:48.699][I] [COM3]* FlashCapacity: 256Mb/32MB
[2026-07-07 16:28:48.699][I] [COM3]* FlashPageSize: 1024B
[2026-07-07 16:28:48.699][I] [COM3]* WiFiMAC: 00:E0:4C:00:0C:24
[2026-07-07 16:28:48.700][I] [COM3]Image download start...
[2026-07-07 16:28:48.794][I] [COM3]image_all.bin [0x08000000-0x08014000] download...
[2026-07-07 16:28:48.820][I] [COM3]Programming progress: 10%
[2026-07-07 16:28:48.845][I] [COM3]Programming progress: 20%
[2026-07-07 16:28:48.871][I] [COM3]Programming progress: 31%
[2026-07-07 16:28:48.896][I] [COM3]Programming progress: 41%
[2026-07-07 16:28:48.921][I] [COM3]Programming progress: 51%
[2026-07-07 16:28:48.947][I] [COM3]Programming progress: 62%
[2026-07-07 16:28:48.973][I] [COM3]Programming progress: 72%
[2026-07-07 16:28:48.999][I] [COM3]Programming progress: 82%
[2026-07-07 16:28:49.024][I] [COM3]Programming progress: 93%
[2026-07-07 16:28:49.058][I] [COM3]Programming progress: 100%
[2026-07-07 16:28:49.059][I] [COM3]image_all.bin [0x08000000-0x08014000] download done: 29KB / 263.0ms / 903.0Kbps
[2026-07-07 16:28:49.075][I] [COM3]Checksum OK: 0xd6c9e1c6
[2026-07-07 16:28:49.077][I] [COM3]image_all.bin [0x08014000-0x08200000] download...
[2026-07-07 16:28:49.758][I] [COM3]Programming progress: 10%
[2026-07-07 16:28:50.436][I] [COM3]Programming progress: 20%
[2026-07-07 16:28:51.116][I] [COM3]Programming progress: 30%
[2026-07-07 16:28:51.792][I] [COM3]Programming progress: 40%
[2026-07-07 16:28:52.464][I] [COM3]Programming progress: 50%
[2026-07-07 16:28:53.139][I] [COM3]Programming progress: 60%
[2026-07-07 16:28:53.820][I] [COM3]Programming progress: 70%
[2026-07-07 16:28:54.502][I] [COM3]Programming progress: 80%
[2026-07-07 16:28:55.176][I] [COM3]Programming progress: 90%
[2026-07-07 16:28:55.866][I] [COM3]Programming progress: 100%
[2026-07-07 16:28:55.866][I] [COM3]image_all.bin [0x08014000-0x08200000] download done: 860KB / 6789.0ms / 1037.0Kbps
[2026-07-07 16:28:56.310][I] [COM3]Checksum OK: 0x313ae2a2
[2026-07-07 16:28:56.315][I] [COM3]All images download done
[2026-07-07 16:28:56.517][I] [COM3]close COM3...
[2026-07-07 16:28:56.587][I] [COM3]COM3 closed.
[2026-07-07 16:28:56.588][I] [COM3]Finished PASS
[2026-07-07 16:28:56.588][I] [main]All flash threads have completed

多个固件示例：

AmebaFlash.py --download \
        --baudrate 1500000 \
        --profile Devices/Profiles/RTL8721Dx.rdev \
        --image-dir D:/Images/image_dp \
        --port COM3

[2026-07-07 16:25:12.688][I] [main]AmebaFlash Version: 1.1.8.1
[2026-07-07 16:25:12.689][I] [main]Settings path: E:\git_repo\meta_tools\flash1\Settings.json
[2026-07-07 16:25:12.689][I] [main]Device profile: .\Devices\Profiles\RTL8721Dx.rdev
[2026-07-07 16:25:12.721][I] [main]Device profile .\Devices\Profiles\RTL8721Dx.rdev loaded
[2026-07-07 16:25:12.721][I] [main]Memory type derived from device profile: 1
[2026-07-07 16:25:12.721][I] [main]Serial port: ['COM3']
[2026-07-07 16:25:12.721][I] [main]Baudrate: 1500000
[2026-07-07 16:25:12.721][I] [main]Image dir: D:\Images\image_dp
[2026-07-07 16:25:12.721][I] [main]Chip erase: False
[2026-07-07 16:25:12.722][I] [main]Settings path: E:\git_repo\meta_tools\flash1\Settings.json
[2026-07-07 16:25:12.882][I] [COM3]Check supported flash size...
[2026-07-07 16:25:15.729][I] [COM3]Current supported flash size <=16MB
[2026-07-07 16:25:15.730][I] [COM3]Device info:
[2026-07-07 16:25:15.730][I] [COM3]* DID: 0x6845
[2026-07-07 16:25:15.731][I] [COM3]* ImageType: 0x0001
[2026-07-07 16:25:15.731][I] [COM3]* CmdSetVersion: 2.0
[2026-07-07 16:25:15.731][I] [COM3]* MemoryType: NOR
[2026-07-07 16:25:15.731][I] [COM3]* FlashMID: C8
[2026-07-07 16:25:15.731][I] [COM3]* FlashDID: 0x6517
[2026-07-07 16:25:15.731][I] [COM3]* FlashCapacity: 64Mb/8MB
[2026-07-07 16:25:15.731][I] [COM3]* FlashPageSize: 1024B
[2026-07-07 16:25:15.732][I] [COM3]* WiFiMAC: FF:FF:FF:FF:FF:FF
[2026-07-07 16:25:15.733][I] [COM3]Image download start...
[2026-07-07 16:25:15.733][I] [COM3]boot.bin download...
[2026-07-07 16:25:15.758][I] [COM3]Programming progress: 10%
[2026-07-07 16:25:15.801][I] [COM3]Programming progress: 20%
[2026-07-07 16:25:15.857][I] [COM3]Programming progress: 31%
[2026-07-07 16:25:15.910][I] [COM3]Programming progress: 41%
[2026-07-07 16:25:15.935][I] [COM3]Programming progress: 51%
[2026-07-07 16:25:15.993][I] [COM3]Programming progress: 62%
[2026-07-07 16:25:16.051][I] [COM3]Programming progress: 72%
[2026-07-07 16:25:16.110][I] [COM3]Programming progress: 82%
[2026-07-07 16:25:16.134][I] [COM3]Programming progress: 93%
[2026-07-07 16:25:16.226][I] [COM3]Programming progress: 100%
[2026-07-07 16:25:16.227][I] [COM3]boot.bin download done: 29KB / 493.0ms / 481.0Kbps
[2026-07-07 16:25:16.233][I] [COM3]Checksum OK: 0xd6c9e1c6
[2026-07-07 16:25:16.233][I] [COM3]app.bin download...
[2026-07-07 16:25:17.036][I] [COM3]Programming progress: 10%
[2026-07-07 16:25:17.723][I] [COM3]Programming progress: 20%
[2026-07-07 16:25:18.405][I] [COM3]Programming progress: 30%
[2026-07-07 16:25:19.082][I] [COM3]Programming progress: 40%
[2026-07-07 16:25:19.814][I] [COM3]Programming progress: 50%
[2026-07-07 16:25:20.507][I] [COM3]Programming progress: 60%
[2026-07-07 16:25:21.199][I] [COM3]Programming progress: 70%
[2026-07-07 16:25:21.890][I] [COM3]Programming progress: 80%
[2026-07-07 16:25:22.622][I] [COM3]Programming progress: 90%
[2026-07-07 16:25:23.494][I] [COM3]Programming progress: 100%
[2026-07-07 16:25:23.495][I] [COM3]app.bin download done: 812KB / 7260.0ms / 916.0Kbps
[2026-07-07 16:25:23.639][I] [COM3]Checksum OK: 0x313b12a2
[2026-07-07 16:25:23.640][I] [COM3]All images download done
[2026-07-07 16:25:23.842][I] [COM3]close COM3...
[2026-07-07 16:25:23.884][I] [COM3]COM3 closed.
[2026-07-07 16:25:23.884][I] [COM3]Finished PASS
[2026-07-07 16:25:23.885][I] [main]All flash threads have completed

1 拖 N 并行示例 (同时烧录三台设备)：

AmebaFlash.py --download \
    --baudrate 1500000 \
    --profile Devices/Profiles/RTL8721Dx.rdev \
    --image-dir D:/Images/image_dp \
    --port COM3 COM4 COM5

[2026-07-07 16:25:27.805][I] [main]AmebaFlash Version: 1.1.8.1
[2026-07-07 16:25:27.805][I] [main]Settings path: E:\git_repo\meta_tools\flash1\Settings.json
[2026-07-07 16:25:27.806][I] [main]Device profile: .\Devices\Profiles\RTL8721Dx.rdev
[2026-07-07 16:25:27.838][I] [main]Device profile .\Devices\Profiles\RTL8721Dx.rdev loaded
[2026-07-07 16:25:27.839][I] [main]Memory type derived from device profile: 1
[2026-07-07 16:25:27.839][I] [main]Serial port: ['COM3', 'COM4', 'COM5']
[2026-07-07 16:25:27.840][I] [main]Baudrate: 1500000
[2026-07-07 16:25:27.840][I] [main]Image dir: D:\Images\image_dp
[2026-07-07 16:25:27.840][I] [main]Chip erase: False
[2026-07-07 16:25:27.840][I] [main]Settings path: E:\git_repo\meta_tools\flash1\Settings.json
[2026-07-07 16:25:27.884][I] [COM4]Check supported flash size...
[2026-07-07 16:25:27.940][I] [COM5]Check supported flash size...
[2026-07-07 16:25:27.943][I] [COM3]Check supported flash size...
[2026-07-07 16:25:28.523][I] [COM3]Current supported flash size >16MB
[2026-07-07 16:25:28.524][I] [COM3]Device info:
[2026-07-07 16:25:28.524][I] [COM3]* DID: 0x6845
[2026-07-07 16:25:28.524][I] [COM3]* ImageType: 0x0001
[2026-07-07 16:25:28.525][I] [COM3]* CmdSetVersion: 2.0
[2026-07-07 16:25:28.525][I] [COM3]* MemoryType: NOR
[2026-07-07 16:25:28.525][I] [COM3]* FlashMID: C8
[2026-07-07 16:25:28.526][I] [COM3]* FlashDID: 0x4019
[2026-07-07 16:25:28.526][I] [COM3]* FlashCapacity: 256Mb/32MB
[2026-07-07 16:25:28.526][I] [COM3]* FlashPageSize: 1024B
[2026-07-07 16:25:28.527][I] [COM3]* WiFiMAC: 00:E0:4C:00:0C:24
[2026-07-07 16:25:28.528][I] [COM3]Image download start...
[2026-07-07 16:25:28.528][I] [COM3]boot.bin download...
[2026-07-07 16:25:28.553][I] [COM3]Programming progress: 10%
[2026-07-07 16:25:28.578][I] [COM3]Programming progress: 20%
[2026-07-07 16:25:28.603][I] [COM3]Programming progress: 31%
[2026-07-07 16:25:28.629][I] [COM3]Programming progress: 41%
[2026-07-07 16:25:28.653][I] [COM3]Programming progress: 51%
[2026-07-07 16:25:28.679][I] [COM3]Programming progress: 62%
[2026-07-07 16:25:28.704][I] [COM3]Programming progress: 72%
[2026-07-07 16:25:28.730][I] [COM3]Programming progress: 82%
[2026-07-07 16:25:28.754][I] [COM3]Programming progress: 93%
[2026-07-07 16:25:28.789][I] [COM3]Programming progress: 100%
[2026-07-07 16:25:28.789][I] [COM3]boot.bin download done: 29KB / 260.0ms / 913.0Kbps
[2026-07-07 16:25:28.805][I] [COM3]Checksum OK: 0xd6c9e1c6
[2026-07-07 16:25:28.805][I] [COM3]app.bin download...
[2026-07-07 16:25:29.459][I] [COM3]Programming progress: 10%
[2026-07-07 16:25:30.097][I] [COM3]Programming progress: 20%
[2026-07-07 16:25:30.707][I] [COM4]Current supported flash size <=16MB
[2026-07-07 16:25:30.707][I] [COM4]Device info:
[2026-07-07 16:25:30.707][I] [COM4]* DID: 0x6845
[2026-07-07 16:25:30.707][I] [COM4]* ImageType: 0x0001
[2026-07-07 16:25:30.707][I] [COM4]* CmdSetVersion: 2.0
[2026-07-07 16:25:30.708][I] [COM4]* MemoryType: NOR
[2026-07-07 16:25:30.708][I] [COM4]* FlashMID: C8
[2026-07-07 16:25:30.708][I] [COM4]* FlashDID: 0x6517
[2026-07-07 16:25:30.708][I] [COM4]* FlashCapacity: 64Mb/8MB
[2026-07-07 16:25:30.708][I] [COM4]* FlashPageSize: 1024B
[2026-07-07 16:25:30.708][I] [COM4]* WiFiMAC: FF:FF:FF:FF:FF:FF
[2026-07-07 16:25:30.710][I] [COM4]Image download start...
[2026-07-07 16:25:30.710][I] [COM4]boot.bin download...
[2026-07-07 16:25:30.734][I] [COM4]Programming progress: 10%
[2026-07-07 16:25:30.740][I] [COM3]Programming progress: 30%
[2026-07-07 16:25:30.778][I] [COM4]Programming progress: 20%
[2026-07-07 16:25:30.801][I] [COM5]Current supported flash size <=16MB
[2026-07-07 16:25:30.801][I] [COM5]Device info:
[2026-07-07 16:25:30.801][I] [COM5]* DID: 0x6845
[2026-07-07 16:25:30.801][I] [COM5]* ImageType: 0x0001
[2026-07-07 16:25:30.802][I] [COM5]* CmdSetVersion: 2.0
[2026-07-07 16:25:30.802][I] [COM5]* MemoryType: NOR
[2026-07-07 16:25:30.802][I] [COM5]* FlashMID: C8
[2026-07-07 16:25:30.802][I] [COM5]* FlashDID: 0x4017
[2026-07-07 16:25:30.802][I] [COM5]* FlashCapacity: 64Mb/8MB
[2026-07-07 16:25:30.802][I] [COM5]* FlashPageSize: 1024B
[2026-07-07 16:25:30.802][I] [COM5]* WiFiMAC: 00:E0:4C:00:0D:26
[2026-07-07 16:25:30.804][I] [COM5]Image download start...
[2026-07-07 16:25:30.805][I] [COM5]boot.bin download...
[2026-07-07 16:25:30.829][I] [COM5]Programming progress: 10%
[2026-07-07 16:25:30.836][I] [COM4]Programming progress: 31%
[2026-07-07 16:25:30.856][I] [COM5]Programming progress: 20%
[2026-07-07 16:25:30.890][I] [COM5]Programming progress: 31%
[2026-07-07 16:25:30.891][I] [COM4]Programming progress: 41%
[2026-07-07 16:25:30.915][I] [COM4]Programming progress: 51%
[2026-07-07 16:25:30.922][I] [COM5]Programming progress: 41%
[2026-07-07 16:25:30.946][I] [COM5]Programming progress: 51%
[2026-07-07 16:25:30.975][I] [COM4]Programming progress: 62%
[2026-07-07 16:25:30.977][I] [COM5]Programming progress: 62%
[2026-07-07 16:25:31.012][I] [COM5]Programming progress: 72%
[2026-07-07 16:25:31.031][I] [COM4]Programming progress: 72%
[2026-07-07 16:25:31.045][I] [COM5]Programming progress: 82%
[2026-07-07 16:25:31.069][I] [COM5]Programming progress: 93%
[2026-07-07 16:25:31.088][I] [COM4]Programming progress: 82%
[2026-07-07 16:25:31.112][I] [COM4]Programming progress: 93%
[2026-07-07 16:25:31.121][I] [COM5]Programming progress: 100%
[2026-07-07 16:25:31.121][I] [COM5]boot.bin download done: 29KB / 316.0ms / 751.0Kbps
[2026-07-07 16:25:31.127][I] [COM5]Checksum OK: 0xd6c9e1c6
[2026-07-07 16:25:31.127][I] [COM5]app.bin download...
[2026-07-07 16:25:31.203][I] [COM4]Programming progress: 100%
[2026-07-07 16:25:31.204][I] [COM4]boot.bin download done: 29KB / 493.0ms / 481.0Kbps
[2026-07-07 16:25:31.210][I] [COM4]Checksum OK: 0xd6c9e1c6
[2026-07-07 16:25:31.210][I] [COM4]app.bin download...
[2026-07-07 16:25:31.374][I] [COM3]Programming progress: 40%
[2026-07-07 16:25:31.799][I] [COM5]Programming progress: 10%
[2026-07-07 16:25:32.005][I] [COM4]Programming progress: 10%
[2026-07-07 16:25:32.008][I] [COM3]Programming progress: 50%
[2026-07-07 16:25:32.430][I] [COM5]Programming progress: 20%
[2026-07-07 16:25:32.647][I] [COM3]Programming progress: 60%
[2026-07-07 16:25:32.687][I] [COM4]Programming progress: 20%
[2026-07-07 16:25:33.067][I] [COM5]Programming progress: 30%
[2026-07-07 16:25:33.284][I] [COM3]Programming progress: 70%
[2026-07-07 16:25:33.362][I] [COM4]Programming progress: 30%
[2026-07-07 16:25:33.701][I] [COM5]Programming progress: 40%
[2026-07-07 16:25:33.918][I] [COM3]Programming progress: 80%
[2026-07-07 16:25:34.034][I] [COM4]Programming progress: 40%
[2026-07-07 16:25:34.336][I] [COM5]Programming progress: 50%
[2026-07-07 16:25:34.549][I] [COM3]Programming progress: 90%
[2026-07-07 16:25:34.766][I] [COM4]Programming progress: 50%
[2026-07-07 16:25:34.978][I] [COM5]Programming progress: 60%
[2026-07-07 16:25:35.193][I] [COM3]Programming progress: 100%
[2026-07-07 16:25:35.193][I] [COM3]app.bin download done: 812KB / 6387.0ms / 1041.0Kbps
[2026-07-07 16:25:35.458][I] [COM4]Programming progress: 60%
[2026-07-07 16:25:35.612][I] [COM3]Checksum OK: 0x313b12a2
[2026-07-07 16:25:35.612][I] [COM3]All images download done
[2026-07-07 16:25:35.617][I] [COM5]Programming progress: 70%
[2026-07-07 16:25:35.813][I] [COM3]close COM3...
[2026-07-07 16:25:35.854][I] [COM3]COM3 closed.
[2026-07-07 16:25:35.854][I] [COM3]Finished PASS
[2026-07-07 16:25:36.149][I] [COM4]Programming progress: 70%
[2026-07-07 16:25:36.257][I] [COM5]Programming progress: 80%
[2026-07-07 16:25:36.835][I] [COM4]Programming progress: 80%
[2026-07-07 16:25:36.896][I] [COM5]Programming progress: 90%
[2026-07-07 16:25:37.578][I] [COM4]Programming progress: 90%
[2026-07-07 16:25:37.623][I] [COM5]Programming progress: 100%
[2026-07-07 16:25:37.624][I] [COM5]app.bin download done: 812KB / 6496.0ms / 1024.0Kbps
[2026-07-07 16:25:37.770][I] [COM5]Checksum OK: 0x313b12a2
[2026-07-07 16:25:37.771][I] [COM5]All images download done
[2026-07-07 16:25:37.972][I] [COM5]close COM5...
[2026-07-07 16:25:38.013][I] [COM5]COM5 closed.
[2026-07-07 16:25:38.013][I] [COM5]Finished PASS
[2026-07-07 16:25:38.444][I] [COM4]Programming progress: 100%
[2026-07-07 16:25:38.445][I] [COM4]app.bin download done: 812KB / 7233.0ms / 919.0Kbps
[2026-07-07 16:25:38.588][I] [COM4]Checksum OK: 0x313b12a2
[2026-07-07 16:25:38.589][I] [COM4]All images download done
[2026-07-07 16:25:38.790][I] [COM4]close COM4...
[2026-07-07 16:25:38.832][I] [COM4]COM4 closed.
[2026-07-07 16:25:38.832][I] [COM4]Finished PASS
[2026-07-07 16:25:38.833][I] [main]All flash threads have completed

小技巧

在 1 拖 N 模式下，每个端口在独立线程中运行，单端口失败不影响其他端口。

备注

工具会首先校验所有指定的固件文件是否存在以及地址是否在设备正确范围内，如有问题，在开始实际烧录前报告错误并停止烧录。
如需在烧录前执行全片擦除，可将 --chip-erase 与烧录命令结合使用。

全片擦除后烧录示例：

AmebaFlash.py --download --chip-erase \
        --baudrate 1500000 \
        --profile Devices/Profiles/RTL8721Dx.rdev \
        --image D:/Images/image_dp/image_all.bin
        --start-address 0x08000000
        --port COM3

[2026-07-07 18:58:55.247][I] [main]AmebaFlash Version: 1.1.8.1
[2026-07-07 18:58:55.247][I] [main]Settings path: E:\git_repo\meta_tools\flash1\Settings.json
[2026-07-07 18:58:55.248][I] [main]Device profile: .\Devices\Profiles\RTL8721Dx.rdev
[2026-07-07 18:58:55.295][I] [main]Device profile .\Devices\Profiles\RTL8721Dx.rdev loaded
[2026-07-07 18:58:55.296][I] [main]Memory type derived from device profile: 1
[2026-07-07 18:58:55.296][I] [main]Serial port: ['COM3']
[2026-07-07 18:58:55.296][I] [main]Baudrate: 1500000
[2026-07-07 18:58:55.296][I] [main]Image info:
[2026-07-07 18:58:55.296][I] [main]> Image: D:\Images\image_dp\image_all.bin
[2026-07-07 18:58:55.297][I] [main]> StartAddress: 134217728
[2026-07-07 18:58:55.297][I] [main]> EndAddress: 136314880
[2026-07-07 18:58:55.297][I] [main]> MemoryType: 1
[2026-07-07 18:58:55.297][I] [main]> FullErase: False
[2026-07-07 18:58:55.297][I] [main]> Mandatory: True
[2026-07-07 18:58:55.297][I] [main]> Description: image_all.bin
[2026-07-07 18:58:55.297][I] [main]Chip erase: True
[2026-07-07 18:58:55.298][I] [main]Settings path: E:\git_repo\meta_tools\flash1\Settings.json
[2026-07-07 18:58:55.465][I] [COM3]Check supported flash size...
[2026-07-07 18:58:56.046][I] [COM3]Current supported flash size >16MB
[2026-07-07 18:58:56.047][I] [COM3]Device info:
[2026-07-07 18:58:56.047][I] [COM3]* DID: 0x6845
[2026-07-07 18:58:56.047][I] [COM3]* ImageType: 0x0001
[2026-07-07 18:58:56.047][I] [COM3]* CmdSetVersion: 2.0
[2026-07-07 18:58:56.048][I] [COM3]* MemoryType: NOR
[2026-07-07 18:58:58.547][I] [COM3]Programming progress: 20%
[2026-07-07 18:58:58.573][I] [COM3]Programming progress: 31%
[2026-07-07 18:58:58.599][I] [COM3]Programming progress: 41%
[2026-07-07 18:58:58.624][I] [COM3]Programming progress: 51%
[2026-07-07 18:58:58.649][I] [COM3]Programming progress: 62%
[2026-07-07 18:58:58.675][I] [COM3]Programming progress: 72%
[2026-07-07 18:58:58.700][I] [COM3]Programming progress: 82%
[2026-07-07 18:58:58.724][I] [COM3]Programming progress: 93%
[2026-07-07 18:58:58.743][I] [COM3]Programming progress: 100%
[2026-07-07 18:58:58.743][I] [COM3]image_all.bin [0x08000000-0x08014000] download done: 29KB / 245.0ms / 969.0Kbps
[2026-07-07 18:58:58.759][I] [COM3]Checksum OK: 0xd6c9e1c6
[2026-07-07 18:58:58.761][I] [COM3]image_all.bin [0x08014000-0x08200000] download...
[2026-07-07 18:58:59.444][I] [COM3]Programming progress: 10%
[2026-07-07 18:59:00.123][I] [COM3]Programming progress: 20%
[2026-07-07 18:59:00.798][I] [COM3]Programming progress: 30%
[2026-07-07 18:59:01.477][I] [COM3]Programming progress: 40%
[2026-07-07 18:59:02.154][I] [COM3]Programming progress: 50%
[2026-07-07 18:59:02.841][I] [COM3]Programming progress: 60%
[2026-07-07 18:59:03.518][I] [COM3]Programming progress: 70%
[2026-07-07 18:59:04.196][I] [COM3]Programming progress: 80%
[2026-07-07 18:59:04.870][I] [COM3]Programming progress: 90%
[2026-07-07 18:59:05.564][I] [COM3]Programming progress: 100%
[2026-07-07 18:59:05.564][I] [COM3]image_all.bin [0x08014000-0x08200000] download done: 860KB / 6802.0ms / 1035.0Kbps
[2026-07-07 18:59:06.008][I] [COM3]Checksum OK: 0x313ae2a2
[2026-07-07 18:59:06.011][I] [COM3]All images download done
[2026-07-07 18:59:06.224][I] [COM3]close COM3...
[2026-07-07 18:59:06.266][I] [COM3]COM3 closed.
[2026-07-07 18:59:06.266][I] [COM3]Finished PASS
[2026-07-07 18:59:06.268][I] [main]All flash threads have completed

Flash 擦除

擦除命令用于清除目标设备 Flash 中的固件数据。提供两种擦除模式：部分擦除（指定地址范围）和全片擦除（整颗 Flash）。

必选参数

以下参数在烧录、擦除和 WiFi MAC 读取操作中均为必选。

-b / --baudrate <value>

设置串口通信波特率。

--baudrate 1500000

支持的波特率： 115200, 128000, 153600, 230400, 380400, 460800, 500000, 921600, 1000000, 1382400, 1444400, 1500000, 2000000, 3000000

-f / --profile <path>

设备配置文件（.rdev 格式）路径。Profile 文件定义了目标芯片的参数，包括 Flash 布局、存储配置和握手波特率等。

Profile 文件位于工具目录下的 Devices/Profiles/ 文件夹。

--profile Devices/Profiles/RTL8721Dx.rdev

-p / --port <port1> [port2 ...]

目标板的串口号。指定多个串口可启用 1 拖 N 并行烧录（v1.1.0 起支持）。

--port COM3                    # 单设备
--port COM3 COM4 COM5          # 1 拖 3 并行

小技巧

在 Linux 上，可使用 ls /dev/tty* 查看可用串口。

擦除模式选择

部分擦除:

使用 --erase 并指定地址范围来擦除 Flash 的特定区域。不同存储类型所需的尺寸参数格式有所不同。

参数	说明
`-e` / `--erase`	触发部分擦除，无需跟随任何值。
`-a` / `--start-address <hex>`	擦除区域的起始地址，十六进制格式。
`-z` / `--size <KB>`	擦除大小，单位 KB，十进制。NOR flash 擦除时必需。
`-n` / `--end-address <hex>`	擦除区域的结束地址，十六进制格式。NAND flash 擦除时必需。

全片擦除:

使用 --chip-erase 擦除整片 Flash。

参数	说明
`--chip-erase`	擦除整片 Flash，无需跟随任何值。

备注

--chip-erase 也可与烧录命令结合使用（参见 Flash 烧录），工具会先执行全片擦除，再执行烧录。

擦除示例

配置好所有参数后，执行以下相应命令。

NOR 部分擦除：

AmebaFlash.py --erase \
    --baudrate 1500000 \
    --profile Devices/Profiles/RTL8721Dx.rdev \
    --start-address 0x08000000 \
    --size 1024 \
    --port COM3

[2026-07-07 16:33:08.456][I] [main]AmebaFlash Version: 1.1.8.1
[2026-07-07 16:33:08.457][I] [main]Settings path: E:\git_repo\meta_tools\flash1\Settings.json
[2026-07-07 16:33:08.479][I] [main]Device profile: .\Devices\Profiles\RTL8721Dx.rdev
[2026-07-07 16:33:08.548][I] [main]Device profile .\Devices\Profiles\RTL8721Dx.rdev loaded
[2026-07-07 16:33:08.548][I] [main]Memory type derived from device profile: 1
[2026-07-07 16:33:08.548][I] [main]Serial port: ['COM3']
[2026-07-07 16:33:08.549][I] [main]Baudrate: 1500000
[2026-07-07 16:33:08.550][I] [main]Chip erase: False
[2026-07-07 16:33:08.551][I] [main]Settings path: E:\git_repo\meta_tools\flash1\Settings.json
[2026-07-07 16:33:09.284][I] [COM3]Device info:
[2026-07-07 16:33:09.284][I] [COM3]* DID: 0x6845
[2026-07-07 16:33:09.285][I] [COM3]* ImageType: 0x0001
[2026-07-07 16:33:09.285][I] [COM3]* CmdSetVersion: 2.0
[2026-07-07 16:33:09.285][I] [COM3]* MemoryType: NOR
[2026-07-07 16:33:09.286][I] [COM3]* FlashMID: C8
[2026-07-07 16:33:09.286][I] [COM3]* FlashDID: 0x4019
[2026-07-07 16:33:09.286][I] [COM3]* FlashCapacity: 256Mb/32MB
[2026-07-07 16:33:09.286][I] [COM3]* FlashPageSize: 1024B
[2026-07-07 16:33:09.287][I] [COM3]* WiFiMAC: 00:E0:4C:00:0C:24
[2026-07-07 16:33:09.287][I] [COM3]NOR flash erase: start address=0x8000000, size=1024KB.
[2026-07-07 16:33:10.659][I] [COM3]Erase nor done
[2026-07-07 16:33:10.659][I] [COM3]close COM3...
[2026-07-07 16:33:10.701][I] [COM3]COM3 closed.
[2026-07-07 16:33:10.701][I] [COM3]Finished PASS
[2026-07-07 16:33:10.703][I] [main]All flash threads have completed

NAND 部分擦除：

AmebaFlash.py --erase \
   --baudrate 1500000 \
   --profile Devices/Profiles/RTL8730E_NAND.rdev \
   --start-address 0x00000000 \
   --end-address 0x00100000 \
   --port COM3

[2026-07-06 20:06:53.527][I] [main]AmebaFlash Version: 1.1.8.1
[2026-07-06 20:06:53.528][I] [main]Settings path: E:\git_repo\meta_tools\flash1\Settings.json
[2026-07-06 20:06:53.542][I] [main]Device profile: .\Devices\Profiles\RTL8730E_NAND.rdev
[2026-07-06 20:06:53.600][I] [main]Device profile .\Devices\Profiles\RTL8730E_NAND.rdev loaded
[2026-07-06 20:06:53.600][I] [main]Memory type derived from device profile: 2
[2026-07-06 20:06:53.601][I] [main]Serial port: ['COM3']
[2026-07-06 20:06:53.601][I] [main]Baudrate: 1500000
[2026-07-06 20:06:53.602][I] [main]Chip erase: False
[2026-07-06 20:06:53.603][I] [main]Settings path: E:\git_repo\meta_tools\flash1\Settings.json
[2026-07-06 20:06:54.322][I] [COM3]Device info:
[2026-07-06 20:06:54.322][I] [COM3]* DID: 0x6678
[2026-07-06 20:06:54.323][I] [COM3]* ImageType: 0x0001
[2026-07-06 20:06:54.323][I] [COM3]* CmdSetVersion: 2.0
[2026-07-06 20:06:54.323][I] [COM3]* MemoryType: NAND
[2026-07-06 20:06:54.323][I] [COM3]* FlashMID: 0xC8
[2026-07-06 20:06:54.323][I] [COM3]* FlashDID: 0x92
[2026-07-06 20:06:54.323][I] [COM3]* FlashMFG: GIGADEVICE
[2026-07-06 20:06:54.324][I] [COM3]* FlashModel: GD5F2GM7U
[2026-07-06 20:06:54.324][I] [COM3]* FlashCapacity: 2Gb/256MB
[2026-07-06 20:06:54.324][I] [COM3]* FlashBlockSize: 128KB
[2026-07-06 20:06:54.324][I] [COM3]* FlashPageSize: 2048B
[2026-07-06 20:06:54.324][I] [COM3]* FlashOobSize: 128B
[2026-07-06 20:06:54.324][I] [COM3]* FlashPagesPerBlock: 64
[2026-07-06 20:06:54.324][I] [COM3]* FlashBlocksPerLun: 2048
[2026-07-06 20:06:54.325][I] [COM3]* FlashLunsPerTarget: 1
[2026-07-06 20:06:54.325][I] [COM3]* FlashTargets: 1
[2026-07-06 20:06:54.325][I] [COM3]* FlashMaxBadBlocksPerLun: 40
[2026-07-06 20:06:54.325][I] [COM3]* FlashReqHostEccLevel: 0
[2026-07-06 20:06:54.325][I] [COM3]* WiFiMAC: 00:E0:4C:00:06:FD
[2026-07-06 20:06:54.326][I] [COM3]NAND flash erase: start address=0x0, end address=0x100000
[2026-07-06 20:06:54.357][I] [COM3]Erase nand done
[2026-07-06 20:06:54.357][I] [COM3]close COM3...
[2026-07-06 20:06:54.398][I] [COM3]COM3 closed.
[2026-07-06 20:06:54.399][I] [COM3]Finished PASS
[2026-07-06 20:06:54.400][I] [main]All flash threads have completed

NOR 全片擦除：

AmebaFlash.py --chip-erase \
        --baudrate 1500000 \
        --profile Devices/Profiles/RTL8721Dx.rdev \
        --port COM3

[2026-07-06 20:17:06.517][I] [main]AmebaFlash Version: 1.1.8.1
[2026-07-06 20:17:06.517][I] [main]Settings path: E:\git_repo\meta_tools\flash1\Settings.json
[2026-07-06 20:17:06.518][I] [main]Device profile: .\Devices\Profiles\RTL8721Dx.rdev
[2026-07-06 20:17:06.572][I] [main]Device profile .\Devices\Profiles\RTL8721Dx.rdev loaded
[2026-07-06 20:17:06.572][I] [main]Memory type derived from device profile: 1
[2026-07-06 20:17:06.572][I] [main]Serial port: ['COM3']
[2026-07-06 20:17:06.573][I] [main]Baudrate: 1500000
[2026-07-06 20:17:06.573][I] [main]Chip erase: True
[2026-07-06 20:17:06.574][I] [main]Settings path: E:\git_repo\meta_tools\flash1\Settings.json
[2026-07-06 20:17:07.171][I] [COM3]Device info:
[2026-07-06 20:17:07.172][I] [COM3]* DID: 0x6845
[2026-07-06 20:17:07.172][I] [COM3]* ImageType: 0x0001
[2026-07-06 20:17:07.172][I] [COM3]* CmdSetVersion: 2.0
[2026-07-06 20:17:07.172][I] [COM3]* MemoryType: NOR
[2026-07-06 20:17:07.172][I] [COM3]* FlashMID: C8
[2026-07-06 20:17:07.173][I] [COM3]* FlashDID: 0x4019
[2026-07-06 20:17:07.173][I] [COM3]* FlashCapacity: 256Mb/32MB
[2026-07-06 20:17:07.173][I] [COM3]* FlashPageSize: 1024B
[2026-07-06 20:17:07.173][I] [COM3]* WiFiMAC: 00:E0:4C:00:0C:24
[2026-07-06 20:17:07.174][I] [COM3]Chip erase start
[2026-07-06 20:17:09.023][I] [COM3]Chip erase end
[2026-07-06 20:17:09.023][I] [COM3]Finished PASS
[2026-07-06 20:17:09.023][I] [main]All flash threads have completed
[2026-07-06 20:17:09.026][I] [COM3]close COM3...
[2026-07-06 20:17:09.068][I] [COM3]COM3 close done

WiFi MAC 读取

--read-wifimac 通过串口读取目标设备中存储的 WiFi MAC 地址。

这是一个独立操作，与烧录（ --download ）、擦除（ --erase ）并列，无需指定固件或地址参数。

必选参数

以下参数在烧录、擦除和 WiFi MAC 读取操作中均为必选。

-b / --baudrate <value>

设置串口通信波特率。

--baudrate 1500000

支持的波特率： 115200, 128000, 153600, 230400, 380400, 460800, 500000, 921600, 1000000, 1382400, 1444400, 1500000, 2000000, 3000000

-f / --profile <path>

设备配置文件（.rdev 格式）路径。Profile 文件定义了目标芯片的参数，包括 Flash 布局、存储配置和握手波特率等。

Profile 文件位于工具目录下的 Devices/Profiles/ 文件夹。

--profile Devices/Profiles/RTL8721Dx.rdev

-p / --port <port1> [port2 ...]

目标板的串口号。指定多个串口可启用 1 拖 N 并行烧录（v1.1.0 起支持）。

--port COM3                    # 单设备
--port COM3 COM4 COM5          # 1 拖 3 并行

小技巧

在 Linux 上，可使用 ls /dev/tty* 查看可用串口。

读取命令

配置好必选参数后，追加 --read-wifimac 即可触发读取，该参数无需跟随任何值。

AmebaFlash.py --read-wifimac \
   --baudrate 1500000 \
   --profile Devices/Profiles/RTL8721Dx.rdev \
   --port COM3

[2026-07-07 13:42:33.563][I] [main]AmebaFlash Version: 1.1.8.1
[2026-07-07 13:42:33.564][I] [main]Settings path: E:\git_repo\meta_tools\flash1\Settings.json
[2026-07-07 13:42:33.565][I] [main]Device profile: .\Devices\Profiles\RTL8721Dx.rdev
[2026-07-07 13:42:33.595][I] [main]Device profile .\Devices\Profiles\RTL8721Dx.rdev loaded
[2026-07-07 13:42:33.595][I] [main]Memory type derived from device profile: 1
[2026-07-07 13:42:33.595][I] [main]Serial port: ['COM3']
[2026-07-07 13:42:33.596][I] [main]Baudrate: 1500000
[2026-07-07 13:42:33.596][I] [main]Settings path: E:\git_repo\meta_tools\flash1\Settings.json
[2026-07-07 13:42:34.347][I] [COM3]WiFiMAC: 00:E0:4C:00:0C:24
[2026-07-07 13:42:34.347][I] [COM3]close COM3...
[2026-07-07 13:42:34.388][I] [COM3]COM3 closed.
[2026-07-07 13:42:34.389][I] [COM3]Finished PASS
[2026-07-07 13:42:34.390][I] [main]All flash threads have completed

重要

--read-wifimac 与 --download 及 --erase 互斥，不可同时使用，适用于仅需要读取 WiFi MAC 的场景。

--download 及 --erase 过程会自动获取并显示 WiFi MAC 信息。

可选参数

本章节介绍 AmebaFlash 的可选命令行参数。与烧录行为相关的 Settings.json 配置项（通信时序、DTR/RTS、写保护处理、烧录后操作、GPIO/PWM 指示等）请参见 Settings.json 参数章节。

自定义分区表

参数 --partition-table <base64> 允许完全自定义固件分区布局，覆盖 Profile 中预定义的布局。

该参数的取值并非直接的分区描述，而是经过以下三步处理后的字符串：

组装 JSON — 按下文字段定义，将各分区信息组织成一个 JSON 数组；
Base64 编码 — 将整个 JSON 字符串进行 Base64 编码，转换为单行 ASCII 字符串；
作为字符串传入 — 将编码结果作为 --partition-table 的参数值传递。

之所以采用 Base64 编码后再传输，是为了把包含路径、地址、引号等特殊字符的多行 JSON 压缩成单个安全的字符串，避免在命令行或进程间传参时被 Shell 转义、换行截断等问题破坏。

小心

该参数主要用于 与其他工具/上层程序对接 的场景：由上层程序动态生成分区表、完成 Base64 编码后再调用 AmebaFlash 传入。

不建议手动单独使用。 如需手动指定固件来源，请优先使用 --image / --image-dir （参见固件来源），无需自行拼装 JSON 与编码，更不易出错。

JSON 数组中的每个对象包含以下字段：

字段	类型	说明
`ImageName`	string	固件二进制文件的完整路径。
`StartAddress`	integer	Flash 起始地址，十进制。
`EndAddress`	integer	Flash 结束地址，十进制。
`FullErase`	boolean	`true` 表示在烧录前擦除整个分区。
`MemoryType`	integer	`0` = RAM，`1` = NOR Flash，`2` = NAND Flash。
`Mandatory`	boolean	`true` 表示该分区为必须烧录项。
`Description`	string	可读的描述标签（可选）。

示例：

[
  {
    "ImageName": "D:/Images/image_dp/boot.bin",
    "StartAddress": 134217728,
    "EndAddress": 134348800,
    "FullErase": false,
    "MemoryType": 1,
    "Mandatory": true,
    "Description": "Bootloader"
  },
  {
    "ImageName": "D:/Images/image_dp/app.bin",
    "StartAddress": 136445952,
    "EndAddress": 137363456,
    "FullErase": false,
    "MemoryType": 1,
    "Mandatory": true,
    "Description": "Application"
  }
]

将 JSON 数组进行 Base64 编码。以下 Python 代码片段读取该 JSON、完成编码，并打印出可传递给 --partition-table 的字符串：

import base64

json_str = """
[
  {
    "ImageName": "D:/Images/image_dp/boot.bin",
    "StartAddress": 134217728,
    "EndAddress": 134348800,
    "FullErase": false,
    "MemoryType": 1,
    "Mandatory": true,
    "Description": "Bootloader"
  },
  {
    "ImageName": "D:/Images/image_dp/app.bin",
    "StartAddress": 136445952,
    "EndAddress": 137363456,
    "FullErase": false,
    "MemoryType": 1,
    "Mandatory": true,
    "Description": "Application"
  }
]
"""

print(base64.b64encode(json_str.encode("utf-8")).decode("utf-8"))

该代码会打印出一整行连续的 Base64 字符串：

WwogICAgIHsKICAgICAgICJJbWFnZU5hbWUiOiAiRDovSW1hZ2VzL2ltYWdlX2RwL2Jvb3QuYmluIiwKICAgICAgICJTdGFydEFkZHJlc3MiOiAxMzQyMTc3MjgsCiAgICAgICAiRW5kQWRkcmVzcyI6IDEzNDM0ODgwMCwKICAgICAgICJGdWxsRXJhc2UiOiBmYWxzZSwKICAgICAgICJNZW1vcnlUeXBlIjogMSwKICAgICAgICJNYW5kYXRvcnkiOiB0cnVlLAogICAgICAgIkRlc2NyaXB0aW9uIjogIkJvb3Rsb2FkZXIiCiAgICAgfSwKICAgICB7CiAgICAgICAiSW1hZ2VOYW1lIjogIkQ6L0ltYWdlcy9pbWFnZV9kcC9hcHAuYmluIiwKICAgICAgICJTdGFydEFkZHJlc3MiOiAxMzY0NDU5NTIsCiAgICAgICAiRW5kQWRkcmVzcyI6IDEzNzM2MzQ1NiwKICAgICAgICJGdWxsRXJhc2UiOiBmYWxzZSwKICAgICAgICJNZW1vcnlUeXBlIjogMSwKICAgICAgICJNYW5kYXRvcnkiOiB0cnVlLAogICAgICAgIkRlc2NyaXB0aW9uIjogIkFwcGxpY2F0aW9uIgogICAgIH0KICAgXQ==

将整个字符串作为单个参数（不能有换行）传给 --partition-table：

AmebaFlash.py --download \
    --baudrate 1500000 \
    --profile Devices/Profiles/RTL8721Dx.rdev \
    --port COM3 \
    --partition-table "WwogICAgIHsKICAgICAgICJJbWFnZU5hbWUiOiAiRDovSW1hZ2VzL2ltYWdlX2RwL2Jvb3QuYmluIiwKICAgICAgICJTdGFydEFkZHJlc3MiOiAxMzQyMTc3MjgsCiAgICAgICAiRW5kQWRkcmVzcyI6IDEzNDM0ODgwMCwKICAgICAgICJGdWxsRXJhc2UiOiBmYWxzZSwKICAgICAgICJNZW1vcnlUeXBlIjogMSwKICAgICAgICJNYW5kYXRvcnkiOiB0cnVlLAogICAgICAgIkRlc2NyaXB0aW9uIjogIkJvb3Rsb2FkZXIiCiAgICAgfSwKICAgICB7CiAgICAgICAiSW1hZ2VOYW1lIjogIkQ6L0ltYWdlcy9pbWFnZV9kcC9hcHAuYmluIiwKICAgICAgICJTdGFydEFkZHJlc3MiOiAxMzY0NDU5NTIsCiAgICAgICAiRW5kQWRkcmVzcyI6IDEzNzM2MzQ1NiwKICAgICAgICJGdWxsRXJhc2UiOiBmYWxzZSwKICAgICAgICJNZW1vcnlUeXBlIjogMSwKICAgICAgICJNYW5kYXRvcnkiOiB0cnVlLAogICAgICAgIkRlc2NyaXB0aW9uIjogIkFwcGxpY2F0aW9uIgogICAgIH0KICAgXQ=="

[2026-07-07 09:19:33.395][I] [main]AmebaFlash Version: 1.1.8.1
[2026-07-07 09:19:33.396][I] [main]Settings path: E:\git_repo\meta_tools\flash1\Settings.json
[2026-07-07 09:19:33.397][I] [main]Device profile: .\Devices\Profiles\RTL8721Dx.rdev
[2026-07-07 09:19:33.429][I] [main]Device profile .\Devices\Profiles\RTL8721Dx.rdev loaded
[2026-07-07 09:19:33.429][I] [main]Memory type derived from device profile: 1
[2026-07-07 09:19:33.429][I] [main]Serial port: ['COM13']
[2026-07-07 09:19:33.430][I] [main]Baudrate: 1500000
[2026-07-07 09:19:33.430][I] [main]Image info:
[2026-07-07 09:19:33.430][I] [main]> Image: D:\Images\image_dp\boot.bin
[2026-07-07 09:19:33.430][I] [main]> StartAddress: 134217728
[2026-07-07 09:19:33.430][I] [main]> EndAddress: 134348800
[2026-07-07 09:19:33.430][I] [main]> MemoryType: 1
[2026-07-07 09:19:33.431][I] [main]> FullErase: False
[2026-07-07 09:19:33.431][I] [main]> Mandatory: True
[2026-07-07 09:19:33.431][I] [main]> Description: boot.bin
[2026-07-07 09:19:33.431][I] [main]> Image: D:\Images\image_dp\app.bin
[2026-07-07 09:19:33.431][I] [main]> StartAddress: 136445952
[2026-07-07 09:19:33.431][I] [main]> EndAddress: 137363456
[2026-07-07 09:19:33.431][I] [main]> MemoryType: 1
[2026-07-07 09:19:33.432][I] [main]> FullErase: False
[2026-07-07 09:19:33.432][I] [main]> Mandatory: True
[2026-07-07 09:19:33.432][I] [main]> Description: app.bin
[2026-07-07 09:19:33.432][I] [main]Chip erase: False
[2026-07-07 09:19:33.433][I] [main]Settings path: E:\git_repo\meta_tools\flash1\Settings.json
[2026-07-07 09:19:33.587][I] [COM13]Check supported flash size...
[2026-07-07 09:19:34.145][I] [COM13]Current supported flash size >16MB
[2026-07-07 09:19:34.145][I] [COM13]Device info:
[2026-07-07 09:19:34.145][I] [COM13]* DID: 0x6845
[2026-07-07 09:19:34.146][I] [COM13]* ImageType: 0x0001
[2026-07-07 09:19:34.146][I] [COM13]* CmdSetVersion: 2.0
[2026-07-07 09:19:34.146][I] [COM13]* MemoryType: NOR
[2026-07-07 09:19:34.146][I] [COM13]* FlashMID: C8
[2026-07-07 09:19:34.146][I] [COM13]* FlashDID: 0x4019
[2026-07-07 09:19:34.146][I] [COM13]* FlashCapacity: 256Mb/32MB
[2026-07-07 09:19:34.147][I] [COM13]* FlashPageSize: 1024B
[2026-07-07 09:19:34.147][I] [COM13]* WiFiMAC: 00:E0:4C:00:0C:24
[2026-07-07 09:19:34.148][I] [COM13]Image download start...
[2026-07-07 09:19:34.148][I] [COM13]boot.bin download...
[2026-07-07 09:19:34.173][I] [COM13]Programming progress: 10%
[2026-07-07 09:19:34.198][I] [COM13]Programming progress: 20%
[2026-07-07 09:19:34.224][I] [COM13]Programming progress: 31%
[2026-07-07 09:19:34.249][I] [COM13]Programming progress: 41%
[2026-07-07 09:19:34.273][I] [COM13]Programming progress: 51%
[2026-07-07 09:19:34.298][I] [COM13]Programming progress: 62%
[2026-07-07 09:19:34.324][I] [COM13]Programming progress: 72%
[2026-07-07 09:19:34.350][I] [COM13]Programming progress: 82%
[2026-07-07 09:19:34.373][I] [COM13]Programming progress: 93%
[2026-07-07 09:19:34.403][I] [COM13]Programming progress: 100%
[2026-07-07 09:19:34.403][I] [COM13]boot.bin download done: 29KB / 255.0ms / 931.0Kbps
[2026-07-07 09:19:34.420][I] [COM13]Checksum OK: 0xd6c9e1c6
[2026-07-07 09:19:34.421][I] [COM13]app.bin download...
[2026-07-07 09:19:35.064][I] [COM13]Programming progress: 10%
[2026-07-07 09:19:35.701][I] [COM13]Programming progress: 20%
[2026-07-07 09:19:36.340][I] [COM13]Programming progress: 30%
[2026-07-07 09:19:36.984][I] [COM13]Programming progress: 40%
[2026-07-07 09:19:37.620][I] [COM13]Programming progress: 50%
[2026-07-07 09:19:38.264][I] [COM13]Programming progress: 60%
[2026-07-07 09:19:38.901][I] [COM13]Programming progress: 70%
[2026-07-07 09:19:39.541][I] [COM13]Programming progress: 80%
[2026-07-07 09:19:40.176][I] [COM13]Programming progress: 90%
[2026-07-07 09:19:40.816][I] [COM13]Programming progress: 100%
[2026-07-07 09:19:40.816][I] [COM13]app.bin download done: 812KB / 6395.0ms / 1040.0Kbps
[2026-07-07 09:19:41.235][I] [COM13]Checksum OK: 0x313b12a2
[2026-07-07 09:19:41.237][I] [COM13]All images download done
[2026-07-07 09:19:41.439][I] [COM13]close COM13...
[2026-07-07 09:19:41.481][I] [COM13]COM13 closed.
[2026-07-07 09:19:41.481][I] [COM13]Finished PASS
[2026-07-07 09:19:41.483][I] [main]All flash threads have completed

小心

请不要从 Python 交互式提示符（>>> / ...）中复制 JSON：续行提示符会被一并写入字符串并参与 Base64 编码，导致解码时得到非法 JSON （json.decoder.JSONDecodeError: Expecting value）。

请如上所示，从文件或纯字符串字面量中读取并编码 JSON。

小心

在 Windows 上，ImageName 中请使用正斜杠（/）或转义的反斜杠（\\）。单个反斜杠不是合法的 JSON 转义，且在 Python 字符串中 \b、\t 等会被解释为控制字符（例如 \boot.bin 会变成一个退格符加 oot.bin），从而破坏路径。

备注

使用 --partition-table 时，不再需要指定 --image 或 --image-dir，因为分区表已包含所有固件路径。

远程串口烧录

当 AmebaFlash 工具运行在远端服务器（如 Linux 编译服务器）上，而开发板及其烧录串口连接在本地 PC 时，可通过 远程串口烧录 功能经网络把本地串口转发给远端工具，从而直接烧录本地设备，无需将固件来回拷贝。

该功能依赖运行在 本地 PC 上的 Ameba Remote Service：本地 PC 启动该服务并监听端口后，远端的 AmebaFlash 通过 --remote-server 指向本地 PC 的 IP、--remote-password 提供认证密码，即可访问本地串口。

小心

远程串口烧录主要面向 SDK 位于 Linux 服务器、而开发板串口连接在本机 PC 的开发调试场景，通常配合 VS Code 远程开发使用。

单独使用 AmebaFlash 时不支持远程烧录功能，请直接在连接开发板的本机上运行 AmebaFlash 进行烧录。

备注

Ameba Remote Service 的下载、安装、启动与密码配置方法，与 VS Code 远程开发使用的服务完全一致，具体步骤请参考 VS Code 远程功能章节。

使用以下参数指定远程串口服务：

参数	说明
`--remote-server <IP>`	远端串口服务器的 IP 地址。
`--remote-password <password>`	远端服务器的认证密码。

--remote-server 192.168.0.1 --remote-password 123456

重要

连接串口的本地 PC（即 --remote-server 所指向的主机）必须已启动 Ameba Remote Service 并监听 TCP 端口 58916。

跳过烧录后复位

参数 --no-reset 阻止工具在烧录完成后复位设备，其优先级高于 Settings.json 中的 PostProcess 配置。

--no-reset

备注

适用于由上层软件控制复位信号、或烧录完成后设备需保持当前状态的场景。

保存日志

参数 -o / --log-file <path> 将工具的完整输出保存到文件。如果目录不存在，工具会自动创建。

--log-file /tmp/AmebaFlash.log

该参数可与任意操作（烧录、擦除、WiFi MAC 读取）组合使用。

日志级别

参数 --log-level 设置工具控制台输出的详细程度。默认值：info。

级别	说明
`debug`	输出详细的内部协议信息，适用于诊断通信故障。
`info`	标准操作信息，显示进度和结果。（默认值）
`warning`	仅输出警告及更高严重级别的信息。
`error`	仅输出错误信息。
`fatal`	仅输出致命错误信息。

--log-level debug

工具版本号查询

参数 -v / --version 打印当前工具版本号后退出。

--version

帮助信息

通过 --help 获取工具支持的完整参数列表：

$AmebaFlash.py --help / $AmebaFlash.exe --help
options:
   -h, --help                                         show this help message and exit
   -d, --download                                     download images
   -f PROFILE, --profile PROFILE                      device profile
   -p PORT [PORT ...], --port PORT [PORT ...]         serial port
   -b BAUDRATE, --baudrate BAUDRATE                   serial port baud rate
   -i IMAGE, --image IMAGE                            single image
   -r IMAGE_DIR, --image-dir IMAGE_DIR                image directory
   -a START_ADDRESS, --start-address START_ADDRESS    start address, hex
   -n END_ADDRESS, --end-address END_ADDRESS          end address, hex
   -z SIZE, --size SIZE                               size in KB
   -m {nor,nand,ram}, --memory-type {nor,nand,ram}    specified memory type (optional, derived from device profile when omitted)
   -e, --erase                                        erase flash
   -o LOG_FILE, --log-file LOG_FILE                   output log file with path
   -v, --version                                      show program's version number and exit
   --chip-erase                                       chip erase
   --log-level LOG_LEVEL                              log level
   --partition-table PARTITION_TABLE                  layout info, list
   --read-wifimac                                     read wifi mac
   --remote-server REMOTE_SERVER                      remote serial server IP address
   --remote-password REMOTE_PASSWORD                  remote serial server validation password
   --no-reset                                         do not reset after flashing finished

图形界面模式

除命令行模式外，AmebaFlash 还提供图形界面版本 Ameba 量产烧录工具 （AmebaMPFlashGUI.exe），面向生产线 1 拖 N 批量烧录场景。界面基于 Python 实现，在 Windows 与 Linux 上外观与操作一致。

启动方式

双击 AmebaMPFlashGUI.exe 或执行 AmebaMPFlashGUI.py 启动后，窗口标题显示为 Ameba 量产烧录工具 v<版本号>。可在配置页通过中文复选框在中英文界面之间切换。

界面概览

主界面由布局、下载、配置三个标签页组成，工具默认打开下载页，但在布局页加载设备 Profile 之前，下载页的内容保持禁用状态。请先加载 Profile。

../_images/flash_tool_gui_download_zh.svg

标签页说明

布局

通过浏览选择设备 Profile 文件（.rdev）。加载后，布局表格以只读方式展示该 Profile 中定义的固件分区：

列	含义
（勾选框）	该分区是否为必烧录项（只读，反映 Profile 定义）。
固件名	分区对应的固件名称。
起始地址 (Hex)	分区起始地址。
结束地址 (Hex)	分区结束地址。
存储类型	`RAM` / `NOR` / `NAND` 。
全区域擦除	烧录前是否全布局区域擦除（只读，反映 Profile 定义）。

加载 Profile 后，工具会根据 support_usb_download 字段自动启用或禁用下载页的 USB 下载 选项；同时清空已选固件，避免与新设备不匹配。

下载

设置波特率、固件、地址等烧录参数，扫描并选择目标设备，启动烧录等集中在此页。

控件	默认值	说明
波特率	1500000	串口通信波特率，可在下拉列表中选择（115200 ~ 4000000）。USB 下载时忽略。
固件/目录	—	点击浏览选择单个固件文件（`.bin`）或一个固件目录。选择文件后，长度自动填入文件大小；选择目录则按目录内布局烧录。
地址 (Hex)	0x08000000	烧录起始地址（仅烧录单个固件文件时使用）。
长度 (Hex)	0x0	烧录数据长度，选择固件文件后自动填充。
全片擦除	关闭	烧录前先擦除整片 Flash。
USB 下载	关闭	通过 USB（而非 LOGUART）烧录。仅当所选 Profile 支持时可勾选。该选项还会决定扫描设备时列出的端口类型。

页面底部的 扫描设备 用于刷新可用串口列表，下载用于启动烧录。

设备列表与进度

下载页下半部分为设备列表。每个检测到的串口占一行，由左至右为：

勾选框：是否对该设备执行烧录，标签为端口名与描述（如 COM12 (USB-Enhanced-SERIAL)）。
用时：该设备本次烧录的已用时间（分:秒）。
进度条：实时烧录进度与状态。

进度条状态如下：

状态	颜色	含义
`Idle`	—	空闲，尚未开始。
`0% ~ 100%`	蓝色	烧录进行中。
`PASS`	绿色	烧录成功。
`FAIL`	红色	烧录失败；将鼠标悬停在进度条上可查看具体错误信息。

列表上方提供全选 / 取消快捷链接，以及所有设备的总计用时。各设备相互独立、并行烧录，因此单个设备失败不会影响其余设备。

备注

每次烧录在后台依次执行以下阶段：协议握手 → Flash 容量检查 → Flash 写保护处理 → 烧录 → 固件校验 → 恢复写保护 → 烧录后处理。

进度条百分比仅反映烧录进度。

配置

此页集中管理烧录后处理、Flash 写保护处理、DTR/RTS、日志及界面语言等选项。

../_images/flash_tool_gui_configuration_zh.svg

选项	默认值	说明
工厂模式	关闭	锁定所有配置项，仅保留设备选择与烧录操作，适合生产线操作员使用。详见工厂模式。
自动编程 4 字节地址模式	开启	对容量 ≥ 16 MB 的 Flash 自动启用 4 字节地址模式。
使用 DTR/RTS 自动进入下载模式	开启	通过 DTR/RTS 信号线自动使设备进入下载模式，无需手动按键。
使用 DTR/RTS 自动复位设备	开启	烧录相关流程中通过 DTR/RTS 信号线自动复位设备。
按 Profile 布局拆分单固件	关闭	烧录单个合并固件时，按 Profile 布局切分并去除尾部 `0xFF` 填充后再烧录，节省烧录时间。对应 `SplitSingleImageByLayout` 配置项。启用后务必严格使用与合并固件实际布局一致的正确 Profile 文件 (不一定是官方自带的默认 Profile)；若 Profile 布局与合并布局不一致，切分边界会错位，导致烧录数据错误。烧录 NAND Flash 时必须勾选：NAND 会自动跳过坏块顺延烧录，不拆分会导致坏块后各分区地址整体偏移而烧录失败。
保存日志	开启	将每次运行的日志保存到 `{AmebaFlash}/log/` 目录下，文件名为启动时间戳（如 `2026_06_18_10_30_00.log`）。
日志级别	信息	日志详细程度：`致命` / `错误` / `警告` / `信息` / `调试`。仅在启用保存日志时可调。
后处理	复位设备	烧录完成后的动作： `无` / `指示下载结果` / `复位设备` / `跳至 RAM 启动`。
Flash 写保护处理	解锁并烧录	遇到 Flash 写保护时的策略： `尝试烧录` / `解锁并烧录` / `中止`。
中文	关闭	在中文与英文界面之间切换。

烧录流程

在布局页点击浏览，选择目标设备的 Profile 文件（.rdev）。加载成功后，下方表格会列出该设备的固件分区布局，下载页随之启用。
切换到下载页，点击浏览选择待烧录的固件文件（.bin）或固件目录，并按需调整 波特率 与地址。
用 USB/LOGUART 线连接所有目标设备，点击 扫描设备，列表中将列出检测到的串口。
勾选需要烧录的设备（可用全选 / 取消快速操作）。
点击下载，工具会对所有勾选的设备并行烧录，并实时显示各设备的进度与用时。

工厂模式

在配置页勾选 工厂模式 后，所有配置项（Profile、波特率、地址、各选项等）将被锁定，界面仅保留 扫描设备、设备勾选与下载操作。

备注

该模式适用于生产线：由工程师预先完成全部配置，操作员仅需连接设备并烧录，避免误改参数。

工厂模式状态会保存在 {AmebaFlash}/Settings.json 中，重启工具后仍保持开启。由于该模式下界面配置项均被锁定，无法直接在界面取消勾选，可通过以下任一方式退出工厂模式：

关闭工具，删除工具根目录下的 Settings.json 文件，然后重新启动工具；
关闭工具，将 Settings.json 中的 FactoryMode 参数修改为 false，然后重新启动工具。

安全启动烧录

若目标设备已启用 Secure Boot，Flashloader 同样需要进行安全启动配置。配置方法请参考安全启动。

配置完成后，将生成的 Flashloader 二进制文件复制到 {AmebaFlash}/Devices/Floaders/ 目录，覆盖原有文件。

配置参数

所有界面设置会在关闭工具时自动保存到 {AmebaFlash}/Settings.json。下次启动时自动恢复 Profile、端口、波特率、固件路径、各选项及界面语言。

配置文件提供对通信时序、烧录行为及后处理的精细控制，同时保存图形界面与命令行上次使用的烧录目标参数。所有键均为可选项；下表所示值为键缺失时应用的默认值。

本章节按适用范围分为两部分：

通用配置参数：CLI 与 GUI 通用的底层协议、时序与烧录行为参数；
图形界面配置参数：仅图形界面读取的参数，包括下载页各控件对应的烧录目标配置（每次启动自动回填），以及界面外观与产线模式设置。

通用配置参数

以下参数控制底层通信时序与烧录行为，CLI 与 GUI 均会读取。

参数	默认值	说明
`RomBootDelayInMillisecond`	`100`	ROM 启动后的等待时间（ms）。最小强制值：50 ms。
`UsbRomBootDelayInMillisecond`	`1000`	USB ROM 启动后的等待时间（ms）。最小强制值：200 ms。
`UsbFloaderBootDelayInMillisecond`	`1000`	USB Flashloader 启动后的等待时间（ms）。最小强制值：200 ms。
`FloaderBootDelayInMillisecond`	`1000`	Flashloader 二进制开始执行后的等待时间（ms）。
`BaudrateSwitchDelayInMillisecond`	`200`	切换到较高波特率后的稳定等待时间（ms）。
`SerialInitialReadTimeoutInMillisecond`	`20`	串口打开后首次读取的超时时间（ms）。
`RomCheckAliveTimeoutMilliSeconds`	`1000`	ROM 存活检测（握手探测）的超时时间（ms）。
`SensePacketCount`	`32`	烧写阶段两次 SENSE（状态确认）之间连续发送的数据包数量。
`RequestRetryCount`	`3`	请求失败时的最大重试次数。
`RequestRetryIntervalInMillisecond`	`10`	每次重试之间的等待时间（ms）。
`AsyncResponseTimeoutInMillisecond`	`1000`	等待设备异步响应的超时时间（ms）。
`SyncResponseTimeoutInMillisecond`	`1000`	等待设备同步响应的超时时间（ms）。
`WriteResponseTimeoutInMillisecond`	`2000`	等待设备确认写入命令的超时时间（ms）。
`SwitchBaudrateAtFloader`	`0`	设为 `1` 时，在 Flashloader 阶段切换波特率（而非 ROM 阶段）。
`AutoSwitchToDownloadModeWithDtrRts`	`1`	设为 `1` 时，通过 DTR/RTS 信号自动进入下载模式。详见 DTR/RTS 配置。
`AutoSwitchToDownloadModeWithDtrRtsTimingFile`	`"Reburn.cfg"`	进入下载模式的 DTR/RTS 时序配置文件路径。详见 DTR/RTS 配置。
`AutoSwitchToDownloadModeWithDtrRtsFirst`	`0`	设为 `1` 时，优先尝试 DTR/RTS 进烧录模式。
`AutoResetDeviceWithDtrRts`	`1`	设为 `1` 时，烧录完成后通过 DTR/RTS 自动复位设备。详见 DTR/RTS 配置。
`AutoResetDeviceWithDtrRtsTimingFile`	`"Reset.cfg"`	设备复位的 DTR/RTS 时序配置文件路径。详见 DTR/RTS 配置。
`FlashProtectionProcess`	`2`	Flash 写保护处理模式，详见 Flash 写保护处理方法。
`EraseByBlock`	`0`	设为 `1` 时，按块为单位擦除 Flash（而非按扇区）。
`AutoProgramSpicAddrMode4Byte`	`1`	设为 `1` 时，对大于 16 MB 的 Flash 自动启用 4 字节寻址。详见自动设置 4 字节寻址模式。
`ProgramConfig1`	`0`	GPIO/PWM 指示配置寄存器 1，详见 GPIO/PWM 指示。
`ProgramConfig2`	`0`	GPIO/PWM 指示配置寄存器 2，详见 GPIO/PWM 指示。
`DisableNandAccessWithUart`	`0`	设为 `1` 时，禁用 LOGUART 方式访问 NAND Flash。
`RamDownloadPaddingByte`	`0x00`	RAM 下载时使用的填充字节值。
`PostProcess`	`"RESET"`	烧录完成后的后续操作，详见烧录结束后操作。
`SplitSingleImageByLayout`	`false`	设为 `true` 时，将单个合并固件（如 `image_all.bin`）按 Profile 布局切分为各分区段，去除尾部 `0xFF` 填充后再烧录，避免烧写无意义的填充数据。详见按 Profile 布局拆分单固件。

DTR/RTS 配置

若硬件支持通过 DTR/RTS 信号自动进入下载模式与烧录后复位，可由上表中的 AutoSwitchToDownloadModeWithDtrRts / AutoResetDeviceWithDtrRts 等键控制启用，并通过对应的 ...TimingFile 键指定时序配置文件。

时序文件定义了 DTR/RTS 脉冲序列和延时值。工具随附的默认文件适配 Realtek 公版开发板。如需支持自定义硬件，可复制并修改时序文件，然后在 Settings.json 中更新对应路径。

# Reburn.cfg（进入下载模式的默认时序）
# 格式：
# <信号线>=<状态>
# delay=<延时毫秒>
dtr=0
rts=1
delay=200
dtr=1
rts=0
delay=100
dtr=0

# Reset.cfg（设备复位的默认时序）
dtr=0
rts=1
delay=200
rts=0
dtr=0

Flash 写保护处理方法

烧录过程中若遇到 Flash 写保护，将导致烧录失败。 FlashProtectionProcess 键控制工具的响应方式：

值	行为
`0`	在控制台暂停并等待用户输入（仅限 CLI 模式）。
`1`	继续尝试烧录，但可能会失败。
`2`	自动解除写保护，继续擦除/烧录，完成后恢复写保护。（默认值）
`3`	立即中止，不弹出交互提示，也不执行任何自动处理。

"FlashProtectionProcess": 2

烧录结束后操作

PostProcess 键指定烧录成功后对设备执行的操作。默认值："RESET"。

值	行为
`"NONE"`	不执行任何操作。
`"INDICATION"`	通过 GPIO/PWM 指示烧录成功或失败。
`"RESET"`	自动复位设备。（默认值）
`"BOOT"`	跳转至 RAM 并开始执行。
`"REBURN"`	复位设备并重新进入下载模式。

"PostProcess": "RESET"

备注

命令行参数 --no-reset 优先级高于 PostProcess：指定后会将后处理强制置为 "NONE"，从而跳过所有后处理操作（RESET / BOOT / REBURN / INDICATION），而不仅仅是阻止复位。

该覆盖仅在本次运行生效，不会写回 Settings.json。

GPIO/PWM 指示

在生产线上，GPIO/PWM 指示功能允许主机自动识别哪些设备已成功烧录，无需重新连接或手动检查。

ProgramConfig1 和 ProgramConfig2 键配置 GPIO/PWM 输出参数。完整位域说明参见下表。

Bit	Description
[63:32]	Download indication configuration: For GPIO indication Bit[63:33]: Reserved Bit[32]: GPIO output level For PWM indication Bit[63:57]: PWM duty cycle (0~100, unit: percent) Bit[56:32]: PWM period (unit: us)
[31:30]	Download indication strategy: 0: Disable 1: GPIO indication after download success 2: PWM indication after download success 3: Reserved
[29:16]	Download indication PIN name, refer to the SoC-specific definition of PinName for MBED API GPIO: all GPIO pins can be selected PWM: PWM channels can be selected
[15:2]	Reserved
[1:0]	NAND Flash bit flip fail level: 2/3: Reserved 1: Fail at fatal bit flip error, i.e. bit flip count > ECC level 0: Fail at bit flip error, i.e. bit flip count >= ECC level

自动设置 4 字节寻址模式

大于 16 MB 的 Flash 模组需要 4 字节寻址。若未启用 4 字节模式，超出 16 MB 的地址将无法访问，导致烧录失败。

AutoProgramSpicAddrMode4Byte 键控制此行为：

0：不启用 4 字节模式，直接报错。
1：自动写 OTP 启用 4 字节寻址并继续烧录。（默认值）

"AutoProgramSpicAddrMode4Byte": 1

小技巧

自动启用 4 字节模式时，工具会编辑对应的 OTP 位，并重启设备，使设置对设备永久生效。

因此，检测到容量大于 16 MB 的 Flash 烧录时，耗时会增加约 3~5 秒。

按 Profile 布局拆分单固件

以 合并 image 方式烧录单个固件（CLI 的 --image，或 GUI 下载页选择的单个 .bin 文件）时，该固件通常把多个分区拼接在一起，并用 0xFF 填充各分区未使用的尾部（主要是两段固件之间的空隙）。 SplitSingleImageByLayout 控制是否跳过这些无实际意义的填充的烧录：

false：将整个合并固件原样写入 Flash。（默认值）
true：按 Profile 的 Layout 将合并固件切分为各分区段，对每段去除尾部连续的 0xFF 填充

（按 4 字节对齐），并跳过内容全为 0xFF 的填充后再烧录，从而节省烧录时间。

"SplitSingleImageByLayout": false

警告

对 NAND Flash 以合并固件方式烧录时，必须启用本功能（CLI 设为 true，或在 GUI 配置页勾选 按 Profile 布局拆分单固件）。

NAND Flash 有坏块可能，工具烧录时会自动跳过坏块、将数据顺延写入后续可用块；若将整块合并固件当作一段连续数据写入，一旦中途遇到坏块，其后所有分区的数据都会整体顺延偏移，导致各分区无法落在 Layout 规定的块地址上，最终烧录失败或设备无法正常启动。

按 Profile 的布局拆分后，工具会将各分区分别烧录到其对应的块区间，坏块跳过被限制在单个分区内，分区起始地址保持正确；同时跳过分区间的 0xFF 填充，避免占用多余的块。

备注

拆分依据的是所选 Profile 的分区。因此以合并固件（如 image_all.bin）方式烧录并启用本功能时， 务必选用与该合并固件实际布局一致的 Profile (不一定是官方自带的默认 Profile)；若 Profile 布局与合并时的分区布局不一致，将导致切分边界错位、烧录数据错误。

若合并固件的起始地址未对齐到任何分区（如使用自定义地址），则不再按分区切分，但仍会去除整块固件末尾的 0xFF 填充。

该参数 CLI 与 GUI 通用；在 GUI 配置页对应 按 Profile 布局拆分单固件 复选框。

图形界面配置参数

以下参数仅图形界面（GUI）读取，命令行不使用。每次在界面上修改后，工具会自动将当前值保存到 Settings.json；下次启动 GUI 时自动读取并回填到界面，无需重新配置。

参数	默认值	说明
`Profile`	`""`	布局页中通过浏览加载的设备 Profile（`.rdev`）文件路径。启动时若此路径有效，工具会自动加载该 Profile 并启用下载页。
`Port`	`[]`	上次烧录时选择的串口列表，如 `["COM13", "COM40"]`。启动时自动回填，便于快速定位上次使用的设备端口。
`Baudrate`	`1500000`	下载页波特率下拉框中选中的串口通信波特率（bps）。
`Image`	`""`	下载页固件/目录中选中的单个固件文件（`.bin`）路径。
`ImageDir`	`""`	下载页固件/目录中选中的固件目录路径；按 Profile 中的 layout 批量烧录该目录下的固件。
`Address`	`0x08000000`	下载页地址 (Hex) 中输入的烧录起始地址（十六进制），仅烧录单个固件文件时使用。
`Length`	`0`	下载页长度 (Hex) 中的烧录数据长度（字节）； `0` 表示按固件文件实际大小处理。选择固件文件后由界面自动填充。
`FactoryMode`	`false`	工厂（生产）模式；设为 `true` 时锁定界面配置项，防止产线误改。
`ChipErase`	`false`	对应下载页全片擦除复选框；启用时烧录前先擦除整片 Flash。
`UsbDownload`	`false`	对应下载页 USB 下载复选框；启用时通过 USB 通道烧录。仅当所选 Profile 支持 USB 下载时可在界面勾选。
`SaveLog`	`true`	对应配置页保存日志复选框；启用时将烧录日志保存到 `{AmebaFlash}/log/` 目录。
`LogLevel`	`"info"`	对应配置页日志级别下拉框；可选值：`fatal` / `error` / `warning` / `info` / `debug`。
`GuiLanguageZh`	`false`	图形界面语言；`true` 为中文，`false` 为英文。
`GuiVisiblePorts`	`20`	图形界面启动时无需滚动即可显示的串口行数。该值受窗口实际高度限制：若显示屏较小或窗口高度不足，配置的行数可能无法完全铺开显示，超出窗口的部分仍需通过滚动查看。此时可适当调小该值，或放大窗口/使用更大的显示屏。

故障排除

无法连接设备

现象：工具无法进入下载模式，或在启动时打印超时错误（如 SYS_TIMEOUT、Finished FAIL）。

可能原因及解决方案：

串口号错误：在 Windows 设备管理器或 Linux 的 ls /dev/tty* 中确认正确的端口号。

确保没有其他程序（如串口终端）同时占用该端口。
设备未进入下载模式：若 DTR/RTS 自动进入功能被禁用或硬件不支持，

请在运行工具前确认设备是否进入烧录模式。详见设备进入烧录模式。
驱动未安装或有误：安装与开发板串口转换芯片（如 CH340、CP2102、FTDI）匹配的驱动，

确认设备在设备管理器中无报错。
USB 枚举延时不足：设备复位后，ROM Bootloader 需重新被主机 USB 总线枚举并完成驱动加载，

工具随后才能与其建立通信。在部分主机上，USB 枚举与驱动加载耗时较长、主机端响应延迟较高，

若工具在枚举完成前即发起握手，会因 ROM Bootloader 尚未就绪而连接失败。此时可适当增大 Settings.json 中的 UsbRomBootDelayInMillisecond（默认 1000 ms，最小 200 ms），为 USB 枚举预留充足时间；经 LOGUART 连接的设备则对应 RomBootDelayInMillisecond（默认 100 ms，最小 50 ms）。

下载超时或失败

现象：工具已成功连接，但烧录过程中卡住，或日志最后打印 Finished FAIL。

可能原因及解决方案：

波特率过高：降低波特率（如改为 921600 或 460800）。部分 USB 转串口适配器在 3 Mbps 下不够稳定。
USB/LOGUART 适配器不稳定：使用质量可靠的适配器并直接连接主机 USB 口。高速传输时避免使用无源 USB Hub。
Flash 写保护已开启：日志会出现写保护警告。确认 Settings.json 中 FlashProtectionProcess 保持默认值 2（自动解除写保护，烧录完成后恢复）。详见 Flash 写保护处理方法。
固件路径包含空格：在 Windows 及 MinGW 环境下，路径需加双引号：
```
--image "E:\路径含空格\image_all.bin"
```
杀毒软件干扰（仅 AmebaFlash.exe）：EXE 每次启动时会解压临时的 Python 运行环境，杀毒软件可能延迟或阻断这一过程。建议将 Windows %TEMP% 目录加入杀毒软件白名单，或直接使用 AmebaFlash.py。

打包版本在 Windows 上启动缓慢

现象：运行 AmebaFlash.exe 后，需要等待数秒才有 log 输出。

原因：AmebaFlash.exe 由 PyInstaller 以 --onefile 模式打包。每次启动时，它会将内嵌的 Python 运行库解压到临时目录再执行。在机械硬盘或杀毒软件监控临时目录的情况下，该过程耗时更长。

解决方案：

使用 AmebaFlash.py 配合本地已安装的 Python 3.8+ 环境，重复运行时速度更快。
将 Windows %TEMP% 目录加入杀毒白名单，减少解压延迟。

NAND Flash 坏块或位翻转警告

现象：日志显示 DEV_NAND_BAD_BLOCK、DEV_NAND_WORN_BLOCK、 DEV_NAND_BIT_FLIP_WARNING 或类似信息。

说明：这是 NAND flash 的正常特性。工具会自动跳过出厂标记的坏块并将数据重定向至备用块。

DEV_NAND_BIT_FLIP_WARNING：ECC 引擎已纠正位错误，该块仍可使用但正在老化。
DEV_NAND_BIT_FLIP_ERROR / DEV_NAND_BIT_FLIP_FATAL：ECC 无法完全纠正错误，该块已不可靠。

处理建议：如果出现坏块或者位翻转警告，建议标记坏块处理，具体方法参考 NAND 坏块管理。

1 拖 N 烧录部分端口失败

现象：指定多个端口时，部分设备显示 Finished PASS，其余显示 Finished FAIL。

说明：每个端口在独立线程中运行，某端口失败不影响其他端口。日志行首的端口名（如 [COM3]）可帮助快速定位问题设备。

排查步骤：

对失败端口单独运行工具，确认是设备问题还是主机问题。
确认所有设备在执行 1 拖 N 命令前已同时进入下载模式。
若多台设备共享同一 USB Hub，检查是否存在带宽瓶颈。建议使用有源 USB Hub

或专用 USB 扩展卡。

Profile 文件找不到

现象：工具打印 Device profile '...' does not exist 后立即退出。

解决方案：提供正确的 .rdev 文件绝对路径或相对路径。Profile 文件位于 AmebaFlash 安装目录下的 Devices/Profiles/ 文件夹中。

--profile Devices/Profiles/RTL8721Dx.rdev

远端串口连接问题

现象：指定 --remote-server 时，工具打印连接错误。

可能原因及解决方案：

远端串口服务必须在目标服务器上运行并监听 TCP 端口 58916，请确认服务已启动。
检查本机到远端服务器 IP 的网络连通性。
确认 --remote-password 与服务器配置的密码完全一致。

配置文件未生效

现象：修改 Settings.json 后，更改似乎没有生效。

解决方案：Settings.json 必须与 AmebaFlash.py / AmebaFlash.exe 位于同一目录。工具启动时会在日志中打印实际加载路径：

[main]Settings path: E:\AmebaFlash\Settings.json

对比日志中的路径与您编辑的文件路径。若系统中存在多份工具副本，请确保修改的是工具实际加载的那份配置文件。