tinic/ha-halo-home

# Halo Home for Home Assistant [](https://hacs.xyz) [](LICENSE) [](https://github.com/tinic/ha-halo-home/actions/workflows/validate.yml) 用于 **Eaton / Cooper Lighting "HALO Home"** 及其他 **Avi-on** Bluetooth mesh 灯具的 Home Assistant 集成。支持通过本地 Bluetooth 进行开关、亮度和色温控制 —— **无需云平台、无需网关、无需 MQTT**。 Home Assistant 内置的 `avion` 集成已在 **HA 2026.7** 中被**移除**。如果你是因为升级后发现 Halo 灯具停止工作而来到这里：本插件正是它的替代品。 ## ⚠️ 首先阅读：备份你的 passphrase 你的整个 mesh 网络由一个密钥控制 —— 一个**针对每个位置的静态 passphrase**。这是控制已安装灯具所需的唯一凭证，且**目前唯一的副本仅保存在 Avi-on 的服务器上。** Cooper 已于 **2023 年 11 月** 停产 HALO Home，并承诺继续运行该应用和云服务约五年 —— 因此预计服务器将在 **2028 年 11 月** 左右关闭。 **届时，任何未保存其 passphrase 的用户将永久丧失重新设置这些灯具的能力。** 唯一的恢复方法是对每个灯具进行恢复出厂设置并重新配置 —— 这意味着必须将每一个天花板上的灯具物理拆卸下来。 因此，在做任何其他事情之前： ``` python3 tools/avion_backup.py # stdlib only; prompts for your Avi-on login ``` 这将生成 `avion_backup.json`（权限模式 `0600`），其中包含你的 passphrase 和设备列表。 **将其复制到可靠且离线的地方。** 仅凭此文件即可设置本集成，无需互联网和 Avi-on 账户 —— 这是一条在 2029 年依然有效的路径。 即使你从未安装过此集成，今天也值得执行此操作。 ## 功能说明 | | | |---|---| | 开 / 关 | ✅ | | 亮度 | ✅ | | 色温（可调白光） | ✅ | | 从灯具读取状态反馈 | ✅ 每个灯都会报告其真实的亮度和颜色 | | 物理墙壁调光器上的更改 | ✅ 发生时实时推送到 HA 中 | | 运行时是否需要云平台 | ❌ 永不需要 —— 仅本地连接到单个灯具 | | 需要安装额外的 Python 包 | ❌ 无需任何安装 | 该 mesh 网络是一个**泛洪网络**：Home Assistant 与最近的一个灯具保持单一的 Bluetooth 连接，然后由该灯具将命令中继给所有其他灯具。你不需要让每个灯具都处于 HA 主机的无线电覆盖范围内 —— 只需一个即可。 ## 环境要求 - Home Assistant **2024.12** 或更高版本，且已配置好 **Bluetooth** 集成。 - 覆盖范围内至少有一个灯具的 Bluetooth 适配器。内置适配器或 USB dongle 均可。[ESPHome Bluetooth Proxy](https://esphome.github.io/bluetooth-proxies/) *应该*也可以工作 —— 本集成使用的是 Home Assistant 标准的 BLE 连接路径 —— 但目前仅在本地 USB 适配器上进行了测试，因此欢迎提供反馈报告。 - 仅在**首次设置时**需要 Avi-on / Halo Home 账户（或者使用备份文件，见上文）。 ## 安装说明 **HACS**（推荐） → HACS → ⋮ → *Custom repositories* → 将 `https://github.com/tinic/ha-halo-home` 添加为 **Integration** → 安装 → 重启 HA。 **手动安装** → 将 `custom_components/halo_home/` 复制到你的 `config/custom_components/` 目录中 → 重启 HA。 ## 设置 *Settings → Devices & Services → Add Integration → **Halo Home***。如果范围内有灯具，Home Assistant 很可能会自动发现它并提示你。 系统会提供两种方式来获取你的 mesh passphrase： - **登录 Avi-on** —— 在服务器仍然运行期间，这是最简单的途径。你的密码只会被使用一次，不会被存储。 - **从备份文件恢复** —— 读取由 `tools/avion_backup.py` 生成的 `avion_backup.json`。无需互联网和账户。**这个方式可以永久使用。** 你的灯具会显示为 `light.*` 实体。由于 Avi-on 倾向于为同一型号的每个灯具赋予相同的名称，因此名称相同的灯具会在后面附加其 MAC 后缀以示区分 —— 你可以在 HA 界面中将它们重命名为更实用的名字。 ## 已测试硬件 基于 7 个 **HALO MicroEdge (HLB)** 嵌入式筒灯（`product_id` 162，2700–5000 K 可调白光）以及两个 Avi-on Accessory Dimmers 开发，使用 CSR8510 USB 适配器。 其他基于 Avi-on 平台的设备极有可能兼容 —— 整个平台使用的是同一种协议 —— 但未经测试。**如果你有其他 Halo 或 Avi-on 硬件，请提交一个 issue 并告知是否正常工作。** 这是目前最有价值的贡献。 ## 工作原理 HALO Home 是 **Avi-on** 平台的贴牌产品，运行 **Qualcomm/CSR CSRmesh 1.x** —— 而*不是* Bluetooth SIG Mesh。它不需要配对，也不需要绑定：所有的安全性都体现在 payload 中，使用由位置 passphrase（`sha256(passphrase + "\x00MCP")`，反转，并截断至 128 位）生成的密钥进行加密。命令使用 AES-OFB 加密，并使用反转且截断的 HMAC-SHA256 进行身份验证，然后写入两个 GATT 特征中。 完整的通信协议 —— 包括加密、数据包封装、MCP 操作码、寻址方案、云 API 以及状态回读路径 —— 均记录在 **[docs/protocol.md](docs/protocol.md)** 中。 文档内容详实，即使没有 Bluetooth 嗅探器，你也可以据此从零开始重新实现这套系统。 ## 相关项目 目前没有其他针对这些灯具提供*本地化、无云平台、原生 HA* 支持的方案，这正是开发本集成的原因。 但必须向相关先驱致敬，如果本集成不符合你的需求，以下项目也很有参考价值： - [`nayaverdier/halohome`](https://github.com/nayaverdier/halohome) —— 最清晰的 Python 云 API 和发送路径参考资料。 - [`nkaminski/csrmesh`](https://github.com/nkaminski/csrmesh) —— 这里所有加密工作的鼻祖，最初的 CSRmesh 加密研究成果。 - [`oyvindkinsey/esphome-avionmesh`](https://github.com/oyvindkinsey/esphome-avionmesh) —— 一个 ESPHome 组件。是目前维护最活跃的 Avi-on 代码；如果你更愿意将 mesh 网络部署在 ESP32 之后，这是一个不错的选择。 - [`oyvindkinsey/recsrmesh`](https://github.com/oyvindkinsey/recsrmesh) —— 现代的异步 CSRmesh 库，也是 **MASP** 的唯一实现，可以使用你指定的密钥为恢复出厂设置的灯具重新进行配置。如果你在云服务关闭后丢失了 passphrase，这就是你的救命稻草。 - [`jhanssen/halo-mqtt`](https://github.com/jhanssen/halo-mqtt) —— 通过 MQTT 将 Halo 桥接到 HA。自 2023 年起已停止维护。 - [`mjg59/python-avion`](https://github.com/mjg59/python-avion) —— 最初的底层代码，HA core 中已被移除的 `avion` 集成正是基于此构建的。 ## 免责声明 本插件不附属于、未受认可，也未与 Eaton、Cooper Lighting 或 Avi-on 有任何关联。"HALO" 和 "HALO Home" 是其各自所有者的商标。本集成是通过对已停产产品线进行独立的协议分析而独立开发的，旨在让用户已经付费购买的硬件在服务器关闭后仍能继续工作。 ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。

标签：Home Assistant, 智能家居, 智能照明, 本地控制, 物联网, 蓝牙网格, 逆向工具