Protocol v1.0: add M3 heater switch / M4 target temp (reserved); protocols.md

2026-10-10 00:28:42 +08:00
parent 3b00ed30d7
commit 9c7aafb78c
4 changed files with 194 additions and 15 deletions
@@ -64,23 +64,30 @@
  参数解析工具（uint_to_str/parse_uint_dec/parse_timer_parameter/find_parameter_value）
  全套保留；通用命令骨架：**M888 软复位 / M999 版本号 / M9999 进 OTA**；
  业务命令（加热/控温）待定义，switch 中扩展（TODO 注释有格式示例）。
-  `command_execute(cmd_str)` 调试入口保留（本地直接 handle，不经接收缓冲）。
-  RS485 拉通回显已由命令协议替代（`rs485_process` 移除）。
+- **命令协议 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（已提出尚未实现）

- [ ] **RS485 拉通上板验证**：COM5（RS485）发数据回显 + COM4（debug）观测，
-      DE 时序实测（逻辑分析仪看 PA8 与 TX 时序）。
- [ ] **NTC 测温上板验证**：固件/换算已验证正确（ADC 忠实读数），**当前板上
-      PC5 实测 3.296V（ADC≈4090 满量程）→ NTC 分压支路未连通**（上电后固件打印
-      "NTC OPEN"）。排查：万用表量 PC5 对 GND 电压（应约 1.5V）；查 NTC 焊点/
-      走线/接地/网络号；断电量焊在板上 NTC 两端阻值（热风焊可能损坏 NTC 致开路）。
-      修好后应读约 1.55V（ADC≈1929）→ 27~29℃。`NTC_B_VALUE` 待两点法确认。
- [ ] **加热驱动**：加热功率器件的驱动与控制（方案待定：MOS/PWM/继电器），
-      与测温闭环（控温策略）。
- [ ] **正式数据协议**：RS485 从回显切换到正式协议（沿用 D5/B5 帧体系或新定义），
-      即 E23x `command.c` 的移植/重写。
+- [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），需实测修正。
@@ -130,6 +130,12 @@ void usart1_irq_handler(void);

 /******************************************************************************/

+/* 加热控制参数（M3 开关 / M4 目标温度设定） */
+#define HEATER_TEMP_MIN      0U      /* 目标温度下限（整数摄氏度） */
+#define HEATER_TEMP_MAX      200U    /* 目标温度上限（整数摄氏度） */
+
+/******************************************************************************/
+
 #define DEBUG_UART              USART1

 #endif //BOARD_CONFIG_H
@@ -63,11 +63,27 @@ static const uint8_t s_report_status_err[] = { 'e','r','r' }; /**< 错误响应

 /** @name M2 连续温度上报状态
 * @{ */
-static bool s_temp_report_enabled = false;     /**< 连续上报使能（M2 切换） */
-static uint16_t s_temp_report_period_ms = 500; /**< 上报间隔（ms），M2S<ms> 设置，100~60000 */
+static bool s_temp_report_enabled = false;     /**< 连续上报使能（M2S<ms> 设置） */
+static uint16_t s_temp_report_period_ms = 500; /**< 上报间隔（ms），100~60000 */
 static uint16_t s_temp_report_counter = 0;     /**< 主循环 10ms 圈计数 */
 /** @} */

+/** @name M3/M4 加热控制状态（预留：当前仅软件状态，硬件执行体待接入）
+ * @{ */
+static bool s_heater_on = false;       /**< 加热开关状态 */
+static float s_heater_target = 0.0f;   /**< 目标温度（摄氏度，M4S 设定） */
+/** @} */
+
+/**
+ * @brief 加热输出执行体（按开关状态与目标温度驱动加热器件）。
+ * @note  TODO: 加热驱动（MOS/PWM/继电器）接入后在此实现真实输出；
+ *       当前 M3/M4 仅维护软件状态（GUI 可先行联调协议）。
+ */
+static void heater_apply(void)
+{
+    /* 占位：接入加热驱动后替换为真实硬件输出 */
+}
+
 void system_software_reset(void)
 {
    // 确保所有待处理的内存访问完成
@@ -338,9 +354,14 @@ static bool __attribute__((unused)) find_parameter_value(const uint8_t *cmd, uin
 *          - M1:     单次查询温度值（payload 为 ASCII 摄氏度，如 "23.8"；OPEN/SHRT=故障）
 *          - M2:     查询连续上报状态（payload: "ON <ms>" 或 "OFF"）
 *          - M2S<ms>: 设置连续上报间隔（100~60000）并开启；M2S0 停止
+ *          - M3:     查询加热状态（payload: "ON" / "OFF"）
+ *          - M3S1/M3S0: 开启/关闭加热（预留，当前仅软件状态）
+ *          - M4:     查询目标温度（payload: ASCII 摄氏度）
+ *          - M4S<temp>: 设定目标温度（整数摄氏度，0~200；预留，当前仅软件状态）
 *          - M888:   软件复位
 *          - M999:   输出固件版本号（v<板卡码>.<主>.<次>.<修订>）
 *          - M9999:  进入 OTA 模式（复位进 Bootloader）
+ *          权威帧示例见工程根 protocols.md（脚本生成，勿手算 CRC）。
 *
 *          具体业务命令（加热/测温/控温等）待定，在 switch 中按需扩展。
 *
@@ -444,6 +465,60 @@ void handle_command(const uint8_t *frame, uint8_t len) {
        }
        return;

+        /* ==========================================
+         * M3 加热开关（预留，当前仅软件状态）
+         * M3       : 查询加热状态（payload: "ON" / "OFF"）
+         * M3S1     : 开启加热
+         * M3S0     : 关闭加热
+         * 注意：上电默认关闭；看门狗/异常处理策略待控温闭环设计时补充。
+         * ========================================== */
+        case 3u:
+        {
+            uint32_t onoff = 0;
+
+            if (find_parameter_value(&cmd[cmd_index], (uint8_t)(cmd_len - cmd_index), 'S', &onoff)) {
+                if (onoff == 0U || onoff == 1U) {
+                    s_heater_on = (onoff == 1U);
+                    heater_apply();
+                    send_response(RESP_TYPE_OK, s_report_status_ok, sizeof(s_report_status_ok));
+                } else {
+                    send_response(RESP_TYPE_PARAM_ERR, s_report_status_err, sizeof(s_report_status_err));
+                }
+            } else {
+                send_response(RESP_TYPE_OK,
+                              s_heater_on ? (const uint8_t *)"ON" : (const uint8_t *)"OFF",
+                              s_heater_on ? 2U : 3U);
+            }
+            COMMAND_DEBUG("M3 heater %s", s_heater_on ? "ON" : "OFF");
+        }
+        return;
+
+        /* ==========================================
+         * M4 温度设定（预留，当前仅软件状态）
+         * M4        : 查询目标温度（payload: ASCII 摄氏度，如 "120.0"）
+         * M4S<temp> : 设定目标温度（整数摄氏度，HEATER_TEMP_MIN~MAX）
+         * ========================================== */
+        case 4u:
+        {
+            uint32_t target = 0;
+
+            if (find_parameter_value(&cmd[cmd_index], (uint8_t)(cmd_len - cmd_index), 'S', &target)) {
+                if (target >= HEATER_TEMP_MIN && target <= HEATER_TEMP_MAX) {
+                    s_heater_target = (float)target;
+                    heater_apply();
+                    send_response(RESP_TYPE_OK, s_report_status_ok, sizeof(s_report_status_ok));
+                } else {
+                    send_response(RESP_TYPE_PARAM_ERR, s_report_status_err, sizeof(s_report_status_err));
+                }
+            } else {
+                char target_str[8];
+                uint8_t n = (uint8_t)sprintf(target_str, "%.1f", s_heater_target);
+                send_response(RESP_TYPE_OK, (const uint8_t *)target_str, n);
+            }
+            COMMAND_DEBUG("M4 target: %.1f", s_heater_target);
+        }
+        return;
+
        /* ==========================================
         * M888 软件重启命令
         * ========================================== */
@@ -0,0 +1,91 @@
+# FilmForge RS485 协议 v1.0（GUI 上位机开发权威参考）
+
+> 本文件为 FilmForge 热压模具固件的对外协议权威定义。**所有帧 hex 由脚本生成**
+> （算法见文末，勿手算 CRC）。GUI 工具按本文件实现即可完整驱动设备。
+
+## 物理层
+
+- RS485 半双工，115200-8-N-1，无流控
+- 固件为从机：上位机发命令帧，固件回响应帧；另有 M2 开启的周期上报帧（主→从单向）
+
+## 帧格式（五段式，与 DLPilot 协议同构）
+
+```
+命令帧（上位机 → 固件）：D5 <BOARD=01> <LEN> <payload ASCII> <CRC>
+响应帧（固件 → 上位机）：B5 <TYPE>     <LEN> <payload>      <CRC>
+```
+
+- `LEN` = payload 字节数
+- `CRC` = 8 位累加和：**从 BOARD 字节累加到 LEN+payload 末尾（即跳过包头 D5/B5，
+  不含 CRC 本身）**，取低 8 位
+- payload 一律 ASCII 文本
+
+## 响应 TYPE 码
+
+| TYPE | 含义 | payload |
+|------|------|---------|
+| `F0` | 成功 | 命令相关数据或 `ok` |
+| `F1` | CRC 校验错 | `err` |
+| `F3` | 板类型错 | `err` |
+| `F4` | 命令格式错 | `err` |
+| `FD` | 参数越界 | `err` |
+| `FE` | 未知命令 | `err` |
+
+## 命令表（hex 全部脚本生成）
+
+| 命令 | 功能 | 命令帧 hex | 成功响应 payload |
+|------|------|-----------|------------------|
+| `M1` | 单次查询温度 | `D5 01 02 4D 31 81` | ASCII 摄氏度（如 `24.5`）；`OPEN`=NTC 开路 / `SHRT`=短路 |
+| `M2` | 查询上报状态 | `D5 01 02 4D 32 82` | `ON <ms>` 或 `OFF` |
+| `M2S500` | 设上报间隔并开启 | `D5 01 06 4D 32 53 35 30 30 6E` | `ok`；范围 100~60000ms，10ms 步进 |
+| `M2S0` | 停止上报 | `D5 01 04 4D 32 53 30 07` | `ok` |
+| `M3` | 查询加热状态 | `D5 01 02 4D 33 83` | `ON` / `OFF`（预留，当前仅软件状态） |
+| `M3S1` | 开启加热 | `D5 01 04 4D 33 53 31 09` | `ok`（预留） |
+| `M3S0` | 关闭加热 | `D5 01 04 4D 33 53 30 08` | `ok`（预留） |
+| `M4` | 查询目标温度 | `D5 01 02 4D 34 84` | ASCII 摄氏度（如 `120.0`） |
+| `M4S120` | 设定目标温度 | `D5 01 06 4D 34 53 31 32 30 6E` | `ok`；整数摄氏度 0~200，越界回 PARAM_ERR |
+| `M888` | 软件复位 | `D5 01 04 4D 38 38 38 FA` | `ok` 后复位（慎发） |
+| `M999` | 查询固件版本 | `D5 01 04 4D 39 39 39 FD` | 如 `v41.0.0.1` |
+| `M9999` | 进入 OTA 模式 | `D5 01 05 4D 39 39 39 39 37` | 直接复位进 Bootloader（未部署 Bootloader 前等同复位） |
+
+## 温度上报帧（M2S<ms> 开启后）
+
+固件按设定周期主动发送，**格式与 M1 响应完全相同**：
+`B5 F0 <LEN> <ASCII 摄氏度> <CRC>`，如 24.5℃ →
+`B5 F0 04 32 34 2E 35 BD`。
+GUI 曲线解析：匹配 `B5 F0`，取 payload 按 ASCII float 解析；payload 为
+`OPEN`/`SHRT` 时为传感器故障态，不画点。
+
+## 温度数据说明
+
+- 后台每 100ms 采样一次（16 次采样修剪均值滤波），M1/M2/上报读同一全局最新值
+- 单次测量耗时约 10~20ms，查询响应延迟 < 主循环周期（10ms 级）
+
+## 加热控制（M3/M4，预留）
+
+- **当前固件仅维护软件状态**（M3S1/M4S 设定会 ack 并可查询回读），
+  真实加热硬件驱动尚未接入；GUI 可先行完成全部协议联调
+- 目标温度范围 0~200℃（整数），越界回 `FD`
+- 上电默认：加热 OFF，目标 0.0℃
+- 后续接入硬件执行体后协议不变
+
+## 通信注意事项
+
+1. **全部命令幂等**：ack 丢失后直接重发，状态不会错乱（无翻转语义）
+2. 建议命令间隔 ≥ 50ms；响应超时建议 300ms 后重发，重发 3 次判失败
+3. `M888`/`M9999` 会复位设备，GUI 需在点击时二次确认
+4. 半双工：固件响应/上报期间（约 1ms/帧）不会接收，无需冲突处理
+
+## CRC 算法参考实现
+
+```python
+def crc8_sum(frame_without_hdr: bytes) -> int:
+    # frame_without_hdr = BOARD + LEN + payload（不含包头 D5/B5，不含 CRC）
+    return sum(frame_without_hdr) & 0xFF
+
+# 组帧示例
+payload = b'M2S500'
+body = bytes([0xD5, 0x01, len(payload)]) + payload
+frame = body + bytes([crc8_sum(body[1:])])
+# -> D5 01 06 4D 32 53 35 30 30 6E
+```