常见问题 FAQ

使用 Inswift USB zigbee dongle 或以太网 zigbee dongle 接入 Home Assistant 时，下面这些问题比较常见。USB 型号：ZBT-1P、ZBM-MG21、ZBM-MG24。ETH 型号：ETH-52P / ETH-52P7、ETH-MG21 / ETH-MG24 及 POE。

ETH 默认 Zigbee 端口 6638、mDNS dongle.local。Zigbee2MQTT 写 tcp://，ZHA 写 socket://。

按报错找

完整接入步骤：Zigbee2MQTT 配置 Inswift 协调器 · 用 ZHA 把协调器接入 Home Assistant。

1. Zigbee2MQTT 串口怎么配

serial 要写对 port、adapter，USB 还要写 baudrate。MQTT 账号用你自己的 Mosquitto，不要照抄别人的用户名密码。

型号 → adapter → 端口

dongle.local 解析不了时改用局域网 IP。HA 附加组件走远程 TCP 时设 socat.enabled: false。USB 优先 by-id，不要只写 /dev/ttyUSB0 或 /dev/ttyACM0。ZHA 网络地址是 socket://dongle.local:6638，不要把 tcp:// 填进 ZHA。

复制：ETH TI（52P / 52P7）

mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://homeassistant.local:1883
  user: 你的MQTT用户名
  password: 你的MQTT密码
serial:
  port: tcp://dongle.local:6638
  # port: tcp://网关IP:6638
  adapter: zstack
socat:
  enabled: false

复制：ETH Silabs（MG21 / MG24 / POE）

mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://homeassistant.local:1883
  user: 你的MQTT用户名
  password: 你的MQTT密码
serial:
  port: tcp://dongle.local:6638
  # port: tcp://网关IP:6638
  adapter: ember
socat:
  enabled: false

复制：USB Silabs

mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://homeassistant.local:1883
  user: 你的MQTT用户名
  password: 你的MQTT密码
serial:
  port: /dev/serial/by-id/usb-XXXX_YYYY-if00-port0
  baudrate: 115200
  adapter: ember

USB Silabs 协调器 / 路由 / Multi-PAN 常见 115200；刷成 Thread 后常见 460800。以网关网页或固件说明为准，刷完不要沿用旧波特率。

官方说明：Zigbee2MQTT adapter 配置 · EmberZNet（芯科） · Z-Stack（TI）

2. ZHA 和 Zigbee2MQTT 不能同时占用同一个协调器

现象： Zigbee2MQTT 起不来、ZHA 时好时坏，或 Home Assistant 刚认出新设备就弹出 ZHA。

原因： 一个协调器（一台 USB dongle 或一台 ETH 网关）同一时间只能给一套协议栈用。

处理：

1. 先决定这个设备用 ZHA 还是 Zigbee2MQTT
2. 若 HA 自动建议了 Zigbee Home Automation，先删掉或停用那个 ZHA，再开 Z2M（反过来也一样）
3. 重启留下的那一套，确认串口或 dongle.local:6638 只有一个客户端
4. 用 Z2M 时 Mosquitto 要继续跑。MQTT 和 Z2M 是上下游，不是互斥

两个协调器可以各跑一套（例如 USB 给 ZHA、ETH 给 Z2M），那是两个独立 Zigbee 网。

官方说明：Zigbee2MQTT FAQ：协调器不能被其它程序占用 · Home Assistant ZHA 限制

3. MQTT 和 Zigbee2MQTT 可以一起开

Mosquitto（MQTT）与 Zigbee2MQTT 是上下游关系，需要同时运行：MQTT 做消息总线，Z2M 连 dongle。不要把「只能装一个 Z2M」理解成「不能开 MQTT」。

官方说明：Zigbee2MQTT MQTT 配置

4. Home Assistant 里只能有一个 Z2M

一台 HA 主机通常只保留一个 Zigbee2MQTT。如果以前在 MQTT 相关附加组件里装过 Z2M，先删掉旧的，再装现在要用的那一个。

5. 刷机或改配置后 ping 超时

现象： 日志出现 SRSP - SYS - ping after 6000ms、Ember HOST_FATAL_ERROR，或显示已连上 socket 立刻协议失败，尤其刚刷完固件。

原因： adapter、波特率、端口 和当前固件 / 网页 Serial settings 不一致，或还有别的程序占着。

处理：

1. adapter 对上芯片：ETH-52P / ETH-52P7（TI CC2652P / TI CC2652P7）用 zstack；ZBT-1P、ZBM-MG21 / MG24、ETH-MG21 / MG24（EFR32）用 ember 或 ezsp（见下一节）
2. 波特率 与固件、ETH 网页一致。USB 协调器常见 115200；Thread 固件常见 460800。刷完不要沿用旧值
3. 端口：USB 用 by-id；Z2M 网络用 tcp://dongle.local:6638（附加组件加 socat.enabled: false）；ZHA 用 socket://dongle.local:6638
4. 关掉第二个 Z2M、ZHA、串口助手
5. 若刚从 TI 换成 Silabs（或反过来），按下一节处理旧 backup

ETH-52P / ETH-52P7 的 ESP32 与 CC2652 可在网关网页升级，见 ETH-52 网页升级。

官方说明：Zigbee2MQTT：SRSP ping / HOST_FATAL_ERROR

6. 从 TI 换成 Silabs 后 Z2M 起不来

先用过 TI（ETH-52P / 52P7）再换成芯科（ZBM / ZBT-1P / ETH-MG）时，Zigbee2MQTT 里常留着旧的 coordinator backup。继续用 ezsp / ember 会失败，日志里可能出现连不上 adapter，例如 SRSP - SYS - ping after 6000ms。

处理：

1. 确认 adapter 已改成与当前 dongle 匹配的类型
2. 在 Zigbee2MQTT 数据目录里删掉旧的 coordinator backup，或卸掉插件后重装
3. 重启 Zigbee2MQTT

官方说明：Zigbee2MQTT FAQ：如何换协调器

7. Silabs 固件选 ezsp 还是 ember

芯科协调器的 adapter 同时看 Zigbee2MQTT 版本 和 NCP 固件（EZSP 协议）：

ember 从 Z2M 1.36.0 引入，现为官方推荐；ezsp 已弃用，只留给旧固件。

若日志出现 Adapter EZSP protocol version (12) is not supported by Host 13-16：当前 Z2M 在用 ember，但固件还是 EZSP v12。升级协调器固件到 7.4 以上，或暂时改回 ezsp。

刷机：USB 走 USB dongle 固件烧录；ETH-52P / ETH-52P7 网页升主机与 Zigbee 走 ETH-52 网页升级；网页进不去时 USB 刷 ETH 主机走 ETH dongle 固件升级。

官方说明：EmberZNet：adapter 配置（ezsp 已弃用） · EZSP 版本不匹配 · GitHub：ember 取代 ezsp

8. TI CC2652P / CC2652P7 开源方案请关掉 LED

用开源协议栈刷 TI CC2652P / CC2652P7（ETH-52P / ETH-52P7）时，请把 LED 关掉，避免干扰串口或被识别成异常设备。Zigbee2MQTT 可设 serial.disable_led: true。

官方说明：Z-Stack：disable_led · adapter 配置里的 disable_led

9. 摆放、USB 延长线和 2.4 GHz 干扰

现象： 入网困难、随机掉线，MAC channel access failure，或离协调器近的设备反而比远处的差。

原因： USB 3.0 / SSD / 2.4 GHz 噪声、短线插在主机后盖、Wi-Fi 信道重叠，或发射功率开到最大导致链路不对称。

处理：

1. 协调器尽量放在房屋中心，天线竖直
2. USB dongle 用 USB 2.0 延长线（至少 0.5–1 m，能到 1–2 m 更好），避开 USB 3.0 口和硬盘。见 部署位置与抗干扰
3. 离 Wi-Fi 路由器、微波炉等 2.4 GHz 干扰源大约 1 m 以上
4. Zigbee 信道尽量避开家里正用的 Wi-Fi（社区里常见 15 / 20 / 25，以你路由器实际信道为准）
5. 不要默认把发射功率拉到最高：太高时远处设备只听得到协调器、回不去

ETH / POE 网关同样要考虑摆放。从机柜里挪到房间中部，往往比再换一个芯片更有效。大户型优先 ETH 网线，再配常电的 Zigbee 路由（灯、插座）。

官方说明：Zigbee2MQTT：USB 延长线 · 避开 Wi-Fi 信道 · Home Assistant ZHA：抗干扰

10. 断电或路由重启后网关连不上

现象： ETH / POE / Wi-Fi 网关本来正常，路由器重启或停电后 Zigbee2MQTT 一直起不来，手动重启附加组件才好。

原因： 网关回来后，到 Zigbee 桥（端口 6638）的 TCP 会话不一定会自动重开。

处理：

1. 给网关做 DHCP 保留（或静态 IP）。dongle.local 断电后不稳时，改用 tcp://网关IP:6638 / socket://网关IP:6638
2. Zigbee2MQTT 打开 watchdog，adapter 路径失败时进程会自己恢复。见 Zigbee2MQTT watchdog
3. 可选：Home Assistant 自动化，等网关 IP ping 通后再重启 Z2M 附加组件
4. 先确认 http://dongle.local/ 或网关 IP 网页能打开，再查 Zigbee 配对

官方说明：Zigbee2MQTT：网口协调器稳定性

11. 换新协调器后设备全掉线

现象： 换了 Inswift dongle 或网关后设备全离线，入网超时，或日志提到 stateChangeInd / PAN ID 冲突。

原因： 旧协调器或路由还在广播同一张网，或把 TI zstack 的 backup 恢复到了芯科 Ember（反过来也不行）。

处理：

1. 关掉旧协调器（拔电，不要还挂在 USB 或局域网上）
2. 给家里的 Zigbee 路由断电 至少 15 秒（常电路灯、插座多时，拉一次总闸很常见）
3. 能恢复 backup 时，只恢复 同一芯片方案 的备份（TI 对 TI，Silabs 对 Silabs）
4. TI ↔ Silabs 对换：删掉不兼容的 coordinator_backup.json（或重装附加组件），准备重新配对，不要把 zstack backup 硬套到 Ember
5. 只启动新协调器，打开入网，需要时再 interview 设备

从另一个 TI CC2652 迁到 ETH-52P / ETH-52P7、想尽量免重新入网：复制旧 IEEE 再恢复 zstack 备份，见 ETH-52P / ETH-52P7修改IEEE(协调器迁移)。芯科 ETH-MG 走网页改 IEEE 并恢复 Ember 备份，见 ETH-MG web修改 IEEE（协调器迁移）。

官方说明：Zigbee2MQTT FAQ：如何换协调器 · Home Assistant ZHA：迁移到新适配器

12. Router 固件不是协调器

现象： 把 ETH-MG 或 USB dongle 刷成 Router，以为插上网线就能给 Zigbee 扩网；或者 ZHA / Z2M 认不出协调器。

原因： Router 模式只在 Zigbee 空中转发。网口、Wi-Fi 不会把 mesh 隧道过去。

处理：

1. 跑 ZHA 或 Zigbee2MQTT 的那一台，必须是 Coordinator 固件
2. Router 固件只用在额外的扩展节点上（例如第二台 ETH-MG）
3. Router 要在协调器 打开入网 后空中加入。只插网线不会扩 Zigbee
4. ETH-MG Router 的网页 Logs & Debug 见 ETH-MG Router 网页 CLI 调试。那是 CLI，不是协调器模式的 6638 端口

官方说明：Zigbee2MQTT FAQ：没有 Zigbee over IP · Router 是什么 · Coordinator 是什么

13. ZHA 删除重建失败

ZHA 里选「删除并重新创建」失败时，可停掉 ZHA，到 Home Assistant 配置目录删掉 zigbee.db、zigbee.db-shm、zigbee.db-wal，再重新添加 ZHA。操作前请备份。

14. Z2M 报找不到 fullchain.pem

日志类似：

MQTT failed to connect, exiting... (ENOENT: no such file or directory, open 'fullchain.pem')

这是 Zigbee2MQTT 的 MQTT 开了 TLS，但证书文件不存在。用 HA 本机 Mosquitto、走普通端口时，打开 configuration.yaml，删掉 mqtt 里的 cert / key（或 ca / fullchain.pem 相关项），保存后重启 Z2M。

官方说明：Zigbee2MQTT MQTT：TLS 证书路径

15. 第一次装 Z2M：先配串口

建议先只配 serial，MQTT 用已经装好的 Mosquitto，不必在首次向导里填一整份 MQTT。

1. 填好串口、波特率、adapter 后启动 Z2M
2. 日志出现 Starting Zigbee2MQTT... 后，打开网页界面
3. 网页里的 MQTT 信息与 Mosquitto 里一致，再提交并等待启动完成

官方说明：Zigbee2MQTT 入门：首次向导 · adapter 基本配置

16. Z2M 网页打不开

若 configuration.yaml 里是：

frontend:
  enabled: false
  port: 8080

前端不会启动，浏览器访问 8080 会 Connection refused。改成：

frontend:
  enabled: true
  port: 8080
  host: 0.0.0.0

局域网访问时建议再设 auth_token。保存后重启 Zigbee2MQTT。

官方说明：Zigbee2MQTT frontend：enabled / host / auth_token

17. 能不能这样做