utsabfdahal/band10-toolkit

# Band 10 工具包 [](https://github.com/utsabfdahal/band10-toolkit/actions/workflows/ci.yml) [](LICENSE) [](https://nodejs.org) [](tsconfig.json) 一个开源优先的开发工作流，用于自定义 **Xiaomi Smart Band 10** (`o66`) 表盘。 设计资源，在 JSON 中描述 widget，进行验证，在 React/SVG 中实时预览，生成可编辑的 FPRJ/GMF 项目，打包逆向工程的 `.face`/`.bin`，检查并将其部署以进行人工确认的 Android 安装。  | Active face | Always-on display | |---|---| |  |  | ## 快速开始（构建并打开模拟器） 一切均在本地运行。您只需要 **Node.js 22+** 和 **git**。 **1. 克隆仓库并安装依赖** ``` git clone https://github.com/utsabfdahal/band10-toolkit.git cd band10-toolkit npm install ``` **2. 生成示例表盘的源图稿** ``` npm run generate:assets ``` **3. 打开实时模拟器（React/SVG 表盘工作室）** ``` npm run preview ``` 这将启动工作室的开发服务器。在浏览器中打开它输出的 URL（默认为 **http://localhost:5173**），即可看到以真实的 Band 10 分辨率（212×520）渲染的表盘， 其中包含拖放、图层检查器、实时 JSON 编辑和数据模拟器功能。在终端中按 `Ctrl+C` 可停止运行。 **4. 构建、验证并打包 `.face`（可选）** ``` npm run validate # schema, coordinates, storage, capability checks npm run build:example # render preview + FPRJ/GMF intermediates npm run package # write the .face / .bin package npm run inspect # print headers, resources, and bindings ``` 打包后的文件将存放在 `examples/minimal-amoled/dist/` 中。 ### 预览其他表盘 每个设计都有自己的 `preview` 脚本，用于生成其资源并打开 相同的模拟器： ``` npm run preview:flux # Flux Core electronics face npm run preview:backend # utsab.json developer face npm run preview:rlc # RLC Singularity animated circuit npm run preview:circuit # Circuit Link reactor npm run preview:odyssey # Odyssey landscape video loop ``` ## Flux Core 电子设计 [`examples/flux-core`](examples/flux-core) 表盘是一款简洁的电子主题设计，带有铜色/青色 PCB 数字、一个 `L1 / 47uH` 电感模块、磁场走线、示波器遥测数据和克制的 AOD。支持碰撞检测的验证报告显示没有剪裁或重叠，并且该布局未使用任何 `allowOverlap` 例外。 | Active display | Always-on display | |---|---| |  |  | ``` npm run generate:flux npm run validate:flux npm run build:flux npm run package:flux npm run inspect:flux npm run preview:flux ``` ## 特色设计 使用此工具包构建的源优先表盘画廊。每个像素都是 通过脚本 + `layout.json` 确定性生成的——无需二进制编辑器。 ### `utsab.json` — 开发者 / JSON 调试器 在纯黑 AMOLED 屏幕上以语法高亮、格式化的 JSON 视图显示当天的状态：粗体等宽时钟、英文日期、带有 Devanagari 键的**尼泊尔历**日期行、步数、电池，以及装饰性的 `status: 200 OK` / `env: production` 元数据。键为青色，字符串为绿色，数字为橙色，标点符号为灰色——就像手腕上的实时 API 响应一样。 | Active display | Always-on display | |---|---| |  |  | ``` npm run generate:backend npm run validate:backend npm run package:backend npm run preview:backend ``` ### RLC Singularity — 动画谐振电路 一个自我合成的串联 **R–L–C** 电路：电阻器成型，电感器产生磁场，电容器锁定电荷，回路点燃形成旋转的谐振核心。60 ms 的 48 帧索引彩色动画，包含英文 + 尼泊尔日期的月/日、步数和电池，并带有平静的静态 AOD。 | Active display | Always-on display | |---|---| |  |  | ``` npm run generate:rlc npm run validate:rlc npm run package:rlc npm run preview:rlc ``` ### Circuit Link (VOID-LINK) — 自组装反应堆 一段“超凡脱俗”的点火序列：八条电路走线向内拉进，粒子汇聚，双层字形环反向旋转，核心引爆两次冲击波，随后链接坍缩回休眠的种子状态。48 帧不透明的索引彩色图像，播放间隔 60 ms，无缝循环。 | Active display | Always-on display | |---|---| |  |  | ``` npm run generate:circuit npm run validate:circuit npm run package:circuit npm run preview:circuit ``` ## 包含的内容 - 适用于 `5A A5 34 12` 现代 Xiaomi 二进制文件的边界安全解析器； - 原生调色板/BGRA 图像块及 RLE v1/v2 编解码器； - 带有错误代码的语义化资源/坐标/存储验证器； - 规范的 `manifest.json` + `layout.json` schema； - FPRJ XML 和 GMF `wfDef.json` 导出器； - 实验性开源 `o66` 二进制打包器，支持 active + AOD； - 闭源编译器和社区 Java 适配器（不重新分发二进制文件）； - React 19 + SVG 桌面预览工作室； - 直接拖放、图层检查器、实时 JSON 和数据模拟； - 确定性源资产生成和 212×520 预览渲染； - 完整的极简 AMOLED 示例，包含时间、日期、电池、步数、心率、天气、进度和 AOD； - 简洁的 Flux Core 电子/电感表盘，包含经过碰撞测试的 active 和 AOD 布局； - 安全的 ADB 部署和可选的 Gadgetbridge 确认 UI 启动； - 研究报告、格式说明、项目目录、架构图以及安装/发布指南； - 30 个自动化单元/集成测试。 ## 快速开始 要求：Node.js 22+ 和 npm。 ``` npm install npm run generate:assets npm run validate npm run build:example npm run package npm run inspect npm run preview ``` 示例包出现在： ``` examples/minimal-amoled/dist/carbon-signal.face examples/minimal-amoled/dist/carbon-signal.bin ``` 这两个文件是字节完全相同的扩展名别名。 ## 项目格式 ``` my-face/ ├── manifest.json ├── layout.json └── assets/ ├── digits/ ├── icons/ └── weather/ ``` 从 [`templates/basic`](templates/basic)、[`examples/minimal-amoled`](examples/minimal-amoled) 或简洁的电子主题表盘 [`examples/flux-core`](examples/flux-core) 开始。 该 schema 使用有意义的源名称，例如 `battery`、`steps` 和 `heartRate`；导出器会将它们映射到已恢复的 Band 10 ID（`0841`、`0821`、`0822` 等）。 ## 命令 | 命令 | 用途 | |---|---| | `band10 validate ` | schema、资源、坐标、尺寸、存储、容量警告 | | `band10 assets ` | 将源图稿标准化为确定性 PNG | | `band10 build ` | 渲染预览并写入 FPRJ + GMF 中间文件 | | `band10 package ` | 使用选定的后端打包 `.face` + `.bin` | | `band10 inspect ` | 打印头、节、资源、坐标和绑定 | | `band10 preview ` | 同步项目并运行 React 工作室 | | `band10 clean ` | 删除 `build/` 和 `dist/` | | `band10 install ` | 通过 ADB 部署到 Android；可选启动 Gadgetbridge 确认 | 通过 npm 使用： ``` npm run band10 -- validate path/to/project ``` 可通过 `validate --json` 和 `inspect --json` 获取机器可读的输出。 ## 打包后端 | 目标 | 开放性 | 当前可信度 | |---|---|---| | `native` | 本仓库中的 MIT 代码 | 结构/资源可往返；物理安装未经核实 | | `mi-create` | 适配器开源；编译器闭源/用户提供 | 社区生产路径；需要 Windows/Wine | | `mi8-tool` | 适配器开源；外部 Java 源无许可证 | 实验性；已知在有效样本上会出现解析器故障 | 不会隐式下载或执行任何专有内容。 ## 已验证的本地结果 在此次 macOS 开发会话中： - 严格的 TypeScript：CLI/core 和 React 均通过； - ESLint：通过； - 测试：**30/30 通过**； - 生产环境预览：224.63 kB JS（69.06 kB gzip），15.09 kB CSS（4.15 kB gzip）； - 示例：41 个源资源，21 个 widget，active + AOD； - 包：53,056 字节（约 51.8 KiB）； - 解码后的包：212×520 预览，8 个单一图像，7 个图像列表，216,648 像素； - 解析器警告：零； - 16 个动态 widget 绑定在两个表盘上均被正确解码。 - Flux Core：76 个资源，33 个 widget，零验证问题，24 个 active + 9 个 AOD 元素，100.9 KiB 包。 这些是构建/测试指标，并非 Band 电池/运行时性能的声明。 ## 研究结论 - `.face` 和 `.bin` 通常包含相同的原始二进制文件，而不是 ZIP 档案。 - 所检查的 Band 10 表盘的 runtime magic 为 `5A A5 34 12`； - runtime 二进制文件未进行全文件加密；图像可能经过调色板/RLE 压缩； - 创作通常使用 `.fprj` XML 或 `wfDef.json`； - AOD 是独立的表盘内容/资源； - 常规排版是光栅化的字形精灵，而不是嵌入的创作字体； - Xiaomi 官方记录了 212×520、AOD、大约 20 MB 的表盘存储空间以及最多九个下载的表盘； - Xiaomi 未公开底层的 Band 10 runtime 格式或开放的全局完整表盘提交路径。 在依赖格式细节之前，请阅读[完整的研究报告](docs/research.md)。 ## 文档 - [研究：所有十二个问题及主要来源](docs/research.md) - [二进制格式](docs/format.md) - [开源项目概览](docs/open-source.md) - [端到端工作流](docs/workflow.md) - [架构和图表](docs/architecture.md) - [创作、widget、字体、天气、进度、动画、AOD](docs/authoring.md) - [构建、安装、安全、发布](docs/installation.md) - [已知限制](docs/limitations.md) ## 安装警告 在 Gadgetbridge/Notify 中打开包仍然会跨越硬件风险边界。确认型号/分辨率并保留手动安装确认。格式不正确的包可能会导致表盘子系统崩溃，并可能需要重置/恢复。本项目与 Xiaomi 没有任何隶属关系。 ## 许可证 工具包源代码采用 MIT 许可。第三方项目、编译器、示例和图稿保留其各自的许可证。没有许可证意味着没有复用许可——而不是“可以免费复制”。

标签：JSON, React, Syscalls, 前端开发工具, 小米手环, 智能穿戴, 物联网开发, 自动化攻击, 表盘定制