TheGrussalo/hekr-bridge-addon

# 用于 Home Assistant 的 Hekr Bridge Add-ons 这是一个 Home Assistant Supervisor add-on，作为 **KKT KOLBE** 抽油烟机的桥接 （可能也适用于其他使用 Hekr/WISEN 协议的 Wi-Fi 设备），将其接入 Home Assistant， 通过 MQTT 进行通信——包括在支持的型号上提供完整的 RGB 色彩控制功能 （例如 **HERMES RGBW**），这是其基于的原始上游项目所未涵盖的。 KKT KOLBE 已停止维护 WISEN 应用，导致这些抽油烟机虽然仍可通过 Wi-Fi 连接，但却没有受支持的控制方式。此 add-on 在抽油烟机和（仍在运行的）Hekr 云端之间充当透明代理， 并通过 MQTT 自动发现功能将完整的控制权暴露给 Home Assistant。 基于 [markobel/kkt-kolbe-homeassistant](https://github.com/markobel/kkt-kolbe-homeassistant) 项目， 扩展了逆向工程得出的 RGB 色彩支持，并打包为标准的 Supervisor add-on。 ## 安装说明 1. 在 Home Assistant 中：**Settings → Add-ons → Add-on Store** 2. 点击 **⋮** 菜单（右上角） → **Repositories** 3. 添加此 URL：`https://github.com/YOUR_USERNAME/YOUR_REPO_NAME` 4. 在新添加的仓库部分下找到 **"KKT Kolbe Hekr Bridge"**，点击 **Install** ## 前置条件 在安装之前，你需要： - 特定于你抽油烟机的 **`devTid`** 和 **`ctrlKey`** — 请参阅下方的[查找你的设备标识符](#finding-your-device-identifiers) - 一台路由器，你可以在其中添加 **DNAT 规则**，将抽油烟机的云端流量（端口 83）重定向到你的 Home Assistant 主机 IP - 运行 **Mosquitto broker** add-on（或任何 MQTT broker），并确保 Home Assistant 可以访问它 ## 配置 安装后，转到 add-on 的 **Configuration** 标签页并填写： | 选项 | 必填 | 说明 | |---|---|---| | `hekr_dev_tid` | **是** | 设备的唯一标识，例如 `ESP_2M_XXXXXXXXXXXX` | | `hekr_ctrl_key` | **是** | 32 字符的十六进制密钥，设备唯一 | | `hekr_cloud_host` | 否 | 默认为 `hub.hekreu.me`（EU Hekr 云端）— 如果你的设备连接到其他地方，请修改此项 | | `mqtt_host` | 否 | 默认为 `localhost` — 此 add-on 使用主机网络，因此 Supervisor 内部的 `core-mosquitto` 主机名无法解析；请使用 `localhost` 或你的 HA 主机自身的局域网 IP | | `mqtt_user` / `mqtt_pass` | 取决于 broker | 如果你的 broker 允许匿名访问，请留空 | | `cmd_power` / `cmd_light` / `cmd_speed` / `cmd_color` | 否 | 协议命令 ID — 默认值 (2/3/4/7) 已确认在 KKT KOLBE HERMES RGBW 和 FREE 型号上可用。其他型号可能有所不同；请参阅下文的 REPL 映射方法。 | **此 add-on 需要主机网络权限**（为了直接监听端口 83）， 因此它不会显示在标准的 "Network" 配置标签页下 — 这是正常现象。 ## 查找你的设备标识符 你需要抽油烟机的 `devTid`、`ctrlKey` 以及它连接到的云端主机地址。 抓取抽油烟机自身的流量（例如通过镜像端口或在你的路由器上运行 `tcpdump`）： ``` tcpdump -i any -nn -s 0 -w hood.pcap 'host ' ``` 在抓包期间重启抽油烟机电源（或强制重新连接），然后检查 JSON payload： ``` tshark -r hood.pcap -Y 'tcp.len > 0' -T fields -e tcp.payload \ | while read p; do printf "%b\n" "$(echo "$p" | sed 's/\(..\)/\\x\1/g')"; done ``` 寻找包含 `devTid` 和 `ctrlKey` 的 `devLoginResp` 消息 —— 这两个 就是必需的配置值。目标端口为 83 的 IP 地址就是你的 `hekr_cloud_host`。 ## 将抽油烟机重定向到 bridge 一旦 add-on 运行起来，在你的路由器上使用 DNAT 规则，将抽油烟机发往云端的流量重定向到你的 Home Assistant 主机 IP，例如： ``` iptables -t nat -A PREROUTING -s -d \ -p tcp --dport 83 -j DNAT --to-destination :83 ``` 如果你的抽油烟机和 Home Assistant 主机位于**同一子网**，你还需要 一条 masquerade 规则来处理 NAT hairpinning： ``` iptables -t nat -A POSTROUTING -s -d \ -p tcp --dport 83 -j MASQUERADE ``` 强制重新连接（重启抽油烟机电源，或在路由器上清除其现有连接， 例如 `conntrack -D -s `），使其应用新的路由。 ## Home Assistant 中暴露的实体 | 实体 | 类型 | 说明 | |---|---|---| | Power | `switch` | 主开关（风扇 + 灯） | | Light | `switch` | 仅白光 | | Speed | `select` | 0–4 | | Fan | `fan` | 与 speed 相同，带有百分比控制 | | **RGB Light** | `light` | 完整的颜色选择器（HERMES RGBW 及类似型号） | | Connected | `binary_sensor` | 在线/离线状态 | | Raw state | `sensor` | 最后的原始十六进制数据帧（诊断信息） | | Sequence | `sensor` | 设备帧计数器（诊断信息） | ## 为其他型号映射命令 如果你的型号的 cmdIds 与默认值不同，你可以通过以下方式找到它们： 连接到 add-on 的日志/控制台，并在测试值时观察 `STATE CHG` 行 — 有关已确认的 帧格式（`48 [len] 02 [seq] [cmdId] [values...] [checksum]`），请参阅 `hekr_bridge.py` 中的注释。 ## 免责声明 非官方的社区项目。不隶属于 KKT KOLBE 或 Hekr。使用风险自负。 ## 开源许可 MIT

标签：Home Assistant, 中间人代理, 抽油烟机控制, 智能家居, 物联网, 请求拦截, 逆向工具