generated from hulk/gd32e23x_template_cmake_vscode
200 lines
9.2 KiB
Markdown
200 lines
9.2 KiB
Markdown
# LDC1612 传感器固件
|
||
|
||
本仓库基于 GD32E23x CMake + VSCode 工程模板（`gd32e23x_template_cmake_vscode`），包含 LDC1612 电感采样、TMP112 温度采集及补偿、RS485 命令处理。当前版本为 V1.0.1。固件采用 Bootloader + APP 布局：APP 链接在 `0x08002000`（54KB Flash / 8KB RAM），启动时自设向量表偏移；开发进度与审查资料见 `doc/` 目录。
|
||
|
||
## 本地编译
|
||
|
||
需要 CMake 3.20 或更新版本、Ninja 和 ARM GCC。CMake、Ninja 应在 `PATH` 中；ARM GCC 通过 `GD32_GCC_BIN` 指定，也可在配置时传入 `-DTOOLCHAIN_DIRECTORY="D:/toolchain/arm-gcc/bin"`，该参数优先于环境变量。工具链路径支持包根目录或 `bin` 目录。
|
||
|
||
在工程根目录运行 PowerShell（工具链路径请替换为本机安装位置）：
|
||
|
||
```powershell
|
||
$env:GD32_GCC_BIN = 'D:\toolchain\xpack-arm-none-eabi-gcc-15.2.1-1.1\bin'
|
||
cmake --preset Debug
|
||
cmake --build --preset Debug
|
||
cmake --preset Release
|
||
cmake --build --preset Release
|
||
```
|
||
|
||
输出位于 `Build/Debug` 或 `Build/Release`：`Application/Application.elf` 用于调试，`LDC1612_V1.0.1_APP_<日期>.bin` / `.hex` 为应用固件；`Application/Application.hex` 供 J-Link 烧录任务使用。应用固件不含 Bootloader：单独烧录需写到 `0x08002000`；整片烧录（Bootloader + APP + 标志页）用配套的固件合并工具（`gd32e230f8_firmware_merge_tool` 仓库）处理。详见[固件布局与 Bootloader](#固件布局与-bootloader)。
|
||
|
||
如果切换 ARM GCC 版本，请使用新的构建目录，或通过 CMake Tools 的 “Delete Cache and Reconfigure” 重新配置。需要独立验证目录时可运行：
|
||
|
||
```powershell
|
||
cmake --preset Debug -B Build/local-check/Debug
|
||
cmake --build Build/local-check/Debug
|
||
```
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [本地编译](#本地编译)
|
||
- [固件布局与 Bootloader](#固件布局与-bootloader)
|
||
- [适用范围](#适用范围)
|
||
- [默认配置](#默认配置)
|
||
- [工具链准备](#工具链准备)
|
||
- [使用说明](#使用说明)
|
||
- [时钟配置说明](#时钟配置说明)
|
||
- [vcpkg 依赖管理（可选）](#vcpkg-依赖管理可选)
|
||
- [建议补充内容](#建议补充内容)
|
||
|
||
---
|
||
|
||
## 固件布局与 Bootloader（双固件，2026-10-24 起）
|
||
|
||
GD32E230F8（64KB Flash）采用与 CeramixNano-MB 相同的双固件（出厂救援）布局：
|
||
|
||
| 区域 | 地址范围 | 说明 |
|
||
|---|---|---|
|
||
| Bootloader | `0x08000000` - `0x08001FFF`（8KB，页 0~7） | **复用 CeramixNano-MB 板 BL**（V0.1.0，4,044B）——RS485 引脚/波特率/DE 方案完全一致；启动判定链 + RS485 Ymodem OTA |
|
||
| FW_A 运行槽（本仓库 dev/main） | `0x08002000` - `0x0800AFFF`（36KB，页 8~43） | 唯一 OTA/Ymodem 接收区；链接 `ORIGIN=0x08002000, LENGTH=36K`（上限防溢出 B 槽）；槽尾锚点 A 记录 @`0x0800AFFC` |
|
||
| FW_B 出厂保底槽（release/golden 分支） | `0x0800B000` - `0x0800FBFF`（19KB，页 44~62） | 出厂救援固件（版本冻结 V1.0.2），OTA 永不擦写；B 记录 @`0x0800FBF8` |
|
||
| 末页标志页 | `0x0800FC00` - `0x0800FFFF`（1KB，页 63） | legacy 标志 `0xEEEE` @`0x0800FFFC` |
|
||
|
||
启动判定：A 记录在位 ⇒ trailer 比对 + 固件体 CRC 复算 + 向量校验 ⇒ 跳 A（不过直落 B，防降级）；锚点擦除态 ⇒ legacy flag ⇒ 跳 A；B 记录 CRC 复算通过 ⇒ 跳 B；否则留 BL 等 Ymodem。OTA 中途断电/中止 ⇒ 重启落 B 跑出厂固件，**设备不变砖**。
|
||
|
||
工程侧的适配点：
|
||
|
||
- `LD/gd32e23x_flash.ld`：FLASH `ORIGIN = 0x08002000, LENGTH = 36K`；
|
||
- `Src/system_gd32e23x.c`：`VECT_TAB_OFFSET = 0x2000`——Bootloader 不写 VTOR，APP 必须自己把向量表指到 `0x08002000`，否则中断会落回 Bootloader 向量表（现象：收到第一个 RS485 字节即死机）；
|
||
- 出厂保底固件在 `release/golden` 分支构建（`ORIGIN=0x0800B000 / LENGTH=0x4BF8`、`VECT_TAB_OFFSET=0xB000`，版本冻结 V1.0.2，判定值 `v26.1.0.2`）；
|
||
- 打包（`_UPDATE/_FULL/_FACTORY` + MD5）用 merge tool / `hulk-mcu-firmware` skill，profile `CeramixNano_EDDY_Dual_FW`；产物命名 `CeramixNano-EDDY_*`（板卡码 26）。
|
||
|
||
⚠️ 与旧版 54K 单槽布局不兼容：需整片烧录一次（FACTORY/FULL 镜像）。RS485 协议、命令集（M1-M6/M999/M9999）与回包格式无任何变化。方案完全体文档见 MB 仓库 `doc/双固件方案_完全体说明.md`；开发约定与实测记录见本项目 `AGENTS.md`。
|
||
|
||
---
|
||
|
||
## 适用范围
|
||
|
||
- 适用于兆易创新 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；本机编译验证使用 15.2.1-1.1。
|
||
- **安装位置**：由本机统一管理，不提交到仓库。
|
||
- **官方下载地址**：https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack/releases
|
||
- **路径自定义说明**：
|
||
编译器与 GDB 均通过 `GD32_GCC_BIN` 环境变量定位（或配置时传 `-DTOOLCHAIN_DIRECTORY`），CMake 文件与 `.vscode` 均无需修改路径。
|
||
|
||
### 2. OpenOCD（GD-Link 支持）
|
||
|
||
- **版本**：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 支持有限，推荐严格使用此版本。
|
||
- **路径自定义说明**：
|
||
通过两个环境变量定位，安装位置任意：
|
||
- `GD32_OPENOCD_BIN`：`openocd.exe` 所在 `bin` 目录；
|
||
- `GD32_OPENOCD_SCRIPTS`：OpenOCD `scripts` 目录。
|
||
`.vscode` 的调试配置与烧录任务全部读取这两个变量，无需修改任何文件。
|
||
|
||
---
|
||
|
||
## 使用说明
|
||
|
||
1. **配置环境变量**（用户级，按本机安装位置设置一次即可）
|
||
|
||
| 环境变量 | 指向 | 用途 |
|
||
|---|---|---|
|
||
| `GD32_GCC_BIN` | ARM GCC 的 `bin` 目录 | 编译、GDB 调试 |
|
||
| `GD32_OPENOCD_BIN` | OpenOCD 的 `bin` 目录 | 烧录、调试 |
|
||
| `GD32_OPENOCD_SCRIPTS` | OpenOCD 的 `scripts` 目录 | 烧录、调试 |
|
||
|
||
设置后重开终端 / VSCode 生效。`cmd` 示例：`setx GD32_GCC_BIN "D:\toolchain\xpack-arm-none-eabi-gcc-15.2.1-1.1\bin"`。
|
||
|
||
2. **编译**
|
||
命令行见上文[本地编译](#本地编译)，或直接用 VSCode 的 CMake Tools 选择 Debug / Release preset 构建。
|
||
|
||
3. **烧录固件**
|
||
- **OpenOCD（GD-Link）**：VSCode 任务 `Flash MCU`（连带编译用 `Build and Flash`）；另有 `Reset MCU`、`Mass Erase MCU`、`OpenOCD Server` 任务。
|
||
- **J-Link**：任务 `Flash MCU (Jlink)` 等，依赖构建生成的 `Build/<preset>/Application/Application.hex`。
|
||
- 器件与接口在 `.vscode/settings.json` 的 `gd32.jlink.*` / `gd32.openocd.*` 中配置，当前为 GD32E230F8 / SWD。
|
||
|
||
4. **调试**
|
||
VSCode 调试配置有两个：`Debug with OpenOCD` 与 `Debug with J-Link`（均使用 cortex-debug，SVD 文件 `GD32E230.svd`，支持外设寄存器查看）。烧录调试器以 GD-Link 为例；J-Link 直接选用对应配置即可。
|
||
|
||
---
|
||
|
||
## 时钟配置说明
|
||
|
||
本工程默认系统时钟为内部 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 的最小点灯/串口输出代码片段。
|
||
- **常见问题与解答**：如构建失败、烧录失败的排查建议。
|
||
- **多板卡适配说明**：如有多种硬件，如何切换 BoardName。
|
||
- **贡献指南**：如何提交 PR、代码风格约定等。
|
||
- **License 说明**：开源协议和版权声明。
|
||
|
||
---
|
||
|
||
如需进一步完善或有其他建议，欢迎随时反馈！
|