M5Stack StopWatch 固件魔改全记录:Avatar、TamaPoke、TE 同步与 4% 的余量
目录
设备:M5Stack StopWatch(SKU C152),ESP32-S3R8(rev v0.2,16 MB Flash + 8 MB PSRAM),1.75" 466×466 圆 AMOLED(CO5300,QSPI)
环境:Arch Linux;ESP-IDF v5.5.4;arduino-cli 1.5.1 +m5stack:esp323.3.9;LVGL v9.5.0
目标:在官方 UserDemo 固件里塞进 Avatar 与 TamaPoke 两个应用,修掉撕裂、25 fps 的「生硬」、黑屏/重启/卡声,再做中文界面并关掉开机绿灯
结果:最终镜像 4,959,232 B / 分区 5,177,344 B,余 218,112 B(4%);Avatar 稳定 60 fps,TE 等待从 11.5 ms 降到 0.24 ms,LVGL handler 峰值从 189 ms 降到 1.37 ms,用户逐项复测通过

一、起点:一块手表和三个「不可能」
M5Stack StopWatch 官方固件(UserDemo V0.5,cf51acc,ESP-IDF v5.5.4)本身是完整的:Launcher、设置、秒表、Wi-Fi、Badge 配置页都有。但它有两个硬限制:
- 没有垂直同步。
waitDisplay()只等 QSPI 总线空闲,displayBusy()恒为 false,TE 引脚(G38)只被设成上拉输入,代码从不读。整屏一动就撕裂。 - 应用槽位是固定的。想加自己的应用,要么改 Launcher,要么另起一套固件;而 TamaPoke 这类 Arduino 工程直接搬进 ESP-IDF,还要补 HAL、字体和音频。
我要的是两个应用真正并进官方固件,滑动、切换、睡眠唤醒这些日常操作不能变差。最后所有改动都在一个仓库里:
~/code/m5stack-stopwatch/
├── docs/NOTES-stopwatch.md # 846 行事实清单,逐条注明行号出处
├── env/ # 工具链、构建、烧录、字体生成
├── examples/ # SmokeTest / Diag / CjkFontTest
├── firmware/ # 官方镜像、备份、自制头像 LittleFS
├── libs/ # M5GFX / M5Unified / UserDemo / LVGL
├── patches/ # M5GFX flush 与 TE 补丁
├── sketches/ # Water / Pokeball / Avatar / TamaPoke / TEDiag
└── tools/
二、先把硬件基线钉住
嵌入式排障最怕「凭感觉」。动手前先量了四组数:
| 项目 | 实测值 | 意义 |
|---|---|---|
| 芯片 | ESP32-S3 rev v0.2,16 MB Flash,8 MB PSRAM | 与官方参数一致 |
| TE 频率 | 58.76 Hz / 17,018.8 µs(高电平 1124.5 µs) | 面板实际刷新周期 |
| 整屏写入 | 23.73 ms = 18.4 MB/s(理论 40 MB/s 的 46%) | 写入慢于扫描 |
| 出厂固件 | 与官方 V0.5 逐字节一致(0x0–0x3AD4F0) |
基线可信 |
整屏写入 23.73 ms 大于帧周期 17.02 ms,所以全屏更新必然撕裂。按「写入前沿快过扫描前沿」的判据,单帧高度要压到约 195 行以内才能天然无撕裂——这也是后面 TE 方案和局部刷新的依据(该判据在 NOTES §3.7 里标注为推断)。
顺手把出厂固件备份了:
# firmware/device-backup/device-0x0-0x3AD4F0-factoryV0.5.bin
md5sum device-0x0-0x3AD4F0-factoryV0.5.bin
# 2aca0236241cf0dd775a4d41c3a5eb5f
还有一个硬件版本的坑值得单独说:v1.0 丝印上的 BAT 实际是 5V IN,不能接电池;v1.0.1 才是真的电池接口。这类信息如果只看丝印,迟早烧板。
三、移植策略:先用 Arduino 验证,再进 IDF
两个应用走了同一条路:先在 sketches/ 里用 arduino-cli 独立编译上机,把「能不能跑、颜色对不对、性能多少」这些问题在简单工程里解决,再移植进 IDF。
| 工程 | 结果 |
|---|---|
Avatar |
上机 [avatar perf] fps=60.0 render_avg=8.3ms,12 种表情、触摸拖动视线、倾斜视线、A/B 键、震动全部由用户逐个确认 |
Pokeball |
编译 687,643 B(21%),上机 7.1 fps |
TamaPoke |
Arduino 版零 error,游戏逻辑保留 |
Water / Breakout / TChart |
用于验证渲染、物理和图表 |
移植进 IDF 时,TamaPoke 的游戏逻辑逐字节保留,只替换板级接口:
main/apps/app_poke/
├── compat/Arduino.h # map/constrain/random 等
├── compat/Preferences.h # NVS 兼容层
├── gfx_compat.h # 把 U8g2 风格调用接到 M5GFX
├── audio.cpp/.h # ES8311 + AW8737A
├── rtcbat.cpp/.h # RX8130CE + 电量
├── sdmon.cpp/.h
├── i18n.cpp/.h
└── dex.h # 151 个官方简中宝可梦名
分区表沿用官方 OTA 布局,app 槽只有 0x4f0000 = 5,177,344 B。这句话在后面会变成一条硬约束。
四、TE 帧同步:11.5 ms → 0.24 ms
TE 同步做了两层,最终只启用一层,避免双重等待:
hal_display的frame_sync:上电后用 2 秒脉冲探测(只接受 20–120 Hz),每帧一次等待 + 一次连续突发,25 ms 超时兜底;没有脉冲时完全回退原行为,可运行时关闭。- M5GFX 侧另有
tear_sync::configure()(Panel_AMOLED.inl),默认关闭。
同时把 M5GFX 的帧缓冲 flush 改成块级双缓冲,单独测纯 QSPI flush:
11.21 ms(38.9 MB/s,达到理论 40 MB/s 的 97%)
效果:
| 指标 | 改前 | 改后 |
|---|---|---|
| TE 等待 | 11.5 ms | 0.24 ms |
| 渲染峰值 | 50–65 ms | 约 1.4 ms |
补丁在 patches/M5GFX-framebuffer-flush.patch 和 patches/M5GFX-te-sync.patch。这里有一个工程判断:只做局部刷新时,不超过 195 行本来就不会撕裂;TE 是给整屏动画兜底的,不是所有绘制都必须等。
五、25 fps 的「生硬」是怎么来的
用户的原话是「滑动切换应用很生硬,没有过渡」。先量:
LVGL handler: 中位 6.5 ms / P90 117 ms / 峰值 189 ms
帧间隔: 39.8 ms ≈ 25 fps
三个独立原因叠在一起:
- 缓冲位置不对。LVGL 用部分缓冲,每块
466×120= 56,160 B,两块都在 PSRAM。 - 每帧无条件失效。
DynamicIconLabel::update()每帧都调_label->setOpa(...),即使值没变也触发 invalidate。 - 没有过渡。图标没有边缘淡出,页面切换是硬切。
修法对应三条:
- 双缓冲改为一块内部 RAM + 一块 PSRAM。两块都放内部 RAM 会挤爆 Wi-Fi(见下一节),只放 PSRAM 又慢。
- 删掉每帧
setOpa。 - 图标用
update_icon_fade(scroll_x):≤120 px 全亮,120–210 px 按 smoothstep 淡出;滚动/吸附 200→300 ms,LVGL 轮询 10→2 ms,应用切换 220 ms 淡出 + 250 ms 淡入。
结果:
handler 平均 0.07 ms,峰值 1.37 ms
内部 RAM 余量 122 KB → 180 KB
六、三个「看起来是玄学」的 Bug
6.1 Avatar 一打开就黑屏
Avatar 引擎是逐图元直绘,每帧几千个图元;但 onOpen 时面板还开着自动回刷,于是每个图元各走一次 QSPI + TE,一帧永远画不完。
修法:onOpen 里 setAutoDisplay(false),onRunning() 每帧只 display() 一次,onClose() 再还原。用户复测「正常了 ✓✓」。
6.2 打开任何应用都闪一下
新加的背光渐变会在打开应用前把亮度拉到 0 再拉回;而 TamaPoke 等应用自己也每帧设亮度。两个写入者互相打架,表现就是闪一下。
加锁解决不了两个写入者抢同一个寄存器,干脆把背光渐变整段删掉,过渡交给图标淡出和 LVGL 动画。用户复测「不闪了 ✓✓」。
6.3 Badge 选 Edit 就重启
两块 LVGL 缓冲(2×56,160 B)都占内部 RAM 后,Wi-Fi SoftAP 连一个 752 字节的 beacon 缓冲都分配不到:
wifi:alloc eb len=752 type=4 fail
Guru Meditation Error: Core 0 panic'ed (LoadProhibited)
改成一块内部 + 一块 PSRAM 后恢复。另一个问题是进入 Edit 模式后退不出来:badge::config_ap::run() 用 xEventGroupWaitBits(..., portMAX_DELAY) 永久阻塞,设备按键全失效,只能靠网页点 Done。改成 50 ms tick 轮询 A+B,并在屏上提示 Hold A+B to exit。
这条修完留下的教训写在 NOTES §792:
全局状态(
setAutoDisplay/ 背光亮度 / LVGL 缓冲所在内存池)谁改谁必须还原,且分配内部 RAM 要给 Wi-Fi 等无线电留足余量。
七、颜色翻车:一次被自己推翻的假设
中途出现「小火龙整只变绿」,第一反应是帧缓冲 16 位字节序反了,于是给所有标量颜色包了一层 canvasColor()。
但受控实验推翻了它:
TColr四选一:fillRect传标准0xF427就是橙色;只有pushImage传0x27F4才对。TColr2用游戏同一套spriteColor()直接画小火龙,颜色正确。
结论:标量 API 原样传标准 RGB565;只有自组像素缓冲再 pushImage 时才预交换。canvasColor() 从 sketches 和 app_poke 全部撤回。绿龙之后未能复现,最可能是连续烧写十几次后 AMOLED 面板/供电轨进入坏状态(推断,非确证)。
那次花屏的恢复流程实测有效,一次就好:
- 拔掉 USB-C;
- 快速连按两次电源键关机(屏幕熄灭);
- 等 3 秒,短按一次电源键开机;
- 再插 USB-C。
判断法则:重新上电后恢复 → 软状态问题;官方固件也依旧花屏 → 才考虑硬件。
八、中文化:只能走子集字体
用户第一反应是「中文字体会不会占非常多空间」。答案是会:
| 方案 | 体积 |
|---|---|
efontJA_16 + efontKR_16 |
773 KB |
simsun_16_cjk |
约 1.4 MB |
CjkFontTest(CN/JA/KR/TW 全量) |
2,803,115 B(89%) |
| 设置页子集(62 汉字 + ASCII + 标点,6 字号) | 49 KB |
efontCN_16(7545 字形) |
数组 318,199 B,nm 实测 310.7 KB |
策略因此分成两块:
- 设置界面:只覆盖菜单与 6 个 worker 的实际用字,62 个汉字 × 6 字号,
+49 KB。 - TamaPoke:语言从 9 种砍到 EN + ZH,85 条字符串 + 151 个官方简中宝可梦名 + 3×8 条勋章,接入
efontCN_16,+295 KB。日/韩/繁数组符号数为 0,--gc-sections会把死代码排掉。
收尾时把字符集做成脚本 tools/fonts/collect_cjk_chars.py:只扫字符串字面量、排除 app_poke/,实测 115 字与手工列表逐字一致,加一个「与」字后 116 字。用户后来自己升级成 Noto Sans CJK SC Medium + 4bpp,各字号源体积 80–228 KB。
子集字体想加多少字都便宜,只有要做输入法或者显示任意文本时,才不得不上全字库。
九、关掉开机绿灯
绿灯不是 ESP32 的 GPIO,而是 M5PM1 的第 5 脚 LED_EN(PM_STATUS_LED),默认高电平,每次上电/断电后 PMIC 都会恢复为高。所以「启动时关一次」不够,得在 HAL 里做开关并持久化。
细节:
- 写
PWR_CFG的LED_CTRL位(bit4,0=低):setLedEnLevel(false)。 - 不能用
setLedCount(0):库只接受 1–32。 - 代价:LED 调用 A/B 对比
0x4b9a00 → 0x4b9b30,304 B;整个设置开关 +7 KB。 - 菜单项不能单独加,否则
SelectMenuPage每项固定+119+21 px,Device 区从 3 项变 4 项会明显撑长。最后并入「按键」子页,改名「按键与指示灯」,三行开关行高 119→90。
十、烧录:别信「假成功」
最终镜像与烧录结果:
StopWatch-UserDemo.bin binary size 0x4bac00 bytes.
Smallest app partition is 0x4f0000 bytes.
0x35400 bytes (4%) free.
Wrote 4959232 bytes (2389164 compressed) at 0x00020000 in 24.5 seconds (effective 1618.5 kbit/s)
Hash of data verified.
-- verify OK (digest matched)
三个坑:
idf.py flash的--after hard_reset对 USB-Serial-JTAG 无效,会停在 ROM(串口只出waiting for download)。改用--after watchdog_reset。- 这条 USB-JTAG 链路连续工作 60–70 秒必掉。
env/flash.sh因此按 512 KiB 分块、块间等 2 秒、掉线自动重试 8 次。 - 只
grep "Hash of data verified"会被部分输出骗过;必须用verify_flash回读校验。
十一、这次学到的
- 体积:官方槽只有 5.18 MB,CJK 全量字库根本放不下,只能走子集字体加
--gc-sections。 - 性能:撕裂是写入比扫描慢,调参调不掉;25 fps 是三件事叠出来的——缓冲放错了地方、每帧多余的失效、切换没有过渡。
- 稳定性:内部 RAM 很紧,LVGL 缓冲不能跟 Wi-Fi 抢;改了全局状态(自动回刷、背光、缓冲所在的内存池)就得自己还原。
- 调试:先在 Arduino 侧做最小复现,再搬进 IDF。颜色、花屏这种问题,第一反应经常是错的,得做对照实验。
- 烧录:打印「成功」不算数,要回读校验;镜像大就分块;连着刷十几次要给面板断电歇一歇。
最终仓库推送在自建 gogs:Serein-213/m5stack-stopwatch,commit 5efd058,475 files / 1,217,187 insertions。注意 3 个 vendored 组件自带 .git,提交前必须移除,否则 Git 只会存成空 submodule 指针。
