halpcomputar/suntek-fridge-ble

# SUNTEK Fridge BLE — Home Assistant 集成 [](https://github.com/halpcomputar/suntek-fridge-ble/actions/workflows/validate.yml) [](https://hacs.xyz/) 为基于 **SUNTEK `SC-BLE-1.0`** 模块构建的 12V 便携式压缩机冰箱提供本地蓝牙监控 —— 逆向工程基于一台 **BougeRV CRD2 V2.0** 双区冰箱。 无需云端，无需厂商账户，无需 ESP32。 这些冰箱 **不是** Alpicool 同类产品。Alpicool、Brass Monkey、Bodega 及其 贴牌产品使用 GATT service `1234` 和二进制 `FE FE … sum16` 协议，并且已经由 [alpicool_ha_ble](https://github.com/Gruni22/alpicool_ha_ble) 和 [refridge](https://github.com/LeanderM99/refridge) 提供支持。此硬件使用 service `FFF0` 并 采用换行符分隔的 **ASCII CSV** 通讯。由于此前没有任何已公布的资料涵盖此协议，因此诞生了本项目。 由于 `SC-BLE-1.0` 是一个通用模块，这很可能适用于除 BougeRV 之外的一系列贴牌 冰箱。[报告你的型号](../../issues/new?template=model-report.yml) —— 无论兼容与否。 ## 我的冰箱适用吗？ 品牌名称不能说明问题。判断标准是 GATT service： | 你看到的内容 | 结论 | |---|---| | Service `FFF0`，write `FFF1`，notify `FFF4` | ✅ 适用本项目 | | Service `1234`，write `1235`，notify `1236` | ❌ 请使用 Alpicool 集成 | | 广播名称以 `SYZ-` 开头 | ✅ 强烈信号 | | 制造商字符串为 `SUNTEK`，型号为 `SC-BLE-1.0` | ✅ 强烈信号 | 在手机上使用 [nRF Connect](https://www.nordicsemi.com/Products/Development-tools/nRF-Connect-for-mobile) 进行检查，并确保厂商 App 已关闭。 ## 状态 **只读。** 冰箱报告的所有数据都作为实体公开。控制功能 —— 设定值、 电源、Eco/Max —— 尚未实现：命令特征 `FFF1` 是只写的， 因此其格式必须从厂商 App 中抓取。请参阅 [PROTOCOL.md](PROTOCOL.md#command-frame-fff1) 了解具体方法和六步命令检查清单。 12 个状态字段中有 10 个已通过厂商 App 和冰箱自身的 显示屏确认。剩下的两个在参考设备上被记录为无法测试，而不是 盲目猜测。 ## 实体 | 实体 | 类型 | 备注 | |---|---|---| | Zone 1 / Zone 2 温度 | sensor | 在参考设备上，zone 1 是较大的隔室 | | Zone 1 / Zone 2 设定值 | sensor | | | 输入电压 | sensor | 诊断 | | 运行模式 | sensor | enum：Eco / Max | | 电池保护 | sensor | enum：Low / Medium / High，诊断 | | 电源 | binary_sensor | 设备类 *running* | 温度在内部统一为 °C，因此 Home Assistant 会根据你的 首选单位进行显示，并且当你频繁在 °F 和 °C 之间切换冰箱时，长期统计数据也不会丢失。 `iot_class` 为 `local_push`：集成仅订阅，不进行轮询。冰箱每 4 秒左右发送 一次状态帧，并且在发生任何变化时立即发送一次。 ## 安装说明 ### HACS 1. HACS → ⋮ → **Custom repositories** 2. 仓库 `https://github.com/halpcomputar/suntek-fridge-ble`，类型为 **Integration** 3. 下载，然后 **重启 Home Assistant** ### 手动 将 `custom_components/suntek_fridge_ble/` 复制到你的 Home Assistant `config/custom_components/` 目录中，然后重启。 ### 设置 在关闭厂商 App 的情况下，冰箱应该会在 **Settings → Devices & Services** 下被自动发现。否则，请通过 **Add Integration → SUNTEK Fridge BLE** 手动添加。 ## 要求与限制 - 范围内有蓝牙适配器，或者有一个 [ESPHome Bluetooth Proxy](https://esphome.io/components/bluetooth_proxy/)。 范围大约为 10 米。 - **同一时间只能建立一个 BLE 连接。** 当 Home Assistant 连接时，厂商 App 无法 连接，反之亦然。集成会将连接中断视为正常情况，并采用退避算法进行 重连。 ## 开发说明 协议层不依赖 Home Assistant，因此其测试可以在任何地方运行： ``` pip install pytest && python3 -m pytest tests/ -q ``` `tools/probe.py` 是一个独立的 BLE 探测器，可以实时解码数据帧并高亮显示 发生变化的字段 —— 包括跨重连的检测，这也是那些仅限 App 设置的映射方式。 有关完整的规范、已确认的内容以及未确认的内容，请参阅 [PROTOCOL.md](PROTOCOL.md)。 ## 致谢 Alpicool 相关项目 —— [Gruni22/alpicool_ha_ble](https://github.com/Gruni22/alpicool_ha_ble), [LeanderM99/refridge](https://github.com/LeanderM99/refridge), [klightspeed/BrassMonkeyFridgeMonitor](https://github.com/klightspeed/BrassMonkeyFridgeMonitor), 以及 [dandwhelan 的兼容性说明](https://github.com/dandwhelan/Alpicool50l12vfridgefreezer) —— 虽然涵盖的是不同的协议，但正是它们的文档让我们能够快速排除该 产品线，并从零开始开发本项目。 ## 许可证 MIT —— 请参阅 [LICENSE](LICENSE)。

标签：Home Assistant, 协议逆向, 安全规则引擎, 智能家居, 物联网, 硬件集成, 蓝牙低功耗, 逆向工具