ESP32-S3 RLCD 4.2 天气时钟

语言： 简体中文（当前） · English · 繁體中文 · 日本語

这是一个基于 ESP32-S3 和 4.2 英寸 RLCD 屏幕 的低功耗天气时钟固件项目。它把常驻显示、本地温湿度、联网天气、日历、图片展示、音频提醒、小智 AI 和 OTA 更新整合到一台桌面设备中。

快速入口

界面主要基于 LVGL 开发。 页面布局、文字、菜单和状态控件由 LVGL 管理；大号时钟、图片和曲线等通过 LVGL Canvas 与自定义绘制实现。底层 RLCD 驱动负责单色输出，并优先采用局部刷新，兼顾显示效果与低功耗。

• 简易用户手册 · 用户详细说明
• 贡献指南 / Contributing Guide
• 安全政策 / Security Policy
• 第三方开源许可说明
• 项目许可证
• 最低功耗 Power Demo
• 实机模拟预览

关联项目

• 微雪 ESP32-S3-RLCD-4.2 官方产品页：本项目所使用开发板的官方介绍、规格和购买信息。
• 微雪 ESP32-S3-RLCD-4.2 官方文档：开发板接口、原理图、示例和硬件资料。
• ESP32-S3-RLCD-4.2_UP：OTA 固件镜像仓库，可查看可用固件及版本信息。
• 在线上位机：配置资源、转换图片/GIF、校验并烧录固件、查看串口日志；源码与说明。

源码目录

• RLCD_CLOCK/：ESP-IDF 固件工程、组件、字体、模拟器和测试。从此目录执行 idf.py build。
• host_web/：网页上位机；Pages 只部署站点文件及经过校验的最近 10 版固件。
• firmware/：OTA 清单，docs/：用户手册和 Power Demo，previews/：SDL 预览。
• .github/：固件构建与网页部署。网页修改独立部署，不会生成新的固件版本。

项目定位

这个项目面向长期摆放使用的桌面天气时钟。设计重点不是追求持续联网或高刷新率，而是在信息始终可读的前提下，让 Wi-Fi、音频、高频 UI 和其它高功耗资源只在真正需要时运行。

主要目标：

• 常驻显示：RLCD 在不持续刷新的情况下保持画面可读。
• 按需功耗：页面不可见时停止其专属刷新，普通联网任务完成后关闭 Wi-Fi。
• 离线可用：支持 RTC 保持时间，也可以不配置网络直接进入离线模式。
• 稳定优先：OTA、音频、显示和网络任务之间设有资源与状态保护。
• 便于维护：页面、天气、配置、音频、传感器、OTA 和小智 AI 按职责维护。

八个工作页面

默认页面顺序如下，用户可以在设置中关闭页面或重新排序；系统始终保留至少一个可用工作页。

1. 天气时钟：时间、日期、实时天气、预警、本地温湿度、电池和状态图标。
2. 图片时钟：本地图片、大号分钟时间和每日文字；自定义图库支持多档切换周期。
3. 天气看板：城市天气、空气质量、湿度、风力、日出日落、预警和未来天气。
4. 温湿时钟：高对比时分秒、本地温湿度、趋势、日期和农历。
5. 日历：当月日历、农历、节日和今日高亮；极端六行月份会保持当前日期可见。
6. 温湿历史：记录并显示本地温湿度历史与趋势。
7. 小智 AI：本地唤醒、语音对话、字幕、回复播放、单次闹钟、番茄钟和天气城市设置。
8. 聚合时钟：秒级时分秒、当天天气及最高/最低温、公历日号与农历月份/日期、本地温湿度，采用灰度点阵信息区与加粗数字。

聚合时钟默认追加在最后，可独立关闭或排序；天气共用缓存和整点同步，温湿度沿用白天每分钟、夜间每两分钟采样，时间仅更新变化数字。升级保留原页面配置，无需恢复出厂。离线模式下该联网页面不可启用。

所有页面采用“能局部刷新就不全屏刷新”的原则。秒级页面只更新变化数字，分钟级页面只在时间、数据或显示状态变化时刷新；隐藏页面不会继续执行无意义的绘制。

配置与联网

天气服务可选和风天气或 Open-Meteo，配网页和网页快捷配置中的开关默认关闭。开启 Open-Meteo 无需和风 Key/Host，显示 US AQI，不提供本项目预警；两个来源不自动混用。公共服务仅限非商业使用，数据来自 Open-Meteo / CAMS，城市查询使用 GeoNames。

首次使用通过设备配网页完成配置：

• 支持主 Wi-Fi 和可选备用 Wi-Fi；主网络连续不可用时会尝试备用网络，成功后可按既有策略晋升。
• 联网天气需要 QWeather API Key 和账号专属 API Host；API Host 在 QWeather 控制台中查看。
• 天气城市可以使用公网 IP 自动定位，也可以通过配网页、上位机或小智 AI 设置手动城市。
• 不配置 Wi-Fi 时，可以填写本地日期时间并进入离线模式。

设备联网行为按需执行：

• 天气时钟、天气看板和聚合时钟共用天气缓存，在需要时按整点及缺数据补拉规则同步；开机为已启用页面错峰预取。
• 图片时钟在需要时获取每日文字。
• NTP 在启动、手动同步和既定校时点运行。
• OTA、网络检测和手动同步只在用户主动操作时运行。
• 小智 AI 只在对应页面激活语音与联网会话，离开页面后释放会话资源。
• 离线模式、低电量、配网和 OTA 期间会拦截不合适的后台联网任务。

天气与每日文字使用本地缓存。短时网络失败不会清空已有内容，后台重试受次数和退避限制，避免 Wi-Fi 反复上电。

提醒与交互

• 两个实体按键用于页面切换、菜单移动、确认、返回和停止提示音。
• 支持整点提醒、全天提醒和多档音量设置。
• 小智 AI 可以设置一个单次闹钟，也可以启动、修改、查询或取消番茄钟。
• 闹钟和番茄钟使用独立状态，并对相同触发时刻进行冲突保护。
• 设置中的“小智节能”可在长时间无操作时返回页面顺序中的首页；番茄钟运行期间不会被自动返回打断。

低功耗策略

固件在不改变屏幕常驻显示的前提下减少无效工作：

• 启用 ESP-IDF 动态电源管理与 FreeRTOS Tickless Idle：CPU 在负载允许时从 240MHz 自动降至 40MHz，空闲窗口自动进入 Light Sleep；联网、音频和 OTA 只在工作期间通过 PM Lock 临时保持所需性能。
• 秒级页面采用局部刷新；静态页面在没有事件时暂停周期绘制。
• 温湿度、电池和历史采样按运行时段及充电状态调度。
• 普通天气、每日文字、NTP 和 OTA 会错峰执行，避免启动阶段集中占用内存与 Wi-Fi。
• 音频播放结束后释放 Codec 和相关资源。
• Wi-Fi 图标与无线电实际状态保持一致，便于直接观察高功耗网络是否仍在运行。
• OTA 下载期间降低 UI 刷新频率，并保留百分比、速度和进度条。
• 低电量模式会进入极简显示并禁止高功耗操作。

docs/Power Demo/ 中的 Power Demo 是独立实验工程，用于验证保留屏幕显示、分钟级唤醒和最小外设条件下的功耗边界。它不包含完整版设置、OTA、多页面和小智业务，也不参与正式固件构建。

硬件与软件

• 开发板：Waveshare ESP32-S3-RLCD-4.2。
• 主控：ESP32-S3-WROOM-1-N16R8，16MB Flash、8MB PSRAM。
• 显示：4.2 英寸 400 × 300 RLCD。
• 本地设备：RTC、温湿度传感器、电池 ADC 和实体按键。
• 音频：麦克风、Codec、功放和扬声器，用于小智 AI 与提示音。
• 网络：Wi-Fi，用于配网、天气、每日文字、NTP、OTA 和网络检测。
• 存储：NVS 保存联网与用户设置，独立资源分区保存可更新素材。
• 开发框架：ESP-IDF v5.5.3；图形界面：LVGL v8.4.0。

源码结构

• RLCD_CLOCK/main/：应用入口和按业务划分的固件模块。
• RLCD_CLOCK/components/：板级支持、显示、音频、资源和第三方组件。
• RLCD_CLOCK/partitions.csv：设备分区表。
• RLCD_CLOCK/CMakeLists.txt：ESP-IDF 工程入口。
• RLCD_CLOCK/sdkconfig.defaults：默认工程配置。
• docs/：用户手册和独立 Power Demo。
• previews/：由当前源码生成的全部详细 SDL 页面预览和总览图。
• .github/：公开仓库的固件构建与源码发布工作流。

构建与提交要求见 贡献指南。先阅读简易用户手册，完整刷机、配网、页面设置和故障处理见用户详细说明。

OTA 与自定义资源

设备通过 OTA manifest 检查版本并下载 App 固件。公开源码仓库在版本标签触发后构建两类附件：

• weather_clock_vX.X.X.bin：只包含 App，供 OTA 或保留现有分区/NVS 的 App 定址刷写使用。
• weather_clock_vX.X.X_merged.bin：包含 bootloader、分区表、OTA data、语音模型和 App，供完整恢复或分区变化后的串口刷写使用。

OTA 不能更新分区表。版本说明明确要求完整刷写时，请不要只执行 OTA。设备还支持通过上位机写入自定义图片资源；资源损坏或不存在时会使用固件内置内容兜底。

开源来源与第三方许可

本项目的小智 AI 页面基于 78/xiaozhi-esp32 移植和二次开发，当前固定参考基线为提交 7b190b78e4f8dfef14126f6cd478c134b3cd3cd8。

xiaozhi-esp32 由 Shenzhen Xinzhi Future Technology Co., Ltd. 及项目贡献者以 MIT License 发布。版权声明、MIT 许可文本和免责声明保留在 THIRD_PARTY_NOTICES.md 中。本项目的非商业许可证只约束项目维护者拥有版权的原创部分，不覆盖第三方许可证已经授予的权利。

贡献与安全

提交 Issue 或 Pull Request 前请阅读：

• 贡献指南 / Contributing Guide
• 安全政策 / Security Policy

请勿在 Issue、日志、截图或提交中公开 Wi-Fi 密码、QWeather API Key、API Host 私有配置、Token、NVS 镜像、设备私钥、本机绝对路径或私有服务地址。

使用限制

本项目仅允许个人学习、研究、评估和其它非商业用途。

严禁商用。

未经项目所有者书面许可，禁止将项目维护者拥有版权的原创部分用于商业产品、付费服务、批量销售、转售、营利性分发或其它商业交付。第三方组件仍遵循各自原始许可证。详细条款见 LICENSE。