ldc1612_cmake_vscode/AGENTS.md

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.3 = 生产实装版原样复制（2026-10-25 起，见开发进度）。保底判定值 = M999 返回 v26.1.0.3 ⇔ 在跑 FW_B；v26.1.0.2（旧 golden）与 v26.1.0.3 均永不 再用于 OTA 升级包版本，dev 线后续 A 版本必须 > V1.0.3。此分支改动不得合回 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 功能全通

• 2026-10-25：golden 托底线整体替换为生产实装版原样复制（用户决策：生产版已在 机器上实装，托底必须与其同源，不做任何"顺手改进"；IIC 新驱动等留给后续 A 线新版本）：

  • 来源：生产仓库（GitLab ceramixnano_eddy_cmake_vscode，dev@151828f，v26.1.0.3， 2026-03-23 已含驱动电流调参 GEN(18)→GEN(8)）；复制 8 文件（Src: command.c/i2c.c/ ldc1612.c/tmp112.c；Inc: command.h/i2c.h/ldc1612.h；CommunicationProtocol.md）， 复制后 fc /b 逐字节核验一致
  • golden 从此与 dev 线的功能差异（属预期，勿"修复"）：LDC1612 驱动电流 GEN(8) （dev 线仍为 GEN(18)，后续 A 线新版本需评估回合生产调参）；命令集 M1~M4 + M999/M9999（无 M5/M6）；M4 温度为生产版无符号算法；i2c 为旧 8 位寄存器地址 API 驱动（与 tmp112.c/ldc1612.c 配套，整组生效）
  • golden 保留项（B 槽专属构建）：LD 0x0800B000/0x4BF8、VTOR 0xB000、gap-fill 0xFF、 BUILD_VARIANT=golden；仅 VERSION_PATCH 2→3 与生产对齐
  • 保底判定值改为 v26.1.0.3；注意 dev 线当前同为 V1.0.3（10-24 的 FULL 测试包 A=V1.0.3）——后续 A 线正式版本必须升到 V1.0.4 以上，否则 M999 无法区分保底

计划 / TODO

• dev → main 合并待发布节奏（V1.0.3 为首个双固件 A 版本，main 仍是 54K 单槽布局）
• M5 温度补偿系数目前为 0（TEMP_COMP_COEFF_*），待标定后填入实际温漂系数
• 上位机/SOC 侧需预存保底判定值 v26.1.0.3（跑 B ⇒ 升级未生效重推；2026-10-25 起判定值随生产版复制从 v26.1.0.2 改为 v26.1.0.3）
• （可选）模板侧 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 正常路径均带）。