d9fba1be5b
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`，明确硬件接线说明及系统功能列表。
220 lines
5.3 KiB
Markdown
220 lines
5.3 KiB
Markdown
# AgriEnv_Monitor
|
||
|
||
## MQTT 协议文档
|
||
|
||
MQTT 上报与双继电器控制格式请参考：`README_MQTT.md`
|
||
|
||
本项目基于 ESP-IDF，新增了一个统一环境采集与控制组件 `agri_env`，实现以下功能：
|
||
|
||
1. DHT11 温湿度采集（DATA -> GPIO10）
|
||
2. BH1750 光照采集（I2C 地址 0x23，SDA -> GPIO4，SCL -> GPIO5）
|
||
3. MQ135 数据采集（AO -> GPIO1）
|
||
4. 双路继电器控制
|
||
5. 统一数据结构与获取接口
|
||
6. MQTT 连接（MQTT 3.1.1，自动获取 UID/MAC/时间）
|
||
7. MQTT 集成控制指令及即时回执（ACK）
|
||
8. 高频环境上报（1 秒一次，2 位精度）
|
||
9. cJSON 数据包序列化与上报
|
||
|
||
## 协议文档
|
||
|
||
详细的 MQTT 报文格式及指令说明请参考：[README_MQTT.md](README_MQTT.md)
|
||
|
||
## 目录说明
|
||
|
||
新增组件位于：
|
||
|
||
- `components/agri_env/include/agri_env.h`
|
||
- `components/agri_env/agri_env.c`
|
||
- `components/agri_env/CMakeLists.txt`
|
||
|
||
`main/main.c` 已接入初始化与示例读取逻辑。
|
||
|
||
## 硬件接线
|
||
|
||
### 1. DHT11
|
||
|
||
- VCC -> 3.3V
|
||
- GND -> GND
|
||
- DATA -> GPIO10
|
||
- 推荐 DATA 加 4.7k~10k 上拉电阻到 3.3V
|
||
|
||
### 2. BH1750
|
||
|
||
- VCC -> 3.3V
|
||
- GND -> GND
|
||
- SDA -> GPIO4
|
||
- SCL -> GPIO5
|
||
- 地址：0x23（ADDR 引脚悬空或接地）
|
||
|
||
### 3. MQ135
|
||
|
||
- DO（数字输出）-> GPIO10
|
||
|
||
注意：当前工程使用 MQ135 的 DO 数字输出，不做 ADC 采样。
|
||
|
||
- 组件直接读取 `mq135_digital_level`（0/1）
|
||
|
||
如需模拟量采集，需要单独引入 AO 接线和 ADC 逻辑（当前版本未启用）。
|
||
|
||
### 4. 两路继电器
|
||
|
||
- 风扇继电器 IN -> GPIO6（高电平有效）
|
||
- 灯光继电器 IN -> GPIO7（高电平有效）
|
||
|
||
## 软件实现概览
|
||
|
||
### 1. 统一数据结构
|
||
|
||
定义在 `agri_env.h`：
|
||
|
||
- `temperature_c`
|
||
- `humidity_percent`
|
||
- `illuminance_lux`
|
||
- `mq135_digital_level`
|
||
- `timestamp_ms`
|
||
|
||
### 2. 传感器读取接口
|
||
|
||
- `agri_env_init()`：初始化 I2C、BH1750、MQ135、继电器
|
||
- `agri_env_read_sensors(agri_env_data_t *out_data)`：一次读取并刷新缓存
|
||
- `agri_env_get_latest_data(agri_env_data_t *out_data)`：读取最近缓存
|
||
|
||
### 3. 继电器控制接口
|
||
|
||
- `agri_env_set_fan_relay(bool on)`
|
||
- `agri_env_set_light_relay(bool on)`
|
||
|
||
### 4. MQTT 接口（MQTT 3.1 + 用户名密码）
|
||
|
||
- `agri_env_mqtt_start()`
|
||
- `agri_env_mqtt_stop()`
|
||
- `agri_env_mqtt_is_connected()`
|
||
- `agri_env_mqtt_publish_latest(const char *topic, int qos, int retain)`
|
||
|
||
组件会在 MQTT 连接成功后自动订阅 `CONFIG_AGRI_ENV_MQTT_SUBSCRIBE_TOPIC`。
|
||
|
||
默认订阅主题与发布主题来自 menuconfig：
|
||
|
||
- `AGRI_ENV_MQTT_SUBSCRIBE_TOPIC`
|
||
- `AGRI_ENV_MQTT_PUBLISH_TOPIC`
|
||
|
||
订阅到的 JSON 命令支持如下字段：
|
||
|
||
- `fan_relay`: `true` / `false`
|
||
- `light_relay`: `true` / `false`
|
||
|
||
### 5. cJSON 数据打包
|
||
|
||
- `char *agri_env_build_data_json(const agri_env_data_t *data)`
|
||
|
||
说明：返回值是动态分配字符串，使用完后需要 `free()`。
|
||
|
||
## menuconfig 配置方法
|
||
|
||
在 `idf.py menuconfig` 中打开 `AgriEnv Monitor` 菜单，配置以下项：
|
||
|
||
- `AGRI_ENV_SAMPLE_PERIOD_MS`：采样周期
|
||
- `AGRI_ENV_MQTT_BROKER_URI`：MQTT 服务器地址
|
||
- `AGRI_ENV_MQTT_USERNAME`：MQTT 用户名
|
||
- `AGRI_ENV_MQTT_PASSWORD`：MQTT 密码
|
||
- `AGRI_ENV_MQTT_CLIENT_ID`：客户端 ID
|
||
- `AGRI_ENV_MQTT_PUBLISH_TOPIC`：发布主题
|
||
- `AGRI_ENV_MQTT_SUBSCRIBE_TOPIC`：订阅主题
|
||
|
||
示例：
|
||
|
||
```text
|
||
AGRI_ENV_SAMPLE_PERIOD_MS=5000
|
||
AGRI_ENV_MQTT_BROKER_URI=mqtt://192.168.1.100:1883
|
||
AGRI_ENV_MQTT_USERNAME=your_user
|
||
AGRI_ENV_MQTT_PASSWORD=your_pass
|
||
AGRI_ENV_MQTT_CLIENT_ID=agri-env-monitor
|
||
AGRI_ENV_MQTT_PUBLISH_TOPIC=agri/env/data
|
||
AGRI_ENV_MQTT_SUBSCRIBE_TOPIC=agri/env/cmd
|
||
```
|
||
|
||
协议版本固定为 `MQTT_PROTOCOL_V_3_1`。
|
||
|
||
## 在 main 中的使用示例
|
||
|
||
当前 `main/main.c` 已包含如下流程：
|
||
|
||
1. 初始化 Wi-Fi 配网：`wifi_connect_init()`
|
||
2. 初始化农业环境组件：`agri_env_init()`
|
||
3. 组件内部周期任务自动读取传感器数据并打印
|
||
4. 若 MQTT 参数已填写，则自动连接并按主题上报
|
||
|
||
你也可以继续在业务层调用 `agri_env_read_sensors()` 和 `agri_env_mqtt_publish_latest()` 做自定义上报。
|
||
|
||
## 构建与烧录步骤（详细）
|
||
|
||
### 1. 进入工程
|
||
|
||
```bash
|
||
cd /home/beihong/esp_projects/AgriEnv_Monitor
|
||
```
|
||
|
||
### 2. 配置目标芯片（如果尚未设置）
|
||
|
||
```bash
|
||
idf.py set-target esp32c3
|
||
```
|
||
|
||
### 3. menuconfig（可选）
|
||
|
||
```bash
|
||
idf.py menuconfig
|
||
```
|
||
|
||
按需配置串口、日志等级、Wi-Fi 配网组件参数。
|
||
|
||
### 4. 编译
|
||
|
||
```bash
|
||
idf.py build
|
||
```
|
||
|
||
### 5. 烧录
|
||
|
||
```bash
|
||
idf.py -p /dev/ttyUSB0 flash
|
||
```
|
||
|
||
### 6. 查看日志
|
||
|
||
```bash
|
||
idf.py -p /dev/ttyUSB0 monitor
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 1. DHT11 读取失败
|
||
|
||
- 检查 DATA 是否正确接 GPIO10
|
||
- 确保上拉电阻存在
|
||
- 线长过长时需降低干扰
|
||
|
||
### 2. BH1750 无数据
|
||
|
||
- 确认地址是 0x23
|
||
- 检查 SDA/SCL 是否与 GPIO4/GPIO5 对应
|
||
- 检查模块供电是否 3.3V
|
||
|
||
### 3. MQ135 只有数字量
|
||
|
||
- 当前版本设计即为数字量模式，只输出 `mq135_digital_level`
|
||
- 若 DO 一直不变，检查 MQ135 模块阈值电位器和 DO 接线
|
||
|
||
### 4. MQTT 无法连接
|
||
|
||
- 确认 `MQTT_BROKER_URI`/用户名/密码已填写
|
||
- 确认设备已联网
|
||
- 检查 broker 是否允许 MQTT 3.1
|
||
|
||
## 后续建议
|
||
|
||
1. 增加 FreeRTOS 周期任务，定时调用 `agri_env_read_sensors()` 与 `agri_env_mqtt_publish_latest()`。
|
||
2. 将 MQTT 参数改为 Kconfig 配置，避免每次改源码。
|
||
3. 对 MQ135 增加校准模型（洁净空气基线和 ppm 拟合）。
|