## 引脚分配

### IIC设备

这类设备有：BH1750光照传感器、AHT30温湿度传感器

| 设备名称 | SCL引脚 | SDA引脚 |
| -------- | ------- | ------- |
| BH1750   | GPIO1  | GPIO2  |
| AHT30    | GPIO1  | GPIO2  |

### 继电器

一共有4个继电器，分别控制4个设备的开关，从1号到4号依次为：风扇、照明灯、制冷片、加热器。

| 设备名称 | 继电器编号 | GPIO引脚 |
| -------- | ---------- | -------- |
| 风扇     | 1          | GPIO12   |
| 照明灯   | 2          | GPIO11   |
| 制冷片   | 3          | GPIO10   |
| 加热器   | 4          | GPIO9   |

### ADC传感器

这个用的是ADC输入，连接到GPIO3引脚。

| 设备名称   | GPIO引脚 |
| ---------- | -------- |
| 火焰传感器 | GPIO3  |
| MQ-2    | GPIO8  |


### 串口设备

| 设备名称 | TX引脚 | RX引脚 |  
| -------- | ------ | ------ |
| 气体传感器   | GPIO4  | GPIO5  |
| 语音模块   | GPIO6  | GPIO7  |

### IO设备

| 设备名称 | GPIO引脚 |
| -------- | -------- |
| HC-SR312   | GPIO16  |
| 微动开关   | GPIO17  |


### 称重模块

| 设备名称 | GPIO引脚 |
| -------- | -------- |
| HX711   | GPIO35  | GPIO36  |

```
    set_var_door_status("关闭");
    set_var_food_status("良好");
    set_var_door_status("关闭");
    set_var_hum_status("有人");
    set_var_hot_status("开");
    set_var_cool_status("关");
    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=关门） |
| door_alarm | boolean | true/false | 门未关超时告警状态 |
| door_open_seconds | number | s | 当前连续开门时长 |
| 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
- door_open_alarm_seconds = 60

### 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 主题，建议在上位机侧做超时重发策略
- 门磁告警建议以 door_alarm 与 door_open_seconds 组合显示，door_alarm=true 时突出提示用户