Zigbee 组件

Zigbee 是一种专为 IoT 设备设计的低功耗、基于网格的网络标准。其低能耗使其 非常适合电池供电的智能家庭设备，而其有限的带宽则适合仅交换 少量数据的设备，如开关、传感器和运动探测器。

Zigbee 与 Thread（IEEE 802.15.4）使用相同的射频技术，但还定义了多个应用标准。 然而，zigbee 组件仅支持 Home Automation 配置文件。 它允许通过 Zigbee 网络将受支持的 ESPHome 组件暴露给 Home Assistant，使用 Zigbee2MQTT 或 ZHA。由于 Zigbee 协议的限制，仅暴露基本属性。 其他属性必须在 Home Assistant 中手动配置。

NOTE

你需要一个像 Zigbee2MQTT 或 ZHA 这样的 Zigbee 协调器。其他商业 Zigbee 网关很可能不 支持 ESPHome 组件，并且可能在更换固件时出现问题。 使用 Zigbee2MQTT 时，请确保至少使用 2.8.0 版本。否则，名称不能包含空格。 在这种情况下，你还需要设置至少 2 个端点。

支持的硬件

Zigbee 仅在 nRF52 平台和具有 IEEE 802.15.4 连接能力的 ESP32（ESP32-C5、ESP32-C6 或 ESP32-H2，以及未来的 ESP32-H4 和 ESP32-H21）上受支持。两个平台支持不同的功能，有不同的限制：

• 在 nRF52 上最多支持 8 个端点，每个 ESPHome 实体占用一个 Zigbee 端点。
• 在 ESP32 上最多支持 239 个端点，ESPHome 实体在 Zigbee 端点上合并。
• ESP32-H2 似乎比 ESP32-C6 工作更可靠。有报告称 ESP32-C6 板只有在放在 协调器旁边时才能工作。
• 在 ESP32 上，Zigbee 可以与 WiFi 一起使用，但有一些限制：
  • WiFi station 模式 + Zigbee end device 工作正常。
  • WiFi station 模式 + Zigbee router 会导致 Zigbee 网络不稳定。如果 WiFi 只在短时间内启用（例如 OTA）仍可以使用
  • WiFi access point + Zigbee 不受支持

CAUTION

每当配置更改时，设备应从 Zigbee 网络中移除并重新添加。 对于 Zigbee2MQTT，还必须重新访谈设备。在添加或删除组件或名称更改时，这一点尤其重要。 更改后的配置有时会导致启动循环。此时请使用 wipe_on_boot 或手动擦除 Flash。

完整配置

# ESP32 上的示例配置条目
zigbee:
  id: my_zigbee
  router: true

# nRF52 上的示例配置条目
zigbee:
  id: my_zigbee
  on_join:
    then:
      - logger.log:
          format: "%s network."
          args: ['x ? "Joined" : "Rejoined"']
  power_source: BATTERY

配置变量

• model (可选, string): Zigbee 设备的模型标识符。默认为 ESPHome 节点名称。

• id (可选, ID): 用于此 zigbee 组件的 ID。

• router (可选, boolean): 如果为真，Zigbee 角色将为 router 而不是 end device，它将 转发来自其他设备的 Zigbee 数据包。路由器比 end device 消耗更多电力，并且需要始终开启 才能保持 Zigbee 网络稳定。出于这些原因，电池供电的设备不应作为路由器使用。 默认为 false。

• power_source (可选, enum): 指示设备使用的电源类型。影响 睡眠行为。可选 UNKNOWN、MAINS_SINGLE_PHASE、MAINS_THREE_PHASE、BATTERY、 DC_SOURCE、EMERGENCY_MAINS_CONST 或 EMERGENCY_MAINS_TRANSF。默认为 DC_SOURCE。

• on_join (可选, Automation): 设备加入网络时要运行的自动化。 在 Lambdas 中，你可以使用 x 获取加入类型。对于加入，它是 true；对于重新加入，它是 false。

仅在 nRF52 上：

• wipe_on_boot (可选): 在启动时擦除所有非易失性存储器数据，包括 Zigbee 网络配对和偏好（例如，上次开关状态）。可选：

  • false（默认）：在重启之间保留数据。
  • true：每次启动时擦除所有数据。仅在没有 SWD 编程器时，从启动循环中恢复使用。
  • once：在刷写新固件后首次启动时擦除数据，然后保留。

• ieee802154_vendor_oui (可选, int): 设置供应商组织唯一标识符（OUI）。 这允许用你自己的 ID 替换 Nordic Semiconductor 的默认公司 ID。 值必须是 0x000000 到 0xFFFFFF 范围内的 24 位整数。 或者，设置为 random 以在每次固件编译时生成一个新的随机 OUI。 这在开发过程中很有用，可以强制协调器（ZHA/Z2M）在固件更新后 将设备识别为新设备。

• sleepy (可选, boolean): 空闲时禁用 RX 以减少电池供电设备的功耗。 可能会导致 Zigbee 连接的稳定性问题。默认为 false。

WARNING

过度使用 random 可能会通过在 Zigbee 协调器中创建大量”幽灵”设备而耗尽内存。

动作

zigbee.factory_reset 动作

此 action 触发 Zigbee 设备的出厂重置。 它处理离开 Zigbee 网络的操作。

on_...:
  then:
    - zigbee.factory_reset

Zigbee 组件基础配置

ESPHome 中所有通过 Zigbee 进行某种通信的组件都可以对一些特定选项进行覆盖。

配置变量

• name (必选, string): 组件的名称。这会作为 Zigbee 描述属性暴露。
• internal (可选, boolean): 将此组件标记为内部。内部组件将 不会通过 Zigbee 暴露。仅指定 id 而不指定 name 将隐式将其设为 true。 如果你用完了 Zigbee 端点，可以使用此选项。

仅在 ESP32 上：

• report (可选, enum): 状态报告的方式。可选 default 或 force。default 使用默认设置激活报告 并尽可能使用协调器的配置。force 对每次更改向协调器发送手动报告。 在 nRF52 上，总是使用协调器的配置。 默认为 default。

NOTE

ZHA 将某些传感器设备的最小报告间隔设置为 30 秒。如果需要更快的响应，请将 report 设置为 force。

• endpoint (可选, int): 1 到 239 范围内的端点编号。这定义了哪个实体放在哪个 端点上，提供更稳定的配置，让你手动组合在逻辑上属于一起的实体。 只有映射到不同 Zigbee 集群的实体才能组合（例如 binary_sensor 和 sensor）； 相同类型的两个实体（如两个传感器）不能共享一个端点。如果端点上有多个实体 具有 Zigbee 设备类型，请将其中的一个设置为 use_device_type: true。
• use_device_type (可选, boolean): 使用此实体的 Zigbee Home Automation 设备类型作为端点。 某些实体有一个 设备类型 ，可供第三方设备发现设备功能。通常应在端点的主要 实体上设置此选项。将其设置为 false 以移除实体的设备类型。在这种情况下，或者如果 实体没有自己的设备类型，端点将使用通用 CUSTOM_ATTR 类型。要暴露实体给 Home Assistant，不需要设备类型。每个端点只能在一个实体上设置为 true。

支持的组件

如果以下组件有名称且未标记为内部组件，则它们将通过 Zigbee 暴露：

• 二进制传感器：仅 状态 和 名称 通过 Zigbee 暴露。

• Sensor：状态、名称 和 unit_of_measurement 通过 Zigbee 暴露。如果未指定单位或不支持，将回退为无单位。

仅在 nRF52 上：

• Switch：仅 状态 和 名称 通过 Zigbee 暴露。

• Number：状态、名称、unit_of_measurement、min_value、max_value 和 step 通过 Zigbee 暴露。如果未指定单位或不支持，将回退为无单位。

组件实现细节

二进制传感器

二进制传感器 实现为具有 description 和 present_value 属性的二进制输入集群。

Sensor

Sensors 实现为具有 description、engineering_units 和 present_value 属性的模拟输入集群。在 ESP32 上，如果适用，还会设置 application type 属性。

附加配置变量

• unit_of_measurement (可选, string): 手动设置或覆盖单位。默认 使用组件的单位，如果组件未设置单位，值将无单位。 仅支持有限的单位集合。不支持的单位将回退为无单位。 这会作为 Zigbee engineering units 属性暴露。

Switch

Switches 实现为具有 description 和 present_value 属性的二进制输出集群。 仅在 nRF52 平台上可用。

Number

Numbers 实现为具有 description、engineering_units 和 present_value 属性的模拟输出集群。仅在 nRF52 平台上可用。

附加配置变量

• unit_of_measurement (可选, string): 手动设置单位。默认值无单位。 仅支持有限的单位集合。不支持的单位将回退为无单位。 这会作为 Zigbee engineering units 属性暴露。
• min_value (可选, float): 此数字的最小值。这会作为 Zigbee min present value 属性暴露。
• max_value (可选, float): 此数字的最大值。这会作为 Zigbee max present value 属性暴露。
• step (可选, float): 数字可设置的粒度。这会作为 Zigbee resolution 属性暴露。

参见

• Zigbee2MQTT
• Zigbee Home Automation