添加 MQTT 命令处理功能，支持远程控制模式与阈值配置

2026-04-22 16:49:00 +08:00
parent 0d117d9d47
commit e446b7515c
4 changed files with 311 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -61,3 +61,181 @@
    set_var_fan_status("开");
    set_var_light_status("开");
 ```
+
+## MQTT 协议说明（上位机对接）
+
+本项目通过 MQTT 实现数据上报与远程控制。上位机可直接按以下协议开发。
+
+### 1. 连接参数与默认配置
+
+参数来自 menuconfig：
+
+| 配置项 | 说明 | 默认值 |
+| ------ | ---- | ------ |
+| AGRI_ENV_MQTT_BROKER_URI | MQTT 服务器地址 | 空 |
+| AGRI_ENV_MQTT_USERNAME | MQTT 用户名 | 空 |
+| AGRI_ENV_MQTT_PASSWORD | MQTT 密码 | 空 |
+| AGRI_ENV_MQTT_CLIENT_ID | 客户端 ID | agri-env-monitor |
+| AGRI_ENV_MQTT_PUBLISH_TOPIC | 设备上报主题 | agri/env/data |
+| AGRI_ENV_MQTT_SUBSCRIBE_TOPIC | 设备订阅主题 | agri/env/cmd |
+
+协议与连接行为：
+
+- MQTT 协议版本：MQTT v3.1
+- 如果 Broker URI 未写协议头，会自动补成 mqtt:// 并默认端口 1883
+- 连接成功后设备自动订阅 AGRI_ENV_MQTT_SUBSCRIBE_TOPIC
+
+### 2. 主题定义
+
+| 方向 | 主题 | 用途 |
+| ---- | ---- | ---- |
+| 设备 -> 上位机 | agri/env/data | 周期上报环境数据、设备状态、阈值配置 |
+| 上位机 -> 设备 | agri/env/cmd | 下发模式切换、阈值修改、手动控制命令 |
+
+发布参数（当前固件实现）：
+
+- 上报周期：1 秒 1 次
+- QoS：0
+- Retain：0
+
+### 3. 上报数据 JSON（agri/env/data）
+
+#### 3.1 完整字段
+
+| 字段名 | 类型 | 单位/取值 | 说明 |
+| ------ | ---- | --------- | ---- |
+| time | string | YYYY-MM-DD HH:MM:SS | 设备本地时间 |
+| lux | number | lux | 光照强度 |
+| temp | number | 摄氏度 | 温度 |
+| humidity | number | %RH | 湿度 |
+| gas_percent | number | % | MQ-2 气体浓度百分比 |
+| tvoc | number | 传感器原始单位 | TVOC（JW01） |
+| hcho | number | 传感器原始单位 | 甲醛（JW01） |
+| co2 | number | ppm | 二氧化碳（JW01） |
+| ice_weight | number | g | HX711 重量值 |
+| fire_percent | number | % | 火焰传感器百分比 |
+| fire_danger | boolean | true/false | 火焰危险判定 |
+| human_present | boolean | true/false | 人体存在状态 |
+| door_closed | boolean | true/false | 门磁状态（true=关门） |
+| fan_on | boolean | true/false | 风扇继电器状态 |
+| light_on | boolean | true/false | 照明继电器状态 |
+| cool_on | boolean | true/false | 制冷继电器状态 |
+| hot_on | boolean | true/false | 制热继电器状态 |
+| su03t_last_msgno | number | 0-255 | SU-03T 最近消息号 |
+| su03t_rx_count | number | >=0 | SU-03T 累计收包次数 |
+| mode | string | auto/manual | 当前控制模式 |
+| th_temp_h | number | 摄氏度 | 制冷阈值（temp >= th_temp_h 触发制冷） |
+| th_temp_l | number | 摄氏度 | 制热阈值（temp <= th_temp_l 触发制热） |
+| th_hum_h | number | %RH | 湿度阈值（humidity >= th_hum_h 触发风扇） |
+| th_gas_h | number | % | 气体阈值（gas_percent >= th_gas_h 触发风扇） |
+| ip_address | string | IPv4 字符串 | 当前联网 IP |
+| food_status | string | good/spoilage | 粮食状态（依据 co2 判定） |
+| uptime_s | number | s | 设备运行时长 |
+| free_heap_kb | number | KB | 剩余堆内存 |
+
+#### 3.2 上报示例
+
+```json
+{
+    "time": "2026-04-22 16:24:39",
+    "lux": 5,
+    "temp": 30.8,
+    "humidity": 65.4,
+    "gas_percent": 9.7,
+    "tvoc": 0,
+    "hcho": 0,
+    "co2": 350,
+    "ice_weight": 0,
+    "fire_percent": 0,
+    "fire_danger": false,
+    "human_present": false,
+    "door_closed": false,
+    "fan_on": false,
+    "light_on": false,
+    "cool_on": false,
+    "hot_on": false,
+    "su03t_last_msgno": 0,
+    "su03t_rx_count": 0,
+    "mode": "manual",
+    "th_temp_h": 35,
+    "th_temp_l": 15,
+    "th_hum_h": 70,
+    "th_gas_h": 20,
+    "ip_address": "192.168.1.12",
+    "food_status": "good",
+    "uptime_s": 1234,
+    "free_heap_kb": 182
+}
+```
+
+### 4. 下发命令 JSON（agri/env/cmd）
+
+下发命令为 JSON。字段可按需携带，未携带字段保持原值。
+
+| 字段名 | 类型 | 说明 |
+| ------ | ---- | ---- |
+| mode | string | auto 或 manual |
+| th_temp_h | number | 更新制冷阈值 |
+| th_temp_l | number | 更新制热阈值 |
+| th_hum_h | number | 更新湿度阈值 |
+| th_gas_h | number | 更新气体阈值 |
+| fan | boolean | 手动控制风扇继电器（1号） |
+| light | boolean | 手动控制照明继电器（2号） |
+| cool | boolean | 手动控制制冷继电器（3号） |
+| hot | boolean | 手动控制制热继电器（4号） |
+
+### 5. 控制逻辑规则
+
+#### 5.1 手动模式（mode=manual）
+
+- 支持 fan/light/cool/hot 四个布尔量直接控制继电器
+- 自动联动逻辑不接管继电器
+
+#### 5.2 自动模式（mode=auto）
+
+- 制冷：temp >= th_temp_h 时开启，否则关闭
+- 制热：temp <= th_temp_l 时开启，否则关闭
+- 风扇：humidity >= th_hum_h 或 gas_percent >= th_gas_h 时开启，否则关闭
+- 照明：当前自动逻辑不控制照明继电器
+
+### 6. 上电默认值
+
+设备上电后的默认模式与阈值：
+
+- mode = manual
+- th_temp_h = 35.0
+- th_temp_l = 15.0
+- th_hum_h = 70.0
+- th_gas_h = 20.0
+
+### 7. 下发示例
+
+#### 7.1 切到自动并设置阈值
+
+```json
+{
+    "mode": "auto",
+    "th_temp_h": 28.5,
+    "th_temp_l": 16.0,
+    "th_hum_h": 65.0,
+    "th_gas_h": 18.0
+}
+```
+
+#### 7.2 切到手动并开风扇、开制冷
+
+```json
+{
+    "mode": "manual",
+    "fan": true,
+    "cool": true,
+    "hot": false,
+    "light": false
+}
+```
+
+### 8. 上位机实现建议
+
+- 命令下发后，以上报主题 agri/env/data 的最新数据作为状态确认
+- 建议上位机做字段容错：新增字段应忽略，缺失字段使用默认显示
+- 当前固件未提供独立 ACK 主题，建议在上位机侧做超时重发策略