# GD32E23x 工程模板

本仓库为兆易创新 GD32E23x 系列 MCU 的 CMake + VSCode 工程模板，适合嵌入式开发快速上手和团队协作。

---

## 目录

- [适用范围](#适用范围)
- [默认配置](#默认配置)
- [工具链准备](#工具链准备)
- [使用说明](#使用说明)
- [时钟配置说明](#时钟配置说明)
- [vcpkg 依赖管理（可选）](#vcpkg-依赖管理可选)
- [建议补充内容](#建议补充内容)

---

## 适用范围

- 适用于兆易创新 GD32E23x 系列 Cortex-M23 内核单片机
- 支持标准外设库开发
- 推荐开发环境：VSCode + CMake + ARM GCC 工具链

---

## 默认配置

- MCU 主频：内部 RC 振荡器，系统时钟配置为 72MHz

---

## 工具链准备

### 1. xPack GNU Arm Embedded GCC Toolchain

- **版本**：xpack-arm-none-eabi-gcc-11.3.1-1.1  
- **建议解压路径**：Tools/xpack-arm-none-eabi-gcc-11.3.1-1.1  
- **官方下载地址**：https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack/releases  
- **路径自定义说明**：  
  如需自定义工具链路径，请同步修改以下文件：  
  - `Projects/<BoardName>/<ProjectName>/cmake/arm-none-eabi-gcc.cmake`（第2行）  
  - `Projects/<BoardName>/<ProjectName>/.vscode/launch.json`（第12行）

### 2. OpenOCD

- **版本**：xpack-openocd-0.11.0-3  
- **建议解压路径**：Tools/xpack-openocd-0.11.0-3  
- **获取地址**：https://github.com/burakenez/gd32-tools-xpack-openocd/tree/v0.11.0-3  
- **说明**：  
  - 本版本提取自 Embedded Builder V1.4.1.23782。  
  - ⚠️ 请勿随意更换版本，因 GD32 MCU 支持有限，推荐严格使用此版本。  
- **路径自定义说明**：  
  如需自定义 OpenOCD 路径，请同步修改以下文件：  
  - `Projects/<BoardName>/<ProjectName>/.vscode/launch.json`（第14、17行）  
  - `Projects/<BoardName>/<ProjectName>/.vscode/task.json` 中所有相关路径

---

## 使用说明

1. **准备工具链**  
   - 按上述说明下载并解压 ARM GCC 和 OpenOCD 到 Tools 目录。
   - Toolchain 目录内容不会被 git 跟踪，需自行维护。

2. **烧录固件**  
   - 可直接使用 VSCode 任务栏的 Flash MCU 任务，或命令行运行 OpenOCD。

---

## 时钟配置说明

本工程默认系统时钟为内部 IRC8M 振荡器经 PLL 倍频后的 72MHz。

如需修改主频或时钟源，请编辑 `Src/system_gd32e23x.c` 文件：

1. 查找如下宏定义区：
   ```c
   // #define __SYSTEM_CLOCK_8M_HXTAL              (__HXTAL)
   // #define __SYSTEM_CLOCK_8M_IRC8M              (__IRC8M)
   // #define __SYSTEM_CLOCK_72M_PLL_HXTAL         (uint32_t)(72000000)
   #define __SYSTEM_CLOCK_72M_PLL_IRC8M_DIV2    (uint32_t)(72000000)
   ```
2. 取消你需要的时钟方案的注释，并注释掉其它方案。
3. 保存后重新编译工程即可生效。

详细时钟初始化流程可参考 `system_gd32e23x.c` 文件中的 `system_clock_config` 及相关函数实现。

---

## vcpkg 依赖管理（可选）

本工程可选支持 vcpkg 作为 C/C++ 工具链和构建工具的自动化依赖管理方案。

- 自动下载和管理如 CMake、Ninja 等构建工具，简化环境配置。
- 可扩展用于第三方 C/C++ 库的统一管理。

**启用方法**：
1. 在项目根目录创建 `vcpkg-configuration.json` 文件，内容如下：

   ```json
   {
     "registries": [
       {
         "name": "microsoft",
         "location": "https://aka.ms/vcpkg-ce-default",
         "kind": "artifact"
       },
       {
         "name": "arm",
         "location": "https://aka.ms/vcpkg-artifacts-arm",
         "kind": "artifact"
       }
     ],
     "requires": {
       "arm:tools/ninja-build/ninja": "^1.12.0",
       "arm:tools/kitware/cmake": "^3.28.4"
     }
   }
   ```

2. 启动 VSCode 或命令行，vcpkg 会自动检测并安装所需工具。

如不需要 vcpkg，可忽略本文件。

---

## 建议补充内容

- **快速上手示例**：如 main.c 的最小点灯/串口输出代码片段。
- **常见问题与解答**：如构建失败、烧录失败的排查建议。
- **调试说明**：如何用 VSCode 调试、断点、查看寄存器等。
- **多板卡适配说明**：如有多种硬件，如何切换 BoardName。
- **贡献指南**：如何提交 PR、代码风格约定等。
- **License 说明**：开源协议和版权声明。

---

## Bootloader: RS485 与中断（重要修改说明）

如果你在工程中使用 RS485 串口作为 bootloader 的传输通道，请按下列步骤检查并修改源码以确保接收与中断工作正常：

1. `board_config.h`：如果板级设计使用 RS485 的发送使能引脚（DE/RE），请取消注释或定义 `RS485_EN_PIN`，例如：

   - 在 `Inc/board_config.h` 中找到 RS485 相关定义区域，确保存在并启用 `RS485_EN_PIN` 的定义（该宏在部分板卡上用于控制驱动器方向）。

2. `Src/uart.c`：在启用 RS485 时，需要把 EN 引脚也加入 AF 配置，以便在需要时由软件控制或保持正确的复用：

   - 修改 `gpio_af_set` 的调用，包含 `RS485_EN_PIN`：
     ```c
     gpio_af_set(RS485_GPIO_PORT, GPIO_AF_1, RS485_TX_PIN | RS485_RX_PIN | RS485_EN_PIN);
     ```

   - 如果你的硬件使用独立的 GPIO 控制 EN（非 AF），请根据实际电路改为 `gpio_mode_set` + `gpio_output_options_set` 并在发送前后切换引脚电平。

3. 中断服务函数（ISR）名称一致性：

   - 当前 `Src/gd32e23x_it.c` 中的接收中断函数为 `USART1_IRQHandler`，但 `RS485_PHY` 使用的是 `USART0`（见 `Inc/board_config.h` 中 `RS485_PHY` 定义）。请确保 NVIC 中断号与 ISR 名称匹配。两种可行的修复：
     - 把 `RS485_IRQ` 设置为 `USART0_IRQn`（推荐，当 `RS485_PHY` 为 `USART0` 时），或
     - 把 ISR 更名为 `USART0_IRQHandler` 并处理 `USART0` 的中断。

   - 示例（推荐修复一）：在 `Inc/board_config.h` 中：
     ```c
     #define RS485_PHY            USART0
     #define RS485_IRQ            USART0_IRQn
     ```

   - 示例（替代修复二）：在 `Src/gd32e23x_it.c` 中将函数签名改为：
     ```c
     void USART0_IRQHandler(void) { ... }
     ```

注意：在做以上修改后，重新编译并烧录固件，然后用示波器或串口日志确认：

- MCU 是否在上电/复位后输出 bootloader 的欢迎/OK 字符；
- 发送单字节（例如 ASCII '0'、'1'）时是否会触发中断并被写入环形缓冲；
- 若使用 RS485，确保 DE/RE 控制在发送/接收期间正确切换以避免收发冲突。

如需，我可以为你生成一个包含以上三项修改的补丁并运行一次构建测试。


如需进一步完善或有其他建议，欢迎随时反馈！