Querbox/openring

# OpenRing    OpenRing 是一个开源平台，用于独立于厂商应用使用智能戒指——检查其蓝牙协议、解码数据，并在此基础上构建你自己的体验。 本仓库是一个 monorepo，包含桌面检查器、移动应用（计划中）、共享包以及特定设备的配置文件。 ## 状态 相对于长期愿景的总体进度：大约 **~12%**。 ``` Phase 1 — Inspector ████████░░░░░░░░░░░░ 40 % Phase 2 — Protocol Explorer █░░░░░░░░░░░░░░░░░░░ 5 % Phase 3 — SDK ██░░░░░░░░░░░░░░░░░░ 10 % Phase 4 — OpenRing Mobile ░░░░░░░░░░░░░░░░░░░░ 0 % ───────────────────────────────────────────────────────── Design system ███████░░░░░░░░░░░░░ 35 % Device profiles ████░░░░░░░░░░░░░░░░ 20 % Public docs █████░░░░░░░░░░░░░░░ 25 % ``` ### 阶段 1 — Inspector `40 %` 首个交付成果：一个桌面工具，能够通过蓝牙找到智能戒指并让你观察其流量。 - [x] Monorepo 脚手架（npm workspaces、TypeScript、Tauri 2 + React） - [x] 设计 token + 深色毛玻璃效果外壳（Linear / Raycast 美学） - [x] 使用 `btleplug` 的 Rust BLE 后端 —— 扫描、连接、发现、订阅、写入 - [x] 实时设备列表（按 RSSI 排序）和完整的 GATT 服务树 - [x] 带 hex dump、时间戳、RX/TX 方向的数据包记录器 - [ ] 用于向戒指发送命令的 Hex / 文本 TX 输入 - [ ] 捕获导出（`.hex` 文件）与重放 - [ ] 设置面板 + 优化的错误 / 空状态 - [ ] Linux 与 Windows 上的首次运行 BLE 权限流程 ### 阶段 2 — Protocol Explorer `5 %` 对捕获的数据包进行模式识别。显示猜测结果及其置信度： “可能的电池数据包 — 87 %”。 - [x] 包桩代码（`@openring/parser`、`@openring/protocol`） - [ ] 首个解码数据包 → 真正的 `ProtocolDefinition` - [ ] 在 Inspector 中渲染置信度评分 - [ ] 模式分组（重复的 opcode、长度前缀、校验和） - [ ] 从观察到的差异自动建议字段边界 ### 阶段 3 — OpenRing SDK `10 %` 一个库，让其他人可以在 OpenRing 之上构建应用，而无需重新 发明 BLE 层。 - [x] 核心类型 + 与传输无关的 `BleAdapter` 接口 - [ ] 稳定的 TypeScript 公共 API - [ ] Python 绑定（用于数据科学 / 临时逆向工程） - [ ] Swift 绑定（用于 iOS 应用） - [ ] 为每个支持的设备记录协议契约 ### 阶段 4 — OpenRing Mobile `0 %` 基于 SDK 构建的开源健康应用。尚未开始。 ### 贯穿各阶段的工作流 - **设计系统** `35 %` — token（颜色 / 间距 / 排版 / 动效）位于 `@openring/ui` 中；组件库尚待推出。 - **设备配置文件** `20 %` — Optim Ring 配置是唯一的一个，且目前的未知部分仍然多于已知部分。 - **公开文档** `25 %` — 愿景、架构、贡献指南位于 `docs/` 中；每个设备的协议文档有待在阶段 2 完成。 ## 结构 ``` openring/ ├── apps/ │ ├── inspector/ # Desktop inspector (Tauri + React) │ └── mobile/ # Mobile health app (planned) ├── packages/ │ ├── core/ # Cross-platform core SDK types │ ├── ble/ # BLE adapter interface │ ├── parser/ # Packet parsing and inference │ ├── protocol/ # Protocol definitions │ └── ui/ # Shared UI components & design tokens ├── devices/ # Device profiles (Optim Ring, etc.) ├── docs/ # Vision, architecture, contributing └── tools/ # Reverse engineering & dev scripts ``` ## 安装 Inspector ### 前置条件 | 工具 | 原因 | 安装 | | --- | --- | --- | | **Node.js 20+** | 构建工具和 React 前端 | [nodejs.org](https://nodejs.org) 或 `brew install node` | | **Rust (stable)** | Tauri 外壳 + BLE 后端 (`btleplug`) | [rustup.rs](https://rustup.rs) 或 `brew install rustup` | | **Git** | 克隆此仓库 | macOS Xcode 工具自带；否则使用操作系统包管理器 | | **可用的 Bluetooth 协议栈** | …显然 | macOS / Linux / Windows | macOS 额外要求：无 — `tauri dev` 会构建一个链接了正确的 `NSBluetoothAlwaysUsageDescription` 的开发二进制文件，因此 CoreBluetooth 会 在首次启动时授予权限。Linux：通过你的包管理器安装 `libdbus-1-dev` 和 `bluez`。Windows：Windows BLE 协议栈在 Windows 10/11 上 开箱即用。 ### 1 · 克隆并安装 ``` git clone https://github.com/Querbox/openring.git cd openring npm install ``` 首次 `npm install` 会拉取大约 ~80 个包，包括 Tauri CLI、React 和 Vite。`cargo` 会在首次 构建时获取自己的 crate（需要几分钟）。 ### 2 · 在开发模式下运行 Inspector ``` npm run inspector:tauri ``` 首次启动会从头编译 Rust crate — 预计首次需要 ~2-5 分钟，后续运行几乎是瞬间完成。一个原生窗口 将会打开，显示 OpenRing Inspector 仪表板。**macOS 会在 首次启动时提示你授予 Bluetooth 权限** — 请接受，否则 扫描器将什么都看不到。 如果你只需要 React 前端（不含 Tauri 外壳）来进行 UI 工作，请运行： ``` npm run inspector # http://localhost:1420 ``` ### 3 · 构建可分发版本 ``` npm run tauri:build -w @openring/inspector ``` 打包好的产物会生成在 `apps/inspector/src-tauri/target/release/bundle/` 下 — macOS 上是 `.app`，Windows 上是 `.msi`，Linux 上是 `.AppImage` / `.deb` / `.rpm`。首先打包完整的图标集（一次性操作）： ``` npm run tauri -w @openring/inspector -- icon apps/inspector/src-tauri/icons/icon.png ``` ### 故障排除 - **`cargo: command not found`** — 通过 [rustup.rs](https://rustup.rs) 安装 Rust，然后重启你的 shell，使 `~/.cargo/bin` 包含在 `$PATH` 中。 - **macOS Bluetooth 权限被拒绝** — 打开系统设置 → 隐私与安全性 → Bluetooth，并授予 *OpenRing Inspector* 访问权限。提示只会出现一次；如果你之前忽略了它，请手动切换该开关。 - **首次运行 `tauri dev` 很慢** — Tauri 首次会编译几百个 Rust crate。后续运行只会重新构建更改的部分（~几秒钟）。 - **`Could not read package.json`** — 你在你的主目录运行了 `npm`。请先 `cd` 进入克隆的 `openring` 文件夹。 请参阅 [`docs/`](./docs) 了解完整的愿景、架构和贡献指南。 ## 许可证 MIT — 见 [LICENSE](./LICENSE)。

标签：Tauri, 可视化界面, 智能戒指, 桌面应用, 物联网, 自动化攻击, 蓝牙, 逆向分析, 逆向工具