# FilmForge — AGENTS.md

## 项目约定

- **用途**：自制热压模具温控固件——塑型 PC 膜，负责加热驱动与测温（NTC），
  对外走 RS485 数据口。基于 GD32F4xx 工程模板
  （`https://gitea.hulk.wang/hulk/gd32f4xx_template_cmake_vscode`，源自
  celalkismiroglu/gd32e23x-demo-suites-cmake 体系）。
- **命名**：仓库 `FilmForge`，固件工程 `FilmForge_FW`（产物自动命名
  `FilmForge_FW_V<版本>_APP_<日期>.bin`），协议板卡类型码 `BOARD_TYPE_CODE 41`。
- **目标芯片**：GD32F405RET6（设备宏 `GD32F405`，IRC16M PLL 168MHz——板上无外部
  晶振；硬件 FPU fpv4-sp-d16 / hard ABI；512K Flash，链接脚本 xE）。
- **串口角色与 PC 端映射**：
  - debug 串口 = USART1（PA2 TX / PA3 RX，AF7，纯串口）→ PC 端 **COM4**；
    printf 重定向到 USART1（`DEBUG_UART` 宏），`DEBUG_MODE` 打开后输出。
  - 数据口 RS485 = USART0（PA9 TX / PA10 RX，AF7）+ DE 引脚 PA8（GPIO 手动切换
    收发）→ PC 端 **COM5**（115200-8-N-1）。拉通阶段主循环回显。
  - 注意 GD 外设编号比 STM32 小 1：PA9/PA10=USART0、PA2/PA3=USART1。
- **NTC 测温**：PC5（ADC0_IN15），硬件 10K 上拉、NTC 接 GND 侧。B 值公式换算，
  `NTC_B_VALUE` 宏（3950/3435 未定，默认 3950，确认后修改）；`R_PULL/NTC_R25`
  均为宏，换料只改宏。
- **语言/工具链**：C（gnu11）+ ARM GCC（xpack 15.2.1 已验证）、CMake ≥ 3.20 +
  Ninja、VSCode + CMake Tools + cortex-debug；工具链路径经 `GD32_GCC_BIN`。
- **目录约定**（沿用模板）：
  - `Build/` —— 构建树与产物（gitignore）；
  - `SDK/` —— CMSIS、标准外设库 V3.3.3、SEGGER_RTT、USB 库（`GD32_ENABLE_USB`
    开关，默认 OFF，当前未用）；
  - `LD/` —— 链接脚本（默认 xE 512K）；
  - `Inc/`+`Src/` —— 应用层，板级引脚/开关集中在 `Inc/board_config.h`；
  - `OpenOCD/` —— 工程内会话配置（GD-LINK/CMSIS-DAP + stm32f4x）；
  - `doc/` —— 芯片文档（数据手册/用户手册/固件库指南/AN，已齐备）。
- **编译方法**：
  ```bash
  cmake --preset Debug && cmake --build Build/Debug
  cmake --preset Release && cmake --build Build/Release
  ```
- **Git/网络经验**：origin = HTTPS（`https://gitea.hulk.wang/hulk/FilmForge.git`），
  该实例 HTTPS/SSH 直传大包均不稳，已在本仓库配置
  `http.proxy http://127.0.0.1:6789` + `http.sslVerify=false`（仓库级），
  代理端口变化时用 `git config http.proxy http://127.0.0.1:<新端口>` 更新。
- **printf 浮点**：`--specs=nano.specs` 默认裁剪 `%f`（输出空白），已在
  `cmake/project.cmake` 启用 `-u _printf_float`（F405 flash 充裕，ROM +8~10KB 无感）。
- **在线排查寄存器地址速查**（GD32F4xx）：ADC0=0x40012000（RDATA@0x4C）、
  USART0=0x40011000、USART1=0x40004400、GPIOA=0x40020000（OCTL@0x14）、
  RCU：CTL0=0x40023800 / **PLL=0x40023804** / **CFG0=0x40023808**。

## 开发进度

### 已完成

- 模板就位（GD32F405RET6 / IRC16M 168MHz / 硬件 FPU / 上板验证过的模板体系）。
- **debug 串口**：USART1 PA2/PA3 @115200，printf 重定向 + RBNE 中断收环形缓冲
  （模板已有，COM4 观测）。
- **RS485 数据口驱动**（`rs485.h/rs485.c`）：USART0 PA9/PA10 AF7 + DE PA8 GPIO
  手动切换；独立接收环形缓冲（预留一格策略 + PRIMASK 临界区）；阻塞发送
  （DE→TBE→TC→DE，防尾字节截断）；`rs485_rx_clear()` 清接收缓冲。
- **NTC 测温驱动**（`ntc.h/ntc.c`）：PC5 模拟输入 + ADC0 常规通道（软件触发单次
  转换 + 校准），16 次采样均值 + 分压反解阻值 + B 值公式换算摄氏度
  （含开路/短路电源轨检测）。
- `debug_uart_write()` 助手（uart.c）：debug 口阻塞单字节发送。
- **命令协议框架移植**（`command.h/command.c`，自 E23x 移植）：D5 帧协议
  （D5 BOARD_TYPE LEN [cmd] CRC 累加和校验）+ B5 响应；数据源改为 RS485 收缓冲
  （`rs485_rx_*`），响应经 `rs485_send` 发出（DE 自动切换）；帧状态机 + CRC +
  参数解析工具（uint_to_str/parse_uint_dec/parse_timer_parameter/find_parameter_value）
  全套保留；通用命令骨架：**M888 软复位 / M999 版本号 / M9999 进 OTA**；
  业务命令（加热/控温）待定义，switch 中扩展（TODO 注释有格式示例）。
- **命令协议 v1.0 定稿**（权威定义见根目录 `protocols.md`，帧 hex 全部脚本生成）：
  - M1 查温度 / M2 查上报状态 / M2S<ms> 上报间隔+开关（M2S0 停）/ M3 加热开关
    （M3S1/M3S0/M3 查询）/ M4 目标温度（M4S<temp>/M4 查询）/ M888 / M999 / M9999
  - M3/M4 为**预留**：仅维护软件状态（ack+可回读），真实加热硬件执行体待接入
    （`command.c` 的 `heater_apply()` 桩）；GUI 可先行全量联调协议
  - 协议要点：全幂等（ack 丢可重发）、响应超时建议 300ms×3 次、温度一律 ASCII
  - 上位机工具：用户另行开发 FilmForge 专用 GUI（协议按 protocols.md）
- **SerialMate 串口工具问题已定位**（见
  `E:\Hulk-Coding\HW-Debug-Tools\SerialMate\ISSUE_rx_timestamp_and_lag.md`）：
  时间戳在 GUI 消费时打导致失真 + 接收日志无限增长致卡顿；待该工具修复后
  再做长时间曲线联调。
- 工程改名：`FilmForge_FW`、`BOARD_TYPE_CODE 41`。

### 计划 / TODO（已提出尚未实现）

- [x] **RS485 拉通上板验证**：命令收发/响应/上报实测通过（固件端零丢字节，
      响应 10ms 级实时）；遗留为 USB-RS485 适配器方向切换丢包（换适配器解决）
      与 SerialMate 显示层问题（见 ISSUE 文档）。
- [x] **NTC 测温上板验证**：NTC 支路修复后读数正常（23.6~25.9℃ 稳定）。
- [ ] **B 值确认**：温度计对照实测定 `NTC_B_VALUE`（3950/3435 二选一）。
- [ ] **适配器更换**：换可靠的 USB-RS485 适配器（当前自动方向切换间歇丢响应）。
- [ ] **加热驱动**：加热功率器件驱动与控制（MOS/PWM/继电器方案待定），
      接入 `command.c` 的 `heater_apply()` 桩；随后控温闭环（PID）。
- [ ] **专用 GUI 上位机**：用户开发中，协议按 `protocols.md`。
- [ ] **LED 引脚确认**：FilmForge 自制板 LED 引脚未定（当前沿用模板默认 PA15，
      仅为构建占位），按原理图修改。
- [ ] **delay_10us 校准**：M4@168MHz 系数为估算值（/300000），需实测修正。

## 备注

- 本机凭据/发布约定见用户级 `C:\Users\Lenovo\.zcode\AGENTS.md`。
- 模板工程位置：`E:\Hulk-Coding\gd32f4xx_template_cmake_vscode`（模板对标工程，
  Gitea: gd32f4xx_template_cmake_vscode）。
- E23x 工程位置：`E:\Hulk-Coding\gd32e23x_template_cmake_vscode`（协议/驱动参考）。