447 lines
13 KiB
Markdown
447 lines
13 KiB
Markdown
# Smart Granary Code
|
||
|
||
基于 ESP-IDF 的智能粮仓监测与联动控制固件，运行于 ESP32-S3。项目集成了光照、温湿度、气体、火焰、人体/门磁、重量等多类传感器，支持本地 UI、语音交互（SU-03T）以及 MQTT 远程上报与控制。
|
||
|
||
## 1. 项目概览
|
||
|
||
### 1.1 核心能力
|
||
|
||
- 多传感器采集：BH1750、AHT30、MQ-2、JW01、火焰传感器、HX711、人体/门磁
|
||
- 本地显示：LVGL + ST7789
|
||
- 两种控制模式：`manual`（手动）/`auto`（自动联动）
|
||
- 四路继电器执行：风扇、照明、制冷、加热
|
||
- 语音模块：SU-03T 查询与告警播报
|
||
- 网络能力：Wi-Fi AP 配网 + STA 联网 + MQTT 双向通信
|
||
|
||
### 1.2 默认运行行为
|
||
|
||
- 上电默认 `manual` 模式
|
||
- MQTT 上报周期：1 秒
|
||
- 门未关告警阈值：60 秒
|
||
- 粮食“变质”判定阈值：`co2 >= 1500 ppm`
|
||
- 火焰危险阈值：`fire_percent >= 35%`
|
||
|
||
## 2. 硬件连接说明
|
||
|
||
以下为当前代码中的实际引脚定义。
|
||
|
||
### 2.1 I2C 设备
|
||
|
||
BH1750 与 AHT30 共享同一 I2C 总线：
|
||
|
||
| 设备 | SCL | SDA |
|
||
| --- | --- | --- |
|
||
| BH1750 | GPIO1 | GPIO2 |
|
||
| AHT30 | GPIO1 | GPIO2 |
|
||
|
||
### 2.2 继电器（4 路）
|
||
|
||
| 继电器编号 | 功能 | GPIO |
|
||
| --- | --- | --- |
|
||
| 1 | 风扇 | GPIO12 |
|
||
| 2 | 照明灯 | GPIO11 |
|
||
| 3 | 制冷片 | GPIO10 |
|
||
| 4 | 加热器 | GPIO9 |
|
||
|
||
### 2.3 ADC 传感器
|
||
|
||
| 设备 | GPIO | 说明 |
|
||
| --- | --- | --- |
|
||
| 火焰传感器 | GPIO3 | 百分比采样 + 危险判定 |
|
||
| MQ-2 | GPIO8 | 有害气体/烟雾百分比 |
|
||
|
||
### 2.4 UART 设备
|
||
|
||
| 设备 | UART | TX | RX | 波特率 |
|
||
| --- | --- | --- | --- | --- |
|
||
| JW01（TVOC/HCHO/CO2） | UART0 | GPIO43 | GPIO44 | 9600 |
|
||
| SU-03T（语音） | UART2 | GPIO42 | GPIO41 | 115200 |
|
||
|
||
### 2.5 IO 输入
|
||
|
||
| 设备 | GPIO | 说明 |
|
||
| --- | --- | --- |
|
||
| HC-SR312 人体感应 | GPIO16 | 高电平表示检测到人体 |
|
||
| 门磁开关 | GPIO17 | 低电平表示门关闭 |
|
||
|
||
### 2.6 称重模块
|
||
|
||
| 设备 | SCK | DOUT |
|
||
| --- | --- | --- |
|
||
| HX711 | GPIO13 | GPIO14 |
|
||
|
||
## 3. 软件架构
|
||
|
||
### 3.1 主要任务
|
||
|
||
- `sensor_task`：周期读取多传感器并更新共享环境数据
|
||
- `ui_task`：驱动 UI 刷新与界面变量更新
|
||
- `status_task`：人体/门磁状态与开门超时告警
|
||
- `relay_status_task`：同步继电器状态到 UI 与上报数据
|
||
- `hx711_task`：称重采样、滤波、去皮与稳定显示
|
||
- `mqtt_publish_task`：每秒打包 JSON 并发布 MQTT
|
||
- `su03t_auto_alert_task`：语音告警节流上报（默认 3 分钟）
|
||
- `sntp_task`：联网后 SNTP 对时
|
||
|
||
### 3.2 模式逻辑
|
||
|
||
- `manual`：接收 MQTT 下发的继电器开关命令，自动联动逻辑不接管
|
||
- `auto`：按阈值自动控制制冷/制热/风扇，照明不参与自动控制
|
||
|
||
## 4. 开发环境要求
|
||
|
||
### 4.1 基础要求
|
||
|
||
- Linux 开发环境
|
||
- ESP-IDF（建议与当前工程一致版本，需包含 `idf.py`）
|
||
- USB 驱动与串口权限正常
|
||
|
||
### 4.2 目标芯片与分区
|
||
|
||
- Target：`esp32s3`
|
||
- Flash Size：16MB（工程当前配置）
|
||
- 分区表：自定义 `partitions.csv`
|
||
|
||
`partitions.csv` 当前配置：
|
||
|
||
- `nvs`：0x9000, 0x6000
|
||
- `phy_init`：0xF000, 0x1000
|
||
- `factory`：0x10000, 4M
|
||
|
||
## 5. 快速开始
|
||
|
||
### 5.1 拉起工程
|
||
|
||
```bash
|
||
idf.py set-target esp32s3
|
||
idf.py build
|
||
```
|
||
|
||
### 5.2 烧录并查看日志
|
||
|
||
```bash
|
||
idf.py -p /dev/ttyUSB0 flash monitor
|
||
```
|
||
|
||
如果你使用的是 USB Serial/JTAG，可根据实际端口替换 `-p` 参数。
|
||
|
||
### 5.3 VS Code（ESP-IDF 插件）建议流程
|
||
|
||
1. 先执行 Build
|
||
2. 再执行 Flash
|
||
3. 最后打开 Monitor 查看日志
|
||
|
||
## 6. menuconfig 关键配置
|
||
|
||
```bash
|
||
idf.py menuconfig
|
||
```
|
||
|
||
### 6.1 Wi-Fi 连接参数
|
||
|
||
菜单位置：`WiFi 连接`
|
||
|
||
| 配置项 | 说明 | 默认值 |
|
||
| --- | --- | --- |
|
||
| WIFI_CONNECT_CONNECT_TIMEOUT_SEC | 连接超时（秒） | 30 |
|
||
| WIFI_CONNECT_MAX_SCAN_RESULTS | 扫描结果上限 | 20 |
|
||
| WIFI_CONNECT_AP_MAX_CONNECTIONS | 配网 AP 最大连接数 | 4 |
|
||
|
||
### 6.2 MQTT 参数
|
||
|
||
菜单位置：`MQTT 配置参数`
|
||
|
||
| 配置项 | 说明 | 默认值 |
|
||
| --- | --- | --- |
|
||
| 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 |
|
||
|
||
## 7. 配网说明
|
||
|
||
工程内置 AP 配网 + HTTP 控制台 + DNS 劫持流程：
|
||
|
||
1. 设备启动 APSTA，开启配网热点
|
||
2. 手机连接热点后访问 `http://192.168.4.1`
|
||
3. 页面扫描附近 Wi-Fi，提交 `SSID + 密码`
|
||
4. 设备连上路由后，页面可显示分配到的 STA IP
|
||
|
||
配网页面 API：
|
||
|
||
- `GET /api/scan`：扫描 AP 列表
|
||
- `POST /api/connect`：提交联网参数
|
||
- `GET /api/status`：查询连接状态
|
||
- `POST /api/clear`：清除保存的 Wi-Fi 配置
|
||
- `GET /api/sysinfo`：查看运行时信息
|
||
|
||
## 8. MQTT 协议说明（上位机对接）
|
||
|
||
### 8.1 协议与连接行为
|
||
|
||
- MQTT 协议版本：MQTT v3.1
|
||
- 连接成功后自动订阅 `AGRI_ENV_MQTT_SUBSCRIBE_TOPIC`
|
||
- 若 Broker URI 无协议头，内部会补全为 `mqtt://`，默认端口 1883
|
||
- 当前发布参数：QoS=0，Retain=0，每秒上报一次
|
||
|
||
### 8.2 主题定义
|
||
|
||
| 方向 | 主题 | 用途 |
|
||
| --- | --- | --- |
|
||
| 设备 -> 上位机 | `agri/env/data` | 周期上报环境数据、状态、阈值 |
|
||
| 上位机 -> 设备 | `agri/env/cmd` | 模式切换、阈值更新、手动控制 |
|
||
|
||
### 8.3 上报 JSON 字段（agri/env/data）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| time | string | 设备本地时间，格式 `YYYY-MM-DD HH:MM:SS` |
|
||
| lux | number | 光照（lux） |
|
||
| temp | number | 温度（摄氏度） |
|
||
| humidity | number | 湿度（%RH） |
|
||
| gas_percent | number | MQ-2 百分比（%） |
|
||
| tvoc | number | JW01 TVOC |
|
||
| hcho | number | JW01 HCHO |
|
||
| co2 | number | JW01 CO2（ppm） |
|
||
| ice_weight | number | HX711 重量（g） |
|
||
| fire_percent | number | 火焰百分比（%） |
|
||
| fire_danger | boolean | 火焰危险判定 |
|
||
| human_present | boolean | 人体存在 |
|
||
| door_closed | boolean | 门是否关闭（true=关） |
|
||
| door_alarm | boolean | 门未关超时告警 |
|
||
| door_open_seconds | number | 连续开门时长（秒） |
|
||
| fan_on | boolean | 风扇继电器状态 |
|
||
| light_on | boolean | 照明继电器状态 |
|
||
| cool_on | boolean | 制冷继电器状态 |
|
||
| hot_on | boolean | 制热继电器状态 |
|
||
| su03t_last_msgno | number | SU-03T 最近消息号 |
|
||
| su03t_rx_count | number | SU-03T 累计收包次数 |
|
||
| mode | string | `auto` 或 `manual` |
|
||
| th_temp_h | number | 制冷阈值 |
|
||
| th_temp_l | number | 制热阈值 |
|
||
| th_hum_h | number | 湿度阈值 |
|
||
| th_gas_h | number | 气体阈值 |
|
||
| ip_address | string | 当前 IP |
|
||
| food_status | string | `good` / `spoilage` |
|
||
| uptime_s | number | 运行时长（秒） |
|
||
| free_heap_kb | number | 剩余堆内存（KB） |
|
||
|
||
上报示例：
|
||
|
||
```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,
|
||
"door_alarm": false,
|
||
"door_open_seconds": 4,
|
||
"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
|
||
}
|
||
```
|
||
|
||
### 8.4 下发命令（agri/env/cmd）
|
||
|
||
字段按需携带，未携带字段保持原值。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| mode | string | `auto` / `manual` |
|
||
| th_temp_h | number | 更新制冷阈值 |
|
||
| th_temp_l | number | 更新制热阈值 |
|
||
| th_hum_h | number | 更新湿度阈值 |
|
||
| th_gas_h | number | 更新气体阈值 |
|
||
| fan | boolean | 手动控制风扇 |
|
||
| light | boolean | 手动控制照明 |
|
||
| cool | boolean | 手动控制制冷 |
|
||
| hot | boolean | 手动控制制热 |
|
||
|
||
下发示例（自动模式）：
|
||
|
||
```json
|
||
{
|
||
"mode": "auto",
|
||
"th_temp_h": 28.5,
|
||
"th_temp_l": 16.0,
|
||
"th_hum_h": 65.0,
|
||
"th_gas_h": 18.0
|
||
}
|
||
```
|
||
|
||
下发示例（手动模式）：
|
||
|
||
```json
|
||
{
|
||
"mode": "manual",
|
||
"fan": true,
|
||
"cool": true,
|
||
"hot": false,
|
||
"light": false
|
||
}
|
||
```
|
||
|
||
### 8.5 SU-03T 语音命令协议
|
||
|
||
说明：
|
||
|
||
- 串口为 UART2（RX=GPIO41，TX=GPIO42），115200 波特率。
|
||
- 语音模块上报命令时，固件按 msgno 匹配语义并立即回包。
|
||
- 数值类回包使用 8 字节 little-endian double 作为参数区。
|
||
- 状态类回包使用“仅 msgno、无参数”格式。
|
||
|
||
#### 8.5.1 查询命令映射（模块 -> 设备）
|
||
|
||
| 命令词（label） | key | 请求 msgno |
|
||
| --- | --- | --- |
|
||
| 温度是多少 | ask_temp | 0x00 |
|
||
| 湿度是多少 | ask_humi | 0x01 |
|
||
| 光照强度是多少 | ask_lux | 0x02 |
|
||
| 烟雾浓度是多少 | ask_mq2 | 0x03 |
|
||
| 二氧化碳浓度是多少 | ask_co2 | 0x04 |
|
||
| 粮食重量是多少 | ask_weight | 0x05 |
|
||
| 有人在吗 | ask_hum | 0x06 |
|
||
| 门磁状态 | ask_door | 0x07 |
|
||
| 风扇继电器状态 | ask_fan | 0x08 |
|
||
| 照明继电器状态 | ask_light | 0x09 |
|
||
| 制冷继电器状态 | ask_cool | 0x0A |
|
||
| 制热继电器状态 | ask_hot | 0x0B |
|
||
| 当前控制模式 | ask_control | 0x0C |
|
||
| 粮食状态 | ask_rice | 0x0D |
|
||
|
||
#### 8.5.2 回包映射（设备 -> 模块）
|
||
|
||
| 场景 | 回包 msgno | 参数 |
|
||
| --- | --- | --- |
|
||
| 温度查询返回 | 0x01 | double（温度） |
|
||
| 湿度查询返回 | 0x02 | double（湿度） |
|
||
| 光照查询返回 | 0x03 | double（lux） |
|
||
| 烟雾查询返回 | 0x04 | double（gas_percent） |
|
||
| CO2 查询返回 | 0x05 | double（co2） |
|
||
| 重量查询返回 | 0x06 | double（ice_weight） |
|
||
| 人体状态：有人 | 0x1A | 无参数 |
|
||
| 人体状态：无人 | 0x1B | 无参数 |
|
||
| 门磁状态：关门 | 0x0D | 无参数 |
|
||
| 门磁状态：开门 | 0x0C | 无参数 |
|
||
| 风扇：开 | 0x14 | 无参数 |
|
||
| 风扇：关 | 0x15 | 无参数 |
|
||
| 照明：开 | 0x20 | 无参数 |
|
||
| 照明：关 | 0x21 | 无参数 |
|
||
| 制冷：开 | 0x16 | 无参数 |
|
||
| 制冷：关 | 0x17 | 无参数 |
|
||
| 制热：开 | 0x18 | 无参数 |
|
||
| 制热：关 | 0x19 | 无参数 |
|
||
| 控制模式：自动 | 0x1C | 无参数 |
|
||
| 控制模式：手动 | 0x1D | 无参数 |
|
||
| 粮食状态：良好 | 0x1E | 无参数 |
|
||
| 粮食状态：变质 | 0x1F | 无参数 |
|
||
|
||
#### 8.5.3 主动告警（设备周期上报）
|
||
|
||
说明：语音主动告警任务每 1 秒检查一次条件，同一类告警最小间隔为 180 秒。
|
||
|
||
| 触发条件 | 告警 msgno | 参数 |
|
||
| --- | --- | --- |
|
||
| temp >= th_temp_h | 0x10 | double（当前温度） |
|
||
| humidity >= th_hum_h | 0x11 | double（当前湿度） |
|
||
| fire_danger = true | 0x12 | 无参数 |
|
||
| door_closed = false | 0x13 | 无参数 |
|
||
|
||
## 9. 自动联动规则
|
||
|
||
仅在 `mode=auto` 时生效：
|
||
|
||
- 制冷：`temp >= th_temp_h` 时开，否则关
|
||
- 制热：`temp <= th_temp_l` 时开，否则关
|
||
- 风扇：`humidity >= th_hum_h` 或 `gas_percent >= th_gas_h` 时开，否则关
|
||
- 照明：当前自动逻辑不控制照明
|
||
|
||
上电默认值：
|
||
|
||
- `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`
|
||
|
||
## 10. 目录结构（核心）
|
||
|
||
```text
|
||
.
|
||
├── main/
|
||
│ └── main.cpp # 系统入口与任务编排
|
||
├── components/
|
||
│ ├── wifi-connect/ # AP 配网、HTTP 控制台、STA 联网
|
||
│ ├── agri_env/ # MQTT 封装
|
||
│ ├── bh1750/ # 光照传感器
|
||
│ ├── MQ-2/ # 气体传感器
|
||
│ ├── JW01/ # TVOC/HCHO/CO2 传感器
|
||
│ ├── fire_sensor/ # 火焰传感器
|
||
│ ├── human_door/ # 人体/门磁检测
|
||
│ ├── relay_ctrl/ # 四路继电器控制
|
||
│ ├── su-03t/ # 语音模块协议
|
||
│ ├── lvgl_st7789_use/ # LCD + LVGL 显示
|
||
│ └── ui/ # UI 页面与变量绑定
|
||
├── partitions.csv # 分区表
|
||
├── sdkconfig # 当前工程配置
|
||
└── update_sdkconfig.sh # 常用 sdkconfig 修补脚本
|
||
```
|
||
|
||
## 11. 常见问题与排障
|
||
|
||
### 11.1 设备始终无法联网
|
||
|
||
- 检查是否连上设备热点并访问了 `http://192.168.4.1`
|
||
- 检查路由器频段（ESP32-S3 常用 2.4GHz）
|
||
- 在串口日志中观察 `wifi_connect` 状态机输出
|
||
|
||
### 11.2 MQTT 无法上报
|
||
|
||
- 确认 `AGRI_ENV_MQTT_BROKER_URI` 是否有效
|
||
- 确认设备已获取 STA IP，且可访问 Broker
|
||
- 检查鉴权参数（用户名/密码/Client ID）
|
||
|
||
### 11.3 JW01 与日志冲突
|
||
|
||
JW01 使用 UART0（GPIO43/44），建议保持控制台输出为 USB Serial/JTAG，避免 UART0 日志与传感器数据冲突。
|
||
|
||
### 11.4 HX711 波动大
|
||
|
||
- 检查供电稳定性与接线
|
||
- 系统已内置去皮、低通与稳定锁定逻辑，仍异常时优先排查硬件噪声
|
||
|
||
## 12. 开发建议
|
||
|
||
- 新增组件时先补齐 `components/<name>/include` 对外接口，再在 `main.cpp` 挂接任务
|
||
- MQTT 字段建议保持向后兼容：新增字段不删除旧字段
|
||
- 上位机建议以 `agri/env/data` 最新数据作为控制确认（当前无独立 ACK 主题）
|
||
|
||
## 13. 许可证
|
||
|
||
当前仓库未提供独立 LICENSE 文件，如需对外发布，请补充开源许可证并在此处声明。
|