jphein/smartring

# smartring **一个无需云端的 Home Assistant 集成，专为廉价的 Lefun 协议 BLE 智能戒指打造 —— 以及基于此构建的房间存在感照明系统。** [](LICENSE)   这个项目最初的想法只是*“我能不能在不用那个充满广告的厂商 App 的情况下，与这枚 10 美元的戒指通信？”*，后来却演变成了一个覆盖全屋、具备身份识别功能的**跟随式照明**系统。所有操作均在本地运行 —— 无需云端，无需厂商 App，也无需手机。 📖 **[项目站点与详细说明 →](https://jphein.github.io/smartring/)**

## 戒指 **[Ti-Vision Smart Fitness Ring](https://www.amazon.com/dp/B0FQTKLSWR)** — 约 9.99 美元，商品描述为 *“钛金属”*（实际上就是普通的塑料），与 *Lefun Health / Life* App 配对。宣传具有*“带有**睡眠追踪**、血压、心率的健康监测功能。”* 剧透一下：睡眠追踪需要加速度计， 而它[并没有](#the-headline-finding-) —— 但心率、SpO₂ 和血压 估算功能都是真实有效的，这已经足以用来构建存在感照明系统了。 ## 项目包含内容 | 组件 | 功能 | |---|---| | **`lefun_ring.py`** | 用于戒指原生 BLE GATT 协议（心率 / SpO₂ / 血压 / 电池 / 设备信息）的独立 Python CLI 和库。完全不需要 HA。 | | **`custom_components/lefun_ring/`** | 完整的 Home Assistant 集成 —— 通过 HA 的 Bluetooth 协议栈（本地适配器*或* ESPHome BLE 代理）进行路由，暴露传感器、服务和实时房间追踪。 | | **`ha-packages/lefun_ring.yaml`** | **存在感照明**引擎：融合入住检测 + 跟随式自动化 + 独立房间开关 + 辅助脚本。 | | **`dashboard/`** | Lovelace 仪表盘 —— 用于戒指和 BLE 代理集群。 | ## 核心发现 🔬 厂商 App 宣传具有步数、睡眠以及“摇一摇拍照/寻找手机”手势。 **这些全都没用 —— 因为这枚戒指没有可用的加速度计。** 经过详尽的 测试（在所有协议路径下步数一直卡在 0，在开启拍照手势的情况下用力摇晃数分钟也没有触发任何摇一摇事件，而且无论是否移动，`find-phone` 操作码都只在固定的定时器上发送），结论非常明确： 这一事实重塑了整个项目：既然没有可以捕捉的摇动按钮，就没有理由 保持持续的 BLE 连接 —— 因此戒指可以自由地进行**广播**，而这正是 实现房间追踪的关键所在。 ## 跟随式照明 你走进的房间会**打开**灯；你离开的房间会**关闭**灯。

每个房间的入住状态都由多达三个独立的估算器**融合**而成，以最先触发的为准： ``` ring advert ─▶ nearest-proxy tracker (custom, recency-weighted) ┐ ring advert ─▶ Bermuda BLE trilateration ├─▶ room occupancy ─▶ that HA mmWave ─▶ ESPHome radar presence (instant, identity-blind) ┘ (OR-fused) area's button_lights ``` - **BLE（戒指）：** 知道*是谁*（身份），覆盖每个房间，但速度较慢 —— 廉价的戒指 广播频率很低（空闲时约 1 次/分钟），且无法通过运动唤醒。两个独立的 BLE 估算器（一个自定义的最近代理追踪器**和** [Bermuda](https://github.com/agittins/bermuda)） 并行运行；谁先解析出房间谁就生效。 - **mmWave 雷达（可选）：** 瞬间响应且在你静坐时保持追踪，但无法识别身份。 在一个房间插入一个，该房间就会自动升级为亚秒级响应 —— 无需 更改配置。*（参考部署目前仅依靠戒指的广播运行； 雷达输入已接通并就绪。）* - **自我修复：** 每个房间*自行*管理（无需跨房间协调），仅在入住状态**上升沿** 触发灯光，因此手动调暗的房间会保持黑暗，而因漏检 过渡导致依然亮着灯的房间会在下一次事件中被清理。可选的“仅在黑暗时”触发门控。 其结果在每一层都能优雅降级：雷达宕机 → BLE 顶上；一个 BLE 追踪器 出故障 → 另一个覆盖；戒指超出范围 → 房间直接清空状态。 **硬件要求：** 房间追踪需要 **[Bluetooth proxies](https://esphome.io/components/bluetooth_proxy.html)** —— 每个你想追踪的房间一个。这是 Home Assistant 中非常成熟的领域：任何 启用了 `bluetooth_proxy:` 的 ESPHome 节点都可以工作，并且这些代理可以一物多用（这栋 房子里运行着一批 **ESP32-C3** 开发套件，它们同时代理广播、保持 iTag 按钮 连接并桥接 BLE 电池监视器）。 ## 硬件发现（测试设备：`FF:2A:35:A7:44:F3`） - **SoC：** Nordic nRF 级别 —— 暴露了真正的 Nordic Secure DFU 服务 `0xFE59`。很可能是 PhyPlus 生产的 nRF 克隆芯片，也是 Gadgetbridge 的 Lefun 驱动所针对的芯片系列。 - **数据协议：** Gadgetbridge **Lefun** —— 服务 `0x18D0`，写入 `0x2D01`，通知 `0x2D00`， 请求前导码 `0xAB`，响应 `0x5A`，按位 CRC8，大端序 payload。 - **光学（可用）：** 心率、SpO₂、单值血压估算（PPG `0x0F`→`0x10`）。 - **运动（失效）：** 步数 `0x12`/`0x13`，睡眠 `0x15`，摇一摇手势 `0x0A`/`0x0E` —— 没有 IMU。 - **异常行为：** DIS 字符串被门控（`NotPermitted` —— 通过命令 `0x00` 获取身份）；重度省电； 处于*连接*状态的戒指会停止广播（这是追踪与连接之间的权衡）。 ## 安装 ### CLI（独立运行） ``` python3 -m venv .venv .venv/bin/pip install -r requirements.txt # 一次性 bond bluetoothctl --timeout 15 scan on bluetoothctl pair && bluetoothctl trust # 读取 live data .venv/bin/python lefun_ring.py --address hr .venv/bin/python lefun_ring.py --address poll ``` ### Home Assistant 1. 将 `custom_components/lefun_ring/` 复制到你的 HA `config/custom_components/` 目录中。 2. 重启 HA → **设置 → 设备与服务 → 添加集成 → "Lefun Ring"** （可通过任何 Bluetooth 适配器或 ESPHome 代理自动发现）。 3. 启用跟随式照明：将 `ha-packages/lefun_ring.yaml` 放入你的 `packages/` 目录中，使用 `button_lights` 标签标记每个房间的灯具，然后从仪表盘切换开启这些房间。 4. 从 `dashboard/` 导入仪表盘（storage-mode Lovelace YAML）。 有关 集成的详细信息，请参阅 [`custom_components/lefun_ring/README.md`](custom_components/lefun_ring/README.md)。 ## 致谢与许可 - 协议移植自 **[Gadgetbridge](https://codeberg.org/Freeyourgadget/Gadgetbridge)** Lefun 驱动。房间三边测量由 **[Bermuda](https://github.com/agittins/bermuda)** 提供。 - 由于协议代码源自 Gadgetbridge (AGPL-3.0)，本项目采用 **[AGPL-3.0](LICENSE)** 许可。 *与 Lefun 无关联。“Lefun”仅用于标识这些戒指所使用的协议。*

标签：Home Assistant, Python, 低功耗蓝牙, 无后门, 智能家居, 智能戒指, 物联网, 网络调试, 自动化, 逆向工具