feat: 集成 MQTT 高频上报与远程控制功能,并标准化协议文档

1. 核心功能增强:
   - 实现 1s/次的传感器数据主动上报,温湿度精度提升至小数点后两位。
   - 新增基于 cJSON 的 MQTT 控制指令解析逻辑,支持对双路继电器的远程开关控制。
   - 引入即时回执 (ACK) 机制:设备在执行控制指令后立即通过 `agri/env/ack` 主题反馈执行状态。

2. 系统架构优化:
   - 引入 `sntp_time` 组件实现自动对时,确保上报数据携带准确的 `YYYY-MM-DD HH:MM:SS` 时间戳。
   - 增加基于 eFuse 的芯片 UID 获取逻辑,结合 MAC 地址实现设备唯一标识。
   - 为传感器采集任务引入 Mutex 互斥锁,确保多任务环境下 `env_sample_data_t` 的线程安全。
   - 将所有传感器任务堆栈提升至 3072 字节,解决 cJSON 操作导致的 Stack Overflow 风险。

3. 文档与规范:
   - 新增 `README_MQTT.md` (V1.2),定义了环境报文、控制指令及 ACK 回执的完整 JSON Schema。
   - 同步更新主工程 `README.md`,明确硬件接线说明及系统功能列表。
This commit is contained in:
Wang Beihong
2026-04-19 20:34:26 +08:00
parent 8548f04733
commit d9fba1be5b
10 changed files with 587 additions and 27 deletions

88
README_MQTT.md Normal file
View File

@@ -0,0 +1,88 @@
# AgriEnv_Monitor MQTT 通信协议文档 (V1.2)
本文档面向上位机(控制端)开发,定义了与 AgriEnv_Monitor 硬件终端的交互格式。
## 1. 通信主题 (Topic)
| 功能 | 主题 (Default) | 说明 |
| :--- | :--- | :--- |
| **环境上报** | `agri/env/data` | 硬件每 1 秒主动推送到此主题 |
| **设备控制** | `agri/env/cmd` | 上位机发送控制指令到此主题 |
| **执行回执** | `agri/env/ack` | 设备执行指令后的状态反馈 |
---
## 2. 环境数据上报 (Device -> Cloud/Client)
硬件会在任务循环中自动采集并打包传感器数据,格式如下:
### 报文示例 (JSON)
```json
{
"uid": "C5E171EDA59400F8",
"mac": "D8:85:AC:5D:EE:30",
"time": "2026-04-19 20:12:48",
"data": {
"temp": 29.0,
"humi": 64.0,
"lux": 109.17,
"gas_do": 1
},
"status": {
"r1": 0,
"r2": 1
}
}
```
### 字段定义
- **uid**: (String) 芯片唯一 ID用于区分不同终端。
- **mac**: (String) 硬件 MAC 地址。
- **time**: (String) 时间戳字符串 (`YYYY-MM-DD HH:MM:SS`)。
- **data**: (Object) 传感器实时数据:
- **temp**: (Float) 温度,单位 °C。
- **humi**: (Float) 相对湿度,单位 %。
- **lux**: (Float) 光照强度,单位 Lux。
- **gas_do**: (Int) MQ135 数字输出电平1: 正常0: 触发报警)。
- **status**: (Object) 执行器当前状态:
- **r1**: (Int) 继电器 1 状态 (0: 关, 1: 开)。
- **r2**: (Int) 继电器 2 状态 (0: 关, 1: 开)。
---
## 3. 设备远程控制 (Client -> Device)
上位机通过发布 JSON 指令到 `agri/env/cmd` 来控制继电器。
### 指令示例 (JSON)
```json
{
"relay": 1,
"state": 1
}
```
### 字段说明
- **relay**: (Int) 目标继电器编号。可选值:`1``2`
- **state**: (Int) 目标状态。可选值:`1` (开启), `0` (关闭)。
---
## 4. 控制执行回执 (Device -> Client)
当设备成功解析并执行控制指令后,会立即向 `agri/env/ack` 主题发布一条回执消息。
### 回执示例 (JSON)
```json
{
"relay": 1,
"state": 1,
"result": "success"
}
```
### 字段说明
- **relay**: (Int) 已控制的继电器编号。
- **state**: (Int) 执行后的状态。
- **result**: (String) 执行结果,固定为 "success"。