# GD32E230 固件工具

本仓库提供 GD32E230 系列固件的处理与烧录工具：

- **DAPLink Flash GUI（推荐）**：图形界面烧录工具，位于 `FlashTool/`
- **命令行固件工具**：`gd32e230_firmware_tool.py`（合成 + 补齐二合一）
- **旧版脚本**：`merge_bin.py`、`fill_bin.py`（保留兼容）

## Flash 布局

```text
0x08000000  ┌──────────────────┐
            │   Bootloader     │  8KB
0x08002000  ├──────────────────┤
            │                  │
            │   Application    │  最大 54KB (F8) / 22KB (F6) / 6KB (F4)
            │                  │
0x0800F800  ├──────────────────┤
            │   校准数据        │  1KB (预留)
0x0800FC00  ├──────────────────┤
            │   0xEEEE 标志     │  1KB
0x08010000  └──────────────────┘
```

- 空白区域填充 `0xFF`（Flash 擦除默认值）
- 标志位 `0xEEEE` 告诉 Bootloader：APP 有效，直接跳转
- 校准页当前为预留空间

## DAPLink Flash GUI（推荐）

日常烧录优先使用图形界面工具，不需要打开 VSCode，也不需要记忆 OpenOCD 命令。

- **免安装版**：到 [Gitea Releases](https://gitea.hulk.wang/hulk/gd32e230f8_firmware_merge_tool/releases)
  下载 `DAPLinkFlash-vX.Y.Z-win64.zip`，解压后进入 `DAPLinkFlash` 文件夹
  双击 `DAPLinkFlash.exe` 即可，**包内自带 OpenOCD 工具链**
  （`toolchain/openocd/`），目标机器无需任何环境。
- **源码运行**：`python FlashTool/src/flash_gui.py` 或双击 `FlashTool\start_flash_gui.bat`
  （需 Python 3.10+ 与 `pip install customtkinter`；OpenOCD 默认找 `D:/toolchain`）。

详细说明见 [FlashTool/README.md](FlashTool/README.md)（GUI 截图说明、命令行模式、
构建与发布流程）。下面是旧单文件版说明保留的要点：

### 功能

- 烧录操作：检测设备、整片擦除、烧录固件、读取 Flash、复位芯片、停止
- 固件格式：BIN / HEX / ELF
  - BIN：手动填写烧录基地址
  - HEX / ELF：自动使用文件内地址
- 芯片型号：GD32E230F4 / F6 / F8 / C8，自动带出 Flash 大小和 target 配置
- 烧录器：DAPLink / CMSIS-DAP、GD-Link、ST-Link、J-Link
- 烧录参数：适配器速度、探针序列号、烧录前擦除、烧录后校验、烧录后复位运行
- 固件处理：补齐（1K / 2K / 4K）、拼接 Bootloader + APP + 有效标志
- 工具链自动定位：内置（exe 旁 `toolchain/openocd`）→ 本机 `D:/toolchain` → PATH

### 配置

- 配置文件：`flash_gui_settings.json`，保存在程序目录（exe 旁 / FlashTool 根），
  自动保存与恢复
- 旧版 `config/flash_gui_<主机名>.json` 在新版首次启动时自动迁移

### 使用步骤

1. 连接烧录器（DAPLink / GD-Link 等）到目标板 SWD：SWDIO、SWCLK、GND
2. 启动 GUI，选择芯片型号和烧录器型号
3. 选择固件文件并确认地址：
   - 完整镜像（bootloader + app）：`0x08000000`
   - 单独烧录 APP：`0x08002000`
4. 点击“检测设备”确认连接正常
5. 点击“烧录固件”

> Bootloader 的 Y-Modem 只按 1K 整包接收，OTA 升级包发送前请先用“补齐”功能处理。

## 命令行固件工具

### 快速开始

```bash
# 合成完整镜像（整片烧录用）
python gd32e230_firmware_tool.py -m app.bin

# 补齐升级包（Ymodem 升级用）
python gd32e230_firmware_tool.py -f app.bin
```

### 模式说明

#### `-m` / `--merge` — 合成完整镜像

将 Bootloader + APP + FLAG 合并为一个 Flash 镜像，直接整片烧录。**不补齐**（整片烧录无需考虑页对齐）。

```bash
python gd32e230_firmware_tool.py -m CeramixNano-MB_V1.0.9.bin
```

输出：`CeramixNano-MB_V1.0.9_BL.bin`

#### `-f` / `--fill` — 补齐升级包

将 APP 尾部补 `0xFF` 到 1KB 页边界，供 Bootloader 的 Ymodem 接收端使用。补齐后自动检查是否超过芯片 APP 容量上限。

```bash
python gd32e230_firmware_tool.py -f CeramixNano-MB_V1.0.9.bin
```

输出：`CeramixNano-MB_V1.0.9_UPDATE.bin`

### 参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `app` | (必填) | APP 的 .bin 文件 |
| `-m, --merge` | — | 合成完整 Flash 镜像 |
| `-f, --fill` | — | 补齐到整页边界 |
| `-s, --flash-size` | `F8` | 芯片型号：`F4`(16K) `F6`(32K) `F8`(64K) |
| `-b, --bootloader` | `gd32e230f8_bootloader_hulk.bin` | Bootloader .bin 路径 |
| `-o, --output` | 自动生成 | 输出文件路径 |
| `-h, --help` | — | 查看帮助 |

> **`-m` 和 `-f` 互斥**，每次只能选一种模式。

### 使用示例

```bash
# F8 合成镜像（默认）
python gd32e230_firmware_tool.py -m CeramixNano-MB_V1.0.9.bin

# F6 合成镜像
python gd32e230_firmware_tool.py -m app.bin -s F6

# F8 补齐升级包（默认）
python gd32e230_firmware_tool.py -f app.bin

# F4 补齐升级包
python gd32e230_firmware_tool.py -f app.bin -s F4

# 自定义 Bootloader 和输出路径
python gd32e230_firmware_tool.py -m app.bin -b my_bootloader.bin -o release.bin
```

### 输出示例

**merge 模式：**

```text
芯片: GD32E230F8 (64KB)

合成完成: CeramixNano-MB_V1.0.9_BL.bin
  芯片       : 64KB
  Bootloader :   3272B  @ 0x08000000
  Application:  25600B  @ 0x08002000
  Flag       : 0xEEEE     @ 0x0800FFFC
  校准预留   : 1KB      @ 0x0800F800
  APP 剩余   :  29696B
  总大小     :  65536B  (64KB)
```

**fill 模式：**

```text
芯片: GD32E230F8 (64KB)
补齐完成: app_UPDATE.bin
  原始大小: 25000B
  页大小  : 1024B (1KB)
  补齐字节: 600B
  输出大小: 25600B
  APP 上限: 55296B (54KB) → 剩余 29696B
```

**超限拦截：**

```text
错误：APP (60000B / 58.6KB) 超过最大容量 (55296B / 54KB)
  芯片 64KB: 64KB - 8KB(BL) - 1KB(校准) - 1KB(Flag) = 54KB
```

### 旧版脚本

`merge_bin.py` / `fill_bin.py` 为旧版命令行脚本，功能已合并进 `gd32e230_firmware_tool.py`，历史说明见 [README_old.md](README_old.md)。

### 烧录

```bash
# OpenOCD
openocd -f interface/cmsis-dap.cfg -f target/gd32e23x.cfg \
  -c "init; reset halt; flash write_image erase merged.bin 0x08000000; reset; exit"

# J-Link
JFlash -openprj project.jflash -open merged.bin,0x08000000 -auto -exit
```

### 安全校验

- Bootloader 体积不超过 APP 起始偏移（8KB）
- APP 大小不超过芯片可用空间
- fill 模式补齐后再次校验容量上限
- 芯片不支持自动检测，需通过 `-s` 手动指定

## License

MIT