微雪ESP32-S3 4.2寸RLCD开发版折腾记录

项目来源

我这次选来做底子的，是 wickenzh/ESP32-S3-RLCD-4.2 的天气时钟固件。它已经有天气、日历、本地温湿度、图片展示和小智 AI 等功能。我沿用了它的硬件支持和界面框架，继续调整页面、数据展示和操作方式。

另一个参考项目是 taifuer/esp32-rlcd-firmware，后面就简称 rlcd。我挺喜欢它的时钟字体和天气图标，看着清楚，所以想把这套显示方式借过来。CODEX 额度、服务器监控、市场行情和网页配置，也参考了 rlcd 工程的实现，再接进原天气时钟的页面和网络逻辑里。

我自己想加的东西其实很具体：看时间的时候，顺便看看 CODEX 还剩多少额度、服务器状态怎么样，最好首页就能看见，不用挨个翻页。设置也希望尽量在手机上完成，设备上的两个按键留着翻页就好。

这样改出来的版本，我整理成了 ESP32-S3-RLCD-Dashboard。整套天气时钟的基础来自原项目，我主要围绕这些日常需求做调整。为了把内容放进这块小屏幕，界面改了好几轮，连秒数大小、图标之间空多少、一条横线有多粗，都重新挪过。

先说明一下：文中几张图都是模拟器预览，用的是示例数据，不是设备实拍。

界面布局

额度和服务器都要加进来，原来的布局就得重新安排。我先看了一遍屏幕，找找哪些地方能腾出位置。

我先把日期、周几、时间和本地温湿度收到顶部一行，电池挪到最右边。电量百分比后来也拿掉了，留一个电池图标就好。Wi-Fi 和声音按实际状态显示，没设闹钟就不显示闹钟图标，也不用特意给它空出一块位置。

上下那两行随小时、秒数变化的黑点，我也不想留了。去掉后，正好把地方让给时钟和下面的数据，粗横线顺便改细。少更新一些内容，我也希望能省点电，不过续航还没测过，能省多少现在说不准。

字体是我比较在意的一处。原来的秒数太小，和时分放在一起不协调，所以这次把秒数放大，换上参考项目里的数字样式，其他页面的小数字也跟着适配。天气图标和描述则挨近一些，作为一整组居中。只有一个“晴”字的时候，右边总空着一大块，看着不太舒服。

天气温度改成 20/26℃ 这样的最低温、最高温，下方再放空气质量和降雨概率。首页下面分成天气、CODEX 额度、服务器三块，底部加了一言。额度百分比放大、加粗；服务器最多六台，不足六台时就整组上下居中，不必全挤在上面。

有些页面我这次干脆去掉了：温湿时钟、聚合时钟，还有 GIF 功能。图片时钟留下，默认不开。日历、天气看板和温湿历史继续保留，腾出来的空间用来放大格子、预测温度和图表。日历加上了“休”“班”，看日期时也能顺便看一眼调休。

数据与刷新

首页里的服务器区域终究不大，想看得仔细一点，还是单独一页合适。

这个页面我要求最多的就是对齐。CPU、内存、磁盘各待在自己的列里，上下几台服务器看过去，数字不要左一下右一下。名称醒目一点，找起来也方便。

行情页也用了紧凑的列表，最多放六项。我把中间的分割线去掉了，行与行之间留一点距离就够。刷新时间不用那么抢眼，缩小后放到右下角，中间多留一行给行情数据。

比起排版，刷新时那个“未知”更让我在意。之前服务器一开始请求，旧数据就没了，画面先显示“未知”，过一会儿才显示状态。明明只是正常刷新，看着却像哪里出了问题，还白白多更新一次画面。

我的想法很简单：新数据还没回来，就先显示旧数据。请求成功了再替换，失败了也别把原来的清掉。CODEX 额度和其他相关页面也按这个思路检查过。右下角的“刷新时间”只在成功拿到数据时更新，所以要判断这份数据新不新，看看时间就知道了。

联网也按需要来。CODEX、行情和服务器有各自的刷新间隔，还要看相关页面有没有在显示。没有网络任务时，Wi-Fi 可能暂时断开，看到未连接的图标先不用急着重新配网。

偶尔想立刻查一次，就长按右键。按住约 1.2 秒后，先显示上次刷新时间，再倒数三秒。看完觉得刚刷过，松手就行；继续按到结束，才真正请求一次。温湿历史和小智 AI 不走这个操作。

配网与设置

设备就两个按键，填地址、输密钥这种事，我还是想在手机上做。

第一次没配过 Wi-Fi，屏幕会给出热点二维码。手机扫一下，加入设备热点，再在配网页里填家里的 Wi-Fi 名称和密码。如果手机提醒“无互联网”，先别切走，这时候连的是设备，家里的网还没配好。

配网页没自动弹出来的话，保持连接设备热点，在浏览器里打开 http://192.168.4.1/。二维码只是省掉了手动找热点这一步，家里的 Wi-Fi 信息还是要自己填。

后面再改配置，就不用每次重新连热点了。长按左键，进入“设置 → 网络 → 网页设置”，屏幕上会显示局域网地址和四位授权码。手机连同一个网络，照着屏幕上的地址打开，输入这次的授权码即可。闲置五分钟会退出，一次设置会话最长三十分钟。

刚上手的话，我建议先把天气配好。和风天气要填 Key 和 Host；不想先折腾这两个，可以开启 Open-Meteo。它的空气质量用的是 US AQI，也不提供本项目的天气预警，这点有区别。

CODEX 和服务器这两项，还得有对应的服务才能用。CODEX 填兼容额度接口的完整地址和管理员 API Key，输入框只放密钥本身，Bearer、x-api-key: 都不用自己加，固件会处理请求头。普通 OpenAI API Key 不能直接查这里的额度。服务器监控则要填服务地址和 Token。没有这些东西就先跳过，不影响先用天气时钟。

平时两个按键这样用：

默认翻页顺序是天气时钟、市场行情、服务器列表、日历、天气看板、温湿历史、小智 AI。觉得哪个不常用，或者想换个顺序，去“设置 → 显示”里调，图片时钟也在那里开。想静音，音量调到零就行。具体怎么填配置，可以对着 上手教程 看。

编译与刷机

这里得提醒一句：截至 2026 年 10 月 18 日，GitHub 放上去的是源码，还没有 Release 固件包。“Code → Download ZIP”下载的那一包也是代码，不能直接拿去刷。

现在要试，需要自己编译。用 ESP-IDF 5.5.3，硬件对应 ESP32-S3-RLCD-4.2 的 16 MB Flash、8 MB PSRAM 版本。USB 线要能传数据，别拿到一根只能充电的。

打开已经激活 ESP-IDF 的终端，进入仓库目录，再运行：

cd RLCD_CLOCK
idf.py build
idf.py -p COM4 flash monitor

COM4 只是例子，要换成自己的串口。Windows 可以去“设备管理器 → 端口”里找。第一次编译会下载依赖，环境怎么准备放在了 编译与刷写文档。如果暂时不想装开发环境，可以等有完整固件包的时候再试。

flash.cmd 和 flash_local.ps1 也放在仓库里了，不过别只下载这两个文件。它们是给完整刷机包用的，还需要旁边的固件、文件清单和工具才能运行。

有完整包的话，把它全部解压，接好设备，关掉占用串口的程序，再运行 flash.cmd。不放心包里的文件是否齐全，可以先在解压目录运行：

.\flash.cmd -DryRun

这一步只检查文件和写入计划，不会刷设备。确认以后，再用 .\flash.cmd -Port COM4，或者双击脚本按提示选择串口。

待解决的问题

SD 卡这件事还没弄好。

字体选择已经加进去了，TTF、OTF、TTC 都放在 /fonts 目录。大字体按需读取，不会把二十多 MB 的文件一口气装进内存。但实际遇到的那张 32 GB FAT32 卡，仍然报 ESP_FAIL (-1)。卡都没挂载上，后面自然读不到字体。所以想先用起来的话，用内置字体就行，外部字体暂时放一放。

同样遇到挂载失败，可以用 SD 日志采集脚本。在已经激活 ESP-IDF 的终端里运行它，按提示打开串口，再去设备网页读取字体列表。报错后按 Ctrl+C 结束，把日志留下来继续查。这个脚本不会格式化卡。

还有小智回复时一卡一卡、夹着杂音，以及之前重新出现开机画面的问题。语音分片处理和启动时的栈占用都做过调整，但语音还得上设备试听，重启最初是哪里写坏了内存，也没有完全确认。目前的情况写在 已知问题 里，已经做过的构建和测试则放在 验证记录。

这份修改用了原项目和 rlcd 的不少东西，来源说明 里有对应记录。原项目的 非商业源码许可证 也保留着，第三方代码和字体还有各自的许可。拿去继续改、再分享的时候，记得把这些声明一起带上。