xydac/sp542e-ha-bridge

# SP542E MQTT ↔ BLE 网桥 无需**任何新硬件**，即可通过 Home Assistant 控制被云端锁定的 **SP542E "BedRoof" LED 控制器**。在常开的 Mac 上运行的一个小型 Python 服务通过 BLE 连接到控制器，并将其作为 MQTT light 暴露给 HA。 ``` HA (VirtualBox) ──MQTT──> Mosquitto (on HA) ──MQTT──> bridge.py (Mac) ──BLE──> SP542E ``` HA **不需要蓝牙**，也**不需要自定义组件** — 实体 `light.bed_roof` 会通过 MQTT discovery 自动显示。这解决了 VirtualBox VM 没有可用蓝牙的问题。 ## 文件 | 文件 | 用途 | |---|---| | `protocol.py` | BanlanX_6xx (`53 ..`) 数据帧构建器（电源/CCT/亮度）。单一事实来源。 | | `probe.py` | 一次性运行：直接驱动灯带以确认协议。 | | `bridge.py` | 服务程序：MQTT light ↔ BLE。 | | `run.sh` | 引导 `.venv`（通过 `uv`），加载 `.env`，运行网桥或探测程序。 | | `.env.example`| MQTT 凭证模板 → 复制到 `.env`。 | | `com.xydac.sp542e-bridge.plist` | 用于常开自动启动的 launchd LaunchAgent。 | ## ⚠️ macOS 蓝牙要求 BLE 只能从 Mac 的**本地 GUI 会话**中工作，绝不能通过 SSH（CoreBluetooth TCC 限制）。请在坐在 Mac 前的终端中运行所有操作。首次运行会提示为 Python 二进制文件授予蓝牙权限（系统设置 → 隐私与安全性 → 蓝牙）。 ## 设置 ``` cd sp542e-ha-bridge cp .env.example .env # then fill in MQTT_USER / MQTT_PASS # 1. 确认协议确实驱动了灯光（观察灯条）： ./run.sh probe # 2. 在前台运行 bridge 以测试 HA integration： ./run.sh # -> light.bed_roof 应该会自动出现在 Home Assistant 中。 # 3. 将其设置为 always-on（登录时自动启动，崩溃时自动重启）： cp com.xydac.sp542e-bridge.plist ~/Library/LaunchAgents/ launchctl load -w ~/Library/LaunchAgents/com.xydac.sp542e-bridge.plist ``` ## 协议 (BanlanX_6xx，明文，通过 FFE0/FFE1) 这是一条 **CCT (可调色温)** 灯带 — HA 暴露了色温 (color-temp) + 亮度 + 开/关，没有 RGB。控制器使用的是 **BanlanX_6xx** 系列（SP630E 风格），*而不是* LED-BLE 的 `7E..EF` 协议，也*不是* idealLED AES（这两者都试过并被直接忽略了）。它广播的制造商 ID 为 `0x5053`，广播数据为 `5d 10..`（型号 ID `0x5d`）。 数据帧是在写入特征值 **FFE1**（服务 FFE0）上传输的明文，格式为 `53 00 01 00 `。**写入必须被确认**（`response=True`），否则设备会忽略它们 — 这是关键的坑。 | 命令 | 字节 | |---|---| | 电源开 / 关 | `53 50 00 01 00 01 01` / `53 50 00 01 00 01 00` | | 静态白光模式 | `53 53 00 01 00 02 02 01`（在 CCT/白光亮度之前设置） | | 色温 (静态) | `53 61 00 01 00 02 `（``/`` 0–255；`0x60` = 动态） | | 亮度 | `53 51 00 01 00 02 `（`` 0=彩色 1=白光；`` 0–255） | | 状态查询 | `53 02 00 01 00 01 01` → 设备回复多包状态（固件、IP、名称） | `color_temp` 使用 **mireds** 为单位：`MAX_MIREDS`=370（~2700K 暖光），`MIN_MIREDS`=153（~6500K 冷光）；`protocol.py:cct()` 会将 mireds 映射为冷/暖字节。 协议参考：[`monty68/uniled`](https://github.com/monty68/uniled) `custom_components/uniled/lib/ble/banlanx_6xx.py`（SP542E 不在 UniLED 的型号列表中，但它属于这个系列）。 ## 注意事项 - **可用性 = Mac 的正常运行时间。** 如果 Mac 进入睡眠/关机状态，灯带将无法控制，并且 HA 会显示其不可用。（常开的台式机 = 没问题。） - **乐观状态。** 控制器没有可靠的状态读取机制，因此网关在本地跟踪状态；通过原始 App/遥控器所做的更改不会反映到 HA 中。 - **单一 BLE 连接。** 请保持原始手机 App 处于断开连接状态。

标签：逆向工具