智能水箱监测系统 (Smart Water Tank Monitor)

一、 项目背景与场景简介

本项目是一套智能水箱监测系统。由于水箱与抽水机之间存在物理隔离，不便直接敷设线缆，本项目采用“智能监测水位 + 手动起停抽水机”的方案。

本项目包含**采集端（ESP32-S3）与展示端（嵌入式 Linux）**两部分。展示端提供极简的屏幕反馈。当水位过低时，通过强烈的视觉信号提醒手动开启抽水机。

二、 核心原则与亮点

• 纯 Rust 全栈：从单片机底层硬件驱动（esp-idf-hal）到上层网络通信，再到展示端的 GUI 渲染任务，全链路使用 Rust 语言，最大程度保证内存安全与跨线程并发的数据高可靠性。
• 极简 UI 逻辑：
  • 展示端无任何触摸或按键交互，只需查看屏幕。
  • 界面采用大字体、高对比度。
  • 强势低水位预警：当接收到水位低于阈值（如 20%）时，屏幕自动触发全屏红色闪烁，提供最直观的视觉指令。
• 强壮的容灾通信管道：
  • 基于局域网 MQTT 通信解耦双端。
  • Retain 机制确保展示端随时上线、异常重启或断线重连后，均能立即拉取到最新的水箱状态，不存在等待盲区。
• 采集端全能热配机制（ESP32-S3）：
  • 内置独立 Web 服务（SPIFFS 分区提供 HTML 页面），可通过网页表单动态配置 Wi-Fi 凭证、MQTT Broker IP 及其它水箱物理参数。
  • 支持设备网络智能降级，无外网或路由器失效时提供自带 AP 热点进行本地化配置（结合 Captive Portal）。
  • 搭载防爆栈及安全的局域网 OTA 功能（带 Magic Byte 与 SHA256 强校验），实现固件与 Web 前端资源的双重空中升级。

三、 系统整体架构与契约

1. 通信协议与数据格式

• 链路：局域网 MQTT（MQTT Broker 推荐部署于展示端同一 Linux 主机或独立节点）
• Topic: water_tank/level
• Payload: 纯数字字符串的百分比，例如 "85", "12", "100"
• QoS: 1 (AtLeastOnce)
• Retain: True

2. 硬件与角色划分

模块	角色	硬件平台	核心逻辑
采集端 (Sensor Node)	阁楼水箱水位采集与播报	ESP32-S3 (N16R8) + HC-SR04 超声波测距	每 5 秒进行一次微秒级高精度脉冲测距，结合 NVS 存储的满/空水标定距离，自动换算成 0-100% 水位并推送到 MQTT。
展示端 (Display Hub)	大屏监控与警报渲染	带屏幕的嵌入式 Linux 设备（如 Raspberry Pi）	运行 Rust GUI 客户端持久订阅水位数据。执行大字体显示及 <20% 全屏红色闪烁警报的高级渲染任务。

四、 本仓库结构：采集端 (ESP32-S3)

本工程即为系统的采集端（阁楼节点）固件项目代码。采集端逻辑已完全闭环并在真实环境中稳定运行。

核心功能模块

• WIFI / Captive Portal：网络初始化，具备 STA/AP 降级及劫持 DNS 到本地配置页面的能力。
• Web Server & OTA：提供 / 提供前端控制台静态资源，并处理 /ota 及各类 API 请求。
• Ultrasonic：封装的 HC-SR04 特有驱动，基于定时器/中断处理微秒级测距逻辑及坏点滤波。
• MQTT Engine：负责维系连接并在后台子线程装载、发布 water_tank/level 数据。
• NVS / SPIFFS：管理非易失性配置（账密、标定数据）及提供打包好的 VFS 文件系统镜像。

编译与运行

本工程依赖现代化的 esp-idf 环境与 Rust xtensa 工具链。 此外，由于项目中使用了 SPIFFS 存储前端静态文件，您需要在系统中安装 mkspiffs：

• mkspiffs 项目地址: https://github.com/igrr/mkspiffs
• 请确保 mkspiffs 已添加到系统环境变量 (PATH) 中。

编译并生成固件及文件系统

在根目录下运行以下命令，build.rs 会自动调用 mkspiffs 将 data 目录打包生成供烧录的 spiffs.bin：

cargo build --release

烧录固件与 SPIFFS 镜像

生成好相关二进制文件后，您需要通过 espflash 烧录。由于系统使用了自定义分区表 (partitions.csv)，可以通过以下命令写入 SPIFFS 镜像：

步骤一：构建并烧录生成的主固件

cargo run --release

步骤二：利用 espflash 烧录 SPIFFS 数据（存放前端 Web 挂载文件） 根据 partitions.csv 自动计算，我们定义了两个各 4MB 的 OTA 分区（ota_0 与 ota_1），在包含前置的基础系统分区后，紧接着的 storage 分区（即 SPIFFS 预留的 2MB 空间）起始偏移地址计算为 0x820000 (具体请在烧录日志中二次核对它的实际 Offset 打印)：

# 烧录打包好的 spiffs.bin 到对应的分区地址
espflash write-bin 0x820000 spiffs.bin