# DAPLink Flash — GD32 固件烧录 · 双固件打包 · 补齐 · 拼接

> GD32E230 系列的桌面烧录/固件处理工具：**OpenOCD 烧录**（DAPLink / GD-Link /
> ST-Link / J-Link）+ **打包 v2**（双固件 profile 布局 → UPDATE / B / FULL 镜像
> + MD5 清单，与命令行工具共用 `fw_pack.py` 公共库）+ **补齐 Pad**（Y-Modem
> 页对齐）+ **拼接 Merge**（Bootloader + APP + 有效标志 → 整片镜像）。
>
> - **只想用工具**：到 [Gitea Releases](https://gitea.hulk.wang/hulk/gd32e230f8_firmware_merge_tool/releases)
>   下载 `DAPLinkFlash-vX.Y.Z-win64.zip`，解压双击 `DAPLinkFlash.exe`
>   （Windows 10/11 x64，免安装、无需 Python，**内置 OpenOCD 工具链**）。
> - **要改代码/重新打包**：见 §5、§6。
>
> 界面与构建方式对齐 DLPilot 项目（CustomTkinter 深色卡片仪表盘 +
> PyInstaller onedir + Gitea Release 发布）。更新：2026-10-22

## 1. 功能总览

| 功能 | 说明 |
|---|---|
| OpenOCD 烧录 | 检测设备 / 烧录固件 / 整片擦除 / 读取 Flash / 复位芯片 / 停止，OpenOCD 输出实时进日志区 |
| 固件格式 | BIN / HEX / ELF——HEX/ELF 自动用文件内地址，仅 BIN 需填基地址（完整镜像 `0x08000000`，单独 APP `0x08002000`） |
| 芯片型号 | GD32E230F4 / F6 / F8 / C8，自动带出 Flash 大小与 target 配置 |
| 烧录器 | DAPLink / CMSIS-DAP、GD-Link、ST-Link、J-Link、CMSIS-DAP(TCP)、Custom；支持适配器速度与探针序列号 |
| 打包 v2 | 双固件 profile 布局（默认 `ceramixnano_mb_v51`）：A/B 包向量表自动识别、补页+trailer/满槽+记录、CRC-16/XMODEM、FULL 整片镜像、MD5 清单、写盘回读复核 |
| 补齐 Pad | BIN 尾部补 `0xFF` 到 1K/2K/4K 页边界；bootloader 的 Y-Modem 只按 1K 整包写 Flash，最后一包不满必须先补齐 |
| 拼接 Merge | Bootloader + APP + 有效标志(`0xEEEEEEEE` @`0x0800FFFC`) → 整片 Flash 镜像，逻辑与 `merge_bin.py` 一致 |
| 内置工具链 | 发布包自带 OpenOCD(`toolchain/openocd/`)，GUI 自动定位，免安装免配置 |
| 命令行模式 | 全部功能可脚本化调用（`--flash / --pack / --pad / --merge ...`，见 §4） |
| 外观 | 跟随系统深/浅色，顶栏可切换 Dark / Light / System |

## 2. 下载与安装

1. 打开 [Releases 页面](https://gitea.hulk.wang/hulk/gd32e230f8_firmware_merge_tool/releases)，
   取最新的 `DAPLinkFlash-vX.Y.Z-win64.zip`；
2. 解压到**任意可写目录**（配置 `flash_gui_settings.json` 写在 exe 旁边）；
3. 进入解压出的 `DAPLinkFlash` 文件夹，双击 `DAPLinkFlash.exe`。
   目录版（onedir）无临时解压等待，启动接近秒开。

包内包含：

```
DAPLinkFlash/
├── DAPLinkFlash.exe        主程序（启动器）
├── _internal/              运行库（PyInstaller onedir, 须与 exe 同目录）
├── toolchain/openocd/      内置 OpenOCD（GUI 自动定位）
│   ├── bin/openocd.exe     + libftdi1.dll / libusb-1.0.dll
│   └── openocd/scripts/    interface / target 配置脚本
└── README.md               本说明
```

> **SmartScreen 拦截（"Windows 已保护你的电脑"）**：exe 未做代码签名，
> 浏览器下载的压缩包带"来自网络"标记。任选其一绕过：
> ① 点"更多信息 → 仍要运行"（每台电脑每个文件仅一次）；
> ② 下载后**先右键 zip → 属性 → 勾选"解除锁定"→ 确定**，再解压，包内所有文件都不会再拦；
> ③ 用 7-Zip / WinRAR 解压（不继承网络标记）。

## 3. GUI 使用

主窗口为单列仪表盘，打包/补齐/拼接经顶栏按钮弹出独立窗口：

```
顶栏  DAPLink Flash [打包 (v2)] [补齐 (Pad)] [拼接 (Merge)]   关于  Dark/Light/System
┌ 探针与工具链 [自动定位]                     ┐
├ 芯片与固件（型号/固件/基地址）               ┤
├ 运行日志 — OpenOCD 输出 / 打包校验          ┤
└ 操作: 检测/烧录/擦除/读取/复位/停止          ┘
弹窗  打包 (v2) / 补齐 (Pad) / 拼接 (Merge) — 非模态, 配置与主窗口共享
```

1. **选工具链**：默认自动定位（内置 → 本机 `D:/toolchain` → PATH），左卡右上
   "自动定位"可重新探测；也可手动浏览指定 `openocd.exe` 与 scripts 目录；
2. **选芯片与烧录器**：芯片型号下拉自动带出 Flash 大小和 target；烧录器下拉
   自动带出 interface cfg；多探针时填序列号；
   **自定义 cfg**：把自己的 OpenOCD cfg 文件（如工程定制的 target 配置）放进
   程序旁的 `cfgs/` 目录，"Target 配置"/"Interface 配置"下拉框即列出
   `cfgs/<文件名>` 供选用；`cfgs/` 会随发布包分发；
3. **选固件**：点"浏览"选 BIN/HEX/ELF；BIN 确认基地址（完整镜像 `0x08000000`，
   单独 APP `0x08002000`）；
4. **点"检测设备"**确认链路通 → **点"烧录固件"**；输出实时显示在右下日志区；
5. **固件工具**（顶栏按钮弹出的独立窗口，非模态）：
   - 打包 v2：选 profile（内置下拉或浏览 JSON）+ BL/A 包/B 包 bin（至少一个）+
     输出目录，点"执行打包"→ `*_UPDATE.bin` / `*_B.bin` / `*_FULL.bin` + MD5 清单；
     A/B 槽按向量表自动校验，逐项字节校验与回读复核结果流进主日志；
   - 补齐：选输入 BIN 后输出名自动带出（`*_update.bin`，Y-Modem 升级包），对齐默认 1K，点"执行补齐"；
   - 拼接：选 Bootloader 与 APP 后输出名自动带出（`*_BL.bin`，整片镜像），地址按典型布局
     预填，点"执行拼接"。

v2 双固件布局（默认 profile `ceramixnano_mb_v51`）与打包规则详见仓库根
[README.md](../README.md)；legacy 单槽布局：`0x08000000` Bootloader 8KB |
`0x08002000` APP | `0x0800FFFC` 有效标志 `0xEEEEEEEE`。

配置（全部输入框的值）自动保存在 exe 旁的 `flash_gui_settings.json`，下次启动
自动恢复；旧版 `config/flash_gui_<主机名>.json` 在首次启动时自动迁移。

## 4. 命令行模式

exe 版无控制台，脚本化请用源码方式（或 `build_exe.py --debug` 打的带控制台变体）：

```
python src/flash_gui.py                        启动 GUI
python src/flash_gui.py --seconds 5            GUI 5 秒自动关闭(冒烟测试)
python src/flash_gui.py --version              打印 OpenOCD 版本(验证工具链定位)
python src/flash_gui.py --detect               检测烧录器与目标芯片
python src/flash_gui.py --flash app.bin        烧录(BIN 默认基地址 0x08000000)
python src/flash_gui.py --flash app.bin --base 0x08002000 --no-reset
python src/flash_gui.py --erase                整片擦除
python src/flash_gui.py --read dump.bin        读取整片 Flash
python src/flash_gui.py --reset                复位运行
python src/flash_gui.py --pad app.bin          补齐到 1K → app_pad.bin
python src/flash_gui.py --merge bl.bin app.bin 拼接 → app_BL.bin
python src/flash_gui.py --pack a.bin b.bin --pack-bl bl.bin -o outdir
                                             v2 双固件打包 → UPDATE/B/FULL+MD5
  --align N / --pad-byte 0xFF / -o OUT         pad 参数(-o 对 pack 为目录)
  --app-addr / --flag-addr / --flash-size / --flag-value   merge 参数
  --pack-profile ceramixnano_mb_v51|JSON / --pack-no-full  pack 参数
  --speed 4000 / --serial SN / --interface cfg / --target cfg
  --openocd PATH / --scripts DIR               手动指定工具链(默认自动定位)
```

退出码：OpenOCD 操作非 0 即失败，可直接用于 CI/脚本串联。

## 5. 目录结构与从源码运行

```
FlashTool/
├── src/                        # 源代码（人工维护区）
│   ├── flash_gui.py            # 入口与命令行模式（argparse 分发）
│   ├── app_gui.py              # CustomTkinter 主界面（单列仪表盘 + 打包/补齐/拼接弹窗）
│   ├── openocd_runner.py       # 工具链定位 / OpenOCD 命令构建与子进程
│   ├── fw_image.py             # 补齐(pad)/拼接(merge) + 芯片参数表
│   ├── config.py               # 运行目录与 flash_gui_settings.json 配置
│   ├── build_exe.py            # PyInstaller 打包 → release/
│   ├── package_release.py      # 组装发布 zip（exe + 内置 OpenOCD 工具链）
│   ├── publish_gitea.py        # 上传到 Gitea Release
│   └── logos/                  # 图标源（make_ico.py + png/ico）
├── release/                    # 构建与发布产物（机器生成区, 不手改/不入库）
│   ├── DAPLinkFlash/           # onedir 程序目录: exe + _internal/ + toolchain/
│   └── *.zip                   # 发布包（上传 Gitea Release）
├── toolchain/openocd/          # (可选) vendor 进仓库的工具链, 不入库
├── start_flash_gui.bat         # 源码模式双击启动器
└── README.md                   # 本说明
```

从源码运行：`python src/flash_gui.py` 或双击 `start_flash_gui.bat`，
需 Python ≥3.10 + customtkinter（`py -m pip install customtkinter`）；
OpenOCD 默认找本机 `D:/toolchain/openocd`，要 vendor 的话把工具链放到
`FlashTool/toolchain/openocd/`（`package_release.py` 打包时同样优先取这里）。

> **fw_pack.py**（v2 打包公共库）位于**仓库根目录**（与命令行工具共用，单一真相）：
> 源码模式由 `app_gui.py`/`flash_gui.py` 自动把仓库根补进 `sys.path`；
> PyInstaller 打包由 `build_exe.py` 的 `--paths 仓库根 --hiddenimport fw_pack`
> 收进运行库，不要把副本复制进 `src/`。

## 6. 构建与发布

```powershell
cd src
python logos/make_ico.py        # (可选) 改图标后重新生成 png/ico, 需 Pillow
python build_exe.py             # 打包 → ../release/DAPLinkFlash/(onedir 目录版,
                                #   启动秒开; 自动装 PyInstaller, CTk 主题数据自动收集)
python build_exe.py --debug     # 额外出一个带控制台的调试变体(命令行模式可见输出)
python package_release.py 0.1.0 # 组装 release/DAPLinkFlash-v0.1.0-win64.zip
                                #   含内置 OpenOCD 工具链(来源见脚本说明)
python publish_gitea.py DAPLinkFlash-v0.1.0-win64.zip --insecure
                                # 上传 Gitea Release(需环境变量 GITEA_TOKEN)
```

版本号默认从最近的 `DAPLinkFlash-v*` git tag 推断，无 tag 时手动指定。

## 7. 注意事项 / FAQ

- **"Windows 已保护你的电脑"（SmartScreen）**：exe 无代码签名所致，
  处理见 §2 的三种绕过方式；要彻底消除需购买代码签名证书对 exe 签名；
- **"找不到 OpenOCD"**：点"自动定位"；发布包用户确认解压后 `toolchain/openocd/`
  目录和 exe 在一起；
- **`Error connecting DP: cannot read IDR`（SWD 完全连不上）**：目标板对 SWD
  无应答，与工具/命令无关，按序排查：
  ① 目标板是否已上电（DAPLink 指示灯亮 ≠ 板子有电，两者供电独立）；
  ② DAPLink 的 **RST 引脚必须接到 GD32 的 NRST**——本类工程固件运行后会把
  SWD 引脚复用为 LED，必须"按住复位连接"（内置 `cfgs/openocd_gdlink_gd32e23x.cfg`
  已配置 `connect_assert_srst`），RST 线没接/松脱时就是这个错；
  ③ 拔插 DAPLink 的 USB、目标板彻底断电再上电（深睡/锁死状态恢复）；
  ④ 速度降到 1000 kHz；
  ⑤ 确认运行的是 `DAPLinkFlash` 文件夹里的 exe（日志第一屏工具链应显示"内置"，
  OpenOCD 版本 0.11.0-3、target 为 `cfgs/...` 才是新版）；
- **烧录失败排查**：①"检测设备"先验链路；② 探针序列号留空可排除序列号问题；
  ③ 速度过高可降到 1000 kHz；④ DAPLink 固件过旧换 GD-Link 固件试试；
- **exe 放只读目录**：`flash_gui_settings.json` 写在 exe 旁边，只读目录存不了配置；
- **重新打包后图标没变**：Windows 图标缓存，`ie4uinit -show` 或改个名即可；
- **残留进程**：修改源码重新打包前先结束残留的 DAPLinkFlash 进程
  （`build_exe.py` 会自动 taskkill）；
- **配置互不影响**：exe 与源码脚本各自按所在目录保存 `flash_gui_settings.json`。