build(golden): 出厂保底线定版——CeramixNano-EDDY 命名/板卡码 26/版本冻结 V1.0.2/variant=golden

build: golden 保底固件布局——LD ORIGIN 0x0800B000 (B 槽 19K-8B) + VECT_TAB_OFFSET 0xB000
build: 恢复正式发布布局 0x08002000/54K + VECT_TAB_OFFSET=0x2000
2026-10-24 21:15:11 +08:00 · 2026-10-23 10:11:14 +08:00 · 2026-10-02 23:21:47 +08:00 · 2026-10-02 23:09:37 +08:00 · 2026-10-02 23:09:19 +08:00 · 2026-10-02 23:07:59 +08:00
20 changed files with 1065 additions and 491 deletions
@@ -0,0 +1,2 @@
+erase
+exit
@@ -1,26 +1,8 @@
 {
-  "recommendations": [
-    "ms-vscode.cmake-tools",
-    "ms-vscode.cpptools",
-    "ms-vscode.cpptools-extension-pack",
-    "ms-vscode.cpptools-themes",
-    "ms-vscode.vscode-embedded-tools",
-    "ms-vscode.hexeditor",
-    "ms-vscode.notepadplusplus-keybindings",
-    "twxs.cmake",
-    "xaver.clang-format",
-    "marus25.cortex-debug",
-    "cheshirekow.cmake-format",
-    "mcu-debug.debug-tracker-vscode",
-    "mcu-debug.memory-view",
-    "mcu-debug.peripheral-viewer",
-    "mcu-debug.rtos-views",
-    "trond-snekvik.gnu-mapfiles",
-    "zixuanwang.linkerscript",
-    "gurumukhi.selected-lines-count",
-    "gruntfuggly.todo-tree",
-    "vscode-icons-team.vscode-icons",
-    "jeff-hykin.better-cpp-syntax",
-    "dan-c-underwood.arm"
-  ]
-}
+    "recommendations": [
+        "marus25.cortex-debug",
+        "ms-vscode.cmake-tools",
+        "twxs.cmake",
+        "ms-vscode.cpptools"
+    ]
+}
@@ -0,0 +1,4 @@
+loadfile Application.hex
+r
+go
+exit
@@ -9,20 +9,19 @@
            "type": "cortex-debug",
            "runToEntryPoint": "main",
            "showDevDebugOutput": "none",
-            "gdbPath": "${workspaceFolder}/Toolchain/xpack-arm-none-eabi-gcc-11.3.1-1.1/bin/arm-none-eabi-gdb.exe",
+            "gdbPath": "${env:GD32_GCC_BIN}/arm-none-eabi-gdb.exe",
            "servertype": "openocd",
-            "serverpath": "${workspaceFolder}/Toolchain/xpack-openocd-0.11.0-3/bin/openocd.exe",
+            "serverpath": "${env:GD32_OPENOCD_BIN}/openocd.exe",
            "svdFile": "${workspaceFolder}/GD32E230.svd",
-            "liveWatch": {
-                "enabled": true,
-                "samplesPerSecond": 1
-            },
            "configFiles": [
-                "${workspaceFolder}/Toolchain/xpack-openocd-0.11.0-3/scripts/target/openocd_gdlink_gd32e23x.cfg"
+                "${env:GD32_OPENOCD_SCRIPTS}/${config:gd32.openocd.targetConfig}"
            ],
            "serverArgs": [
-                "-s", "${workspaceFolder}/Toolchain/xpack-openocd-0.11.0-3/scripts"
+                "-s", "${env:GD32_OPENOCD_SCRIPTS}"
            ],
+            "env": {
+                "OPENOCD_SCRIPTS": "${env:GD32_OPENOCD_SCRIPTS}"
+            },
            "searchDir": [
                "${workspaceFolder}"
            ],
@@ -30,7 +29,30 @@
            "preRestartCommands": [
                "load",
                "continue"
-            ],
+            ]
        },
+        {
+            "cwd": "${workspaceFolder}",
+            "executable": "${workspaceFolder}/Build/Debug/Application/Application.elf",
+            "name": "Debug with J-Link",
+            "request": "launch",
+            "type": "cortex-debug",
+            "runToEntryPoint": "main",
+            "showDevDebugOutput": "none",
+            "gdbPath": "${env:GD32_GCC_BIN}/arm-none-eabi-gdb.exe",
+            "servertype": "jlink",
+            "device": "${config:gd32.jlink.device}",
+            "interface": "${config:gd32.jlink.interface}",
+            "svdFile": "${workspaceFolder}/GD32E230.svd",
+            "liveWatch": {
+                "enabled": true,
+                "samplesPerSecond": 1
+            },
+            "preLaunchTask": "Build",
+            "preRestartCommands": [
+                "load",
+                "continue"
+            ]
+        }
    ]
-}
+}
@@ -0,0 +1,23 @@
+# DAPLink-friendly GD32E23x flash/debug config
+# Difference vs target/openocd_gdlink_gd32e23x.cfg:
+#   - no connect_assert_srst (breaks target examination with the current DAPLink)
+adapter driver cmsis-dap
+transport select swd
+
+source [find target/swj-dp.tcl]
+source [find mem_helper.tcl]
+
+set _CHIPNAME gd32e23x
+swj_newdap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0xf -expected-id 0x0BF11477
+dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu
+
+set _TARGETNAME $_CHIPNAME.cpu
+target create $_TARGETNAME cortex_m -dap $_CHIPNAME.dap
+$_TARGETNAME configure -work-area-phys 0x20000000 -work-area-size 0x1000 -work-area-backup 0
+
+flash bank $_CHIPNAME.flash gd32e23x 0x08000000 0 0 0 $_TARGETNAME
+
+adapter speed 1000
+reset_config srst_only srst_nogate
+
+cortex_m reset_config sysresetreq
@@ -0,0 +1,2 @@
+r
+exit
@@ -1,30 +1,15 @@
 {
-    "terminal.integrated.tabs.enabled": true,
-    "terminal.integrated.profiles.windows": {
-        "Git Bash": {
-            "path": "C:\\Program Files\\Git\\bin\\bash.exe",
-            "icon": "terminal-bash"
-        },
-        "Git-Bash": {
-            "path": "D:\\Git\\bin\\bash.exe",
-            "icon": "terminal-bash"
-        }
-    },
-    "terminal.integrated.defaultProfile.windows": "Git-Bash",
-    "clang-format.assumeFilename": ".clang-format",
-    "clang-format.executable": "clang-format",
-    "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools",
    "cmake.configureOnOpen": true,
-    "cmake.buildDirectory": "${workspaceFolder}/Build",
-    "vcpkg.storageLocation": "C:\\Dev\\Tools\\vcpkg",
+    "cmake.useCMakePresets": "always",
+    "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools",
+    "cortex-debug.variableUseNaturalFormat": true,
+    "gd32.openocd.targetConfig": "target/openocd_gdlink_gd32e23x.cfg",
+    "gd32.openocd.massEraseCommand": "gd32e23x mass_erase 0",
+    "gd32.jlink.device": "GD32E230F8",
+    "gd32.jlink.interface": "SWD",
+    "gd32.jlink.speed": "4000",
    "files.associations": {
        "*.h": "c",
-        "*.c": "c",
-        "array": "c",
-        "string": "c",
-        "string_view": "c",
-        "ranges": "c",
-        "span": "c"
-    },
-    "cortex-debug.variableUseNaturalFormat": true,
-}
+        "*.c": "c"
+    }
+}
@@ -1,116 +1,6 @@
 {
    "version": "2.0.0",
    "tasks": [
-        {
-            "label": "Build and Flash",
-            "group": {
-                "kind": "build",
-                "isDefault": true
-            },
-            "dependsOn": [
-                "Build",
-                "Flash MCU"
-            ],
-            "dependsOrder": "sequence",
-            "icon": {
-                "id": "insert",
-                "tooltip": "Build and Flash"
-            }
-        },
-        {
-            "label": "Flash MCU",
-            "type": "shell",
-            "command": "'${workspaceFolder}/Toolchain/xpack-openocd-0.11.0-3/bin/openocd.exe' -s '${workspaceFolder}' -f '${workspaceFolder}/Toolchain/xpack-openocd-0.11.0-3/scripts/target/openocd_gdlink_gd32e23x.cfg' -c 'init; reset halt; flash write_image erase ${command:cmake.launchTargetFilename}; reset; exit'",
-            "group": {
-                "kind": "build",
-                "isDefault": true
-            },
-            "problemMatcher": [],
-            "options": {
-                "cwd": "${command:cmake.buildDirectory}/Application",
-                "environment": {
-                    "CLICOLOR_FORCE": "1",
-                    "OPENOCD_SCRIPTS": ""
-                }
-            },
-            "presentation": {
-                "clear": true
-            },
-            "icon": {
-                "id": "gather",
-                "tooltip": "Flash MCU"
-            }
-        },
-        {
-            "label": "Reset MCU",
-            "type": "shell",
-            "command": "'${workspaceFolder}/Toolchain/xpack-openocd-0.11.0-3/bin/openocd.exe' -s '${workspaceFolder}' -f '${workspaceFolder}/Toolchain/xpack-openocd-0.11.0-3/scripts/target/openocd_gdlink_gd32e23x.cfg' -c 'init; reset; exit'",
-            "group": {
-                "kind": "build",
-                "isDefault": true
-            },
-            "problemMatcher": [],
-            "options": {
-                "cwd": "${command:cmake.buildDirectory}/Application",
-                "environment": {
-                    "CLICOLOR_FORCE": "1",
-                    "OPENOCD_SCRIPTS": ""
-                }
-            },
-            "presentation": {
-                "clear": true
-            },
-            "icon": {
-                "id": "discard",
-                "tooltip": "Reset MCU"
-            }
-        },
-        {
-            "label": "Mass Erase MCU",
-            "type": "shell",
-            "command": "'${workspaceFolder}/Toolchain/xpack-openocd-0.11.0-3/bin/openocd.exe' -s '${workspaceFolder}' -f '${workspaceFolder}/Toolchain/xpack-openocd-0.11.0-3/scripts/target/openocd_gdlink_gd32e23x.cfg' -c 'init; reset halt; gd32e23x mass_erase 0; exit'",
-            "group": {
-                "kind": "build",
-                "isDefault": true
-            },
-            "problemMatcher": [],
-            "options": {
-                "cwd": "${command:cmake.buildDirectory}/Application",
-                "environment": {
-                    "CLICOLOR_FORCE": "1",
-                    "OPENOCD_SCRIPTS": ""
-                }
-            },
-            "presentation": {
-                "clear": true
-            },
-            "icon": {
-                "id": "clear-all",
-                "tooltip": "Erase MCU"
-            }
-        },
-        {
-            "label": "OpenOCD Server",
-            "type": "shell",
-            "command": [
-                "'${workspaceFolder}/Toolchain/xpack-openocd-0.11.0-3/bin/openocd.exe' -s '${workspaceFolder}' -f '${workspaceFolder}/Toolchain/xpack-openocd-0.11.0-3/scripts/target/openocd_gdlink_gd32e23x.cfg'"
-            ],
-            "group": {
-                "kind": "build",
-                "isDefault": true
-            },
-            "problemMatcher": [],
-            "options": {
-                "cwd": "${command:cmake.buildDirectory}/Application",
-                "environment": {
-                    "CLICOLOR_FORCE": "1",
-                    "OPENOCD_SCRIPTS": ""
-                }
-            },
-            "presentation": {
-                "clear": true
-            }
-        },
        {
            "label": "Build",
            "type": "cmake",
@@ -130,7 +20,8 @@
            ],
            "options": {
                "environment": {
-                    "CLICOLOR_FORCE": "1"
+                    "CLICOLOR_FORCE": "1",
+                    "OPENOCD_SCRIPTS": "${env:GD32_OPENOCD_SCRIPTS}"
                }
            },
            "presentation": {
@@ -140,6 +31,224 @@
                "id": "code",
                "tooltip": "Build"
            }
+        },
+        {
+            "label": "Build and Flash",
+            "dependsOn": [
+                "Build",
+                "Flash MCU"
+            ],
+            "dependsOrder": "sequence",
+            "group": "build",
+            "icon": {
+                "id": "insert",
+                "tooltip": "Build and Flash"
+            }
+        },
+        {
+            "label": "Flash MCU",
+            "type": "process",
+            "command": "${env:GD32_OPENOCD_BIN}/openocd.exe",
+            "args": [
+                "-s", "${env:GD32_OPENOCD_SCRIPTS}",
+                "-f", "${env:GD32_OPENOCD_SCRIPTS}/${config:gd32.openocd.targetConfig}",
+                "-c", "init; reset halt; flash write_image erase ${command:cmake.launchTargetFilename}; reset; exit"
+            ],
+            "group": "build",
+            "problemMatcher": [],
+            "options": {
+                "cwd": "${command:cmake.buildDirectory}/Application",
+                "environment": {
+                    "OPENOCD_SCRIPTS": "${env:GD32_OPENOCD_SCRIPTS}"
+                }
+            },
+            "presentation": {
+                "clear": true
+            },
+            "icon": {
+                "id": "gather",
+                "tooltip": "Flash MCU"
+            }
+        },
+        {
+            "label": "Flash MCU (DAPLink)",
+            "type": "process",
+            "command": "${env:GD32_OPENOCD_BIN}/openocd.exe",
+            "args": [
+                "-s", "${env:GD32_OPENOCD_SCRIPTS}",
+                "-f", "${workspaceFolder}/.vscode/openocd_daplink_gd32e23x.cfg",
+                "-c", "program Application.elf verify reset exit"
+            ],
+            "group": "build",
+            "problemMatcher": [],
+            "options": {
+                "cwd": "${command:cmake.buildDirectory}/Application",
+                "environment": {
+                    "OPENOCD_SCRIPTS": "${env:GD32_OPENOCD_SCRIPTS}"
+                }
+            },
+            "presentation": {
+                "clear": true
+            },
+            "icon": {
+                "id": "zap",
+                "tooltip": "Flash MCU via DAPLink (no connect_assert_srst)"
+            }
+        },
+        {
+            "label": "Reset MCU",
+            "type": "process",
+            "command": "${env:GD32_OPENOCD_BIN}/openocd.exe",
+            "args": [
+                "-s", "${env:GD32_OPENOCD_SCRIPTS}",
+                "-f", "${env:GD32_OPENOCD_SCRIPTS}/${config:gd32.openocd.targetConfig}",
+                "-c", "init; reset; exit"
+            ],
+            "group": "build",
+            "problemMatcher": [],
+            "options": {
+                "cwd": "${command:cmake.buildDirectory}/Application",
+                "environment": {
+                    "OPENOCD_SCRIPTS": "${env:GD32_OPENOCD_SCRIPTS}"
+                }
+            },
+            "presentation": {
+                "clear": true
+            },
+            "icon": {
+                "id": "discard",
+                "tooltip": "Reset MCU"
+            }
+        },
+        {
+            "label": "Mass Erase MCU",
+            "type": "process",
+            "command": "${env:GD32_OPENOCD_BIN}/openocd.exe",
+            "args": [
+                "-s", "${env:GD32_OPENOCD_SCRIPTS}",
+                "-f", "${env:GD32_OPENOCD_SCRIPTS}/${config:gd32.openocd.targetConfig}",
+                "-c", "init; reset halt; ${config:gd32.openocd.massEraseCommand}; exit"
+            ],
+            "group": "build",
+            "problemMatcher": [],
+            "options": {
+                "cwd": "${command:cmake.buildDirectory}/Application",
+                "environment": {
+                    "OPENOCD_SCRIPTS": "${env:GD32_OPENOCD_SCRIPTS}"
+                }
+            },
+            "presentation": {
+                "clear": true
+            },
+            "icon": {
+                "id": "clear-all",
+                "tooltip": "Erase MCU"
+            }
+        },
+        {
+            "label": "OpenOCD Server",
+            "type": "process",
+            "command": "${env:GD32_OPENOCD_BIN}/openocd.exe",
+            "args": [
+                "-s", "${env:GD32_OPENOCD_SCRIPTS}",
+                "-f", "${env:GD32_OPENOCD_SCRIPTS}/${config:gd32.openocd.targetConfig}"
+            ],
+            "group": "build",
+            "problemMatcher": [],
+            "options": {
+                "cwd": "${command:cmake.buildDirectory}/Application",
+                "environment": {
+                    "OPENOCD_SCRIPTS": "${env:GD32_OPENOCD_SCRIPTS}"
+                }
+            },
+            "presentation": {
+                "clear": true
+            }
+        },
+        {
+            "label": "Build and Flash (Jlink)",
+            "dependsOn": [
+                "Build",
+                "Flash MCU (Jlink)"
+            ],
+            "dependsOrder": "sequence",
+            "group": "build",
+            "icon": {
+                "id": "insert",
+                "tooltip": "Build and Flash (Jlink)"
+            }
+        },
+        {
+            "label": "Flash MCU (Jlink)",
+            "type": "process",
+            "command": "JLink.exe",
+            "args": [
+                "-device", "${config:gd32.jlink.device}",
+                "-if", "${config:gd32.jlink.interface}",
+                "-speed", "${config:gd32.jlink.speed}",
+                "-autoconnect", "1",
+                "-CommanderScript", "${workspaceFolder}/.vscode/flash.jlink"
+            ],
+            "group": "build",
+            "problemMatcher": [],
+            "options": {
+                "cwd": "${command:cmake.buildDirectory}/Application"
+            },
+            "presentation": {
+                "clear": true
+            },
+            "icon": {
+                "id": "gather",
+                "tooltip": "Flash MCU (Jlink)"
+            }
+        },
+        {
+            "label": "Reset MCU (Jlink)",
+            "type": "process",
+            "command": "JLink.exe",
+            "args": [
+                "-device", "${config:gd32.jlink.device}",
+                "-if", "${config:gd32.jlink.interface}",
+                "-speed", "${config:gd32.jlink.speed}",
+                "-autoconnect", "1",
+                "-CommanderScript", "${workspaceFolder}/.vscode/reset.jlink"
+            ],
+            "group": "build",
+            "problemMatcher": [],
+            "options": {
+                "cwd": "${workspaceFolder}"
+            },
+            "presentation": {
+                "clear": true
+            },
+            "icon": {
+                "id": "discard",
+                "tooltip": "Reset MCU (Jlink)"
+            }
+        },
+        {
+            "label": "Mass Erase MCU (Jlink)",
+            "type": "process",
+            "command": "JLink.exe",
+            "args": [
+                "-device", "${config:gd32.jlink.device}",
+                "-if", "${config:gd32.jlink.interface}",
+                "-speed", "${config:gd32.jlink.speed}",
+                "-autoconnect", "1",
+                "-CommanderScript", "${workspaceFolder}/.vscode/erase.jlink"
+            ],
+            "group": "build",
+            "problemMatcher": [],
+            "options": {
+                "cwd": "${workspaceFolder}"
+            },
+            "presentation": {
+                "clear": true
+            },
+            "icon": {
+                "id": "clear-all",
+                "tooltip": "Erase MCU (Jlink)"
+            }
        }
    ]
-}
+}
@@ -0,0 +1,128 @@
+# 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     复用 MB 板 BL bin（V0.1.0，4,044B，MD5 f7b447cf…）
+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 复用**：直接使用 `gd32e230_bootloader` 仓库 `bootloader_CeramixNano_MB` 分支
+  V0.1.0 bin（RS485 引脚/波特率/DE 方案与 EDDY 完全一致；唯一差异 LED 引脚
+  MB=PA14 / EDDY=PB1——BL 的 LED 仅 Ymodem 收包闪烁，纯装饰，EDDY 板不亮无碍）。
+- **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 复用 MB V0.1.0 bin（未改动 BL 代码，仅文档说明）
+  - 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（A=V1.0.3/B=V1.0.2，19 项校验过）、FACTORY（12 项校验过）+ MD5 清单；
+    独立 python XMODEM 复算全部命中
+  - **硬件实测矩阵（SWD 探针 PC 采样 + 485 命令双重手段，全部 PASS）**：
+    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 宏体系同步
+
+### 教训（避免复发）
+
+- **SWRSTF 残留**：M9999/调试器软复位置位的 SWRSTF **不随 NRST/SRST 清除**（仅 POR
+  或 RSTFC 清），此后任何复位 BL 都直进升级模式、不跳 APP——表现为"设备沉默，
+  M999 无响应，但 0x30 能回 ok"。排障/测试时须 SWD `mww 0x40021024 0x01000000`
+  清标志后再放跑（`swd.py boot` 已内置）。
+- **BL 收到 0x30 后 SWD 必死**：复用的 MB BL 在 0x30 应答后调用 gpio_init 把
+  PA14（EDDY 板=SWCLK）切为 LED 输出。因此：探针类 SWD 操作前**不要**发 0x30；
+  OTA/升级会话结束后 SWD 失联属预期，恢复 = `M9999` 复位（PA14 回默认）后再连。
+  若 APP 也没在跑（BL 卡收包），用 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 正常路径均带）。
@@ -62,6 +62,9 @@ target_link_options(${PROJECT_NAME} PRIVATE
    -T${CMAKE_SOURCE_DIR}/LD/gd32e23x_flash.ld -Xlinker
    -L${CMAKE_SOURCE_DIR}/LD
 )
+# LD 变更时触发重链接（改布局不重编也要重新生成 bin）
+set_target_properties(${PROJECT_NAME} PROPERTIES LINK_DEPENDS
+    ${CMAKE_SOURCE_DIR}/LD/gd32e23x_flash.ld)

 # 生成 map 文件等
 target_link_options(${PROJECT_NAME} PRIVATE
@@ -79,7 +82,8 @@ add_custom_command(TARGET ${PROJECT_NAME}
    POST_BUILD
    COMMAND echo -- Running Post Build Commands
    COMMAND ${CMAKE_OBJCOPY} -O ihex $<TARGET_FILE:${PROJECT_NAME}> ${CMAKE_CURRENT_BINARY_DIR}/${OUTPUT_PREFIX}.hex
-    COMMAND ${CMAKE_OBJCOPY} -O binary $<TARGET_FILE:${PROJECT_NAME}> ${CMAKE_CURRENT_BINARY_DIR}/${OUTPUT_PREFIX}.bin
+        COMMAND ${CMAKE_OBJCOPY} -O ihex $<TARGET_FILE:${PROJECT_NAME}> $<TARGET_FILE_DIR:${PROJECT_NAME}>/Application.hex
+    COMMAND ${CMAKE_OBJCOPY} -O binary --gap-fill=0xFF $<TARGET_FILE:${PROJECT_NAME}> ${CMAKE_CURRENT_BINARY_DIR}/${OUTPUT_PREFIX}.bin
    COMMAND ${CMAKE_SIZE} $<TARGET_FILE:${PROJECT_NAME}>
    COMMAND ${CMAKE_OBJDUMP} -h -S $<TARGET_FILE:${PROJECT_NAME}> > ${CMAKE_CURRENT_BINARY_DIR}/${OUTPUT_PREFIX}.list
    COMMAND ${CMAKE_SIZE} --format=berkeley $<TARGET_FILE:${PROJECT_NAME}> > ${CMAKE_CURRENT_BINARY_DIR}/${OUTPUT_PREFIX}.bsz
@@ -58,5 +58,28 @@

 ### 4. 单次读取并发送板载温度传感器数据

- M3 指令 单次读取并发送板载温度传感器数据
+- M4 指令 单次读取并发送板载温度传感器数据（TMP112，返回温度值×10000，4 字节有符号大端）
    - `D5 03 02 4D 34 86`
+    - 示例回复：`B5 F0 04 00 04 28 74 94`，有效数据 `0x00042874` = 272500，即 `27.25°C`
+
+### 5. 单次读取并发送温度补偿后的涡流传感器数据
+
+- M5 指令 单次读取并发送温度补偿后的涡流传感器数据（补偿系数默认为 0，与 M3 等价）
+    - `D5 03 02 4D 35 87`
+
+### 6. 单次读取并发送标定数据（涡流原始值 + 温度值）
+
+- M6 指令 单次读取涡流原始值和板载温度值，用于温度标定
+    - `D5 03 02 4D 36 88`
+    - 回复 9 字节：涡流原始值(4字节大端) + 0xFF + 温度值×10000(4字节大端)
+    - 示例回复：`B5 F0 09 01 AD BA DC FF 00 04 28 74 DC`
+
+### 7. 查询固件版本号
+
+- M999 指令 返回固件版本号字符串，如 `v23.1.0.1`（板卡类型.主版本.次版本.修订号）
+    - `D5 03 04 4D 39 39 39 FF`
+
+### 8. 复位 MCU
+
+- M9999 指令 立即复位 MCU（无回复）
+    - `D5 03 05 4D 39 39 39 39 39`
@@ -89,9 +89,9 @@ i2c_result_t i2c_bus_reset(void);
 void i2c_scan(void);

 /*!
-    \brief      write 16-bit data to I2C device
+    \brief      write 16-bit data to I2C device (8-bit register address + 2 data bytes)
    \param[in]  slave_addr: 7-bit slave address
-    \param[in]  reg_addr: register address
+    \param[in]  reg_addr: register address (8-bit)
    \param[in]  data: pointer to 2-byte data array
    \param[out] none
    \retval     i2c_result_t
@@ -99,9 +99,9 @@ void i2c_scan(void);
 i2c_result_t i2c_write_16bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t data[2]);

 /*!
-    \brief      read 16-bit data from I2C device
+    \brief      read 16-bit data from I2C device (8-bit register address + 2 data bytes)
    \param[in]  slave_addr: 7-bit slave address
-    \param[in]  reg_addr: register address
+    \param[in]  reg_addr: register address (8-bit)
    \param[out] data: pointer to 2-byte data buffer
    \retval     i2c_result_t
 */
@@ -111,70 +111,33 @@ i2c_result_t i2c_read_16bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data
 /*!
    \brief      write data to I2C device with configurable length
    \param[in]  slave_addr: slave device address (7-bit)
-    \param[in]  reg_addr: register address
+    \param[in]  reg_addr: register address (16-bit, high byte first)
    \param[in]  data: pointer to data buffer
    \param[in]  length: number of bytes to write (1-255)
    \param[out] none
    \retval     i2c_result_t: operation result
 */
-i2c_result_t i2c_write(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8_t length);
+i2c_result_t i2c_write(uint8_t slave_addr, uint16_t reg_addr, uint8_t *data, uint8_t length);

 /*!
    \brief      read data from I2C device with configurable length
    \param[in]  slave_addr: slave device address (7-bit)
-    \param[in]  reg_addr: register address
+    \param[in]  reg_addr: register address (16-bit, high byte first)
    \param[out] data: pointer to data buffer
    \param[in]  length: number of bytes to read (1-255)
    \retval     i2c_result_t: operation result
 */
-i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8_t length);
+i2c_result_t i2c_read(uint8_t slave_addr, uint16_t reg_addr, uint8_t *data, uint8_t length);

-/* Convenience functions for common operations */
+/* Pure read response without sub-address phase (for commands that already sent read request parameters) */
 /*!
-    \brief      write single byte to I2C device
+    \brief      read data from I2C device without register/sub-address phase
    \param[in]  slave_addr: slave device address (7-bit)
-    \param[in]  reg_addr: register address
-    \param[in]  data: data byte to write
-    \retval     i2c_result_t: operation result
-*/
-i2c_result_t i2c_write_8bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t data);
-
-/*!
-    \brief      read single byte from I2C device
-    \param[in]  slave_addr: slave device address (7-bit)
-    \param[in]  reg_addr: register address
-    \param[out] data: pointer to data byte
-    \retval     i2c_result_t: operation result
-*/
-i2c_result_t i2c_read_8bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data);
-
-/*!
-    \brief      write 32-bit data to I2C device
-    \param[in]  slave_addr: slave device address (7-bit)
-    \param[in]  reg_addr: register address
-    \param[in]  data: pointer to 4-byte data array
-    \retval     i2c_result_t: operation result
-*/
-i2c_result_t i2c_write_32bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t data[4]);
-
-/*!
-    \brief      read 32-bit data from I2C device
-    \param[in]  slave_addr: slave device address (7-bit)
-    \param[in]  reg_addr: register address
-    \param[out] data: pointer to 4-byte data buffer
-    \retval     i2c_result_t: operation result
-*/
-i2c_result_t i2c_read_32bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data);
-
-/*!
-    \brief      read display panel parameters (multi-byte)
-    \param[in]  slave_addr: slave device address (7-bit)
-    \param[in]  reg_addr: register address
    \param[out] data: pointer to data buffer
-    \param[in]  length: number of bytes to read (1-13)
+    \param[in]  length: number of bytes to read (1-255)
    \retval     i2c_result_t: operation result
 */
-i2c_result_t i2c_read_display_params(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8_t length);
+i2c_result_t i2c_read_raw(uint8_t slave_addr, uint8_t *data, uint8_t length);

 #ifdef DEBUG_VERBOSE
 /*!
@@ -10,9 +10,11 @@ _Min_Heap_Size = 0x200; /* required amount of heap */
 _Min_Stack_Size = 0x400; /* required amount of stack */

 /* Memories definition */
+/* FW_B 保底槽布局：0x0800B000~0x0800FC00 共 19K，末 8B（0x0800FBF8 起）为 B 记录
+ * {magic16,pages16,crc16,2B 保留}，由打包工具写入，链接区上限 = 槽 - 8B = 0x4BF8 */
 MEMORY
 {
-    FLASH (rx)  : ORIGIN = 0x08000000, LENGTH = 32K
+    FLASH (rx)  : ORIGIN = 0x0800B000, LENGTH = 0x4BF8
    RAM (xrw)   : ORIGIN = 0x20000000, LENGTH = 8K
 }

@@ -1,11 +1,36 @@
-# GD32E23x 工程模板
+# LDC1612 传感器固件

-本仓库为兆易创新 GD32E23x 系列 MCU 的 CMake + VSCode 工程模板，适合嵌入式开发快速上手和团队协作。
+本仓库基于 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)
 - [适用范围](#适用范围)
 - [默认配置](#默认配置)
 - [工具链准备](#工具链准备)
@@ -16,6 +41,30 @@

 ---

+## 固件布局与 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 内核单片机
@@ -34,37 +83,49 @@

 ### 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  
+- **原模板版本**：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  
 - **路径自定义说明**：  
-  如需自定义工具链路径，请同步修改以下文件：  
-  - `Projects/<BoardName>/<ProjectName>/cmake/arm-none-eabi-gcc.cmake`（第2行）  
-  - `Projects/<BoardName>/<ProjectName>/.vscode/launch.json`（第12行）
+  编译器与 GDB 均通过 `GD32_GCC_BIN` 环境变量定位（或配置时传 `-DTOOLCHAIN_DIRECTORY`），CMake 文件与 `.vscode` 均无需修改路径。

-### 2. OpenOCD
+### 2. OpenOCD（GD-Link 支持）

 - **版本**：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` 中所有相关路径
+  通过两个环境变量定位，安装位置任意：  
+  - `GD32_OPENOCD_BIN`：`openocd.exe` 所在 `bin` 目录；  
+  - `GD32_OPENOCD_SCRIPTS`：OpenOCD `scripts` 目录。  
+  `.vscode` 的调试配置与烧录任务全部读取这两个变量，无需修改任何文件。

 ---

 ## 使用说明

-1. **准备工具链**  
-   - 按上述说明下载并解压 ARM GCC 和 OpenOCD 到 Tools 目录。
-   - Toolchain 目录内容不会被 git 跟踪，需自行维护。
+1. **配置环境变量**（用户级，按本机安装位置设置一次即可）

-2. **烧录固件**  
-   - 可直接使用 VSCode 任务栏的 Flash MCU 任务，或命令行运行 OpenOCD。
+   | 环境变量 | 指向 | 用途 |
+   |---|---|---|
+   | `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 直接选用对应配置即可。

 ---

@@ -129,7 +190,6 @@

 - **快速上手示例**：如 main.c 的最小点灯/串口输出代码片段。
 - **常见问题与解答**：如构建失败、烧录失败的排查建议。
- **调试说明**：如何用 VSCode 调试、断点、查看寄存器等。
 - **多板卡适配说明**：如有多种硬件，如何切换 BoardName。
 - **贡献指南**：如何提交 PR、代码风格约定等。
 - **License 说明**：开源协议和版权声明。
@@ -34,6 +34,7 @@ void i2c_gpio_config(void) {
 i2c_result_t i2c_config(void) {
    /* configure I2C GPIO */
    i2c_gpio_config();
+
    /* enable I2C clock */
    rcu_periph_clock_enable(RCU_I2C);
    /* configure I2C clock */
@@ -149,7 +150,7 @@ i2c_result_t i2c_bus_reset(void) {
    }

 #ifdef DEBUG_VERBOSE
-        printf("I2C bus reset: bus recovered\r\n");
+    printf("I2C bus reset: bus recovered\r\n");
 #endif
    /* 8. Reconfigure & enable peripheral */
    i2c_config();
@@ -197,10 +198,12 @@ void i2c_scan(void) {
        i2c_master_addressing(I2C0, (address << 1), I2C_TRANSMITTER);
        timeout = 0;

-        // 等待地址发送完成
-        while (!i2c_flag_get(I2C0, I2C_FLAG_ADDSEND) && (timeout < I2C_TIME_OUT))
+        // 等待地址发送完成或错误
+        while (!i2c_flag_get(I2C0, I2C_FLAG_ADDSEND) && !i2c_flag_get(I2C0, I2C_FLAG_AERR) && (timeout < I2C_TIME_OUT))
            timeout++;
-        if (timeout < I2C_TIME_OUT) {
+
+        if (timeout < I2C_TIME_OUT && i2c_flag_get(I2C0, I2C_FLAG_ADDSEND)) {
+            // 设备响应 - 清除地址标志
            i2c_flag_clear(I2C0, I2C_FLAG_ADDSEND);
            // printf("Found device at 0x%02X\r\n", address);
            const char* msg2_prefix = "Found device at 0x";
@@ -221,6 +224,9 @@ void i2c_scan(void) {
            }
            while (usart_flag_get(I2C_DEBUG_UART, USART_FLAG_TC) == RESET) {}
            found_devices++;
+        } else if (i2c_flag_get(I2C0, I2C_FLAG_AERR)) {
+            // 设备无响应 - 清除错误标志
+            i2c_flag_clear(I2C0, I2C_FLAG_AERR);
        }

        // 生成停止条件
@@ -263,6 +269,53 @@ void i2c_scan(void) {
    }
 }

+/**
+ * @brief 内部辅助函数：等待指定的I2C标志位被设置，带有超时。
+ * @param[in]  flag: 要等待的I2C事件标志。
+ * @retval     i2c_result_t: I2C_RESULT_SUCCESS 或 I2C_RESULT_TIMEOUT。
+ */
+static i2c_result_t _i2c_wait_flag_timeout(uint32_t flag)
+{
+    uint16_t timeout = 0;
+    while(!i2c_flag_get(I2C0, flag)){
+        if(timeout++ > I2C_TIME_OUT){
+#ifdef DEBUG_VERBOSE
+            const char* fname = "UNKNOWN";
+            switch (flag) {
+                case I2C_FLAG_SBSEND: fname = "SBSEND"; break;
+                case I2C_FLAG_ADDSEND: fname = "ADDSEND"; break;
+                case I2C_FLAG_TBE: fname = "TBE"; break;
+                case I2C_FLAG_RBNE: fname = "RBNE"; break;
+                case I2C_FLAG_BTC: fname = "BTC"; break;
+                case I2C_FLAG_AERR: fname = "AERR"; break;
+                case I2C_FLAG_BERR: fname = "BERR"; break;
+                case I2C_FLAG_LOSTARB: fname = "LOSTARB"; break;
+                case I2C_FLAG_I2CBSY: fname = "I2CBSY"; break;
+            }
+            printf("I2C wait flag timeout: flag=0x%08X (%s)\r\n", (unsigned int)flag, fname);
+#endif
+            return I2C_RESULT_TIMEOUT;
+        }
+    }
+    return I2C_RESULT_SUCCESS;
+}
+
+/**
+ * @brief 内部辅助函数：等待指定的I2C标志位被清除，带有超时。
+ * @param[in]  flag: 要等待的I2C事件标志。
+ * @retval     i2c_result_t: I2C_RESULT_SUCCESS 或 I2C_RESULT_TIMEOUT。
+ */
+static i2c_result_t _i2c_wait_flag_clear_timeout(uint32_t flag)
+{
+    uint16_t timeout = 0;
+    while(i2c_flag_get(I2C0, flag)){
+        if(timeout++ > I2C_TIME_OUT){
+            return I2C_RESULT_TIMEOUT;
+        }
+    }
+    return I2C_RESULT_SUCCESS;
+}
+
 i2c_result_t i2c_write_16bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t data[2]) {
    i2c_state_t state = I2C_STATE_START;
    uint16_t timeout = 0;
@@ -325,7 +378,7 @@ i2c_result_t i2c_write_16bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t data
                } else {
                    i2c_flag_clear(I2C0, I2C_FLAG_AERR);
                    timeout =0;
-#ifdef DEBUG_VERBOES
+#ifdef DEBUG_VERBOSE
                    printf("IIC write failed for Error Slave Address. \n");
 #endif
                    return I2C_RESULT_NACK;
@@ -333,39 +386,28 @@ i2c_result_t i2c_write_16bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t data

            case I2C_STATE_TRANSMIT_REG:
                /* wait until the transmit data buffer is empty */
-                while ((!i2c_flag_get(I2C0, I2C_FLAG_TBE)) && (timeout < I2C_TIME_OUT)) {
-                    timeout++;
-                }
-                if (timeout >= I2C_TIME_OUT) {
+                if(_i2c_wait_flag_timeout(I2C_FLAG_TBE) != I2C_RESULT_SUCCESS) {
                    state = I2C_STATE_ERROR;
                    break;
                }

                /* send register address */
                i2c_data_transmit(I2C0, reg_addr);
-                timeout = 0;
                state = I2C_STATE_TRANSMIT_DATA;
                break;

            case I2C_STATE_TRANSMIT_DATA:
                /* wait until the transmit data buffer is empty */
-                while ((!i2c_flag_get(I2C0, I2C_FLAG_TBE)) && (timeout < I2C_TIME_OUT)) {
-                    timeout++;
-                }
-                if (timeout >= I2C_TIME_OUT) {
+                if(_i2c_wait_flag_timeout(I2C_FLAG_TBE) != I2C_RESULT_SUCCESS) {
                    state = I2C_STATE_ERROR;
                    break;
                }

                /* send register MSB value */
                i2c_data_transmit(I2C0, data[0]);
-                timeout = 0;
-                
+
                /* wait until the transmit data buffer is empty */
-                while ((!i2c_flag_get(I2C0, I2C_FLAG_TBE)) && (timeout < I2C_TIME_OUT)) {
-                    timeout++;
-                }
-                if (timeout >= I2C_TIME_OUT) {
+                if(_i2c_wait_flag_timeout(I2C_FLAG_TBE) != I2C_RESULT_SUCCESS) {
                    state = I2C_STATE_ERROR;
                    break;
                }
@@ -381,13 +423,9 @@ i2c_result_t i2c_write_16bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t data

                /* send register LSB value */
                i2c_data_transmit(I2C0, data[1]);
-                timeout = 0;
-                
+
                /* wait until BTC bit is set */
-                while (!i2c_flag_get(I2C0, I2C_FLAG_BTC) && (timeout < I2C_TIME_OUT)) {
-                    timeout++;
-                }
-                if (timeout >= I2C_TIME_OUT) {
+                if(_i2c_wait_flag_timeout(I2C_FLAG_BTC) != I2C_RESULT_SUCCESS) {
                    state = I2C_STATE_ERROR;
                    break;
                }
@@ -413,25 +451,13 @@ i2c_result_t i2c_write_16bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t data
                return I2C_RESULT_SUCCESS;

            case I2C_STATE_ERROR:
-                /* send a stop condition to I2C bus */
-                i2c_stop_on_bus(I2C0);
-
-                timeout = 0;
-                while ((I2C_CTL0(I2C0) & I2C_CTL0_STOP) && (timeout < I2C_TIME_OUT)) {
-                    timeout++;
-                }
-                if (timeout >= I2C_TIME_OUT) {
-                    return I2C_RESULT_ERROR;
-                }
-
-                i2c_flag_clear(I2C0, I2C_FLAG_AERR);
-                i2c_flag_clear(I2C0, I2C_FLAG_BERR);
-                i2c_flag_clear(I2C0, I2C_FLAG_LOSTARB);
+                /* I2C bus error, try to reset the bus and retry */
+                i2c_bus_reset();

                retry_count ++;
                if (retry_count >= I2C_MAX_RETRY)
                {
-#ifdef DEBUG_VERBOES
+#ifdef DEBUG_VERBOSE
                    printf("IIC write failed after %d retries\n", I2C_MAX_RETRY);
 #endif
                    return I2C_RESULT_ERROR;
@@ -444,7 +470,7 @@ i2c_result_t i2c_write_16bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t data
                /* small delay before retry */
                delay_10us(10);
                break;
-                
+
            default:
                state = I2C_STATE_START;
                break;
@@ -472,11 +498,8 @@ i2c_result_t i2c_read_16bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data
            case I2C_STATE_START:
                timeout = 0;

-                // wait for bus to be idle
-                while (i2c_flag_get(I2C0, I2C_FLAG_I2CBSY) && (timeout < I2C_TIME_OUT)) {
-                    timeout++;
-                }
-                if (timeout >= I2C_TIME_OUT) {
+                /* wait for bus to be idle */
+                if(_i2c_wait_flag_clear_timeout(I2C_FLAG_I2CBSY) != I2C_RESULT_SUCCESS) {
                    state = I2C_STATE_ERROR;
                    break;
                }
@@ -484,15 +507,11 @@ i2c_result_t i2c_read_16bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data
                // send start condition
                i2c_start_on_bus(I2C0);
                state = I2C_STATE_SEND_ADDRESS;
-                timeout = 0;
                break;

            case I2C_STATE_SEND_ADDRESS:
                /* wait for start condition to be sent  */
-                while ((!i2c_flag_get(I2C0, I2C_FLAG_SBSEND)) && (timeout < I2C_TIME_OUT)) {
-                    timeout++;
-                }
-                if (timeout >= I2C_TIME_OUT) {
+                if(_i2c_wait_flag_timeout(I2C_FLAG_SBSEND) != I2C_RESULT_SUCCESS) {
                    state = I2C_STATE_ERROR;
                    break;
                }
@@ -540,10 +559,7 @@ i2c_result_t i2c_read_16bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data

            case I2C_STATE_TRANSMIT_DATA:
                /* wait for transmit buffer to be empty */
-                while ((!i2c_flag_get(I2C0, I2C_FLAG_TBE)) && (timeout < I2C_TIME_OUT)) {
-                    timeout++;
-                }
-                if (timeout >= I2C_TIME_OUT) {
+                if(_i2c_wait_flag_timeout(I2C_FLAG_TBE) != I2C_RESULT_SUCCESS) {
                    state = I2C_STATE_ERROR;
                    break;
                }
@@ -551,28 +567,20 @@ i2c_result_t i2c_read_16bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data
                /* send register address */
                i2c_data_transmit(I2C0, reg_addr);
                state = I2C_STATE_RESTART;
-                timeout = 0;
                break;

            case I2C_STATE_RESTART:
                /* wait for byte transfer complete  BTC: Bit Transfer Complete */
-                while ((!i2c_flag_get(I2C0, I2C_FLAG_BTC)) && (timeout < I2C_TIME_OUT)) {
-                    timeout++;
-                }
-                if (timeout >= I2C_TIME_OUT) {
+                if(_i2c_wait_flag_timeout(I2C_FLAG_BTC) != I2C_RESULT_SUCCESS) {
                    state = I2C_STATE_ERROR;
                    break;
                }

                /* generate repeated start condition */
                i2c_start_on_bus(I2C0);
-                
+
                /* wait for repeated start condition to be sent */
-                timeout = 0;
-                while ((!i2c_flag_get(I2C0, I2C_FLAG_SBSEND)) && (timeout < I2C_TIME_OUT)) {
-                    timeout++;
-                }
-                if (timeout >= I2C_TIME_OUT) {
+                if(_i2c_wait_flag_timeout(I2C_FLAG_SBSEND) != I2C_RESULT_SUCCESS) {
                    state = I2C_STATE_ERROR;
                    break;
                }
@@ -588,10 +596,7 @@ i2c_result_t i2c_read_16bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data

            case I2C_STATE_RECEIVE_DATA:
                /* Wait for BTC (both bytes received) */
-                while ((!i2c_flag_get(I2C0, I2C_FLAG_BTC)) && (timeout < I2C_TIME_OUT)) {
-                    timeout++;
-                }
-                if (timeout >= I2C_TIME_OUT) {
+                if(_i2c_wait_flag_timeout(I2C_FLAG_BTC) != I2C_RESULT_SUCCESS) {
                    state = I2C_STATE_ERROR;
                    break;
                }
@@ -621,13 +626,13 @@ i2c_result_t i2c_read_16bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data
                return I2C_RESULT_SUCCESS;

            case I2C_STATE_ERROR:
-                /* send stop condition to release bus */
-                i2c_stop_on_bus(I2C0);
+                /* I2C bus error, try to reset the bus and retry */
+                i2c_bus_reset();

                retry_count++;
                if (retry_count >= I2C_MAX_RETRY) {
-#ifdef DEBUG_VERBOES
-                    printf("IIC read failed after %d retries\n", I2C_RETRY_MAX);
+#ifdef DEBUG_VERBOSE
+                    printf("IIC read failed after %d retries\n", I2C_MAX_RETRY);
 #endif
                    return I2C_RESULT_ERROR;
                }
@@ -652,13 +657,13 @@ i2c_result_t i2c_read_16bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data
 /*!
    \brief      write data to I2C device with configurable length
    \param[in]  slave_addr: slave device address (7-bit)
-    \param[in]  reg_addr: register address
+    \param[in]  reg_addr: register address (16-bit, high byte first)
    \param[in]  data: pointer to data buffer
    \param[in]  length: number of bytes to write (1-255)
    \param[out] none
    \retval     i2c_result_t: operation result
 */
-i2c_result_t i2c_write(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8_t length) {
+i2c_result_t i2c_write(uint8_t slave_addr, uint16_t reg_addr, uint8_t *data, uint8_t length) {
    i2c_state_t state = I2C_STATE_START;
    uint16_t timeout = 0;
    uint8_t retry_count = 0;
@@ -666,6 +671,9 @@ i2c_result_t i2c_write(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint

    /* parameter validation */
    if (data == NULL || slave_addr > 0x7F || length == 0) {
+#ifdef DEBUG_VERBOSE
+        printf("I2C write invalid param: slave=0x%02X, len=%u, data=%p\r\n", slave_addr, length, data);
+#endif
        return I2C_RESULT_INVALID_PARAM;
    }

@@ -719,67 +727,71 @@ i2c_result_t i2c_write(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint
                    state = I2C_STATE_TRANSMIT_REG;
                    break;
                } else {
+                    /* NACK received - address not acknowledged */
                    i2c_flag_clear(I2C0, I2C_FLAG_AERR);
+                    i2c_stop_on_bus(I2C0);
                    timeout = 0;
 #ifdef DEBUG_VERBOSE
-                    printf("IIC write failed for Error Slave Address. \n");
+                    printf("I2C write failed for Error Slave Address. \n");
 #endif
                    return I2C_RESULT_NACK;
                }

            case I2C_STATE_TRANSMIT_REG:
                /* wait until the transmit data buffer is empty */
-                while ((!i2c_flag_get(I2C0, I2C_FLAG_TBE)) && (timeout < I2C_TIME_OUT)) {
-                    timeout++;
-                }
-                if (timeout >= I2C_TIME_OUT) {
+                if(_i2c_wait_flag_timeout(I2C_FLAG_TBE) != I2C_RESULT_SUCCESS) {
                    state = I2C_STATE_ERROR;
                    break;
                }

-                /* send register address */
-                i2c_data_transmit(I2C0, reg_addr);
-                timeout = 0;
+                /* send register address, high byte first */
+                if(_i2c_wait_flag_timeout(I2C_FLAG_TBE) != I2C_RESULT_SUCCESS) {
+                    state = I2C_STATE_ERROR;
+                    break;
+                }
+                i2c_data_transmit(I2C0, (uint8_t)(reg_addr >> 8));
+
+                if(_i2c_wait_flag_timeout(I2C_FLAG_TBE) != I2C_RESULT_SUCCESS) {
+                    state = I2C_STATE_ERROR;
+                    break;
+                }
+                i2c_data_transmit(I2C0, (uint8_t)(reg_addr & 0xFF));
                state = I2C_STATE_TRANSMIT_DATA;
                break;

            case I2C_STATE_TRANSMIT_DATA:
                /* wait until the transmit data buffer is empty */
-                while ((!i2c_flag_get(I2C0, I2C_FLAG_TBE)) && (timeout < I2C_TIME_OUT)) {
-                    timeout++;
-                }
-                if (timeout >= I2C_TIME_OUT) {
-                    state = I2C_STATE_ERROR;
-                    break;
-                }
+                while (data_index < length) {
+                    if(_i2c_wait_flag_timeout(I2C_FLAG_TBE) != I2C_RESULT_SUCCESS) {
+                        state = I2C_STATE_ERROR;
+                        break;
+                    }

-                /* send data byte */
-                i2c_data_transmit(I2C0, data[data_index]);
-                data_index++;
+                    /* send data byte */
+                    i2c_data_transmit(I2C0, data[data_index]);
+                    data_index++;

-                /* check for errors */
-                if (i2c_flag_get(I2C0, I2C_FLAG_AERR)) {
-                    i2c_stop_on_bus(I2C0);
-                    return I2C_RESULT_NACK;
-                } else if (i2c_flag_get(I2C0, I2C_FLAG_BERR) || i2c_flag_get(I2C0, I2C_FLAG_LOSTARB)) {
-                    i2c_stop_on_bus(I2C0);
-                    return I2C_RESULT_ERROR;
+                    /* check for errors */
+                    if (i2c_flag_get(I2C0, I2C_FLAG_AERR)) {
+                        i2c_stop_on_bus(I2C0);
+                        return I2C_RESULT_NACK;
+                    } else if (i2c_flag_get(I2C0, I2C_FLAG_BERR) || i2c_flag_get(I2C0, I2C_FLAG_LOSTARB)) {
+                        i2c_stop_on_bus(I2C0);
+                        return I2C_RESULT_ERROR;
+                    }
                }
+                if(state == I2C_STATE_ERROR) break;
+

                /* check if all data has been sent */
                if (data_index >= length) {
                    /* wait until BTC bit is set for last byte */
-                    timeout = 0;
-                    while (!i2c_flag_get(I2C0, I2C_FLAG_BTC) && (timeout < I2C_TIME_OUT)) {
-                        timeout++;
-                    }
-                    if (timeout >= I2C_TIME_OUT) {
+                    if(_i2c_wait_flag_timeout(I2C_FLAG_BTC) != I2C_RESULT_SUCCESS) {
                        state = I2C_STATE_ERROR;
                        break;
                    }
                    state = I2C_STATE_STOP;
                }
-                timeout = 0;
                break;

            case I2C_STATE_STOP:
@@ -799,17 +811,8 @@ i2c_result_t i2c_write(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint
                return I2C_RESULT_SUCCESS;

            case I2C_STATE_ERROR:
-                /* send a stop condition to I2C bus */
-                i2c_stop_on_bus(I2C0);
-
-                timeout = 0;
-                while ((I2C_CTL0(I2C0) & I2C_CTL0_STOP) && (timeout < I2C_TIME_OUT)) {
-                    timeout++;
-                }
-
-                i2c_flag_clear(I2C0, I2C_FLAG_AERR);
-                i2c_flag_clear(I2C0, I2C_FLAG_BERR);
-                i2c_flag_clear(I2C0, I2C_FLAG_LOSTARB);
+                /* I2C bus error, try to reset the bus and retry */
+                i2c_bus_reset();

                retry_count++;
                if (retry_count >= I2C_MAX_RETRY) {
@@ -826,7 +829,7 @@ i2c_result_t i2c_write(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint
                /* small delay before retry */
                delay_10us(10);
                break;
-                
+
            default:
                state = I2C_STATE_START;
                break;
@@ -838,12 +841,12 @@ i2c_result_t i2c_write(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint
 /*!
    \brief      read data from I2C device with configurable length
    \param[in]  slave_addr: slave device address (7-bit)
-    \param[in]  reg_addr: register address
+    \param[in]  reg_addr: register address (16-bit, high byte first)
    \param[out] data: pointer to data buffer
    \param[in]  length: number of bytes to read (1-255)
    \retval     i2c_result_t: operation result
 */
-i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8_t length) {
+i2c_result_t i2c_read(uint8_t slave_addr, uint16_t reg_addr, uint8_t *data, uint8_t length) {
    i2c_state_t state = I2C_STATE_START;
    uint16_t timeout = 0;
    uint8_t retry_count = 0;
@@ -858,6 +861,10 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8
    /* enable acknowledge */
    i2c_ack_config(I2C0, I2C_ACK_ENABLE);

+#ifdef DEBUG_VERBOSE
+    printf("I2C read start: slave=0x%02X reg=0x%02X len=%u\r\n", slave_addr, reg_addr, length);
+#endif
+
    while (retry_count < (uint8_t)I2C_MAX_RETRY) {
        switch (state) {
            case I2C_STATE_START:
@@ -865,10 +872,7 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8
                data_index = 0;

                /* wait for bus to be idle */
-                while (i2c_flag_get(I2C0, I2C_FLAG_I2CBSY) && (timeout < I2C_TIME_OUT)) {
-                    timeout++;
-                }
-                if (timeout >= I2C_TIME_OUT) {
+                if(_i2c_wait_flag_clear_timeout(I2C_FLAG_I2CBSY) != I2C_RESULT_SUCCESS) {
                    state = I2C_STATE_ERROR;
                    break;
                }
@@ -876,15 +880,11 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8
                /* send start condition */
                i2c_start_on_bus(I2C0);
                state = I2C_STATE_SEND_ADDRESS;
-                timeout = 0;
                break;

            case I2C_STATE_SEND_ADDRESS:
                /* wait for start condition to be sent */
-                while ((!i2c_flag_get(I2C0, I2C_FLAG_SBSEND)) && (timeout < I2C_TIME_OUT)) {
-                    timeout++;
-                }
-                if (timeout >= I2C_TIME_OUT) {
+                if(_i2c_wait_flag_timeout(I2C_FLAG_SBSEND) != I2C_RESULT_SUCCESS) {
                    state = I2C_STATE_ERROR;
                    break;
                }
@@ -912,67 +912,92 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8
                    break;
                }

+                /* debug: show address ack and error flags */
+#ifdef DEBUG_VERBOSE
+                printf("I2C CLEAR_ADDRESS: write_phase=%d ADDSEND=%d AERR=%d\r\n",
+                       (int)write_phase,
+                       (int)i2c_flag_get(I2C0, I2C_FLAG_ADDSEND),
+                       (int)i2c_flag_get(I2C0, I2C_FLAG_AERR));
+#endif
+
                if (write_phase) {
                    /* clear address flag (write phase) */
                    i2c_flag_clear(I2C0, I2C_FLAG_ADDSEND);
                    state = I2C_STATE_TRANSMIT_DATA;
                } else {
-                    /* read phase setup based on length */
+                    /* READ phase: handle ACK/ACKPOS based on requested length
+                       - length == 1: disable ACK before clearing ADDR
+                       - length == 2: set ACKPOS_NEXT and disable ACK before clearing ADDR
+                       - length > 2: keep ACK enabled and clear ADDR; we'll handle N-2/BTF sequence later */
                    if (length == 1) {
-                        /* single byte read: disable ACK before clearing ADDR */
                        i2c_ack_config(I2C0, I2C_ACK_DISABLE);
-                        i2c_flag_clear(I2C0, I2C_FLAG_ADDSEND);
-                        /* send STOP immediately after clearing ADDR for single byte */
-                        i2c_stop_on_bus(I2C0);
+#ifdef DEBUG_VERBOSE
+                        printf("I2C READ phase: length=1, disabling ACK before clearing ADDSEND\r\n");
+#endif
                    } else if (length == 2) {
-                        /* two bytes read: set POS=NEXT and disable ACK before clearing ADDR */
                        i2c_ackpos_config(I2C0, I2C_ACKPOS_NEXT);
                        i2c_ack_config(I2C0, I2C_ACK_DISABLE);
-                        i2c_flag_clear(I2C0, I2C_FLAG_ADDSEND);
+#ifdef DEBUG_VERBOSE
+                        printf("I2C READ phase: length=2, set ACKPOS_NEXT and disabling ACK before clearing ADDSEND\r\n");
+#endif
                    } else {
-                        /* multi-byte read: clear ADDR with ACK enabled */
-                        i2c_flag_clear(I2C0, I2C_FLAG_ADDSEND);
+                        /* length > 2: keep ACK enabled so slave will clock out data */
+                        i2c_ack_config(I2C0, I2C_ACK_ENABLE);
+#ifdef DEBUG_VERBOSE
+                        printf("I2C READ phase: length=%u (>2), keeping ACK enabled\r\n", length);
+#endif
                    }
+
+                    /* now clear address flag to release SCL and enter data phase */
+                    i2c_flag_clear(I2C0, I2C_FLAG_ADDSEND);
+
                    state = I2C_STATE_RECEIVE_DATA;
                }
+
                timeout = 0;
                break;

            case I2C_STATE_TRANSMIT_DATA:
                /* wait for transmit buffer to be empty */
-                while ((!i2c_flag_get(I2C0, I2C_FLAG_TBE)) && (timeout < I2C_TIME_OUT)) {
-                    timeout++;
-                }
-                if (timeout >= I2C_TIME_OUT) {
+                if(_i2c_wait_flag_timeout(I2C_FLAG_TBE) != I2C_RESULT_SUCCESS) {
                    state = I2C_STATE_ERROR;
                    break;
                }

-                /* send register address */
-                i2c_data_transmit(I2C0, reg_addr);
+                /* send register address, high byte first */
+                if(_i2c_wait_flag_timeout(I2C_FLAG_TBE) != I2C_RESULT_SUCCESS) {
+                    state = I2C_STATE_ERROR;
+                    break;
+                }
+                i2c_data_transmit(I2C0, (uint8_t)(reg_addr >> 8));
+
+                if(_i2c_wait_flag_timeout(I2C_FLAG_TBE) != I2C_RESULT_SUCCESS) {
+                    state = I2C_STATE_ERROR;
+                    break;
+                }
+                i2c_data_transmit(I2C0, (uint8_t)(reg_addr & 0xFF));
                state = I2C_STATE_RESTART;
-                timeout = 0;
                break;

            case I2C_STATE_RESTART:
                /* wait for byte transfer complete */
-                while ((!i2c_flag_get(I2C0, I2C_FLAG_BTC)) && (timeout < I2C_TIME_OUT)) {
-                    timeout++;
-                }
-                if (timeout >= I2C_TIME_OUT) {
+                if(_i2c_wait_flag_timeout(I2C_FLAG_BTC) != I2C_RESULT_SUCCESS) {
                    state = I2C_STATE_ERROR;
                    break;
                }

+#ifdef DEBUG_VERBOSE
+                printf("I2C RESTART: after BTC, delay 5ms and issuing repeated START\r\n");
+#endif
+                /* small delay to allow slave device to prepare multi-byte data before repeated start */
+                /* increased to 5ms to improve reliability for DLPC multi-byte reads */
+                delay_ms(5);
+
                /* generate repeated start condition */
                i2c_start_on_bus(I2C0);
-                
+
                /* wait for repeated start condition to be sent */
-                timeout = 0;
-                while ((!i2c_flag_get(I2C0, I2C_FLAG_SBSEND)) && (timeout < I2C_TIME_OUT)) {
-                    timeout++;
-                }
-                if (timeout >= I2C_TIME_OUT) {
+                if(_i2c_wait_flag_timeout(I2C_FLAG_SBSEND) != I2C_RESULT_SUCCESS) {
                    state = I2C_STATE_ERROR;
                    break;
                }
@@ -984,15 +1009,18 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8
                write_phase = false;
                state = I2C_STATE_CLEAR_ADDRESS;
                timeout = 0;
+#ifdef DEBUG_VERBOSE
+                printf("I2C addressing sent for read (slave=0x%02X)\r\n", slave_addr);
+#endif
                break;

            case I2C_STATE_RECEIVE_DATA:
+#ifdef DEBUG_VERBOSE
+                printf("I2C RECEIVE_DATA: expecting %u bytes\r\n", length);
+#endif
                if (length == 1) {
                    /* single byte read */
-                    while ((!i2c_flag_get(I2C0, I2C_FLAG_RBNE)) && (timeout < I2C_TIME_OUT)) {
-                        timeout++;
-                    }
-                    if (timeout >= I2C_TIME_OUT) {
+                    if(_i2c_wait_flag_timeout(I2C_FLAG_RBNE) != I2C_RESULT_SUCCESS) {
                        state = I2C_STATE_ERROR;
                        break;
                    }
@@ -1000,10 +1028,7 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8
                    state = I2C_STATE_STOP;
                } else if (length == 2) {
                    /* two bytes read */
-                    while ((!i2c_flag_get(I2C0, I2C_FLAG_BTC)) && (timeout < I2C_TIME_OUT)) {
-                        timeout++;
-                    }
-                    if (timeout >= I2C_TIME_OUT) {
+                    if(_i2c_wait_flag_timeout(I2C_FLAG_BTC) != I2C_RESULT_SUCCESS) {
                        state = I2C_STATE_ERROR;
                        break;
                    }
@@ -1016,40 +1041,39 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8
                } else {
                    /* multi-byte read (length > 2) */
                    while (data_index < length) {
-                        /* wait for RBNE (receive buffer not empty) */
-                        while ((!i2c_flag_get(I2C0, I2C_FLAG_RBNE)) && (timeout < I2C_TIME_OUT)) {
-                            timeout++;
-                        }
-                        if (timeout >= I2C_TIME_OUT) {
-                            state = I2C_STATE_ERROR;
-                            break;
-                        }
-
-                        /* special handling for last 3 bytes */
-                        if (data_index == length - 3) {
-                            /* wait for BTF (byte transfer finished) before reading N-2 */
-                            while ((!i2c_flag_get(I2C0, I2C_FLAG_BTC)) && (timeout < I2C_TIME_OUT)) {
-                                timeout++;
-                            }
-                            if (timeout >= I2C_TIME_OUT) {
+                        if (data_index < length - 2) {
+                            /* normal bytes: wait for RBNE and read with ACK */
+                            if(_i2c_wait_flag_timeout(I2C_FLAG_RBNE) != I2C_RESULT_SUCCESS) {
                                state = I2C_STATE_ERROR;
                                break;
                            }
-                            /* disable ACK for last 2 bytes */
+                            data[data_index] = i2c_data_receive(I2C0);
+                            data_index++;
+                        } else if (data_index == length - 2) {
+                            /* second to last byte: wait for BTF, then disable ACK and read */
+                            if(_i2c_wait_flag_timeout(I2C_FLAG_BTC) != I2C_RESULT_SUCCESS) {
+                                state = I2C_STATE_ERROR;
+                                break;
+                            }
+                            /* disable ACK before reading N-1 byte */
                            i2c_ack_config(I2C0, I2C_ACK_DISABLE);
-                        }
-
-                        /* read data byte */
-                        data[data_index] = i2c_data_receive(I2C0);
-                        data_index++;
-
-                        /* send STOP after reading N-1 byte */
-                        if (data_index == length - 1) {
+                            /* send STOP before reading N-1 byte */
                            i2c_stop_on_bus(I2C0);
+                            /* read N-1 byte */
+                            data[data_index] = i2c_data_receive(I2C0);
+                            data_index++;
+                        } else {
+                            /* last byte: wait for RBNE and read */
+                            if(_i2c_wait_flag_timeout(I2C_FLAG_RBNE) != I2C_RESULT_SUCCESS) {
+                                state = I2C_STATE_ERROR;
+                                break;
+                            }
+                            /* read last byte */
+                            data[data_index] = i2c_data_receive(I2C0);
+                            data_index++;
                        }
-
-                        timeout = 0;
                    }
+                    if(state == I2C_STATE_ERROR) break;
                    state = I2C_STATE_STOP;
                }
                break;
@@ -1072,8 +1096,11 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8
                return I2C_RESULT_SUCCESS;

            case I2C_STATE_ERROR:
-                /* send stop condition to release bus */
-                i2c_stop_on_bus(I2C0);
+                /* I2C bus error, try to reset the bus and retry */
+#ifdef DEBUG_VERBOSE
+                printf("I2C_STATE_ERROR: resetting bus and retrying (retry_count=%u)\r\n", retry_count);
+#endif
+                i2c_bus_reset();

                /* reset ACK configuration */
                i2c_ack_config(I2C0, I2C_ACK_ENABLE);
@@ -1082,7 +1109,13 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8
                retry_count++;
                if (retry_count >= I2C_MAX_RETRY) {
 #ifdef DEBUG_VERBOSE
-                    printf("I2C read failed after %d retries\n", I2C_MAX_RETRY);
+                    /* Print diagnostic flags to help root-cause analysis */
+                    printf("I2C read final failure after %d retries, last_state=%d\r\n", I2C_MAX_RETRY, state);
+                    printf("  FLAGS: AERR=%d BERR=%d LOSTARB=%d I2CBSY=%d\r\n",
+                           (int)i2c_flag_get(I2C0, I2C_FLAG_AERR),
+                           (int)i2c_flag_get(I2C0, I2C_FLAG_BERR),
+                           (int)i2c_flag_get(I2C0, I2C_FLAG_LOSTARB),
+                           (int)i2c_flag_get(I2C0, I2C_FLAG_I2CBSY));
 #endif
                    return I2C_RESULT_ERROR;
                }
@@ -1101,39 +1134,179 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8
                break;
        }
    }
+    /* timeout path: provide debug info */
+#ifdef DEBUG_VERBOSE
+    printf("I2C read timeout (end state). slave=0x%02X, len=%u\r\n", slave_addr, length);
+    printf("  FLAGS: AERR=%d BERR=%d LOSTARB=%d I2CBSY=%d\r\n",
+           (int)i2c_flag_get(I2C0, I2C_FLAG_AERR),
+           (int)i2c_flag_get(I2C0, I2C_FLAG_BERR),
+           (int)i2c_flag_get(I2C0, I2C_FLAG_LOSTARB),
+           (int)i2c_flag_get(I2C0, I2C_FLAG_I2CBSY));
+#endif
    return I2C_RESULT_TIMEOUT;
 }

-/* convenience functions for common operations */
-i2c_result_t i2c_write_8bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t data) {
-    return i2c_write(slave_addr, reg_addr, &data, 1);
-}
+/*!
+    \brief      read data from I2C device without register/sub-address phase
+    \param[in]  slave_addr: slave device address (7-bit)
+    \param[out] data: pointer to data buffer
+    \param[in]  length: number of bytes to read (1-255)
+    \retval     i2c_result_t: operation result
+*/
+i2c_result_t i2c_read_raw(uint8_t slave_addr, uint8_t *data, uint8_t length)
+{
+    i2c_state_t state = I2C_STATE_START;
+    uint16_t timeout = 0;
+    uint8_t retry_count = 0;
+    uint8_t data_index = 0;

-i2c_result_t i2c_read_8bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data) {
-    return i2c_read(slave_addr, reg_addr, data, 1);
-}
-
-i2c_result_t i2c_write_32bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t data[4]) {
-    return i2c_write(slave_addr, reg_addr, data, 4);
-}
-
-i2c_result_t i2c_read_32bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data) {
-    return i2c_read(slave_addr, reg_addr, data, 4);
-}
-
-/* 显示面板专用函数 - 支持读取显示界面参数 */
-i2c_result_t i2c_read_display_params(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8_t length) {
-    /* 针对显示面板的多字节读取，支持13字节的完整参数读取 */
-    if (length > 13) {
+    if (data == NULL || slave_addr > 0x7F || length == 0) {
        return I2C_RESULT_INVALID_PARAM;
    }
-    return i2c_read(slave_addr, reg_addr, data, length);
+
+    i2c_ack_config(I2C0, I2C_ACK_ENABLE);
+
+    while (retry_count < (uint8_t)I2C_MAX_RETRY) {
+        switch (state) {
+            case I2C_STATE_START:
+                timeout = 0;
+                data_index = 0;
+
+                if (_i2c_wait_flag_clear_timeout(I2C_FLAG_I2CBSY) != I2C_RESULT_SUCCESS) {
+                    state = I2C_STATE_ERROR;
+                    break;
+                }
+
+                i2c_start_on_bus(I2C0);
+                state = I2C_STATE_SEND_ADDRESS;
+                break;
+
+            case I2C_STATE_SEND_ADDRESS:
+                if (_i2c_wait_flag_timeout(I2C_FLAG_SBSEND) != I2C_RESULT_SUCCESS) {
+                    state = I2C_STATE_ERROR;
+                    break;
+                }
+
+                i2c_master_addressing(I2C0, (slave_addr << 1), I2C_RECEIVER);
+                state = I2C_STATE_CLEAR_ADDRESS;
+                timeout = 0;
+                break;
+
+            case I2C_STATE_CLEAR_ADDRESS:
+                while ((!i2c_flag_get(I2C0, I2C_FLAG_ADDSEND)) && (!i2c_flag_get(I2C0, I2C_FLAG_AERR)) && (timeout < I2C_TIME_OUT)) {
+                    timeout++;
+                }
+                if (timeout >= I2C_TIME_OUT) {
+                    state = I2C_STATE_ERROR;
+                    break;
+                }
+                if (i2c_flag_get(I2C0, I2C_FLAG_AERR)) {
+                    i2c_flag_clear(I2C0, I2C_FLAG_AERR);
+                    i2c_stop_on_bus(I2C0);
+                    return I2C_RESULT_NACK;
+                }
+
+                if (length == 1) {
+                    i2c_ack_config(I2C0, I2C_ACK_DISABLE);
+                } else if (length == 2) {
+                    i2c_ackpos_config(I2C0, I2C_ACKPOS_NEXT);
+                    i2c_ack_config(I2C0, I2C_ACK_DISABLE);
+                } else {
+                    i2c_ack_config(I2C0, I2C_ACK_ENABLE);
+                }
+
+                i2c_flag_clear(I2C0, I2C_FLAG_ADDSEND);
+                state = I2C_STATE_RECEIVE_DATA;
+                timeout = 0;
+                break;
+
+            case I2C_STATE_RECEIVE_DATA:
+                if (length == 1) {
+                    if (_i2c_wait_flag_timeout(I2C_FLAG_RBNE) != I2C_RESULT_SUCCESS) {
+                        state = I2C_STATE_ERROR;
+                        break;
+                    }
+                    data[0] = i2c_data_receive(I2C0);
+                    state = I2C_STATE_STOP;
+                } else if (length == 2) {
+                    if (_i2c_wait_flag_timeout(I2C_FLAG_BTC) != I2C_RESULT_SUCCESS) {
+                        state = I2C_STATE_ERROR;
+                        break;
+                    }
+                    i2c_stop_on_bus(I2C0);
+                    data[0] = i2c_data_receive(I2C0);
+                    data[1] = i2c_data_receive(I2C0);
+                    state = I2C_STATE_STOP;
+                } else {
+                    while (data_index < length) {
+                        if (data_index < length - 2) {
+                            if (_i2c_wait_flag_timeout(I2C_FLAG_RBNE) != I2C_RESULT_SUCCESS) {
+                                state = I2C_STATE_ERROR;
+                                break;
+                            }
+                            data[data_index++] = i2c_data_receive(I2C0);
+                        } else if (data_index == length - 2) {
+                            if (_i2c_wait_flag_timeout(I2C_FLAG_BTC) != I2C_RESULT_SUCCESS) {
+                                state = I2C_STATE_ERROR;
+                                break;
+                            }
+                            i2c_ack_config(I2C0, I2C_ACK_DISABLE);
+                            i2c_stop_on_bus(I2C0);
+                            data[data_index++] = i2c_data_receive(I2C0);
+                        } else {
+                            if (_i2c_wait_flag_timeout(I2C_FLAG_RBNE) != I2C_RESULT_SUCCESS) {
+                                state = I2C_STATE_ERROR;
+                                break;
+                            }
+                            data[data_index++] = i2c_data_receive(I2C0);
+                        }
+                    }
+                    if (state == I2C_STATE_ERROR) break;
+                    state = I2C_STATE_STOP;
+                }
+                break;
+
+            case I2C_STATE_STOP:
+                while ((I2C_CTL0(I2C0) & I2C_CTL0_STOP) && (timeout < I2C_TIME_OUT)) {
+                    timeout++;
+                }
+                if (timeout >= I2C_TIME_OUT) {
+                    state = I2C_STATE_ERROR;
+                    break;
+                }
+
+                i2c_ack_config(I2C0, I2C_ACK_ENABLE);
+                i2c_ackpos_config(I2C0, I2C_ACKPOS_CURRENT);
+                return I2C_RESULT_SUCCESS;
+
+            case I2C_STATE_ERROR:
+                i2c_bus_reset();
+                i2c_ack_config(I2C0, I2C_ACK_ENABLE);
+                i2c_ackpos_config(I2C0, I2C_ACKPOS_CURRENT);
+
+                retry_count++;
+                if (retry_count >= I2C_MAX_RETRY) {
+                    return I2C_RESULT_ERROR;
+                }
+
+                state = I2C_STATE_START;
+                timeout = 0;
+                delay_10us(10);
+                break;
+
+            default:
+                state = I2C_STATE_START;
+                break;
+        }
+    }
+
+    return I2C_RESULT_TIMEOUT;
 }

 #ifdef DEBUG_VERBOSE
 /*!
    \brief      get status string for debugging
-    \param[in]  status: i2c_status_t value
+    \param[in]  status: i2c_result_t value
    \param[out] none
    \retval     const char* status string
 */
@@ -148,11 +148,17 @@ ldc1612_status_t ldc1612_init(void) {
 */
 ldc1612_status_t ldc1612_config_single_channel(uint8_t channel) {
    i2c_result_t status;
+    uint16_t freq_divider;

    if (channel > 1) {
        return LDC1612_STATUS_INVALID_PARAM;
    }

+    freq_divider = ldc1612_calculate_freq_divider(channel);
+    if (freq_divider == 0) {
+        return LDC1612_STATUS_INVALID_PARAM;
+    }
+
    /* 配置顺序严格按照TI官方文档要求 */
    
    /* Step 1: 确保传感器处于睡眠模式 - 配置前必须 */
@@ -161,28 +167,34 @@ ldc1612_status_t ldc1612_config_single_channel(uint8_t channel) {
    delay_ms(10);

    /* Step 2: 配置频率分频 - 必须在其他配置之前 */
-    uint16_t freq_divider = ldc1612_calculate_freq_divider(channel);
-    ldc1612_write_register(SET_FREQ_REG_START + channel, freq_divider);
+    status = ldc1612_write_register(SET_FREQ_REG_START + channel, freq_divider);
+    if (status != I2C_RESULT_SUCCESS) return LDC1612_STATUS_ERROR;
    delay_ms(5);

    /* Step 3: 配置LC稳定时间 - 影响测量精度 */
-    ldc1612_write_register(SET_SETTLECOUNT_REG_START + channel, LDC1612_SETTLECOUNT_CH0);
+    status = ldc1612_write_register(SET_SETTLECOUNT_REG_START + channel, LDC1612_SETTLECOUNT_CH0);
+    if (status != I2C_RESULT_SUCCESS) return LDC1612_STATUS_ERROR;

    /* Step 4: 配置转换时间 - 影响测量速度和精度 */
-    ldc1612_write_register(SET_CONVERSION_TIME_REG_START + channel, LDC1612_RCOUNT_TIME_CH0);
+    status = ldc1612_write_register(SET_CONVERSION_TIME_REG_START + channel, LDC1612_RCOUNT_TIME_CH0);
+    if (status != I2C_RESULT_SUCCESS) return LDC1612_STATUS_ERROR;

    /* Step 5: 配置转换偏移 */
-    ldc1612_write_register(SET_CONVERSION_OFFSET_REG_START + channel, SET_CONVERSION_OFFSET_CH0);
+    status = ldc1612_write_register(SET_CONVERSION_OFFSET_REG_START + channel, SET_CONVERSION_OFFSET_CH0);
+    if (status != I2C_RESULT_SUCCESS) return LDC1612_STATUS_ERROR;

    /* Step 6: 配置驱动电流 - 影响传感器灵敏度 */
-    ldc1612_write_register(SET_DRIVER_CURRENT_REG + channel, LDC1612_DRIVE_CURRENT);
+    status = ldc1612_write_register(SET_DRIVER_CURRENT_REG + channel, LDC1612_DRIVE_CURRENT);
+    if (status != I2C_RESULT_SUCCESS) return LDC1612_STATUS_ERROR;

    /* Step 7: 配置多路复用器 - 设置通道选择和滤波 */
    // ldc1612_configure_mux_register(LDC1612_MUX_AUTOSCAN_DISABLE, LDC1612_MUX_RR_SEQUENCE_0, LDC1612_MUX_FILTER_ALL_LOW, LDC1612_MUX_FILTER_NONE);
-    ldc1612_write_register(MUX_CONFIG_REG, LDC1612_MUX_CONFIG);
+    status = ldc1612_write_register(MUX_CONFIG_REG, LDC1612_MUX_CONFIG);
+    if (status != I2C_RESULT_SUCCESS) return LDC1612_STATUS_ERROR;

    /* Step 8: 配置错误输出 */
-    ldc1612_write_register(ERROR_CONFIG_REG, LDC1612_ERROR_CONFIG_DEFAULT);
+    status = ldc1612_write_register(ERROR_CONFIG_REG, LDC1612_ERROR_CONFIG_DEFAULT);
+    if (status != I2C_RESULT_SUCCESS) return LDC1612_STATUS_ERROR;

    /* Step 9: 最后启动传感器 - 必须最后一步 */
    status = ldc1612_write_register(SENSOR_CONFIG_REG, LDC1612_SENSOR_CONFIG_CH0);
@@ -332,4 +344,4 @@ uint16_t ldc1612_check_status_and_log_errors(void) {

    // 读取STATUS寄存器会自动清除错误标志，但不会清除DRDY和UNREADCONV标志
    return status;
-}
+}
@@ -41,7 +41,7 @@
 #define __HXTAL           (HXTAL_VALUE)            /* high speed crystal oscillator frequency */
 #define __SYS_OSC_CLK     (__IRC8M)                /* main oscillator frequency */

-#define VECT_TAB_OFFSET  (uint32_t)0x00            /* vector table base offset */
+#define VECT_TAB_OFFSET  (uint32_t)0xB000           /* vector table base offset, FW_B slot 0x0800B000 */

 /* select a system clock by uncommenting the following line */
 //#define __SYSTEM_CLOCK_8M_HXTAL              (__HXTAL)
@@ -86,8 +86,7 @@ tmp112a_status_t tmp112a_read_temperature(tmp112a_result_t *result) {
 }

 void tmp112a_get_raw_temperature_value(uint8_t *value) {
-    // i2c_read_16bits(TMP112A_ADDR, TMP112A_TEMP_REG, value);
-    i2c_read(TMP112A_ADDR, TMP112A_TEMP_REG, value, 2);
+    i2c_read_16bits(TMP112A_ADDR, TMP112A_TEMP_REG, value);
    return;
 }

@@ -1,5 +1,61 @@
-# You can change TOOLCHAIN_DIRECTORY if you want to use different toolchain.
-set(TOOLCHAIN_DIRECTORY "${CMAKE_SOURCE_DIR}/Toolchain/xpack-arm-none-eabi-gcc-11.3.1-1.1/bin")
+# The project never stores a compiler package. Each machine supplies a path.
+# TOOLCHAIN_DIRECTORY (CMake cache) has priority over the environment variable.
+# GD32_GCC_ENV_VAR lets a workstation use a different variable name if needed.
+set(TOOLCHAIN_DIRECTORY "" CACHE PATH "Path to arm-none-eabi toolchain bin directory")
+set(GD32_GCC_ENV_VAR "GD32_GCC_BIN" CACHE STRING "Environment variable containing the ARM GCC path")
+set(CMAKE_TRY_COMPILE_PLATFORM_VARIABLES TOOLCHAIN_DIRECTORY GD32_GCC_ENV_VAR)
+
+if(GD32_GCC_ENV_VAR AND NOT GD32_GCC_ENV_VAR MATCHES "^GD32_[A-Za-z0-9_]+$")
+    message(FATAL_ERROR "GD32_GCC_ENV_VAR must use the GD32_ prefix: ${GD32_GCC_ENV_VAR}")
+endif()
+
+if(NOT TOOLCHAIN_DIRECTORY AND GD32_GCC_ENV_VAR)
+    if(DEFINED ENV{${GD32_GCC_ENV_VAR}} AND NOT "$ENV{${GD32_GCC_ENV_VAR}}" STREQUAL "")
+        file(TO_CMAKE_PATH "$ENV{${GD32_GCC_ENV_VAR}}" TOOLCHAIN_DIRECTORY)
+    endif()
+endif()
+
+if(NOT TOOLCHAIN_DIRECTORY)
+    message(FATAL_ERROR
+        "Cannot find ARM GCC toolchain. Set ${GD32_GCC_ENV_VAR} in the machine environment "
+        "or pass -DTOOLCHAIN_DIRECTORY=<toolchain-bin>.")
+endif()
+
+file(TO_CMAKE_PATH "${TOOLCHAIN_DIRECTORY}" TOOLCHAIN_DIRECTORY)
+get_filename_component(TOOLCHAIN_DIRECTORY "${TOOLCHAIN_DIRECTORY}" ABSOLUTE)
+
+if(WIN32)
+    set(TOOLCHAIN_SUFFIX ".exe")
+else()
+    set(TOOLCHAIN_SUFFIX "")
+endif()
+
+# Accept either the package root or its bin directory.
+if(NOT EXISTS "${TOOLCHAIN_DIRECTORY}/arm-none-eabi-gcc${TOOLCHAIN_SUFFIX}" AND
+   EXISTS "${TOOLCHAIN_DIRECTORY}/bin/arm-none-eabi-gcc${TOOLCHAIN_SUFFIX}")
+    set(TOOLCHAIN_DIRECTORY "${TOOLCHAIN_DIRECTORY}/bin")
+endif()
+
+set(_ARM_GCC_EXECUTABLE "${TOOLCHAIN_DIRECTORY}/arm-none-eabi-gcc${TOOLCHAIN_SUFFIX}")
+
+set(_TOOLCHAIN_BINARIES
+    arm-none-eabi-gcc
+    arm-none-eabi-g++
+    arm-none-eabi-gdb
+    arm-none-eabi-ar
+    arm-none-eabi-ranlib
+    arm-none-eabi-as
+    arm-none-eabi-ld
+    arm-none-eabi-objcopy
+    arm-none-eabi-objdump
+    arm-none-eabi-size
+)
+foreach(_binary IN LISTS _TOOLCHAIN_BINARIES)
+    if(NOT EXISTS "${TOOLCHAIN_DIRECTORY}/${_binary}${TOOLCHAIN_SUFFIX}")
+        message(FATAL_ERROR
+            "ARM GCC toolchain is incomplete; missing ${_binary}${TOOLCHAIN_SUFFIX} in ${TOOLCHAIN_DIRECTORY}")
+    endif()
+endforeach()

 set(CMAKE_C_FLAGS_DEBUG "")
 set(CMAKE_CXX_FLAGS_DEBUG "")
@@ -12,10 +68,6 @@ set(CMAKE_COLOR_DIAGNOSTICS ON)

 set(CMAKE_EXPORT_COMPILE_COMMANDS ON CACHE INTERNAL "")

-if(WIN32)
-    set(TOOLCHAIN_SUFFIX ".exe")
-endif()
-
 set(CMAKE_SYSTEM_NAME               Generic)
 set(CMAKE_SYSTEM_PROCESSOR          arm)

@@ -28,21 +80,48 @@ set(FLAGS                           "-mcpu=cortex-m23 -std=gnu11 -fstack-usage -
 set(ASM_FLAGS                       "-x assembler-with-cpp")
 set(CPP_FLAGS                       "-fno-rtti -fno-exceptions -fno-threadsafe-statics")

-set(CMAKE_C_COMPILER                ${TOOLCHAIN_PREFIX}gcc${TOOLCHAIN_SUFFIX})
-set(CMAKE_CXX_COMPILER              ${TOOLCHAIN_PREFIX}g++${TOOLCHAIN_SUFFIX})
-set(CMAKE_ASM_COMPILER              ${TOOLCHAIN_PREFIX}gcc${TOOLCHAIN_SUFFIX})
+set(_REQUESTED_C_COMPILER "${TOOLCHAIN_PREFIX}gcc${TOOLCHAIN_SUFFIX}")
+if(DEFINED CMAKE_C_COMPILER AND CMAKE_C_COMPILER AND
+   IS_ABSOLUTE "${CMAKE_C_COMPILER}" AND
+   NOT CMAKE_C_COMPILER STREQUAL "${_REQUESTED_C_COMPILER}")
+    message(FATAL_ERROR
+        "The build directory is already configured for a different ARM GCC compiler:\n"
+        "  cached:  ${CMAKE_C_COMPILER}\n"
+        "  selected: ${_REQUESTED_C_COMPILER}\n"
+        "Delete the build directory or run CMake Tools 'Delete Cache and Reconfigure'.")
+endif()
+
+set(CMAKE_C_COMPILER                "${_REQUESTED_C_COMPILER}")
+set(CMAKE_CXX_COMPILER              "${TOOLCHAIN_PREFIX}g++${TOOLCHAIN_SUFFIX}")
+set(CMAKE_ASM_COMPILER              "${TOOLCHAIN_PREFIX}gcc${TOOLCHAIN_SUFFIX}")

 set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${FLAGS}")
 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${FLAGS} ${CPP_FLAGS}")
 set(CMAKE_ASM_FLAGS "${CMAKE_ASM_FLAGS} ${FLAGS} ${ASM_FLAGS}")
-set(CMAKE_OBJCOPY                   ${TOOLCHAIN_PREFIX}objcopy${TOOLCHAIN_SUFFIX})
-set(CMAKE_SIZE                      ${TOOLCHAIN_PREFIX}size${TOOLCHAIN_SUFFIX})
-set(CMAKE_OBJDUMP                   ${TOOLCHAIN_PREFIX}objdump${TOOLCHAIN_SUFFIX})
-set(CMAKE_AS                        ${TOOLCHAIN_PREFIX}as${TOOLCHAIN_SUFFIX})
-set(CMAKE_LD                        ${TOOLCHAIN_PREFIX}ld${TOOLCHAIN_SUFFIX})
+set(CMAKE_AR                        "${TOOLCHAIN_PREFIX}ar${TOOLCHAIN_SUFFIX}")
+set(CMAKE_RANLIB                    "${TOOLCHAIN_PREFIX}ranlib${TOOLCHAIN_SUFFIX}")
+set(CMAKE_OBJCOPY                   "${TOOLCHAIN_PREFIX}objcopy${TOOLCHAIN_SUFFIX}")
+set(CMAKE_SIZE                      "${TOOLCHAIN_PREFIX}size${TOOLCHAIN_SUFFIX}")
+set(CMAKE_OBJDUMP                   "${TOOLCHAIN_PREFIX}objdump${TOOLCHAIN_SUFFIX}")
+set(CMAKE_AS                        "${TOOLCHAIN_PREFIX}as${TOOLCHAIN_SUFFIX}")
+set(CMAKE_LD                        "${TOOLCHAIN_PREFIX}ld${TOOLCHAIN_SUFFIX}")
+set(CMAKE_LINKER                   "${TOOLCHAIN_PREFIX}ld${TOOLCHAIN_SUFFIX}")
+
+execute_process(
+    COMMAND "${_ARM_GCC_EXECUTABLE}" --version
+    OUTPUT_VARIABLE _ARM_GCC_VERSION_OUTPUT
+    ERROR_VARIABLE _ARM_GCC_VERSION_ERROR
+    RESULT_VARIABLE _ARM_GCC_VERSION_RESULT
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+if(NOT _ARM_GCC_VERSION_RESULT EQUAL 0)
+    message(FATAL_ERROR "Unable to execute ${_ARM_GCC_EXECUTABLE}: ${_ARM_GCC_VERSION_ERROR}")
+endif()
+string(REGEX MATCH "[0-9]+\\.[0-9]+\\.[0-9]+" _ARM_GCC_VERSION "${_ARM_GCC_VERSION_OUTPUT}")
+message(STATUS "Using ARM GCC ${_ARM_GCC_VERSION} from ${TOOLCHAIN_DIRECTORY}")

 set(CMAKE_EXECUTABLE_SUFFIX_ASM     ".elf")
 set(CMAKE_EXECUTABLE_SUFFIX_C       ".elf")
 set(CMAKE_EXECUTABLE_SUFFIX_CXX     ".elf")

-set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)
+set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)
@@ -1,9 +1,11 @@
 # Project basic info
-set(PROJECT_NAME "LDC1612")
-set(BOARD_TYPE_CODE 23)
+# golden 出厂保底线：版本号冻结 V1.0.2（保底判定值 v26.1.0.2，永不再用于 OTA 升级包）
+# 此分支改动不得合回 dev/main（链接基址 0x0800B000 为 B 槽专属）
+set(PROJECT_NAME "CeramixNano-EDDY")
+set(BOARD_TYPE_CODE 26)
 set(VERSION_MAJOR 1)
 set(VERSION_MINOR 0)
-set(VERSION_PATCH 1)
+set(VERSION_PATCH 2)
 set(VERSION "V${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_PATCH}")
 string(TIMESTAMP BUILD_DATE "%Y-%m-%d")

@@ -11,7 +13,7 @@ string(TIMESTAMP BUILD_DATE "%Y-%m-%d")
 # Example: HW-IIC_APP / HW-IIC_Bootloader
 # set(BUILD_VARIANT "AutoDetectDriveCurrent")
 # set(BUILD_VARIANT "HW-IIC")
-set(BUILD_VARIANT "APP")
+set(BUILD_VARIANT "golden")

 # 其它自定义宏
 add_definitions(-DBUILD_VARIANT=${BUILD_VARIANT})
Author	SHA1	Message	Date
hulk	8dcbfa9f99	build(golden): 出厂保底线定版——CeramixNano-EDDY 命名/板卡码 26/版本冻结 V1.0.2/variant=golden	2026-10-24 21:15:11 +08:00
hulk	4af24a4dfb	build: golden 保底固件布局——LD ORIGIN 0x0800B000 (B 槽 19K-8B) + VECT_TAB_OFFSET 0xB000	2026-10-23 10:11:14 +08:00
hulk	b6da450f8a	build: 恢复正式发布布局 0x08002000/54K + VECT_TAB_OFFSET=0x2000 调试裸机布局(0x08000000/VTOR=0)仅限本地临时修改，不进仓库；	2026-10-02 23:21:47 +08:00
hulk	de6afa1717	docs: AGENTS.md 记录 V1.0.2 发布	2026-10-02 23:09:37 +08:00
hulk	57963d179a	build: 调试阶段 APP 临时链接 0x08000000（VECT_TAB_OFFSET=0，脱离 bootloader 直接运行）正式发布仍用 V1.0.2 tag 处的 0x08002000/54K Bootloader 布局打包（见 Release V1.0.2）	2026-10-02 23:09:19 +08:00
hulk	8d5c33236d	release:(1.0.2) 版本号提升至 V1.0.2	2026-10-02 23:07:59 +08:00
hulk	a40c2ec793	build(vscode): 新增 DAPLink 专用烧录配置与任务 - openocd_daplink_gd32e23x.cfg：去掉 connect_assert_srst（该选项导致 DAPLink 下 Cortex-M23 识别失败）	2026-10-02 23:07:55 +08:00
hulk	e81c902341	docs: 修正协议文档命令编号并补全 M4~M9999 帧格式说明；新增项目 AGENTS.md - 温度上报命令由 M3 笔误更正为 M4，补充 M4 回复示例	2026-10-02 23:07:51 +08:00
hulk	07b631b254	feat(i2c): 导入模板 IIC 驱动改进（总线恢复重试/超时辅助函数/read_raw/scan AERR 处理）	2026-10-02 23:07:41 +08:00
hulk	89e7191cd5	build: 对齐模板工具链与 .vscode，APP 迁移 Bootloader 布局(0x08002000/54K) 工程编译与开发环境（参照 gd32e23x_template_cmake_vscode 模板） - cmake/arm-none-eabi-gcc.cmake：硬编码工具链路径改为 GD32_GCC_BIN 环境变量 / -DTOOLCHAIN_DIRECTORY 参数，与模板逐字一致 - .vscode：launch/tasks/settings/extensions 对齐模板，烧录与调试全部读取 GD32_GCC_BIN / GD32_OPENOCD_BIN / GD32_OPENOCD_SCRIPTS 环境变量；新增 J-Link 调试配置与 flash/reset/erase.jlink 脚本 - CMakeLists.txt：POST_BUILD 增加 Application/Application.hex 生成（J-Link 烧录脚本 loadfile 依赖） - 验证：Debug / Release 编译通过（本机 ARM GCC 15.2.1） Bootloader 布局适配（与旧版独立镜像不兼容，升级需整片烧录一次） - LD/gd32e23x_flash.ld：FLASH ORIGIN=0x08002000, LENGTH=54K - Src/system_gd32e23x.c：VECT_TAB_OFFSET=0x2000——Bootloader 不写 VTOR，APP 必须自设向量表，否则中断落回 Bootloader 向量表 - 验证：.vectors 链接于 0x08002000，固件 12164B（54KB 上限 22%）驱动修复 - Src/ldc1612.c：ldc1612_config_single_channel 各步骤 I2C 写入检查返回值，失败立即返回错误（原审查项 L3）文档 - README：重写本地编译/烧录/调试说明，新增"固件布局与 Bootloader"章节	2026-09-26 18:41:29 +08:00