From f1083aebfa34d40f9cdb8f2a92831d6ee36cfb7c Mon Sep 17 00:00:00 2001 From: wangbeihong Date: Wed, 11 Mar 2026 20:15:36 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 220 +----------------------------------------------------- 1 file changed, 1 insertion(+), 219 deletions(-) diff --git a/README.md b/README.md index 3f3b6ea..be9bb36 100644 --- a/README.md +++ b/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... \ No newline at end of file