小米手环Web控制程序

基于WebAssembly的Web控制界面，用于管理小米手环设备。 wasm模块基于开源项目Astrobox-NG 网页端https://mibandinstall.0pen.top/

功能特性

• 🚀 设备连接管理：支持SPP/BLE连接小米手环
• 📊 设备信息展示：实时显示设备状态、电池、存储等信息
• 🎨 表盘管理：查看、设置、卸载表盘
• 📱 应用管理：管理第三方应用（安装、启动、卸载）
• 📁 文件安装：支持安装表盘文件(.bin)、固件(.bin)、快应用(.rpk)
• 🔄 实时进度：文件安装进度实时显示
• 📝 操作日志：完整的操作记录和状态反馈
• ⚛️ 现代化UI：基于React的响应式界面

技术架构

• 前端：React 18 + TypeScript + Tailwind CSS + Vite
• WASM模块：Rust编译的WebAssembly模块（浏览器直接调用）
• 构建工具：Vite（快速开发和生产构建）
• UI框架：Tailwind CSS + React组件

快速开始

1. 安装依赖

npm install

2. 启动开发服务器

npm start

访问：http://localhost:3000

3. 构建生产版本

npm run build

构建后的静态文件位于dist/目录，可直接部署到任何静态文件服务器：

• index.html - 主页面
• assets/ - 打包的JS/CSS资源
• wasm/ - WASM模块文件（自动复制）

使用说明

连接设备

1. 在"设备管理"区域点击"添加设备"按钮
2. 填写设备信息：
   • 设备名称：自定义名称（如：Mi Band 7）
   • 设备地址：蓝牙MAC地址（格式：XX:XX:XX:XX:XX:XX）
   • 认证密钥：16字节认证密钥
   • SAR版本：选择SAR v1或v2
   • 连接类型：选择SPP或BLE
3. 点击"保存设备"
4. 在设备列表中选择设备，点击"连接"

管理表盘

1. 切换到"表盘管理"标签页
2. 查看已安装的表盘列表
3. 可以：
   • 点击"设为当前"切换表盘
   • 点击"卸载"删除表盘（当前使用的表盘不能卸载）

管理应用

1. 切换到"应用管理"标签页
2. 查看已安装的第三方应用
3. 可以：
   • 点击"启动"运行应用
   • 点击"卸载"删除应用

安装文件

1. 切换到"文件安装"标签页
2. 点击"选择文件"或拖放文件到上传区域
3. 支持的文件类型：.bin (表盘/固件), .rpk (快应用)
4. 设置安装类型和包名（可选）
5. 点击"开始安装"

文件类型说明

文件扩展名	类型说明	资源类型值	说明
.bin	表盘文件	16	表盘文件（.bin格式）
.bin	固件文件	32	固件更新文件（.bin格式）
.rpk	快应用文件	64	快应用安装包
.bin	快应用文件	64	快应用安装包

注意：不再支持ABP和ZIP格式。固件文件为.bin格式（不是.zip）。文件类型检测基于文件内容，而非扩展名。

资源类型映射说明

• 表盘（WATCHFACE）：资源类型值 16，对应.bin文件
• 固件（FIRMWARE）：资源类型值 32，对应.bin文件
• 快应用（QUICK_APP）：资源类型值 64，对应.rpk/.bin文件

自动检测功能

当选择"自动检测"（资源类型值 0）时，程序会：

1. 使用JSZip检测文件是否为zip压缩包（与文件扩展名无关）
2. 如果是zip文件，检查其中是否包含manifest.json文件
3. 如果存在manifest.json，读取其中的"package"或"packageName"字段作为包名，并自动识别为快应用（资源类型64）
4. 如果是zip文件但没有manifest.json，识别为表盘文件（资源类型16）
5. 如果不是zip文件，根据文件扩展名进行判断：
   • .bin文件：暂时按表盘处理（资源类型16）
   • .rpk文件：识别为快应用（资源类型64）
6. 检测到的包名会自动填入包名字段（如果存在）

开发说明

项目结构

miband-web-install/
├── public/            # 静态资源文件
│   ├── wasm/          # 预编译的WASM文件（构建时直接使用这些文件）
│   │   ├── astrobox_ng_wasm.js
│   │   ├── astrobox_ng_wasm_bg.wasm
│   │   └── ...其他WASM相关文件
│   └── wasm-client.js # WASM客户端封装
├── src/               # React前端源代码
│   ├── App.tsx        # 主应用组件
│   ├── main.tsx       # 应用入口点
│   ├── index.css      # 全局样式
│   └── hooks/         # React自定义钩子
├── dist/              # 构建输出目录
├── vite.config.ts     # Vite构建配置
├── tailwind.config.js # Tailwind CSS配置
├── postcss.config.js  # PostCSS配置
├── tsconfig.json      # TypeScript配置
└── package.json       # 项目依赖配置

重要说明：

• 构建过程直接使用 public/wasm/ 中的预编译WASM文件，wasm来源于开源项目Astrobox-NG
• 所有WASM文件已预先编译并放置在 public/wasm/ 目录中

构建说明

项目使用Vite构建工具，提供现代化开发体验：

• 开发服务器：npm start启动本地服务器（端口3000）
• 生产构建：npm run build生成优化后的静态文件
• WASM支持：直接使用 public/wasm/ 中的预编译WASM文件，构建时自动复制到输出目录（不会重新编译Rust代码）
• 热更新：开发时实时预览修改效果

构建后的dist/目录包含完整静态文件，可部署到任何Web服务器。

重要：构建过程仅复制 public/wasm/ 中已编译好的WASM文件，不会重新编译 app_wasm/ 中的Rust源代码。确保 public/wasm/ 目录中包含所需的WASM文件。

注意事项

1. 浏览器支持：需要现代浏览器支持WebAssembly和Web Bluetooth API
2. 蓝牙权限：首次连接需要授予浏览器蓝牙权限
3. 设备兼容性：支持小米手环系列设备，具体兼容性取决于WASM模块
4. 安全警告：不要在生产环境暴露此服务，确保仅在可信网络中使用
5. 静态部署：构建后的静态文件可在任何Web服务器部署，无需Node.js环境

故障排除

WASM模块加载失败

• 检查public/wasm/目录中是否存在WASM文件（构建时自动复制到dist/wasm/）
• 检查浏览器控制台错误信息
• 确保浏览器支持WebAssembly

设备连接失败

• 检查设备蓝牙是否开启
• 确认设备地址和认证密钥正确
• 检查浏览器是否已授予蓝牙权限

文件安装失败

• 检查文件格式是否支持（.bin、.rpk）
• 确认设备有足够的存储空间
• 检查网络连接是否稳定

开发或构建失败

• 检查Node.js版本（需要>=18）
• 清除缓存：删除node_modules和package-lock.json后重新运行npm install
• 检查TypeScript类型错误

许可证

MIT License

贡献

欢迎提交Issue和Pull Request！