Zigbee 终端设备

zigbee 组件允许通过 Zigbee2MQTT 或 ZHA 将支持的 ESPHome 组件通过 Zigbee 网络暴露给 Home Assistant。 由于 Zigbee 协议的限制，仅暴露基本属性。其他属性必须在 Home Assistant 中手动配置。每个 ESPHome 实体消耗一个 Zigbee 端点。 单端点模式需要 ZHA 或至少 Zigbee2MQTT 2.8.0。对于旧版本的 Zigbee2MQTT，请使用多端点模式。 名称中的空格需要 ZHA 或至少 Zigbee2MQTT 2.8.0。对于旧版本的 Zigbee2MQTT，请勿使用空格。 支持的最大端点数为八个。

Zigbee 支持目前仅在 nRF52 平台上可用。

完整配置

# 示例配置条目
zigbee:
  id: my_zigbee
  on_join:
    then:
      - logger.log: "已加入网络"

binary_sensor:
  - platform: template
    name: "门 1"
  - platform: template
    name: "门 2"

配置变量

• wipe_on_boot (可选): 启动时擦除所有非易失性存储器数据，包括 Zigbee 网络配对和首选项（例如，最后的开关状态）。可选值：

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

• on_join (可选, 自动化): 设备加入网络时运行的自动化。

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

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

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

WARNING

过度使用 random 可能会通过创建许多”幽灵”设备来耗尽 Zigbee 协调器的内存。

动作

zigbee.factory_reset 动作

此动作触发 Zigbee 设备的恢复出厂设置。 它会处理离开 Zigbee 网络的操作。

on_...:
  then:
    - zigbee.factory_reset

支持的组件

二进制传感器配置

所有带有 name 的二进制传感器都会自动通过 Zigbee 暴露。

binary_sensor:
  - platform: template
    name: "门 1"
  - platform: template
    name: "门 2"
  - platform: template
    id: internal_sensor
  - platform: template
    name: "另一个内部传感器"
    internal: true

配置变量

• name (必需, string): 二进制传感器的名称。这将作为 Zigbee 端点描述暴露。
• internal (可选, boolean): 将此组件标记为内部。内部组件 不会通过 Zigbee 暴露。仅指定 id 而不指定 name 将隐式设置此值为 true。 如果 Zigbee 端点用尽，请使用此选项。

传感器配置

所有带有 name 的传感器都会自动通过 Zigbee 暴露。

sensor:
  - platform: template
    name: "模拟量 1"
    lambda: return 10.0;
    unit_of_measurement: "°C"
  - platform: template
    name: "模拟量 2"
    lambda: return 11.0;
  - platform: template
    id: internal_sensor
    lambda: return 9.0;
  - platform: template
    name: "另一个内部传感器"
    internal: true
    lambda: return 8.0;

配置变量

• name (必需, string): 传感器的名称。这将作为 Zigbee 端点描述暴露。
• internal (可选, boolean): 将此组件标记为内部。内部组件 不会通过 Zigbee 暴露。仅指定 id 而不指定 name 将隐式设置此值为 true。 如果 Zigbee 端点用尽，请使用此选项。
• unit_of_measurement (可选, string): 手动设置单位。默认情况下，值没有单位。 仅支持有限的单位集合。不支持的单位将恢复为无单位。 这将作为 Zigbee 端点工程单位暴露。

开关配置

所有带有 name 的开关都会自动通过 Zigbee 暴露。

switch:
  - platform: template
    name: "模板开关"
    optimistic: true

配置变量

• name (*必需, string): 开关的名称。这将作为 Zigbee 端点描述暴露。
• internal (可选, boolean): 将此组件标记为内部。内部组件 不会通过 Zigbee 暴露。仅指定 id 而不指定 name 将隐式设置此值为 true。 如果 Zigbee 端点用尽，请使用此选项。

数值配置

所有带有 name 的数值都会自动通过 Zigbee 暴露。

number:
  - platform: template
    name: "模板数值"
    optimistic: true
    min_value: 2
    max_value: 100
    step: 1

配置变量

• name (*必需, string): 数值的名称。这将作为 Zigbee 端点描述暴露。
• internal (可选, boolean): 将此组件标记为内部。内部组件 不会通过 Zigbee 暴露。仅指定 id 而不指定 name 将隐式设置此值为 true。 如果 Zigbee 端点用尽，请使用此选项。
• unit_of_measurement (可选, string): 手动设置单位。默认情况下，值没有单位。 仅支持有限的单位集合。不支持的单位将恢复为无单位。 这将作为 Zigbee 端点工程单位暴露。
• min_value (可选, float): 此数值可以设置的最小值。这将作为 Zigbee 端点最小当前值暴露。
• max_value (可选, float): 此数值可以设置的最大值。这将作为 Zigbee 端点最大当前值暴露。
• step (可选, float): 设置数值的粒度。这将作为 Zigbee 端点分辨率暴露。

另见

• Zigbee2MQTT
• Zigbee Home Automation