refactor(flash-gui): 对齐 DLPilot 重构 GUI 并内置 OpenOCD 发布链
This commit is contained in:
+138
-39
@@ -1,55 +1,154 @@
|
||||
# DAPLink Flash GUI
|
||||
# DAPLink Flash — GD32 固件烧录 · 补齐 · 镜像拼接
|
||||
|
||||
一个面向 GD32 日常烧录的 Windows 小工具，不依赖 VSCode，也不用记 OpenOCD 命令。
|
||||
双击 `start_flash_gui.bat` 即可启动。
|
||||
> GD32E230 系列的桌面烧录/固件处理工具：**OpenOCD 烧录**（DAPLink / GD-Link /
|
||||
> ST-Link / J-Link）+ **补齐 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 onefile + Gitea Release 发布）。更新：2026-09-14
|
||||
|
||||
## 功能
|
||||
## 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；支持适配器速度与探针序列号 |
|
||||
| 补齐 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 / --pad / --merge ...`，见 §4） |
|
||||
| 外观 | 跟随系统深/浅色，顶栏可切换 Dark / Light / System |
|
||||
|
||||
- 芯片型号：GD32E230F4 / F6 / F8 / C8，自动带出 Flash 大小和 OpenOCD target 配置
|
||||
- 烧录器型号：DAPLink / CMSIS-DAP、GD-Link、ST-Link、J-Link、CMSIS-DAP (TCP)
|
||||
- OpenOCD 路径和 scripts 目录可配置，默认使用 `D:/toolchain` 下同一套工具
|
||||
- BIN 文件可指定烧录基地址，HEX/ELF 使用文件内地址
|
||||
- 常用烧录参数：适配器速度、探针序列号、烧录前擦除、烧录后校验、复位运行
|
||||
- 操作：检测设备、整片擦除、烧录固件、读取 Flash、复位芯片、停止当前操作
|
||||
## 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.exe`。首次启动比脚本慢一两秒（onefile 解压），属正常现象。
|
||||
|
||||
- 补齐：把 BIN 填充到 1K（或 2K/4K）整数倍，默认填充 `0xFF`。
|
||||
因为 bootloader 的 Y-Modem 只按 1K 整包写 Flash，最后一包不满 1K 时
|
||||
必须先在发送侧补齐。
|
||||
- 拼接：把 Bootloader + APP + 有效标志合成一个完整 Flash 镜像，
|
||||
逻辑与 `gd32e230f8_firmware_merge_tool/merge_bin.py` 一致。
|
||||
包内包含：
|
||||
|
||||
## 典型布局
|
||||
|
||||
```text
|
||||
0x08000000 Bootloader 8KB
|
||||
0x08002000 Application
|
||||
0x0800FFFC 有效标志 0xEEEEEEEE
|
||||
0x08010000 Flash 结束 (64KB)
|
||||
```
|
||||
DAPLinkFlash/
|
||||
├── DAPLinkFlash.exe 主程序（单文件自包含）
|
||||
├── toolchain/openocd/ 内置 OpenOCD（GUI 自动定位）
|
||||
│ ├── bin/openocd.exe + libftdi1.dll / libusb-1.0.dll
|
||||
│ └── openocd/scripts/ interface / target 配置脚本
|
||||
└── README.md 本说明
|
||||
```
|
||||
|
||||
完整镜像烧录基地址为 `0x08000000`；只烧 APP 时基地址为 `0x08002000`。
|
||||
## 3. GUI 使用
|
||||
|
||||
## 使用
|
||||
主窗口为双栏仪表盘：
|
||||
|
||||
1. 连接 DAPLink 和目标板 SWD（SWDIO / SWCLK / GND）。
|
||||
2. 双击 `start_flash_gui.bat`，或执行：
|
||||
```
|
||||
左列 右列
|
||||
┌ 探针与工具链 [自动定位] ┐ ┌ 补齐 (Pad) — Y-Modem 对齐 ┐
|
||||
├ 芯片与固件（型号/固件/基地址）┤ ├ 拼接 (Merge) — BL+APP+标志 ┤
|
||||
└ 操作: 检测/烧录/擦除/读取/复位/停止 ┘ └ 运行日志 — OpenOCD 输出 ┘
|
||||
```
|
||||
|
||||
```bat
|
||||
python daplink_flash_gui.py
|
||||
```
|
||||
1. **选工具链**：默认自动定位（内置 → 本机 `D:/toolchain` → PATH），左卡右上
|
||||
"自动定位"可重新探测；也可手动浏览指定 `openocd.exe` 与 scripts 目录；
|
||||
2. **选芯片与烧录器**：芯片型号下拉自动带出 Flash 大小和 target；烧录器下拉
|
||||
自动带出 interface cfg；多探针时填序列号；
|
||||
3. **选固件**：点"浏览"选 BIN/HEX/ELF；BIN 确认基地址（完整镜像 `0x08000000`，
|
||||
单独 APP `0x08002000`）；
|
||||
4. **点"检测设备"**确认链路通 → **点"烧录固件"**；输出实时显示在右下日志区；
|
||||
5. **固件工具**（右列）：
|
||||
- 补齐：选输入 BIN 后输出名自动带出（`*_pad.bin`），对齐默认 1K，点"执行补齐"；
|
||||
- 拼接：选 Bootloader 与 APP 后输出名自动带出（`*_BL.bin`），地址按典型布局
|
||||
预填，点"执行拼接"。
|
||||
|
||||
3. 选择芯片型号、烧录器型号、固件文件，点击“烧录固件”。
|
||||
典型布局：`0x08000000` Bootloader 8KB | `0x08002000` APP | `0x0800FFFC`
|
||||
有效标志 `0xEEEEEEEE` | `0x08010000` Flash 结束 (64KB)。
|
||||
|
||||
运行参数会自动保存到 `FlashTool/config/flash_gui_<主机名>.json`。首次打开会自动创建
|
||||
`config` 目录并生成当前电脑的配置；下次打开检测到就加载，没有就重新创建。
|
||||
每台电脑使用独立文件名，同步仓库时不会互相覆盖。
|
||||
配置（全部输入框的值）自动保存在 exe 旁的 `flash_gui_settings.json`，下次启动
|
||||
自动恢复；旧版 `config/flash_gui_<主机名>.json` 在首次启动时自动迁移。
|
||||
|
||||
## 环境要求
|
||||
## 4. 命令行模式
|
||||
|
||||
- Windows
|
||||
- Python 3.10+（标准安装自带 tkinter，无需第三方库）
|
||||
- OpenOCD（默认 `D:/toolchain/openocd/bin/openocd.exe`，可在界面中修改）
|
||||
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
|
||||
--align N / --pad-byte 0xFF / -o OUT pad 参数
|
||||
--app-addr / --flag-addr / --flash-size / --flag-value merge 参数
|
||||
--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.exe # 打包单文件版
|
||||
│ ├── toolchain/openocd/ # package_release.py 复制的内置工具链
|
||||
│ └── *.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`）或先跑一次
|
||||
`package_release.py` 把工具链放进 `release/toolchain/`。
|
||||
|
||||
## 6. 构建与发布
|
||||
|
||||
```powershell
|
||||
cd src
|
||||
python logos/make_ico.py # (可选) 改图标后重新生成 png/ico, 需 Pillow
|
||||
python build_exe.py # 打包 → ../release/DAPLinkFlash.exe(约 19MB;
|
||||
# 自动装 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
|
||||
|
||||
- **"找不到 OpenOCD"**：点"自动定位"；发布包用户确认解压后 `toolchain/openocd/`
|
||||
目录和 exe 在一起；
|
||||
- **烧录失败排查**：①"检测设备"先验链路；② 探针序列号留空可排除序列号问题；
|
||||
③ 速度过高可降到 1000 kHz；④ DAPLink 固件过旧换 GD-Link 固件试试；
|
||||
- **exe 放只读目录**：`flash_gui_settings.json` 写在 exe 旁边，只读目录存不了配置；
|
||||
- **重新打包后图标没变**：Windows 图标缓存，`ie4uinit -show` 或改个名即可；
|
||||
- **残留进程**：修改源码重新打包前先结束残留的 DAPLinkFlash 进程
|
||||
（`build_exe.py` 会自动 taskkill）；
|
||||
- **配置互不影响**：exe 与源码脚本各自按所在目录保存 `flash_gui_settings.json`。
|
||||
|
||||
Reference in New Issue
Block a user