Initial Commit

.gitattributes

@@ -0,0 +1,11 @@
+# 文本按 LF 存，二进制一律别碰（.bin/.face 被转换就会损坏负载）
+* text=auto eol=lf
+*.py   text eol=lf
+*.lua  text eol=lf
+*.md   text eol=lf
+*.sh   text eol=lf
+*.json text eol=lf
+*.bin  -text
+*.face -text
+*.png  -text
+*.ttf  -text

.gitignore

@@ -0,0 +1,26 @@
+# ==== 体积大 / 有版权 / 可再生成的东西，不进仓库 ====
+
+# 固件分区镜像 + 字体（版权属小米；从官方 OTA 包 / vela_font.bin 自行获取）
+**/inputs/**/*.bin
+**/inputs/fonts/
+**/inputs/**/*.ttf
+**/inputs/**/*.otf
+
+# 第三方编译器（含 Compiler.exe；自行从 GitHub 取）
+**/vendor/LuaDevTemplate-main/
+
+# 构建中间产物
+**/.work/
+**/__pycache__/
+*.pyc
+
+# 逐条负载（可由 make_dd_payload.py / s5e_payload.py 重新生成）
+**/payload/*.bin
+**/payload_rollback/*.bin
+**/payload.json
+
+# 编辑器 / 系统垃圾
+.vscode/
+.idea/
+Thumbs.db
+desktop.ini

README.md

@@ -1,3 +1,138 @@
-# o62lte-customising-plan
+# 小米手表 系统图标修改器（Lua 表盘）
 
-Xiaomi Watch S4 eSIM 系统个性化项目
+两个互相独立的项目，同一套机制：**用一个 Lua 表盘把系统应用图标「等长原地覆盖」进 ROMFS 资源分区**，重启生效；界面里带只读预检查、写入进度和一键回滚。
+
+| 项目 | 目标机型 | 屏幕 | 写入分区 | 主交付物 |
+|---|---|---|---|---|
+| [`s4e-icons/`](s4e-icons/) | Xiaomi Watch S4 eSIM（o62lte, 3.202.79） | 466×466 | `/dev/app` | `dist/S5Icons.face` |
+| [`s5e-icons/`](s5e-icons/) | Xiaomi Watch S5 eSIM 46mm（p62lte, 3.112.035） | 480×480 | `/dev/app` + `/dev/health` | `dist/S5eIcons.face` |
+
+两个项目的**图标来源都是 Xiaomi Watch S5 41mm（q63, v4.101.020）的 OS4 图标包**。
+
+每个项目内部结构：
+
+```
+README.md        项目说明（交付物 / 装法 / 边界）
+main.lua         表盘源码（含 __PAY__ / __RB__ / __UIIMG__ 占位符，构建时回填）
+tools/           全部 Python 脚本（ROMFS 解析、LVGL 编解码、负载生成、两遍构建、独立校验）
+assets/          设计素材；assets/override/ 里的自制 PNG 优先级高于固件来源
+inputs/          固件分区镜像（**要自己放，不进仓库**）
+vendor/          第三方 LuaDevTemplate-main（含 Compiler.exe，**不进仓库**）
+.work/           构建工作区（产物，可删）
+dist/            交付的 .face
+docs/            说明、分析报告、预览图
+```
+
+---
+
+## 跑起来（全部在 `icon-editors/` 目录内完成）
+
+前置：**Python 3 + Pillow**（`pip install pillow`）。
+
+### 1) 放 `inputs/`（固件分区镜像）
+
+官方 OTA 包（ZIP）里的 `vela_*.bin` 条目，解压后按下面的名字放（`ota.sh`、`CERT.*`、`MANIFEST.MF` 不需要）：
+
+| 路径 | 是什么 | 字节 | sha256 前 16 |
+|---|---|---:|---|
+| `s4e-icons/inputs/target/vela_app.bin` | S4 eSIM 的 app 分区 | 265,684,992 | `caa66693f49477dd` |
+| `s4e-icons/inputs/source/vela_app.bin` | S5 41mm q63 的 app 分区 | 206,000,128 | `161a8f7a5f0bd8af` |
+| `s4e-icons/inputs/source/vela_health.bin` | q63 的 health 分区 | 233,939,968 | `12a3bd2f8b62e969` |
+| `s5e-icons/inputs/target/vela_app.bin` | S5 eSIM 的 app 分区 | 103,043,072 | `9b41c5f5eb17c112` |
+| `s5e-icons/inputs/target/vela_health.bin` | S5 eSIM 的 health 分区 | 206,924,800 | `489752c8a3fb24ff` |
+| `s5e-icons/inputs/source/*` | 与 s4e 的 `source/` 是同一份 q63 镜像 | | |
+
+### 2) 放 `vendor/`（第三方编译器）
+
+把 [FangAiden/LuaDevTemplate](https://github.com/FangAiden/LuaDevTemplate) 解压成
+`<项目>/vendor/LuaDevTemplate-main/`（里面必须有 `watchface/tools/Compiler.exe`）。
+两个项目各一份。没有它只能生成负载，不能编译 `.face`。
+
+（本项目本来也支持 `ICON_EDIT_VENDOR=<目录>` 指向别处的模板，路径定义集中在
+`tools/paths.py`，可用 `ICON_EDIT_INPUTS / ICON_EDIT_VENDOR / ICON_EDIT_WORK / ICON_EDIT_DIST` 覆盖。）
+
+### 3) 构建
+
+```powershell
+cd icon-editors/s4e-icons
+python tools/make_s5_to_s4_inset.py    # q63 素材 -> S4 槽位（含尺寸归一化、格式转换、I8 调色板复用）
+python tools/make_dd_payload.py        # 逐条负载 + 回滚负载 + flash.sh / rollback.sh + payload.json
+python tools/gen_ui_lua.py             # 两遍构建 -> dist/S5Icons.face（回填偏移，断言 0 漂移）
+python tools/s4e_verify.py             # 独立校验（不复用构建代码，建议每次跑）
+
+cd ../s5e-icons
+python tools/s5e_payload.py            # q63 素材 -> S5e 槽位
+python tools/s5e_build.py              # -> dist/S5eIcons.face
+python tools/s5e_verify.py             # 独立校验
+```
+
+### 4) 内容开关
+
+默认打进表盘的是「应用图标 + 控制中心顶栏状态 + 系统 UI + 通知 / 电话 / 录音机 / 计时器 / 待办」。
+下面两组**默认关闭**：
+
+| 环境变量 | 作用 |
+|---|---|
+| `ICON_MIJIA=1` | 控制中心里的米家 / 融合中心设备图标（实测目标机本来就装了同一个米家表 App，129 张设备图标里 128 张与 q63 逐字节相同，一般不需要） |
+| `ICON_WALKIE=1` | 对讲机素材 `walkie_talkie/**`（160 条；S5 41mm 没有这个 App，素材来自用户提供的 PNG） |
+| `ICON_SKIP_WALKIE=1` / `ICON_ONLY_WALKIE=1` | 要分组出表盘时用（一个大表盘拆两张） |
+
+---
+
+## 为什么必须等长
+
+ROMFS 把 inode、文件名、文件数据首尾相接顺序排布，所有 `next` / `spec` 都是**绝对偏移**。替换文件只要长度差一个字节，它后面所有文件的偏移就整体平移 —— 轻则图标错乱，重则资源分区损坏。
+
+所以两个项目都保证 **每条负载的长度 == 原槽位长度**，只动数据、不碰 inode 表 / superblock / 目录项。
+
+## 表盘到底做了什么
+
+Lua 表盘不能「设置图标」。系统图标住在 ROMFS 分区镜像里，必须写分区 + 重启。表盘只做运载 + 执行：
+
+```
+每条记录三步（只用官方存在的 dd，判据全看内容，不看 os.execute 的返回值 —— 它不可靠）：
+  1 对版   读出设备上该偏移处 64 字节，与「原厂字节」或「替换后字节」比对
+           两者都不是 -> 判「版本不符」，该分区剩余记录全部跳过（绝不往别人的文件里写）
+  2 写入   dd if=/tmp/xxx of=<分区> bs=4 seek=<偏移/4> count=<长度/4>
+  3 回读   整段读回来逐字节比对
+
+回滚 = 同一套流程，只是写入的字节换成原厂字节
+最后 sync + reboot（ROMFS 是只读挂载 + 有页缓存，不重启看不到新图标）
+```
+
+偏移都在**构建时两遍测量回填**：先编一遍，在 .face 里搜负载定位，量出真实偏移写回 Lua，再编第二遍并逐条校验 0 漂移。
+
+## 只安装、不重建
+
+直接拿 `s4e-icons/dist/S5Icons.face` 或 `s5e-icons/dist/S5eIcons.face`，和普通 Lua 表盘一样安装（`resource.bin` 推到 `/data/app/watchface/market/<id>/`）。装到手表后在表盘上操作：
+
+```
+首页 →「快速帮助」→「环境预检查」   只读，一个字节都不写
+首页 →「开始替换」→ 确认 → 自动写入 → 「重启手表」
+       快速帮助 →「回滚修改」→ 确认 → 写回原厂图标
+```
+
+**环境预检查是只读的**，它只能证明「两个分区可读 + 抽样偏移对版」，证明不了「可写」；但写入路径每条都自带对版 + 回读校验，最坏结果是「图标没变」，不会把分区写坏。
+
+## 已知边界
+
+1. **偏移锁固件版本**：ROMFS 绝对偏移排布，换固件版本必须拿新镜像重跑，旧偏移会写错位置。
+2. **等长是硬要求**：长度不等会让后面所有偏移平移；脚本对每条断言长度相等。
+3. **I8 槽位**必须复用源图调色板，否则边缘锯齿 + 彩点。
+4. **真机能力**：`os.execute` / `dd` 可用；`io.popen` 捕获不到输出；`os.execute` 返回值不可靠（成功也可能是 65280），判据一律看内容读回。
+5. 首次请只点「环境预检查」，看清输出再替换。
+
+## 仓库里没有的东西（体积 / 版权）
+
+| 不含 | 原因 | 怎么补 |
+|---|---|---|
+| `inputs/**/*.bin`（固件分区镜像） | 体积 + 版权 | 从官方 OTA 包解包，见上表 |
+| `inputs/fonts/*.ttf`（MiSans） | 版权属小米 | 从固件 `vela_font.bin` 取；没有只影响预览图 |
+| `vendor/LuaDevTemplate-main/` | 第三方 | 从 GitHub 取，见上 |
+
+## 第三方与法律
+
+- `.face` 由 [FangAiden/LuaDevTemplate](https://github.com/FangAiden/LuaDevTemplate) 的 `Compiler.exe` 编译；本仓库不含它，请自行放到 `vendor/LuaDevTemplate-main/`
+- MiSans 字体版权属小米；本仓库不含字体文件，需要时从固件 `vela_font.bin` 里取
+- 固件 / OTA 版权属小米，请从官方更新包里自行解包
+- **改系统分区有风险**：写错偏移可能损坏资源分区。两个项目都自带版本校验和回滚，但请自行确认设备所有权并承担后果

s4e-charge/.gitignore

@@ -0,0 +1,10 @@
+# 大文件 / 中间产物：不进仓库
+.work/
+inputs/
+vendor/
+__pycache__/
+*.pyc
+payload/
+payload_restore/
+blob_replace/
+blob_restore/

s4e-charge/README.md

@@ -0,0 +1,71 @@
+# S4Chg —— 把 S5 41mm(q63) 的充电动画搬到 S4 eSIM
+
+**当前阶段：全量版已交付（57 帧全换）** —— 轻量测试（5 帧）已在真机确认生效：**`/dev/system` 可写 + 动画确实取自这 57 帧**。
+
+## 改了什么
+
+| | |
+|---|---|
+| 目标 | `inputs/target/vela_system.bin`（S4 eSIM `/dev/system`）→ `charging/charge0..56.bin`（57 帧 464×464 I8 RLE） |
+| 源 | `inputs/source/vela_system.bin`（q63 S5 41mm）→ `charging/charge0..60.bin`（61 帧） |
+| 映射 | 第 n 帧 ← q63 第 `round(n/56*60)` 帧（时间轴按比例映射） |
+| 本次 | **57/57 全换**，**每帧都是 256 色**（槽位 79~119 KB 很宽裕；背景压平后 RLE 完全放得下） |
+| 校验 | 57/57 回解逐像素一致、usize 长度一致、inode 表逐位不变、superblock 不变、回放一致 |
+
+## 交付物
+
+| 文件 | 说明 |
+|---|---|
+| `dist/S4Chg.face` | **替换盘**：6,422,844 B（6.1 MB），id `362150103`，b5=0，sha256 `687f600df38597e8…` |
+| `dist/S4ChgRestore.face` | **还原盘**：同 id，sha256 `a243fb4734913280…`（装上即还原，也用来顶掉替换盘） |
+| `docs/full_before_after.png` | 全量对照图（原厂 vs q63，采样 10 帧） |
+| `docs/full_preview.mp4` | 换后整段 57 帧预览 |
+| `docs/sample_before_after.png` / `sample_preview.mp4` | 轻量测试阶段（5 帧）的留档 |
+
+## 真机怎么做
+
+1. 装 `dist/S4Chg.face`（同 id 会自动顶掉测试盘）
+2. 表盘「环境预检查」→「开始替换」→ 等 `失败 0`（57 条，约 6 MB；失败会打印 `> 失败 #N off=0x… len=… 首差@i 得AA期BB`）
+3. 「重启手表」→ 插上充电器看整段动画
+4. 还原：装 `dist/S4ChgRestore.face` →「开始还原」→ 重启
+
+## 重建
+
+```powershell
+python tools/make_charge_payload.py all    # 全量 57 帧（不加 all = 只改 5 帧的轻量测试）
+python tools/make_dd_payload.py replace    # 负载 + 指纹 + blob_replace/
+python tools/gen_ui_lua.py replace         # 两遍构建 -> dist/S4Chg.face（0 漂移校验）
+python tools/verify_anim.py replace        # 独立校验（只看交付物 + 原厂镜像）
+python tools/make_dd_payload.py restore
+python tools/gen_ui_lua.py restore         # -> dist/S4ChgRestore.face
+python tools/verify_anim.py restore
+```
+
+`inputs/`（固件分区镜像）与 `vendor/`（LuaDevTemplate，含 Compiler.exe）不进仓库；`payload*/`、`blob_*/`、`.work/` 是可再生产物。
+
+## 备注
+
+- 本盘写的是 **`/dev/system`**（系统资源分区）：轻量测试证明它可 dd 写入，这是本轮最重要的发现 —— 以后 `system/drain/*`（排水）、`ota/anim*`（升级动画）、`setupwizard/*`（配对引导）都能用同一套办法改。
+- ROMFS 的数据偏移是**结构性**的（`data_off = inode + 16 + align16(名字长度+1)`），所以只能逐帧等长覆盖，不能把数据指到别处、也不能跨分区。
+
+# 编码 v2（2026-10-02）：画质问题的根因与修法
+
+真机反馈「有点糊」。诊断后发现是**编码器**的问题，不是素材上限：
+
+| | 旧方案 | 新方案 |
+|---|---|---|
+| 做法 | 整帧重新量化（MEDIANCUT 256 色）+ 把暗于 46 的像素压成纯黑 | **沿用 q63 原帧的调色板与索引**，只把接近黑的暗区归到一个索引，阈值按每帧预算取最小值（实测 4~40） |
+| 圆环 | 亮部面积小，MEDIANCUT 按像素数分配颜色 → 圆环分不到颜色；阈值 46 还把环上的暗段啃成黑色缺口 | **逐像素与原帧完全一致** |
+| 整帧 PSNR（57 帧） | 25.1 dB（最差 24.0） | **33.4 dB（最差 25.2）** |
+| 接近黑区域均差 | 8.56 | 6.46 |
+
+对照图见 docs/quality_v1_vs_v2.png（整帧 / 局部 2× / 与 q63 原帧的差异 ×4）。
+
+**天花板在哪**：圆环已经到顶（逐像素一致，除非改尺寸或格式）；雾面暗区受**槽位字节预算**限制 —— q63 原帧是 135~201 KB/帧，S4e 槽位只有 79~119 KB，而暗区是噪点雾面、最吃 RLE。要连暗区也几乎无损，需要把 57 个槽位当总池重新分配，但总池 5.7 MB < 源 10.6 MB，仍然要取舍。
+
+| 盘 | v2 体积 / sha256 | 校验 |
+|---|---|---|
+| dist/S4Chg.face | 6,422,844 B / 66640d3a869bbc29… | 11/11 通过 + 自检 57/57 |
+| dist/S4ChgRestore.face | 6,422,844 B / 9652747f3c79402f… | 11/11 通过 |
+
+**若之前装过 v1 全量版**（sha 687f600d…）：设备上是旧编码的帧，新盘替换时会提示「版本不符」（指纹表记的是**原厂**字节），但**它会照写**（版本不符只提示不阻止），写完重启即为 v2 画质。