generated from hulk/gd32e23x_template_cmake_vscode
142 lines
10 KiB
Markdown
142 lines
10 KiB
Markdown
# AGENTS.md — CeramixNano EDDY（ldc1612_cmake_vscode）项目约定与进度
|
||
|
||
## 项目概述
|
||
|
||
CeramixNano EDDY 电涡流传感器单板固件（工程目录名沿用 ldc1612_cmake_vscode）：
|
||
LDC1612（电涡流/电感数字转换器）+ TMP112（板载温度），RS485 串口命令协议
|
||
（`D5 03 LEN [cmd] CRC`，板卡类型 0x03），支持温度补偿与标定。
|
||
|
||
- 协议文档：`CommunicationProtocol.md`；寄存器速查：`LDC1612_REG_LIST.md`
|
||
- 命名/版本规则（2026-10-24 起）：产物名 `CeramixNano-EDDY_*`，板卡码 **26**
|
||
（M999 应答 `v26.主.次.修订`，与 MB 的 25 同源规则）；版本维护在
|
||
`cmake/project_config.cmake`（编译时生成 version.h，`Inc/version.h` 说法已过时）
|
||
|
||
## 工具链与构建
|
||
|
||
- 语言/环境：C99，GD32E23x 标准库（`SDK/`），MCU GD32E230F8（64K Flash/8K RAM）
|
||
- 编译器：xpack-arm-none-eabi-gcc 15.2.1（`GD32_GCC_BIN` 环境变量解析）
|
||
- 构建：CMake + Ninja，preset `Debug` / `Release`，输出 `Build/<preset>/Application/`
|
||
及 `Build/<preset>/CeramixNano-EDDY_<版本>_<variant>_<日期>.bin/.hex` 等
|
||
（variant：dev 线 `APP`，golden 线 `golden`）
|
||
- 烧录/调试（.vscode/tasks.json、launch.json）：
|
||
- OpenOCD：`GD32_OPENOCD_BIN` 指向定制构建（含 gd32e23x flash 驱动，CMSIS-DAP 后端）
|
||
- `Flash MCU (DAPLink)` 任务 + `.vscode/openocd_daplink_gd32e23x.cfg`：
|
||
适配 DAPLink 探针（无 connect_assert_srst；该选项在此 DAPLink 上会导致
|
||
examination 失败，但 SRST 线是接通的，见下文排障）
|
||
- J-Link 任务需 SEGGER 探针 + PATH 中 JLink.exe（当前接的是 DAPLink，不适用）
|
||
- 调试器探针历史问题（2026-10-02 已解决）：DAPLink 的 CMSIS-DAP v1 接口曾被 Zadig
|
||
装上 libwdi WinUSB 驱动（oem244.inf），导致 OpenOCD 枚举不到探针；删除该驱动包后
|
||
恢复 HID。若复发：管理员运行 `pnputil /delete-driver <oemNN.inf> /uninstall`。
|
||
- 串口验证：RS485 转 USB（FTDI，COM15），115200-8N1，**需同时置位 RTS+DTR**
|
||
（转换器方向控制），否则命令发不出去；DAPLink 虚拟串口为 COM8。
|
||
- 本地测试工具（git 不跟踪，在 `Toolchain/eddy_test/`）：`eddy_cmd.py`（D5 帧命令行）、
|
||
`soc_ota.py`（PC 模拟 SOC 完整 OTA/Ymodem，支持 `--abort-after`/`--no-ca` 中止模式）、
|
||
`swd.py`（OpenOCD 封装：probe/image/boot/erasepage/read/dump）、`verify_pack.py`、
|
||
`verify_dump.py`（独立 CRC 复算与读回比对）。
|
||
|
||
## 硬件/板级约定（Inc/board_config.h）
|
||
|
||
- MCU：GD32E230（自动探测 Flash 容量，64KB → USART1 作 RS485）
|
||
- RS485：SP3487（无自动方向），USART1 PA2(TX)/PA3(RX)，DE=PA1（USART 硬件 DE，AF1）
|
||
- I2C0：PF0(SDA)/PF1(SCL)，硬件 IIC 100kHz（`SOFTWARE_IIC` 可切换软模拟，默认关闭）
|
||
- LED：PB1
|
||
- 传感器：LDC1612 @0x2B（40MHz 外部时钟），TMP112 @0x49（ADD0=GND）
|
||
- 调试宏（均默认关闭）：DEBUG_VERBOSE / COM_DEBUG / LDC_DEBUG / EDDY_DRIVE_CURRENT_DETECTION
|
||
|
||
## 双固件布局（2026-10-24 移植完成，与 CeramixNano-MB 完全相同的 Flash 分配）
|
||
|
||
```
|
||
0x08000000 ┌─────────────────┐
|
||
│ Bootloader │ 8K 页 0~7 专属分支 bootloader_CeramixNano_EDDY（V0.1.0，4,040B）
|
||
0x08002000 ├─────────────────┤
|
||
│ FW_A 运行槽 │ 36K 页 8~43 OTA/Ymodem 接收区；锚点 A 记录@0x0800AFFC
|
||
0x0800B000 ├─────────────────┤
|
||
│ FW_B 出厂保底槽│ 19K 页 44~62 golden 线构建；B 记录@0x0800FBF8
|
||
0x0800FC00 ├─────────────────┤
|
||
│ 末页标志页 │ 1K 页 63 legacy 0xEEEE@0x0800FFFC
|
||
0x08010000 └─────────────────┘
|
||
```
|
||
|
||
- **BL = 并列板卡分支 `bootloader_CeramixNano_EDDY`**（BL 仓库，2026-10-24 自 MB 分支
|
||
创建；板卡宏 CERAMIXNANO_EDDY，**LED=PB1**，Ymodem 每成功烧录一包翻转一次，逻辑
|
||
同 MB 分支；版本独立编号 V0.1.0 = 4,040B，MD5 1dcc17bf…）。RS485 配置与 MB 逐宏
|
||
相同；**PA14 不被 BL 占用 ⇒ 升级会话期间 SWD 保持可用**（MB 分支 BL 的 LED=PA14
|
||
会占 SWCLK，勿混烧）。
|
||
- **A 线 = dev/main**：链接 0x08002000 / **LENGTH 36K**（LD 上限防溢出 B 槽），
|
||
VTOR 0x2000；版本从 V1.0.3 起（首个双固件 A 版本，码 26）。
|
||
- **B 线 = release/golden**：链接 0x0800B000 / LENGTH 0x4BF8（19K−8B，B 记录由打包
|
||
工具写入，链接区不含尾 8B——与 MB 的 .fw_tail 方案等价），VTOR 0xB000；
|
||
**版本冻结 V1.0.2**（保底判定值 = M999 返回 `v26.1.0.2` ⇔ 在跑 FW_B，该版本号
|
||
永不再用于 OTA 升级包）。此分支改动不得合回 dev/main。
|
||
- 打包：`hulk-mcu-firmware` skill / merge tool profile **`CeramixNano_EDDY_Dual_FW`**
|
||
（布局与 `CeramixNano_MB_Dual_FW` 逐字节相同），产出 `_UPDATE/_FULL/_FACTORY + MD5`。
|
||
- 升级链路：上位机（原 SOC 职责）—RS485—> BL（Ymodem）；APP 用 `M9999` 软复位进
|
||
升级模式（SWRSTF=1 ⇒ BL 直留升级模式）。握手：BL 发 `ok` → `0x30` → BL `ok` →
|
||
`0x31` → 预擦 A+末页 → `'C'` 周期 → Ymodem（文件头 ACK 后 **ACK+'C' 连发**，
|
||
发送器须一次等齐）→ EOT → ACK×2 → 跳新固件。
|
||
- 完全体方案文档：`E:\Hulk-Coding\capsule_mb_camke_vscode\doc\双固件方案_完全体说明.md`。
|
||
|
||
## 开发进度
|
||
|
||
### 已完成
|
||
|
||
- LDC1612 驱动（初始化/单通道配置/原始值读取/状态检查）
|
||
- TMP112 驱动（初始化/温度读取/阈值/单次转换）
|
||
- RS485 命令体系：M1/M2（周期上报开关）、M3（涡流原始值）、M4（温度×10000）、
|
||
M5（温度补偿涡流值）、M6（标定数据：涡流+温度）、M999（版本）、M9999（复位）
|
||
- v1.0.1：涡流传感器温度标定方法与标定命令（M6）
|
||
- 2026-10-02：IIC 驱动改进导入（总线恢复重试/超时辅助/read_raw/scan AERR 处理）；
|
||
硬件全命令实测通过；DAPLink 烧录问题解决；发布 V1.0.2（Gitea Release + tag）
|
||
- **2026-10-24：双固件（出厂救援）方案移植完成并全链路实测通过**（详见下节）
|
||
- BL 仓库新建并列板卡分支 `bootloader_CeramixNano_EDDY`（LED=PB1，V0.1.0 = 4,040B，
|
||
每收包翻转一次；此前短暂采用"复用 MB bin"方案，因 LED 引脚不同已废弃并重打包）
|
||
- dev：LD 54K→36K、命名 CeramixNano-EDDY、板卡码 26、V1.0.3；
|
||
golden：V1.0.2 冻结命名 + variant=golden
|
||
- 两线 CMake 补齐 `--gap-fill=0xFF` 与 `LD LINK_DEPENDS`
|
||
- fw_pack 新增 `CeramixNano_EDDY_Dual_FW` profile（55 项回归过，skill 缓存已同步）
|
||
- 产物（`Build/test/dualfw_2026-10-24/`）：UPDATE（12 页，trailer 0x5C09000C）、
|
||
FULL（EDDY BL + A=V1.0.3/B=V1.0.2，19 项校验过）、FACTORY（12 项校验过）+ MD5 清单；
|
||
独立 python XMODEM 复算全部命中
|
||
- **硬件实测矩阵（SWD 探针 PC 采样 + 485 命令双重手段，全部 PASS；先用 MB bin 实测，
|
||
换 EDDY 专属 BL 后 FULL/FACTORY/OTA 全周期复测通过）**：
|
||
FACTORY→跳B(v26.1.0.2) / FULL→记录路径跳A(v26.1.0.3) / PC 模拟 SOC 完整 OTA
|
||
44s 成功+读回整片逐字节与包一致（B 区在真实 OTA 中毫发无损）/
|
||
擦锚点页→legacy 跳A / 锚点在位毁A体→CRC 拦截直落B（防降级）/
|
||
再毁B体→拒跳坏固件停留 BL(PC=0x080001B6) / OTA 第4包 CA 中止→落B /
|
||
非整页裸 bin 包→头部预检 CA×2 拒收→落B / M3/M4/M6 功能全通
|
||
|
||
### 计划 / TODO
|
||
|
||
- dev → main 合并待发布节奏（V1.0.3 为首个双固件 A 版本，main 仍是 54K 单槽布局）
|
||
- M5 温度补偿系数目前为 0（TEMP_COMP_COEFF_*），待标定后填入实际温漂系数
|
||
- 上位机/SOC 侧需预存保底判定值 `v26.1.0.2`（跑 B ⇒ 升级未生效重推）
|
||
- （可选）模板侧 SEGGER RTT / CFG_ENABLE 宏体系同步
|
||
|
||
### 已删除的历史分支（2026-10-24 清理，均为开发过程产物）
|
||
|
||
- `dev_more_information`（远端）：零独有提交，内容早已全部并入 main/dev。
|
||
- `dev_feature_iic_more_byte`（远端）：仅 2 个 2025-08-25 的孤立实验提交，从未接入构建——
|
||
`75ea93c`（iic_new.c 975 行并行驱动实验，实际采用的是后来模板导入 i2c.c 的改进）、
|
||
`dbb6569`（"dlpc3421 driver from kimi"，DLPC3421 为 MB 光机芯片，与本板无关）。
|
||
如需找回：本地对象库在 gc 前仍可 `git show <hash>`。
|
||
|
||
### 教训（避免复发）
|
||
|
||
- **SWRSTF 残留**：M9999/调试器软复位置位的 SWRSTF **不随 NRST/SRST 清除**（仅 POR
|
||
或 RSTFC 清），此后任何复位 BL 都直进升级模式、不跳 APP——表现为"设备沉默，
|
||
M999 无响应，但 0x30 能回 ok"。排障/测试时须 SWD `mww 0x40021024 0x01000000`
|
||
清标志后再放跑（`swd.py boot` 已内置）。
|
||
- **（历史）误烧 MB 分支 BL 会让 SWD 在 0x30 后失联**：MB 分支 BL 的 LED=PA14
|
||
（SWCLK），0x30 应答后切输出 ⇒ SWD 死。**本板专用 `bootloader_CeramixNano_EDDY`
|
||
分支 LED=PB1，PA14 不占用，升级会话期间 SWD 全程可用**（2026-10-24 起所有镜像
|
||
均为 EDDY BL，此坑仅存档）。若真误烧：`M9999` 复位（有 APP 时）或用
|
||
connect_assert_srst 变体 cfg（`Toolchain/eddy_test/daplink_srst.cfg`）脉冲 SRST
|
||
复位恢复——SRST 线已验证接通，但该 DAPLink 下 examination 必失败属正常，
|
||
复位本身生效。
|
||
- **Ymodem 文件头 ACK 后是 ACK+'C' 连发**：发送器若分两次等会永远等不到第二个 'C'
|
||
（首次 OTA 调试即栽在此，BL 无超时会卡死；随后发 5×CA 可解）。
|
||
- OpenOCD `program`/`dump_image` 的文件路径必须转正斜杠，否则 Tcl 吃掉 `\l` `\t`。
|
||
- legacy 路径（锚点擦除态+flag 在）**没有 CRC 安全网**：实测毁 A 体后仍会跳进坏 A
|
||
导致 HardFault（xPSR=0x41000003）——这正是 v5 记录机制存在的意义，量产镜像必须
|
||
带锚点（FULL/OTA 正常路径均带）。
|