# M5StopWatch 个人定制固件 https://gitee.com/ftliang/M5StopWatch > 给 **M5Stack StopWatch（SKU C152）** 这块圆屏手表，写的一套**中文化、随手可用的课堂 / 实验室小工具**。 > 基于官方 [M5StopWatch-UserDemo](https://github.com/m5stack/M5StopWatch-UserDemo) 做个人定制开发，不是官方分支、不跟进上游。 > > **18 个实用 App**，全部真机烧录验证过；开源（AGPL-3.0 + 上游保留 MIT），可改可重刷。  > 上图是**渲染的设计稿，不是真机照片**：落款四行用系统比例字体代替固件里的 `montserrat_14`，宽度略有差异。重新生成：`python tools/gen_boot_screen_preview.py`（需 Pillow）。 --- ## 这是什么 - **硬件**：M5Stack StopWatch C152 — ESP32-S3R8 + 466×466 圆形 AMOLED + 旋钮/按键。 - **工具链**：ESP-IDF v5.5.4 + LVGL 9.5 + mooncake 应用框架。 - **当前版本**：v0.98。`0.x` 的含义是"还没经过真实掉电 / 长稳测试，也没有 OTA"——分区表里连 OTA 备用槽都删掉了。它是个**个人日常在用的增强固件**，不是商业固件。 --- ## 为什么值得刷（和官方 demo 的区别） 1. **彻底中文化**。官方 demo 大量英文 UI，本固件界面、菜单、提示全中文。 2. **真机实测驱动**。每个 App 都是烧进真机、在板上跑过才交付的；`tools/` 下 13 个校验脚本、约 1200 项断言随时可重跑。不交付"只编译通过"的东西。 3. **功能密度高**。18 个可用 App（计时 / 番茄 / 节拍 / 校音 / 水平仪 / 手电筒 / 录音 / 量子门演示 / 电子木鱼……），不是空壳。 4. **较真的细节**： - 电子木鱼的敲击声是**算出来的**（模态合成），不是采样； - 手电筒 SOS 严格按 ITU 1:3:1:3:7 时序； - 圆屏几何自动校验，元素不越圆、不重叠、中文字形不缺。 5. **防误触交互铁律**。不可逆动作（停止 / 清零 / 删除）只走**长按 A**，触屏对不可逆动作只选中不执行；可逆动作短按即可。 6. **开源可改**。AGPL-3.0 + 上游 MIT，代码随便改、随便重刷（见下方「许可」）。 --- ## 功能一览（18 个可用 App） 启动器、二级菜单「更多」、App 模板为框架性入口，不计入功能 App。 ### 一级（程序选择首页） | App | 说明 | |---|---| | **正计时** | 正计时，支持记圈 | | **倒计时** | 10 个预置档位 + 自定义滚轮；进度环随剩余比例青绿→琥珀→红渐变；归零三连音 + 振动 + 闪烁，支持 60 秒贪睡循环 | | **番茄钟** | 专注 / 短休 / 长休自动交替（每 4 个专注进长休）；阶段配色一眼分工作还是休息；上行 / 下行两种提示旋律 | | **节拍器** | 相位累加，刻度可调 | | **胸牌** | 会议用名牌，可切换图片；自带配网页（设备开 AP + HTTP 服务，浏览器里改） | | **表盘** | 3 款：上游数码大数字（Simple）+ 精简指针 2 款（运动 / 商务）；左右滑或按 B 换款 | | **录音机** | 录 WAV 到内部存储，可回放；在程序选择界面**按住 B 录、松手停**（按住 ≥0.5 秒触发，短按仍是切图标） | ### 二级「更多」 | App | 说明 | |---|---| | **校音器** | 实时音高检测 + 音名显示 | | **水平仪** | 双轴气泡水平仪，可标定零点 | | **手电筒** | 常亮 / 呼吸 / SOS / 频闪四种模式 | | **闹钟** | 每天固定时刻，或「之后 N 小时 M 分钟」一次性 | | **幸运转盘** | 抽签用 | | **讲课计时** | 分段计时（讲课 / 休息 / 问答…），到点自动进下一段 | | **噪音计** | 课堂音量表，可设基准做相对比较 | | **布洛赫球** | 量子门演示：触屏拖动旋转视角（伪 3D、按深度前后分色）、罗德里格旋转的态矢量动画 | | **电子木鱼** | 点一下响一声、功德 +1、随机弹一句；敲击声是模态合成算出来的 | | **设置** | 亮度 / 音量 / 按键 / 空闲退出 / 时间日期 / 固件信息 | | **U盘** | 把数据分区当 U 盘交给电脑 | --- ## 快速上手 ### 方式 A：自己构建烧录（当前唯一可用方式） 硬件要求：**M5Stack StopWatch C152（SKU C152）**。 ```bash python fetch_repos.py # 拉 9 个依赖组件（非 submodule） idf.py set-target esp32s3 idf.py build idf.py -p <COMx> flash monitor ``` Windows + 国内网络推荐用封装入口（处理国内镜像、`ar` 并发互斥锁等）： ```bash python tools/idf_run.py <工程根目录> build # 或 .\tools\idf.cmd build ``` > 新增 / 删除源文件后必须 `idf.py reconfigure`（`main/CMakeLists.txt` 用 `GLOB_RECURSE`，新文件不自动进构建）。本机两个硬坑见 [BUILD.md](BUILD.md)。 ### 方式 B：预编译固件（已提供） `v0.98` Release 已附带预编译 `StopWatch-UserDemo.bin`（合并镜像），下载后用 esptool 从 `0x0` 一键烧录： ```bash esptool.py --chip esp32s3 --port COMx --baud 921600 \ --before default_reset --after hard_reset \ write_flash -z --flash_mode dio --flash_freq 80m --flash_size 16MB \ 0x0 StopWatch-UserDemo.bin ``` > 下载地址：<https://gitee.com/ftliang/M5StopWatch/releases/tag/v0.98> > ⚠️ 固件**未开启 Secure Boot / Flash Encryption**（AGPL §6 反锁定），接收者可随时刷回自己改的版本。 对外发 `.bin` 已按 [LICENSING.md](LICENSING.md) 附上 LICENSE + 对应 tag（v0.98）。没装工具链走方式 B，想自己改走方式 A。 --- ## 给开发者 - **改代码前必看**：[docs/项目结构与维护说明.md](docs/项目结构与维护说明.md) —— 目录约定、新增 App 的 5 处注册点、交互铁律、校验脚本、已知待办。 - **全部文档索引**：[docs/README.md](docs/README.md)（硬件上手 / App 开发 / 专题方案 / 审查报告）。 - **校验脚本**：改完跑一遍 `tools/verify/*.py`，合计约 1200 项核验，全部带退出码可串成一行。 - **目录结构**：见现有仓库 `main/`（固件）、`tools/`（开发脚本）、`docs/`（文档）、`components/` + `managed_components/`（依赖）。 --- ## 许可 分层许可： | 范围 | 许可 | 文件 | |---|---|---| | **整体**（含编出的固件 `.bin`） | **AGPL-3.0-or-later** | [LICENSE-AGPL-3.0.txt](LICENSE-AGPL-3.0.txt) | | 派生自上游 `M5StopWatch-UserDemo` 的部分 | **MIT**（原样保留，不可移除） | [LICENSE](LICENSE) | MIT 原文明确含 `sublicense` 权利且无 copyleft，所以定制部分可合法改为 AGPL；MIT 唯一义务是保留声明，已逐字节照做。 **AGPL 两条真实约束（把设备 / 固件交给别人前必看）**： 1. **别在有交付的机器上开 Secure Boot / Flash Encryption** —— AGPL §6 反锁定条款要求不得阻止接收者刷入自己改的固件（当前两者均关闭，合规）。 2. **设备上跑着改过的固件、就得能拿到对应源码** —— AGPL §13：胸牌 App 的配网页由设备自开 AP + HTTP 服务，构成「远程网络交互」。**仓库需对公众可读**才满足；若改了固件却不公开对应源码即违规。 文件级划分、第三方组件逐项清单、交付二进制要带什么，见 [LICENSING.md](LICENSING.md)。本项目与 M5Stack 官方无隶属关系。 --- ## 署名 开发方式：**人给需求、设计与验收标准，AI 代理负责实现**。开机启动画面落款即此： ``` Designed by LIANG Futian Built with WorkBuddy Model DeepSeek-V4.1 Flash Verified by 13 check scripts ``` 作者位只在人，工具只用字段名（`Built with` / `Model` / `Assisted-by:`，不用 `by`）。理由与细节见 [docs/项目结构与维护说明.md](docs/项目结构与维护说明.md) §4.7。 --- ## 相关链接 - 本仓库：<https://gitee.com/ftliang/M5StopWatch> - 上游：<https://github.com/m5stack/M5StopWatch-UserDemo> - 文档索引：[docs/README.md](docs/README.md) - 许可与合规：[LICENSING.md](LICENSING.md) # M5StopWatch 个人定制固件 https://gitee.com/ftliang/M5StopWatch > 给 **M5Stack StopWatch（SKU C152）** 这块圆屏手表，写的一套**中文化、随手可用的课堂 / 实验室小工具**。 > 基于官方 [M5StopWatch-UserDemo](https://github.com/m5stack/M5StopWatch-UserDemo) 做个人定制开发，不是官方分支、不跟进上游。 > > **18 个实用 App**，全部真机烧录验证过；开源（AGPL-3.0 + 上游保留 MIT），可改可重刷。  > 上图是**渲染的设计稿，不是真机照片**：落款四行用系统比例字体代替固件里的 `montserrat_14`，宽度略有差异。重新生成：`python tools/gen_boot_screen_preview.py`（需 Pillow）。 --- ## 这是什么 - **硬件**：M5Stack StopWatch C152 — ESP32-S3R8 + 466×466 圆形 AMOLED + 旋钮/按键。 - **工具链**：ESP-IDF v5.5.4 + LVGL 9.5 + mooncake 应用框架。 - **当前版本**：v0.98。`0.x` 的含义是"还没经过真实掉电 / 长稳测试，也没有 OTA"——分区表里连 OTA 备用槽都删掉了。它是个**个人日常在用的增强固件**，不是商业固件。 --- ## 为什么值得刷（和官方 demo 的区别） 1. **彻底中文化**。官方 demo 大量英文 UI，本固件界面、菜单、提示全中文。 2. **真机实测驱动**。每个 App 都是烧进真机、在板上跑过才交付的；`tools/` 下 13 个校验脚本、约 1200 项断言随时可重跑。不交付"只编译通过"的东西。 3. **功能密度高**。18 个可用 App（计时 / 番茄 / 节拍 / 校音 / 水平仪 / 手电筒 / 录音 / 量子门演示 / 电子木鱼……），不是空壳。 4. **较真的细节**： - 电子木鱼的敲击声是**算出来的**（模态合成），不是采样； - 手电筒 SOS 严格按 ITU 1:3:1:3:7 时序； - 圆屏几何自动校验，元素不越圆、不重叠、中文字形不缺。 5. **防误触交互铁律**。不可逆动作（停止 / 清零 / 删除）只走**长按 A**，触屏对不可逆动作只选中不执行；可逆动作短按即可。 6. **开源可改**。AGPL-3.0 + 上游 MIT，代码随便改、随便重刷（见下方「许可」）。 --- ## 功能一览（18 个可用 App） 启动器、二级菜单「更多」、App 模板为框架性入口，不计入功能 App。 ### 一级（程序选择首页） | App | 说明 | |---|---| | **正计时** | 正计时，支持记圈 | | **倒计时** | 10 个预置档位 + 自定义滚轮；进度环随剩余比例青绿→琥珀→红渐变；归零三连音 + 振动 + 闪烁，支持 60 秒贪睡循环 | | **番茄钟** | 专注 / 短休 / 长休自动交替（每 4 个专注进长休）；阶段配色一眼分工作还是休息；上行 / 下行两种提示旋律 | | **节拍器** | 相位累加，刻度可调 | | **胸牌** | 会议用名牌，可切换图片；自带配网页（设备开 AP + HTTP 服务，浏览器里改） | | **表盘** | 3 款：上游数码大数字（Simple）+ 精简指针 2 款（运动 / 商务）；左右滑或按 B 换款 | | **录音机** | 录 WAV 到内部存储，可回放；在程序选择界面**按住 B 录、松手停**（按住 ≥0.5 秒触发，短按仍是切图标） | ### 二级「更多」 | App | 说明 | |---|---| | **校音器** | 实时音高检测 + 音名显示 | | **水平仪** | 双轴气泡水平仪，可标定零点 | | **手电筒** | 常亮 / 呼吸 / SOS / 频闪四种模式 | | **闹钟** | 每天固定时刻，或「之后 N 小时 M 分钟」一次性 | | **幸运转盘** | 抽签用 | | **讲课计时** | 分段计时（讲课 / 休息 / 问答…），到点自动进下一段 | | **噪音计** | 课堂音量表，可设基准做相对比较 | | **布洛赫球** | 量子门演示：触屏拖动旋转视角（伪 3D、按深度前后分色）、罗德里格旋转的态矢量动画 | | **电子木鱼** | 点一下响一声、功德 +1、随机弹一句；敲击声是模态合成算出来的 | | **设置** | 亮度 / 音量 / 按键 / 空闲退出 / 时间日期 / 固件信息 | | **U盘** | 把数据分区当 U 盘交给电脑 | --- ## 快速上手 ### 方式 A：自己构建烧录（当前唯一可用方式） 硬件要求：**M5Stack StopWatch C152（SKU C152）**。 ```bash python fetch_repos.py # 拉 9 个依赖组件（非 submodule） idf.py set-target esp32s3 idf.py build idf.py -p <COMx> flash monitor ``` Windows + 国内网络推荐用封装入口（处理国内镜像、`ar` 并发互斥锁等）： ```bash python tools/idf_run.py <工程根目录> build # 或 .\tools\idf.cmd build ``` > 新增 / 删除源文件后必须 `idf.py reconfigure`（`main/CMakeLists.txt` 用 `GLOB_RECURSE`，新文件不自动进构建）。本机两个硬坑见 [BUILD.md](BUILD.md)。 ### 方式 B：预编译固件（已提供） `v0.98` Release 已附带预编译 `StopWatch-UserDemo.bin`（合并镜像），下载后用 esptool 从 `0x0` 一键烧录： ```bash esptool.py --chip esp32s3 --port COMx --baud 921600 \ --before default_reset --after hard_reset \ write_flash -z --flash_mode dio --flash_freq 80m --flash_size 16MB \ 0x0 StopWatch-UserDemo.bin ``` > 下载地址：<https://gitee.com/ftliang/M5StopWatch/releases/tag/v0.98> > ⚠️ 固件**未开启 Secure Boot / Flash Encryption**（AGPL §6 反锁定），接收者可随时刷回自己改的版本。 对外发 `.bin` 已按 [LICENSING.md](LICENSING.md) 附上 LICENSE + 对应 tag（v0.98）。没装工具链走方式 B，想自己改走方式 A。 --- ## 给开发者 - **改代码前必看**：[docs/项目结构与维护说明.md](docs/项目结构与维护说明.md) —— 目录约定、新增 App 的 5 处注册点、交互铁律、校验脚本、已知待办。 - **全部文档索引**：[docs/README.md](docs/README.md)（硬件上手 / App 开发 / 专题方案 / 审查报告）。 - **校验脚本**：改完跑一遍 `tools/verify/*.py`，合计约 1200 项核验，全部带退出码可串成一行。 - **目录结构**：见现有仓库 `main/`（固件）、`tools/`（开发脚本）、`docs/`（文档）、`components/` + `managed_components/`（依赖）。 --- ## 许可 分层许可： | 范围 | 许可 | 文件 | |---|---|---| | **整体**（含编出的固件 `.bin`） | **AGPL-3.0-or-later** | [LICENSE-AGPL-3.0.txt](LICENSE-AGPL-3.0.txt) | | 派生自上游 `M5StopWatch-UserDemo` 的部分 | **MIT**（原样保留，不可移除） | [LICENSE](LICENSE) | MIT 原文明确含 `sublicense` 权利且无 copyleft，所以定制部分可合法改为 AGPL；MIT 唯一义务是保留声明，已逐字节照做。 **AGPL 两条真实约束（把设备 / 固件交给别人前必看）**： 1. **别在有交付的机器上开 Secure Boot / Flash Encryption** —— AGPL §6 反锁定条款要求不得阻止接收者刷入自己改的固件（当前两者均关闭，合规）。 2. **设备上跑着改过的固件、就得能拿到对应源码** —— AGPL §13：胸牌 App 的配网页由设备自开 AP + HTTP 服务，构成「远程网络交互」。**仓库需对公众可读**才满足；若改了固件却不公开对应源码即违规。 文件级划分、第三方组件逐项清单、交付二进制要带什么，见 [LICENSING.md](LICENSING.md)。本项目与 M5Stack 官方无隶属关系。 --- ## 署名 开发方式：**人给需求、设计与验收标准，AI 代理负责实现**。开机启动画面落款即此： ``` Designed by LIANG Futian Built with WorkBuddy Model DeepSeek-V4.1 Flash Verified by 13 check scripts ``` 作者位只在人，工具只用字段名（`Built with` / `Model` / `Assisted-by:`，不用 `by`）。理由与细节见 [docs/项目结构与维护说明.md](docs/项目结构与维护说明.md) §4.7。 --- ## 相关链接 - 本仓库：<https://gitee.com/ftliang/M5StopWatch> - 上游：<https://github.com/m5stack/M5StopWatch-UserDemo> - 文档索引：[docs/README.md](docs/README.md) - 许可与合规：[LICENSING.md](LICENSING.md) Last modification：September 22, 2026 © Allow specification reprint Support Appreciate the author AliPayWeChat Like 送杯咖啡，做个交流，谢谢！
