ESP32 墨水屏天气终端

这是一个基于 ESP32-S3 的墨水屏天气终端项目，用于显示室内温湿度、和风天气、Home Assistant 农历信息与基础状态数据。

当前仓库适配的屏幕为：汉朔Stellar-XL3N
当前开发板为：Fri3d Badge 2024 (ESP32-S3-WROOM-1)
屏幕分辨率为：400 x 300

功能特点

• 开机首刷使用较完整刷新，后续运行中默认使用 SOFT 刷新，减少明显闪烁
• 支持本地 SHT4x 温湿度采样
• 支持和风天气当前天气与多日预报
• 支持通过 MQTT 上报数据，并可接入 Home Assistant
• 支持从 Home Assistant 拉取农历相关实体信息
• 配置与图标通过 LittleFS 文件系统管理
• 内置 OTA 升级能力

项目结构

• te.ino：主程序，包含联网、天气、MQTT、绘图与刷新逻辑
• ssd1680_native.cpp：按 SSD1680 / DEPG 系列文档重写的屏幕驱动
• ssd1680_native.h：驱动头文件
• data：LittleFS 运行时资源目录
• data/conf.example.json：配置示例
• data/icons_bin：64x64 天气图标二进制资源
• data/icons_bin24：24x24 小图标二进制资源
• tools：字体、图标、LittleFS 上传等辅助脚本
• assets：字体源文件与调试素材
• icon：天气图标源 PNG / SVG 资源

配置文件

实际运行时需要在 LittleFS 中提供 conf.json。仓库不会提交你的真实配置，使用时可参考 data/conf.example.json 创建自己的 data/conf.json。

主要配置项包括：

• wifi_ssid / wifi_password
• mqtt_host / mqtt_port / mqtt_user / mqtt_pass / mqtt_base
• qweather_host / qweather_token / qweather_location
• ha_host / ha_port / ha_token / ha_lunar_entity
• ota_password
• battery_adc_pin / battery_scale

注意：

• data/conf.json 已被 .gitignore 忽略，不会进入版本控制
• 图标二进制资源需要随 LittleFS 一起写入设备，否则天气图标无法显示

开发环境

• Arduino IDE 2.x
• ESP32 Arduino Core
• 开发板：Fri3d Badge 2024
• 分区方案：huge_app

建议安装的常用库：

• ArduinoJson
• PubSubClient
• LittleFS
• WiFi
• HTTPClient
• ArduinoOTA

编译与烧录

1. 固件编译

在 Arduino IDE 中选择：

• Board: Fri3d Badge 2024
• Partition Scheme: Huge APP

然后直接编译并上传固件。

2. LittleFS 资源上传

本项目依赖 data/ 目录中的资源文件，首次烧录或修改配置、图标后，需要重新上传文件系统。

仓库已提供脚本：

• tools/upload_littlefs.ps1

示例：

powershell -ExecutionPolicy Bypass -File .\tools\upload_littlefs.ps1 -Port COM4

上传内容包括：

• data/conf.json
• data/icons_bin/
• data/icons_bin24/
• data/ha_button.yaml

刷新策略说明

当前驱动策略为：

• 开机后的第一次显示使用 FAST
• 后续运行期间只要画面有变化，就使用 SOFT
• 画面没有变化时跳过刷新

这样可以尽量降低运行中突兀的整屏强刷感。

资源生成

如果你需要重新生成字体或图标，可以使用：

• tools/generate_icons.py
• tools/font_export.py
• tools/update_all_fonts.py

说明：

• icon/ 中保留了图标源素材
• data/icons_bin* 中保存的是设备运行时直接读取的二进制结果

Home Assistant 参考

仓库附带了一个简单参考文件：

• homeassistant_mqtt_sensors.yaml

可以按自己的 MQTT 主题前缀做对应修改。

当前状态

这版仓库已经整理为适合公开发布的结构，重点保留了：

• 当前可用的 汉朔Stellar-XL3N 驱动实现
• 运行所需的 LittleFS 资源
• 字体与图标生成工具
• 配置示例与中文说明