技术

M5Stack StopWatch 固件魔改全记录:Avatar、TamaPoke、TE 同步与 4% 的余量

目录
  1. 一、起点:一块手表和三个「不可能」
  2. 二、先把硬件基线钉住
  3. 三、移植策略:先用 Arduino 验证,再进 IDF
  4. 四、TE 帧同步:11.5 ms → 0.24 ms
  5. 五、25 fps 的「生硬」是怎么来的
  6. 六、三个「看起来是玄学」的 Bug
    1. 6.1 Avatar 一打开就黑屏
    2. 6.2 打开任何应用都闪一下
    3. 6.3 Badge 选 Edit 就重启
  7. 七、颜色翻车:一次被自己推翻的假设
  8. 八、中文化:只能走子集字体
  9. 九、关掉开机绿灯
  10. 十、烧录:别信「假成功」
  11. 十一、这次学到的

设备: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:esp32 3.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 真机

一、起点:一块手表和三个「不可能」

M5Stack StopWatch 官方固件(UserDemo V0.5,cf51acc,ESP-IDF v5.5.4)本身是完整的:Launcher、设置、秒表、Wi-Fi、Badge 配置页都有。但它有两个硬限制:

  1. 没有垂直同步。waitDisplay() 只等 QSPI 总线空闲,displayBusy() 恒为 false,TE 引脚(G38)只被设成上拉输入,代码从不读。整屏一动就撕裂。
  2. 应用槽位是固定的。想加自己的应用,要么改 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

三个独立原因叠在一起:

  1. 缓冲位置不对。LVGL 用部分缓冲,每块 466×120 = 56,160 B,两块都在 PSRAM。
  2. 每帧无条件失效。DynamicIconLabel::update() 每帧都调 _label->setOpa(...),即使值没变也触发 invalidate。
  3. 没有过渡。图标没有边缘淡出,页面切换是硬切。

修法对应三条:

  • 双缓冲改为一块内部 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 面板/供电轨进入坏状态(推断,非确证)。

那次花屏的恢复流程实测有效,一次就好:

  1. 拔掉 USB-C;
  2. 快速连按两次电源键关机(屏幕熄灭);
  3. 等 3 秒,短按一次电源键开机;
  4. 再插 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)

三个坑:

  1. idf.py flash 的 --after hard_reset 对 USB-Serial-JTAG 无效,会停在 ROM(串口只出 waiting for download)。改用 --after watchdog_reset。
  2. 这条 USB-JTAG 链路连续工作 60–70 秒必掉。env/flash.sh 因此按 512 KiB 分块、块间等 2 秒、掉线自动重试 8 次。
  3. 只 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 指针。

自绘 Guruguru 头像素材,9 方向 + 眨眼