初始提交

2025-07-07 14:29:26 +08:00
commit 905b860e2a
416 changed files with 225362 additions and 0 deletions
--- a/ref/主控与舱室通信协议.md
+++ b/ref/主控与舱室通信协议.md
@ -0,0 +1,232 @@
+# 主控与舱室通信协议
+
+## 1. 协议概述
+
+**协议名称：** 主控-舱室通信协议  
+**协议版本：** V1.0  
+**通信方式：** 串口通信  
+**波特率：** 115200  
+**数据位：** 8位  
+**停止位：** 1位  
+**校验位：** 无  
+
+## 2. 基础消息格式
+
+```
+[头部][长度][消息类型][设备地址][参数][校验和][尾部]
+|HEAD |LEN  |MSG     |ADDR    |PARA |CHKSUM |END |
+|2字节|4字节|1字节   |1字节   |变长 |2字节  |1字节|
+```
+
+**字段说明：**
+- **HEAD（头部）：** 固定值 0x7E7E
+- **LEN（长度）：** 从消息类型到校验和的字节数
+- **MSG（消息类型）：** 具体指令类型
+- **ADDR（设备地址）：** 舱室设备地址（1-32）
+- **PARA（参数）：** 指令参数，长度可变
+- **CHKSUM（校验和）：** 从消息类型到参数的所有字节累加和
+- **END（尾部）：** 固定值 0x0D
+
+## 3. 指令集
+
+### 3.1 舱室控制指令（0x1x系列）
+
+| 指令码 | 指令名称 | 参数格式 | 说明 |
+|--------|----------|----------|------|
+| 0x11 | 温度设置 | 8字节 | 设置上盖和底盖温度 |
+| 0x12 | PID参数设置 | 17字节 | 设置PID控制参数 |
+| 0x13 | 状态设置 | 1字节 | 设置舱室运行状态 |
+| 0x14 | UTC时间设置 | 4字节 | 设置UTC时间戳 |
+| 0x15 | 温度校准设置 | 变长 | 设置温度传感器校准 |
+| 0x16 | 加热器开关 | 1字节 | 控制加热器开关 |
+| 0x17 | 加热器功率 | 1字节 | 设置加热器功率比例 |
+| 0x18 | 配置设置 | 变长 | 设置舱室配置参数 |
+| 0x19 | 标签设置 | 变长 | 设置设备标签 |
+| 0x1A | 配置清除 | 1字节 | 清除配置参数 |
+| 0x1B | 重启指令 | 0字节 | 重启舱室设备 |
+| 0x1C | 超温设置 | 9字节 | 设置超温保护参数 |
+
+### 3.2 混气机控制指令（0x2x系列）
+
+| 指令码 | 指令名称 | 参数格式 | 说明 |
+|--------|----------|----------|------|
+| 0x21 | 温度设置 | 4字节 | 设置混气机温度 |
+| 0x22 | CO2浓度设置 | 4字节 | 设置CO2浓度 |
+| 0x23 | O2浓度设置 | 4字节 | 设置O2浓度 |
+| 0x24 | 泵设置 | 2字节 | 设置泵开关和速度 |
+| 0x25 | UVC LED设置 | 1字节 | 控制UVC LED |
+| 0x26 | 排气阀设置 | 1字节 | 控制排气阀 |
+| 0x27 | 排气校准 | 1字节 | 排气阀校准 |
+| 0x28 | UTC时间设置 | 4字节 | 设置UTC时间 |
+| 0x29 | 蜂鸣器设置 | 1字节 | 控制蜂鸣器 |
+| 0x2A | 温度校准 | 变长 | 温度传感器校准 |
+| 0x2B | CO2校准 | 变长 | CO2传感器校准 |
+| 0x2C | O2校准 | 变长 | O2传感器校准 |
+| 0x2D | 配置设置 | 变长 | 设置混气机配置 |
+
+### 3.3 查询指令
+
+| 指令码 | 指令名称 | 参数格式 | 说明 |
+|--------|----------|----------|------|
+| 0x1F | 舱室信息查询 | 0字节 | 查询舱室状态信息 |
+| 0x2F | 混气机信息查询 | 0字节 | 查询混气机状态信息 |
+
+## 4. 响应格式
+
+### 4.1 成功响应格式
+
+```
+[头部][长度][消息类型][设备地址][ACK][参数][校验和][尾部]
+|HEAD |LEN  |MSG     |ADDR    |ACK |PARA |CHKSUM |END |
+|2字节|4字节|1字节   |1字节   |1字节|变长 |2字节  |1字节|
+```
+
+**ACK字段说明：**
+- **0x00：** DEVICE_OK - 命令执行成功
+- **0x01：** DEVICE_BUSY - 设备忙
+- **0x02：** DEVICE_CMD_ERR - 命令错误
+- **0x03：** DEVICE_ADDR_ERR - 地址错误
+- **0x04：** DEVICE_PARAM_ERR - 参数错误
+- **0x05：** DEVICE_CHKSUM_ERR - 校验错误
+- **0x06：** DEVICE_CMD_NOT_RSP - 包头包尾错误
+- **0x07：** DEVICE_DATA_PUT_ERR - 数据下发错误
+- **0x08：** DEVICE_DATA_GET_ERR - 数据获取错误
+- **0x09：** DEVICE_ISSUED_ERR - 命令处理错误
+- **0x0A：** DEVICE_UPGRADE_ERR - 升级错误
+- **0xFF：** DEVICE_UNKNOWN_ERR - 未知错误
+
+### 4.2 查询响应数据格式
+
+**舱室信息响应（0x1F）：**
+```c
+typedef struct {
+    float temp_up;           // 上盖温度
+    float temp_dw;           // 底盖温度
+    float tmp117;            // TMP117温度
+    float pid_ctrl_up;       // 上盖PID输出
+    float pid_ctrl_dw;       // 底盖PID输出
+    uint8_t heater_power;    // 加热器开关状态
+    uint8_t heater_ratio;    // 加热器功率比例
+    uint8_t swtch;           // 舱室开关状态
+    uint8_t state;           // 舱室运行状态
+    uint8_t stage;           // 运行阶段
+    uint8_t addr;            // 设备地址
+    uint32_t err_flag;       // 错误标志
+    uint32_t ticks;          // 运行时间
+    uint32_t utc;            // UTC时间
+} cabin_info_t;
+```
+
+**混气机信息响应（0x2F）：**
+```c
+typedef struct {
+    gasmixing_gas_t gas;     // 气体信息
+    gasmixing_pump_t pump;   // 泵信息
+    gasmixing_cumsum_t cumsum; // 累计信息
+    gasmixing_adc_t adc;     // ADC信息
+    uint8_t ev_return;       // 排气阀状态
+    uint8_t ev_calib;        // 排气校准状态
+    uint8_t uvc_led;         // UVC LED状态
+    uint8_t beep;            // 蜂鸣器状态
+    uint8_t power_12v;       // 12V电源状态
+    uint8_t state;           // 运行状态
+    uint32_t ticks;          // 运行时间
+    uint32_t utc;            // UTC时间
+} gasmixing_info_t;
+```
+
+## 5. 通信示例
+
+### 5.1 设置舱室温度
+
+**主控发送：**
+```
+7E 7E 00 08 11 01 41 20 00 00 41 30 00 00 8A 0D
+|头 |长 |类型|地址|上盖温度|底盖温度|校验|尾|
+```
+
+**舱室响应：**
+```
+7E 7E 00 05 11 01 00 8A 0D
+|头 |长 |类型|地址|ACK |校验|尾|
+```
+
+### 5.2 查询舱室信息
+
+**主控发送：**
+```
+7E 7E 00 05 1F 01 25 0D
+|头 |长 |类型|地址|校验|尾|
+```
+
+**舱室响应：**
+```
+7E 7E 00 3F 1F 01 00 [舱室信息数据] 校验 0D
+|头 |长 |类型|地址|ACK |数据(60字节) |校验|尾|
+```
+
+## 6. 状态管理
+
+### 6.1 轮询状态（SUBDEV_POLL_STATE_POLL）
+- 用于周期性查询设备状态
+- 超时时间：100ms
+- 队列：g_subdev_poll_queue
+
+### 6.2 指令状态（SUBDEV_POLL_STATE_ISSUE）
+- 用于下发控制指令
+- 超时时间：3000ms
+- 队列：g_subdev_issue_queue
+
+## 7. 设备状态定义
+
+### 7.1 舱室状态
+```c
+typedef enum {
+    CABIN_NOT_USED = 0X00,       // 未使用
+    CABIN_RUNNING = 0x01,        // 正常运行
+    CABIN_TEMP_DRIFT = 0X02,     // 温度漂移
+    CABIN_OPEN_TOO_LONG = 0X03,  // 开盖时间过长
+    CABIN_SELECTED = 0x04,       // 被选中
+    CABIN_SENSOR_ERR = 0X05,     // 传感器故障
+    CABIN_HEAT_POWER_ERR = 0X06, // 加热器故障
+    CABIN_CPU_POWER_ERR = 0X07,  // CPU电源故障
+    CABIN_SENSOR_PWR_ERR = 0X08, // 传感器电源故障
+    CABIN_UNKNOWN_STATE = 0XFF   // 未知状态
+} cabin_state_e;
+```
+
+### 7.2 混气机状态
+```c
+typedef enum {
+    GASMIX_NOT_USED = 0X00,         // 未使用
+    GASMIX_RUNNING = 0x01,          // 正常运行
+    GASMIX_TEMP_EXCESS = 0X02,      // 温度异常
+    GASMIX_PRESSURE_EXCESS = 0X03,  // 压力异常
+    GASMIX_FLOW_EXCESS = 0X04,      // 流量异常
+    GASMIX_O2_SOLUB_EXCESS = 0x05,  // O2浓度异常
+    GASMIX_CO2_SOLUB_EXCESS = 0X06, // CO2浓度异常
+    GASMIX_SENSOR_ERR = 0X07,       // 传感器故障
+    GASMIX_HEAT_POWER_ERR = 0X08,   // 加热器故障
+    GASMIX_CPU_POWER_ERR = 0X09,    // CPU电源故障
+    GASMIX_GAS_INPUT_OFF = 0X0A,    // 气路关闭
+    GASMIX_TEMP_CTRL_OFF = 0X0B,    // 温度控制关闭
+    GASMIX_SHUTDOWN = 0X0C,         // 关机
+    GASMIX_UNKNOWN_STATE = 0XFF     // 未知状态
+} gasmix_state_e;
+```
+
+## 8. 错误处理
+
+- **通信超时：** 主控等待响应超时，应重发指令
+- **校验错误：** 接收方检测到校验错误，不响应
+- **参数错误：** 参数格式或范围错误，返回DEVICE_PARAM_ERR
+- **地址错误：** 设备地址不存在，返回DEVICE_ADDR_ERR
+
+## 9. 注意事项
+
+1. **地址范围：** 设备地址范围为1-32
+2. **超时时间：** 轮询100ms，指令3000ms
+3. **重发机制：** 建议实现指令重发机制
+4. **状态同步：** 主控应定期轮询设备状态
+5. **错误恢复：** 通信异常时应能自动恢复
+6. **并发控制：** 使用信号量保护串口资源