# FLASH_WRITE

**Repository Path**: fx283/flash_-write

## Basic Information

- **Project Name**: FLASH_WRITE
- **Description**: 基于GD32W515的flash烧写器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-06
- **Last Updated**: 2026-08-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flash Writer

Flash Writer 是一款面向 SPI NOR Flash 的浏览器烧写器。GD32W515 通过原生 USB Full-Speed CDC 与 Web Serial 上位机通信，同时负责 J3 板外 Flash 的检测、供电、擦写、校验和回读，并对板载存储 U2、电源采样、LED、用户按键和蜂鸣器执行板级自检。

板载存储 U2 与 J3 板外 Flash 是两条完全独立的硬件通道：U2 只服务板内固件/日志，J3 才是“Flash 烧写”的默认目标。

## 仓库结构

```text
.
├── README.md                         当前产品和软件说明
├── hardware/                         只保存 PDF 版硬件资料
│   ├── FLASH_WRITER_schematic.pdf    最新原理图
│   └── FLASH_WRITER_pcb_layout.pdf  最新 PCB 点位/布局图
└── software/                         MCU 固件工程
    ├── src/                          应用源代码
    ├── inc/                          应用头文件和板级引脚定义
    ├── lib/                          CMSIS、GD32 外设库和 USB Device CDC 库
    ├── startup/                      Cortex-M33 启动文件
    ├── ld/                           链接脚本
    ├── usb_cdc_example/              USB 硬件辅助和 CDC 配置
    ├── tests/                        PC 端纯逻辑回归测试
    ├── doc/build_flash.bat           编译并通过 PW-Link 烧写
    └── Makefile                      底层编译规则
```

## 产品方案

硬件核心为 GD32W515PIQ6 MCU，板上提供两条 USB 相关链路：CH340 调试串口链路，以及 MCU 原生 USB CDC 链路。当前固件使用 MCU 原生 USB CDC，不依赖 CH340 的 UART 转换功能。

MCU 固件启动后完成以下工作：

1. 配置 IRC16M → PLL → 168 MHz 系统时钟，并生成 USBFS 所需的 48 MHz 时钟；
2. 初始化 USBFS Device 模式和 CDC ACM 虚拟串口；
3. USB 中断启用后保持软断开 250 ms，再重新连接，确保 Windows 能够重新枚举设备；
4. 在主循环中持续处理 CDC 收发、文本命令、用户按键和 LED 心跳；
5. 按键或串口命令触发板级硬件测试，并将结果通过 CDC 输出。

## 当前硬件映射

引脚按照仓库中的最新 PDF 原理图和点位图使用：

| 功能 | MCU 引脚 | 说明 |
|---|---|---|
| USB DP/DM | PB12/PB13 | MCU 原生 USBFS，AF10 |
| LED0 | PB6 | 低电平点亮 |
| LED1 | PA15 | 低电平点亮 |
| 用户按键 | PA2 | 内部上拉，按下为低电平 |
| 蜂鸣器 | PB5 | 高电平驱动三极管 |
| 外部 Flash QSPI | PA4/PA5/PA6/PA7/PB3/PB4 | QSPI，AF3，经 U6/TXS0108 连接 J3 |
| 板载 U2 SPI0 | PA9/PA10/PA11/PA12 | 仅为板载器件使用，不作为外部目标烧写通道 |
| NOR CS | PA12 | 普通 GPIO 软件片选 |
| ADC | PA3/PC0/PC1/PC2 | Flash VCC、1.8 V、3.3 V、5 V |

ADC 电源检测通道使用 1:1 电阻分压，MCU 采到的引脚电压需要乘以 2 才是实际电源电压。

### USB 硬件注意事项

MCU 原生 USB 路径上的外部 D+ 上拉电阻会影响 MCU 复位期间的 USB detach。当前硬件调试已经确认：必须移除原理图中的 R6 外部上拉电阻，让 USBFS 内部上拉由 USB 控制器管理。否则按住 MCU 复位键时 D+ 仍保持高电平，Windows 不会收到真正的 USB 断开事件，复位后 CDC 端口可能无法重新打开。

如果使用板上的可选 USB 路径，请确认 MCU CDC 路径和 CH340 路径的跳线状态不会同时连接，避免两个 USB 设备驱动器件争用同一组 D+/D- 信号。

## CDC 命令

串口打开后输入命令，以回车换行或单独换行结束：

| 命令 | 功能 |
|---|---|
| `HELP` | 显示命令列表 |
| `PING` | 返回 `PONG`，验证通信链路 |
| `ECHO <text>` | 原样返回参数 |
| `STATUS` | 输出系统时钟、tick、USB 状态和测试状态 |
| `ADC` | 采集并判断 1.8 V、3.3 V、5 V 等电源 |
| `STORAGE` | 读取板载存储 U2 的 JEDEC ID，并对保留的最后 4KB 扇区执行擦写回读校验 |
| `NOR` | `STORAGE` 的兼容别名，测试对象同样是板载存储 U2 |
| `LED` | 交替闪烁 LED0/LED1，需要人工观察 |
| `BEEP` | 输出 200 ms 蜂鸣器脉冲，需要人工听取 |
| `TEST` | 执行完整板级测试 |

按下板上的用户按键等价于执行 `TEST`。

## 软件实现方式

### USB CDC 控制台

官方 USBFS CDC ACM 驱动负责 USB 枚举、端点和中断处理；项目自己的 `cdc_console.c` 在上层增加了：

- 4 KB TX 环形队列，避免连续日志阻塞主循环；
- 2 KB RX 环形队列，支持 USB 包分割和连续输入；
- 128 字节命令行缓冲区；
- CR、LF、CRLF 三种行结束方式；
- USB 未配置、复位或断开时自动清理应用层状态。

应用代码不等待 CDC IN 端点完成，而是在主循环中持续调用 `cdc_console_poll()`。这样即使串口助手尚未打开，LED 和板级测试仍可以继续运行。

### 浏览器 CDC 通信协议

当前固件同时支持文本控制台和第一阶段二进制协议。收到 `0xAA` 时进入二进制帧解析，否则继续按文本命令处理。二进制帧格式为：

```text
SOF(0xAA) | VER | FLAGS | SEQ | CMD | LEN(LE) | PAYLOAD | CRC16(LE) | EOF(0x55)
```

协议层支持 USB 分包、粘包、CRC 错误恢复和请求序号关联。当前已实现 `HELLO`、`PING`、`GET_INFO`、`GET_STATUS`、`RUN_TEST` 和 `GET_TEST_DATA`，网页端通过 Web Serial 直接连接 MCU 原生 CDC。周期心跳由网页每 1 秒发送一次，连续 3 次超时显示离线。

### 板级测试

板级测试按“硬件初始化 → 执行测试 → CDC 输出结果”的方式组织：

- ADC 测试包含 ADC 超时保护、原始值输出、引脚电压和分压还原电压；
- 板载存储测试通过 SPI0 读取 U2 JEDEC ID，再擦除永久保留的最后 4KB 测试扇区，写入 256 字节模式并回读比较；
- 板测开始前临时关闭 J3 目标供电，避免外部 3.3V 供电影响 1.8V ADC；结束后恢复原来的单一目标电压；
- LED 和蜂鸣器测试输出固定时序，但最终物理现象需要人工确认；
- 用户按键采用 20 ms 消抖，并保证一次按下只触发一次完整测试。

## 编译和烧写

工具链要求：

- ARM GNU Toolchain，包含 `arm-none-eabi-gcc`；
- GNU Make；
- PowerShell；
- PyOCD；
- GigaDevice GD32W51x DFP 软件包；
- PW-Link 或兼容 CMSIS-DAP 调试器。

在 `software` 目录下执行：

```powershell
# 清理、编译并通过 PW-Link 烧写
doc\build_flash.bat clean

# 只编译，不烧写
doc\build_flash.bat build

# 默认编译并烧写
doc\build_flash.bat
```

DFP 软件包不放入本仓库。若 DFP 包不在原始工程的外部目录中，可以设置环境变量：

```powershell
$env:GD32_DFP_PACK = 'D:\Tools\GigaDevice.GD32W51x_DFP.1.0.3.pack'
doc\build_flash.bat
```

## 当前阶段边界

当前仓库现在包含 MCU 板级验证固件、硬件 PDF 图纸以及 Web Serial 上位机代码。

### Web 上位机

网页端代码位于整个工程工作区的 `H:\31_FLASH_Writer\04_APP_Code`，使用浏览器 Web Serial API 直接连接 MCU 的 USB CDC 虚拟串口。网页不依赖专用 Windows 串口驱动，也不需要额外安装桌面程序；在支持 Web Serial 的浏览器中通过 HTTP/HTTPS 页面即可使用。

当前网页端包含：

- `index.html`：上位机界面、分段烧写、完整回读和文件保存逻辑；
- `flash_logic.js`：Flash 型号、Intel HEX、数据预览和回读分块纯逻辑；
- `flash_logic.node.test.js`：可自动运行的网页纯逻辑回归测试；
- `protocol.js`：二进制帧编码、CRC16、帧解析和心跳管理；
- `protocol.test.html`：浏览器端协议回归测试页面；
- `Flash烧写器上位机_设计方案.md`：通信协议和后续 Flash 烧写功能规划。

当前网页已支持板外 Flash 自动电压检测、擦除、BIN/Intel HEX 固件预览与分段烧写、CRC32 校验、按芯片容量完整回读，以及回读数据保存为 BIN 或标准 Intel HEX。CDC 帧格式和既有命令号保持兼容。

注意：部分 Winbond 芯片的三字节 JEDEC ID 不能区分 1.8V 与 3.3V 系列。网页检测到这类 ID 时只显示“电压待确认”，由用户根据芯片完整料号手动选择供电电压，不会自动假定推荐电压。