# 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"。