# 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 正常路径均带）。