更新 README.md
This commit is contained in:
220
README.md
220
README.md
@@ -1,219 +1 @@
|
||||
# BotanicalBuddy
|
||||
|
||||
基于 ESP-IDF 的智能盆栽系统固件项目（ESP32-C3）。
|
||||
|
||||
当前结论：单片机端核心功能已完成，可直接联调 App/小程序侧。
|
||||
|
||||
## 固件完成度
|
||||
|
||||
- 环境采集：空气温湿度、光照强度
|
||||
- 本地显示：LCD + LVGL 多页面轮播
|
||||
- 设备控制：风扇、补光灯、加热、制冷（高电平有效）
|
||||
- 自动控制：阈值 + 回差控制
|
||||
- 手动控制：MQTT 远程开关风扇/灯/加热/制冷
|
||||
- 模式切换：`auto` / `manual`
|
||||
- 告警推送：超阈值边沿事件上报
|
||||
- 状态上报：周期性遥测（含模式与执行器状态）
|
||||
- Wi-Fi 配网：SoftAP + Captive Portal
|
||||
- 状态网页：独立 HTTP 状态看板与 JSON API（端口 8080）
|
||||
|
||||
## 系统架构
|
||||
|
||||
- `main/`：业务编排、控制循环、MQTT 回调对接
|
||||
- `components/wifi-connect/`：配网与路由连接
|
||||
- `components/lvgl_st7735s_use/`：LCD 与 LVGL 端口
|
||||
- `components/ui/`：界面对象与变量绑定
|
||||
- `components/i2c_master_messager/`：AHT30、BH1750 采集
|
||||
- `components/io_device_control/`：风扇/补光灯/加热/制冷 GPIO 控制
|
||||
- `components/mqtt_control/`：MQTT 连接、发布、控制指令解析
|
||||
- `main/auto_ctrl_thresholds.*`：阈值存取与校验
|
||||
- `main/auto_alerts.*`：告警判定与回调分发
|
||||
- `main/status_web.*`：独立状态网页服务（HTTP 8080）
|
||||
|
||||
## 状态网页（独立于配网页）
|
||||
|
||||
- 配网页面：`http://192.168.4.1`（仅 SoftAP 配网阶段）
|
||||
- 状态页面：`http://<设备STA_IP>:8080/`
|
||||
- 状态 API：`http://<设备STA_IP>:8080/api/status`
|
||||
|
||||
说明：
|
||||
- 两个网页服务独立运行，端口不同、职责不同。
|
||||
- 状态页用于运行态观测，不承载 Wi-Fi 配网流程。
|
||||
|
||||
`/api/status` 当前主要字段：
|
||||
- `temp`、`hum`、`lux`：传感器字符串值
|
||||
- `fan`、`light`、`hot`、`cool`：执行器状态（`on/off`）
|
||||
- `mode`：控制模式（`auto/manual`）
|
||||
- `light_on`、`light_off`：光照阈值
|
||||
- `hot_on_temp`、`hot_off_temp`：加热温度阈值（摄氏度）
|
||||
- `cool_on_temp`、`cool_off_temp`：制冷温度阈值（摄氏度）
|
||||
- `fan_on_hum`、`fan_off_hum`：风扇湿度阈值（%RH）
|
||||
- `wifi_status`：Wi-Fi 状态（`idle/provisioning/connecting/connected/failed/timeout`）
|
||||
- `sta_ip`：STA 当前 IP
|
||||
- `mqtt_connected`：MQTT 连接状态（布尔）
|
||||
- `i2c_ready`：关键外设初始化状态（布尔）
|
||||
- `loop_counter`：主循环计数
|
||||
- `uptime_ms`：设备运行时长（毫秒）
|
||||
- `free_heap`、`min_free_heap`、`largest_block`：堆内存指标
|
||||
- `app_version`：固件版本字符串
|
||||
- `snapshot_update_ms`、`snapshot_update_count`、`snapshot_age_ms`：状态快照时间与更新统计
|
||||
|
||||
## 运行逻辑
|
||||
|
||||
1. 上电初始化 Wi-Fi、LCD、传感器、IO。
|
||||
2. Wi-Fi 连通后启动 MQTT 与 Console。
|
||||
3. 主循环每 1s 执行：
|
||||
- 采集传感器并刷新 UI 数据。
|
||||
- 若 `mode=auto`，按阈值进行风扇/灯/加热/制冷自动控制。
|
||||
- 进行告警边沿判定并发布告警消息。
|
||||
- 每 5s 发布一次状态遥测消息。
|
||||
4. 收到 MQTT 控制消息时：
|
||||
- 可切模式（`auto/manual`）。
|
||||
- 可更新阈值（8 个阈值需同条下发）。
|
||||
- 可手动控制风扇/补光灯/加热/制冷开关。
|
||||
|
||||
## 开发环境
|
||||
|
||||
- Linux
|
||||
- ESP-IDF `v5.5.2`
|
||||
- 目标芯片：`esp32c3`
|
||||
|
||||
## 编译与烧录
|
||||
|
||||
1. 配置环境变量
|
||||
```bash
|
||||
export IDF_PATH=/home/beihong/esp/v5.5.2/esp-idf
|
||||
source $IDF_PATH/export.sh
|
||||
```
|
||||
|
||||
2. 构建
|
||||
```bash
|
||||
idf.py set-target esp32c3
|
||||
idf.py build
|
||||
```
|
||||
|
||||
3. 烧录并监视日志
|
||||
```bash
|
||||
idf.py -p /dev/ttyACM0 flash monitor
|
||||
```
|
||||
|
||||
## MQTT 协议
|
||||
|
||||
### ESP32 -> WEX
|
||||
|
||||
1. 告警消息主题：`topic/alert/esp32_iothome_001`
|
||||
|
||||
```json
|
||||
{
|
||||
"metric": "light",
|
||||
"state": "alarm"
|
||||
}
|
||||
```
|
||||
|
||||
字段：
|
||||
- `metric`：`light`
|
||||
- `state`：`normal` 或 `alarm`
|
||||
|
||||
2. 状态消息主题：`topic/sensor/esp32_BotanicalBuddy_001`
|
||||
|
||||
```json
|
||||
{
|
||||
"temp": "34.3",
|
||||
"hum": "30.5",
|
||||
"lux": "40",
|
||||
"fan": "on",
|
||||
"light": "off",
|
||||
"hot": "off",
|
||||
"cool": "off",
|
||||
"mode": "auto",
|
||||
"light_on": 100.0,
|
||||
"light_off": 350.0,
|
||||
"hot_on_temp": 18.0,
|
||||
"hot_off_temp": 20.0,
|
||||
"cool_on_temp": 30.0,
|
||||
"cool_off_temp": 28.0,
|
||||
"fan_on_hum": 80.0,
|
||||
"fan_off_hum": 70.0
|
||||
}
|
||||
```
|
||||
|
||||
字段：
|
||||
- `fan`：`on/off`
|
||||
- `light`：`on/off`
|
||||
- `hot`：`on/off`
|
||||
- `cool`：`on/off`
|
||||
- `mode`：`auto/manual`
|
||||
- `light_on`：光照低阈值（低于该值自动开灯）
|
||||
- `light_off`：光照高阈值（高于该值自动关灯）
|
||||
- `hot_on_temp` / `hot_off_temp`：加热开关阈值（含回差）
|
||||
- `cool_on_temp` / `cool_off_temp`：制冷开关阈值（含回差）
|
||||
- `fan_on_hum` / `fan_off_hum`：风扇开关阈值（含回差）
|
||||
|
||||
### WEX -> ESP32
|
||||
|
||||
控制主题：`topic/control/esp32_BotanicalBuddy_001`
|
||||
|
||||
1. 切换模式
|
||||
```json
|
||||
{ "mode": "manual" }
|
||||
```
|
||||
```json
|
||||
{ "mode": "auto" }
|
||||
```
|
||||
|
||||
2. 手动控制（建议先切到 `manual`）
|
||||
```json
|
||||
{ "fan": "on", "light": "off", "hot": "off", "cool": "off" }
|
||||
```
|
||||
|
||||
3. 更新自动阈值（8 个字段需同时下发）
|
||||
```json
|
||||
{
|
||||
"light_on": 100,
|
||||
"light_off": 350,
|
||||
"hot_on_temp": 18,
|
||||
"hot_off_temp": 20,
|
||||
"cool_on_temp": 30,
|
||||
"cool_off_temp": 28,
|
||||
"fan_on_hum": 80,
|
||||
"fan_off_hum": 70
|
||||
}
|
||||
```
|
||||
|
||||
4. 混合下发（同一条消息可同时包含模式、阈值、手动开关）
|
||||
```json
|
||||
{
|
||||
"mode": "auto",
|
||||
"light_on": 100,
|
||||
"light_off": 350,
|
||||
"hot_on_temp": 18,
|
||||
"hot_off_temp": 20,
|
||||
"cool_on_temp": 30,
|
||||
"cool_off_temp": 28,
|
||||
"fan_on_hum": 80,
|
||||
"fan_off_hum": 70,
|
||||
"fan": "off",
|
||||
"light": "on",
|
||||
"hot": "off",
|
||||
"cool": "off"
|
||||
}
|
||||
```
|
||||
|
||||
兼容输入：
|
||||
- `fan/light/hot/cool` 支持 `on/off`、`true/false`、`1/0`
|
||||
- `mode` 支持 `auto/manual`，也兼容 `true/false`、`1/0`（`true/1=auto`）
|
||||
|
||||
## 联调建议
|
||||
|
||||
1. 先下发 `{"mode":"manual"}`，验证手动风扇/灯/加热/制冷控制。
|
||||
2. 再下发阈值并切 `{"mode":"auto"}`，观察自动控制接管。
|
||||
3. 注意阈值含回差：
|
||||
- 光照：`light_on` 开灯，`light_off` 关灯
|
||||
- 温度：`hot_on_temp/hot_off_temp` 与 `cool_on_temp/cool_off_temp`
|
||||
- 湿度：`fan_on_hum` 开风扇，`fan_off_hum` 关风扇
|
||||
|
||||
## 说明
|
||||
|
||||
- 当前 README 聚焦单片机固件能力与联调协议。
|
||||
- App/小程序页面与云端业务可按本协议直接对接。
|
||||
|
||||
todo...
|
||||
Reference in New Issue
Block a user