用 ZHA 把协调器接入 Home Assistant

ZHA 是 Home Assistant 内置的 Zigbee 集成，不用单独跑 Zigbee2MQTT。

USB Silabs（ZBT-1P、ZBM-MG21、ZBM-MG24）多数情况下免刷固件，配置流常能自动扫到串口。以太网网关（ETH-52P / ETH-52P7、ETH-MG21 / ETH-MG24，含 POE）走网络，填 socket 地址。同一个协调器不要同时开 ZHA 和 Zigbee2MQTT。

Zigbee2MQTT 网络端口写成 tcp://…:6638，不要写成 socket://。见 Zigbee2MQTT 配置 Inswift 协调器。

速查

产品	芯片	在 ZHA 里怎么连
ZBT-1P、ZBM-MG21、ZBM-MG24	EFR32MG21 / EFR32MG24	USB 串口，优先 by-id
ETH-52P / ETH-52P7	TI CC2652P / TI CC2652P7	`socket://dongle.local:6638` 或 `socket://网关IP:6638`
ETH-MG21 / ETH-MG24（含 POE）	EFR32MG21 / EFR32MG24	同上

ETH 网关 Zigbee 端口默认 6638
mDNS 主机名默认 dongle.local

网关网页里可以直接复制 USB 或 TCP 配置。下图是 ETH 网页的 ZHA 页（Silabs 示例，Radio Type 为 EZSP；TI 在 ZHA 里选 ZNP / zstack）。

ETH 网关网页中的 ZHA USB / TCP 配置

USB 准备

用 USB 延长线 把协调器插到 Home Assistant 主机（尽量避开 USB 3.0 口）。位置见部署位置与抗干扰
确认系统能看到串口，优先 by-id：Home Assistant → 设置 → 系统 → 硬件，或在主机上执行 ls -l /dev/serial/by-id/
/dev/ttyUSB0 / /dev/ttyACM0 能用，但重启后编号可能变
关闭占用该串口的程序，不要用同一根 dongle 再开 Zigbee2MQTT

Windows / macOS 需安装对应 USB 驱动（CP210x / CH9102），见 USB dongle 固件烧录。

以太网 / Wi-Fi 准备

给网关上电，接到与 Home Assistant 同一局域网（优先网线；Wi-Fi 要稳）
打开网关网页：http://dongle.local/ 或 http://网关IP/
确认 Zigbee 是 协调器 固件，不是 Router。Router 只扩展网络，不能当 ZHA 协调器
Zigbee 桥接端口默认 6638

dongle.local 解析不了（Docker、VLAN、禁止组播 DNS）时改用局域网 IP。给网关做 DHCP 保留更省事。

添加集成：USB

设置 → 设备与服务 → 添加集成 → 搜索 ZHA
选择串口（优先 by-id）
波特率保持默认，除非固件说明另有要求
完成后进入集成页，点 添加设备，让终端进入配对

添加集成：以太网 / Wi-Fi

设置 → 设备与服务 → 添加集成 → 搜索 ZHA
要填串口 / 射频路径时，选网络 / socket（Home Assistant 各版本用词可能不同）。不要选本地 /dev/tty…
填下面之一：

socket://dongle.local:6638

或（mDNS 失败时换成网关的局域网 IP）：

socket://网关IP:6638

走完向导。网关指示灯绿色常亮，通常表示主机已连上 Zigbee 桥
进入集成 → 添加设备，再让终端进入配对

ETH-52P / ETH-52P7 与 ETH-MG / POE 在 ZHA 里 socket 写法相同，都是 socket://dongle.local:6638。

Router 固件不是协调器

ETH-MG21 / MG24（含 POE）若刷的是 Zigbee Router 固件：

ZHA 不会把它当网络协调器
调试走设备网页 Logs & Debug，见 ETH-MG Router 网页 CLI 调试
网页 CLI 和协调器模式用的 Zigbee 端口 6638 不是同一件事

常见问题

现象	先查什么
串口列表是空的	Win/macOS 驱动、线材和口；到硬件页看 by-id
网络添加失败 / 超时	与 HA 同一局域网；端口 6638；改用 IP；网页能否打开
已配置 / 射频占用	停掉占用同一个协调器的 Zigbee2MQTT 或另一个 ZHA
ZHA「删除并重新创建」失败	见常见问题 FAQ（清理 `zigbee.db`，先备份）
设备加不进来	ZHA 允许加入；终端进入配对；摆放与干扰