把 Aqara/米家 Zigbee 设备接入 Home Assistant：ZHA 网关配置与回家离家自动化实战

摘要：本文以 Sonoff Dongle-P 协调器 + Home Assistant ZHA 集成为例，手把手讲解如何绕过厂商云网关，把 Aqara 门窗传感器、人体存在传感器与智能开关接入本地 HA，并落地"回家亮灯、离家布防"自动化。

为什么选 ZHA 而不是厂商多模网关

很多朋友家里已经有一两个 Aqara（绿米）或米家 Zigbee 设备，最初都是通过厂家的多模网关 + App 使用。这套方案胜在上手快，但有两个明显痛点：一是自动化逻辑必须依赖厂商云，断网就失效；二是跨品牌联动受限，Aqara 设备想和 Home Assistant 里的其它实体协作很别扭。

Home Assistant 的 ZHA（Zigbee Home Automation）集成则把 Zigbee 网络的控制权完全收回到本地。你只需要一个 Zigbee 协调器（USB 棒或网关联动器），就能直接管理所有符合 Zigbee 3.0 规范的设备，所有自动化都在 HA 本地运行，断网也能触发。本文实测 Aqara 的门窗传感器、FP1 人体存在传感器和单路智能开关都能被 ZHA 原生识别，无需额外插件。

准备工作：硬件与网络

一台已运行 Home Assistant OS 或 Container 的主机（本文基于 HA 2024.x，树莓派 4 或 x86 迷你主机均可）。
一个 Zigbee 协调器：推荐 Sonoff Dongle-P（基于 EFR32，firmware 建议刷到 ncp-uart-sw 最新版）或 Smlight SLZB-06 以太网协调器。
Aqara 设备若干，确保处于"未绑定到旧网关"的状态（旧网关里已删除/重置）。
不建议把协调器插在 HA 主机前置 USB 口紧贴金属机箱，Zigbee 天线会被屏蔽，建议用 USB 延长线引出来。

步骤一：准备 Zigbee 协调器

如果你用的是 Sonoff Dongle-P，到手后建议先更新固件。用 universal-silabs-flasher 工具：

pip install universal-silabs-flasher
universal-silabs-flasher flash --device /dev/ttyUSB0   --firmware nagami-efr32-zigbee-ncp-uart-sw-<版本>.gbl

刷完拔插一次。如果是 Smlight 以太网协调器，直接记下它的 IP 和端口（默认 6638），后续 ZHA 用 socket://IP:6638 连接即可，不用插 USB。

步骤二：在 Home Assistant 中启用 ZHA

进入设置 → 设备与服务 → 添加集成，搜索 "ZHA"。配置时传输方式选"串行"/"TCP socket"：

USB 协调器路径填 /dev/ttyUSB0（Container 部署需把设备映射到容器内，docker run 加 --device=/dev/ttyUSB0）。
以太网协调器填 socket://192.168.1.50:6638。

下一步选择"创建新的 Zigbee 网络"，等待约 10 秒，HA 会生成一个网络 PAN ID 和信道。建议把信道固定到 15 或 25，避开与 WiFi 2.4G（常用 1/6/11）重叠最严重的信道，能显著降低延迟和掉线。

步骤三：配对 Aqara 设备

在 ZHA 集成页面点"添加设备"，进入配对模式后，对 Aqara 设备执行重置：

门窗传感器：长按复位键 5 秒至指示灯快闪。
单路智能开关：快速拨动按键 5 次。
FP1 人体存在传感器：用取卡针长按底部复位孔。

设备出现后，HA 会自动加载实体：门窗传感器提供 binary_sensor（开/关），FP1 提供 device_tracker（有人/无人）和 illuminance 光照度，开关提供 switch 与 energy 功率（部分型号）。建议立刻在 ZHA 里点开设备，把"电量"实体加到仪表盘，方便监控纽扣电池余量。

步骤四：编写"回家/离家"自动化

核心思路是用手机 GPS 或路由器在线状态判断人在/离家。下面用 HA 自动化 YAML 实现"回家亮灯 + 离家关灯布防"：

automation:
  - alias: 回家亮灯
    trigger:
      - platform: state
        entity_id: device_tracker.iphone_liang
        to: "home"
    action:
      - service: light.turn_on
        target:
          entity_id: light.living_room
        data:
          brightness_pct: 80
          kelvin: 4000
      - service: switch.turn_on
        target:
          entity_id: switch.entrance
  - alias: 离家布防
    trigger:
      - platform: state
        entity_id: device_tracker.iphone_liang
        to: "not_home"
        for: "00:05:00"
    condition:
      - condition: state
        entity_id: binary_sensor.door_contact
        state: "off"
    action:
      - service: light.turn_off
        target:
          area_id: all
      - service: switch.turn_off
        target:
          entity_id: switch.entrance

注意 for: "00:05:00" 是防抖：GPS 短暂漂移导致"离家"误报时，5 分钟内回到 home 不会触发关灯。再加一个 condition 要求门窗已关，避免人还在家却误布防。

常见问题与避坑

配对搜不到设备：先确认设备已从旧网关解绑；把协调器用延长线远离 WiFi 路由器与金属机箱；配对时让设备尽量靠近协调器（1 米内）完成入网后再挪远。
设备频繁掉线：多半是 Zigbee 信道与 WiFi 冲突，或路由设备（插电的开关/插座）太少导致末端电池设备离协调器太远。多布几个常供电的 Zigbee 路由设备形成网状中继。
FP1 误报有人：雷达存在传感器对窗帘飘动、宠物敏感，在 ZHA 里把 occupancy_timeout 调到 30–60 秒，并用光照度做二次判定。

小结

用 ZHA 把 Aqara/米家 Zigbee 设备收编到 Home Assistant，是摆脱厂商云锁定、构建真正本地可控智能家居的关键一步。协调器选型、信道避开 WiFi、配对后建立路由中继，是稳定不掉线的三件套；回家/离家自动化则是最能体现本地智能价值的入门场景。后续你可以在此基础上叠加"夜间起夜柔光""无人自动关空调"等更复杂的自动化。