tpawley2001/Wyze-Bolt-WiFi-Bridge-ESP32
GitHub: tpawley2001/Wyze-Bolt-WiFi-Bridge-ESP32
通过 ESP32 充当 Wi-Fi 与 BLE 之间的桥接，将纯蓝牙的 Wyze Lock Bolt 接入 Home Assistant 并实现实时电量解密读取。
Stars: 0 | Forks: 0
# Wyze Bolt Wi‑Fi Bridge (ESP32)
通过 **ESP32 作为 Wi‑Fi ↔ Bluetooth 桥接**，将纯 **BLE 的 Wyze Lock Bolt (YD_BT1)** 完全接入 **Home Assistant over Wi‑Fi**，实现**上锁/解锁、实时状态和实时电量**。
Bolt 本身没有网关或 Wi‑Fi；一切都依赖于 Bluetooth LE，且其无线电信号较弱。本仓库封装了一套完整、可靠的设置方案：
- **ESP32 Wi‑Fi ↔ BLE bridge** —— 在门附近运行 ESPHome 的 ESP32 作为*主动式* Bluetooth proxy，从而让 HA 能够通过您的局域网访问门锁。
- **上锁/解锁 + 状态** —— 由 [`ha-wyzeapi`](https://github.com/SecKatie/ha-wyzeapi)提供，它通过该桥接解析 Bolt 的加密 BLE 协议。（这是他们的工作成果——本仓库在此基础之上构建。）
- **实时电量** —— 一个用于解密门锁 BLE Battery Level 特征值的小补丁，`ha-wyzeapi` 原本并不读取该数据（它只会回退到陈旧的 Wyze **云**电量，这是一个长期以来的痛点：[ha-wyzeapi #833](https://github.com/SecKatie/ha-wyzeapi/issues/833)）。**此处的解码即为本仓库的原创贡献。**
- **更新防护守卫** —— 在 `ha-wyzeapi` 的 HACS 更新（会覆盖原有补丁）之后，自动重新应用电量补丁。
## 架构
```
Wyze Lock Bolt ──BLE──► ESP32 (ESPHome active BT proxy) ──Wi‑Fi──► Home Assistant
(YD_BT1) esphome/…-proxy.yaml │
├─ ha-wyzeapi ──► lock.* (lock/unlock, state)
└─ battery patch ─► sensor.*_lock_battery_ble
(+ MQTT)
```
为什么需要**主动式** proxy：被动式 proxy 虽能监听到门锁的广播，但无法承载查询状态、电量或进行上锁/解锁所需的 GATT 连接。请将 ESP32 放置在距离房门约 15 英尺的范围内。
## 仓库内容
| 路径 | 用途 |
|------|---------|
| `esphome/wyze-bolt-ble-proxy.example.yaml` | ESP32 主动式 BT‑proxy 固件 |
| `ha-wyzeapi-patch/battery.patch` | 将 BLE 电量读取功能添加到 `ha-wyzeapi` 的 Diff |
| `ha-wyzeapi-patch/coordinator_patcher.py` | 幂等且基于锚点检查的补丁应用器 |
| `guard/` | 用于在 HACS 更新后重新应用补丁的 systemd timer + 脚本 |
| `examples/decode_battery.py` | 独立的 AES‑ECB 电量解码演示 |
| `docs/PROTOCOL.md` | BLE GATT + 加密 + 上锁/解锁协议说明 |
## 安装
**前置条件：** Home Assistant + MQTT 集成、一台 ESP32 以及关联在您 Wyze 账户下的 Wyze Bolt。
### 1. 刷入 ESP32 桥接固件
修改 `esphome/wyze-bolt-ble-proxy.example.yaml`（填入您的 ESPHome `secrets.yaml`），并将其刷入放置在门附近的 ESP32 中。HA 会将其识别为 ESPHome 设备 / Bluetooth proxy。
### 2. 添加门锁（上锁/解锁 + 状态）
通过 HACS 安装 [`ha-wyzeapi`](https://github.com/SecKatie/ha-wyzeapi) 并使用您的 Wyze 凭据登录。Bolt 将显示为一个 `lock.*` 实体，并通过 ESP32 桥接经由 BLE 进行连接。验证您是否可以进行上锁/解锁操作并查看状态。
### 3. 添加实时电量
将补丁应用到 `ha-wyzeapi` 的 coordinator，然后重启 HA：
```
# 选项 A — the diff
cd /config/custom_components/wyzeapi && patch -p1 < /path/to/ha-wyzeapi-patch/battery.patch
# 选项 B — the idempotent patcher (验证 anchors；拒绝不干净的 apply)
python3 ha-wyzeapi-patch/coordinator_patcher.py /config/custom_components/wyzeapi/coordinator.py
```
在下一次轮询后，一个 `sensor.*_lock_battery_ble` (`device_class: battery`) 实体会通过 MQTT 发现机制发布——无需 broker 密码。它会通过 BLE 读取**真实的实时**百分比（带有门锁自身的时间戳），而不是陈旧的云端数值。如有需要，您可以在补丁中重命名该实体或 topic。
### 4.（推荐）保持其在更新后依然生效
`ha-wyzeapi` 是一个 HACS 组件，因此每次更新都会覆盖 `coordinator.py` 并移除该补丁。请在任意可以通过 SSH 连接到 HA 且常开的设备上安装此防护守卫：
```
cp guard/*.example ~/.config/systemd/user/ # then edit the Environment= lines
systemctl --user daemon-reload
systemctl --user enable --now wyze-ble-battery-guard.timer
loginctl enable-linger "$USER"
```
它每 6 小时检查一次；如果补丁丢失，它会重新应用补丁，重启 HA，并可通过 Telegram 通知您。如果未来的 `ha-wyzeapi` 重构了文件结构，导致无法安全地自动应用补丁，它会提醒您手动重新打补丁，而不会静默失败。
## 电量解码原理（简述）
门锁暴露了标准的 Battery Level 特征值 `0x2A19`，但读取返回的是 16 字节的 **AES‑128‑ECB 密文**。其密钥是门锁 Wyze `uuid` **最后 16 个字符**的小写 ASCII 字符串——这与 `ha-wyzeapi` 用于门锁状态的*密钥相同*。解密后，`byte[0]` 即为电池百分比；结尾处固定的 `"loock"` 标记用于确认密钥正确。完整详情（包括上锁/解锁的 UART 交互流程）请参阅 [`docs/PROTOCOL.md`](docs/PROTOCOL.md)。
密钥是在运行时派生的——**本仓库中不存储任何设备密钥**。
## 注意事项
- 已在 `ha-wyzeapi` 0.1.38 和一台 Bolt (`YD_BT1` / `XFPL106`) 上测试通过。
- 配套的**密码键盘**是一个拥有独立密钥的 BLE 设备——不在此项目范围内。
- 属于社区逆向工程成果，不提供任何担保。遵循 MIT 许可证 (`LICENSE`)。
## 致谢
感谢 [`SecKatie/ha-wyzeapi`](https://github.com/SecKatie/ha-wyzeapi) 提供 Bolt BLE 协议（状态特征值、AES‑ECB 密钥派生以及上锁/解锁的挑战-响应机制）。本仓库在此基础上增加了 ESP32 桥接封装、电量特征值解码以及更新防护守卫。
标签：ESP32, ESPHome, Home Assistant, Wi-Fi网桥, 智能家居, 物联网, 蓝牙低功耗, 逆向工具