Zigbee Component

Zigbee is a low-power, mesh-based networking standard designed for IoT devices. Its low energy consumption makes it well-suited for battery-powered smart-home devices, while its limited bandwidth is ideal for devices that exchange only small amounts of data, such as switches, sensors, and motion detectors.

Zigbee uses the same RF technology as Thread (IEEE 802.15.4) but also defines multiple application standards. The zigbee component, however, supports only the Home Automation profile. It allows exposing supported ESPHome components over a Zigbee network to Home Assistant via Zigbee2MQTT or ZHA. Due to the limitations of the Zigbee protocol, only basic properties are exposed. Additional properties must be configured manually in Home Assistant. Each ESPHome entity consumes one Zigbee endpoint.

NOTE

You will need a Zigbee coordinator like Zigbee2MQTT or ZHA. Other commercial Zigbee hubs most likely do not support ESPHome components and might have issues with changing firmware. When using Zigbee2MQTT, make sure to use at least version 2.8.0. Otherwise, names cannot contain spaces. You also need to set up at least 2 endpoints in this case.

Supported Hardware

Zigbee is only supported on nRF52 platforms and on ESP32 with IEEE 802.15.4 connectivity (ESP32-C5, ESP32-C6, or ESP32-H2 and in the future ESP32-H4 and ESP32-H21). Both platforms support different features and have different limitations:

• On nRF52 a maximum of 8 endpoints is supported.
• ESP32-H2 seems to work more reliably than ESP32-C6. There are reports of ESP32-C6 boards that work only if placed next to the coordinator.
• On ESP32 Zigbee can be used together with WiFi with some limitations:
  • WiFi station mode + Zigbee end device is working fine.
  • WiFi station mode + Zigbee router leads to an unstable Zigbee network. Still can be used if WiFi is only enabled for short times (e.g. OTA)
  • WiFi access point + Zigbee is not supported

CAUTION

Whenever the configuration is changed, the device should be removed and re-added to the Zigbee network. For Zigbee2MQTT, the device must also be re-interviewed. This is especially important if components are added or removed or if names change. Sometimes a changed configuration can lead to boot loops. In this case use wipe_on_boot or erase the flash manually.

Full Configuration

# Example configuration entry on ESP32
zigbee:
  id: my_zigbee
  router: true

# Example configuration entry on nRF52
zigbee:
  id: my_zigbee
  on_join:
    then:
      - logger.log:
          format: "%s network."
          args: ['x ? "Joined" : "Rejoined"']
  power_source: BATTERY

Configuration variables

• model (Optional, string): Model Identifier of the Zigbee device. Defaults to the ESPHome node name.

• id (Optional, ID): The ID to use for this zigbee component.

• router (Optional, boolean): If true the Zigbee role will be router instead of end device and it will forward Zigbee packets from other devices. Routers drain more power than end devices and need to be always on for a stable Zigbee network. For this reasons battery-powered devices should not be used as routers. Defaults to false.

• power_source (Optional, enum): Indicates what kind of power the device uses. Affects sleep behavior. One of UNKNOWN, MAINS_SINGLE_PHASE, MAINS_THREE_PHASE, BATTERY, DC_SOURCE, EMERGENCY_MAINS_CONST, or EMERGENCY_MAINS_TRANSF. Defaults to DC_SOURCE.

• on_join (Optional, Automation): Automation to run when the device joins the network. In Lambdas you can get the join type with x. It is true for join and false for rejoin.

Only on nRF52:

• wipe_on_boot (Optional): Erases all non-volatile memory data on boot, including Zigbee network pairing and preferences (e.g., last switch state). One of:

  • false (default): Preserve data across reboots.
  • true: Erase all data on every boot. Use only for recovery from boot loops when you don’t have an SWD programmer.
  • once: Erase data only on first boot after flashing new firmware, then preserve.

• ieee802154_vendor_oui (Optional, int): Sets the Vendor Organizationally Unique Identifier (OUI). This allows replacing Nordic Semiconductor’s default company ID with your own. The value must be a 24-bit integer in the range 0x000000 to 0xFFFFFF. Alternatively, set to random to generate a new random OUI on every firmware compilation. This is useful during development to force the coordinator (ZHA/Z2M) to recognize the device as new after firmware updates.

• sleepy (Optional, boolean): Disable RX during idle to reduce power consumption for battery-powered devices. It may cause stability problems with the Zigbee connection. Defaults to false.

WARNING

Overusing random may exhaust memory in the Zigbee coordinator by creating many “ghost” devices.

Actions

zigbee.factory_reset Action

This action triggers a factory reset of the Zigbee device. It handles leaving the Zigbee network.

on_...:
  then:
    - zigbee.factory_reset

Zigbee Component Base Configuration

All components in ESPHome that do some sort of communication through Zigbee can have some overrides for specific options.

Configuration variables

• name (Required, string): The name for the component. This is exposed as the Zigbee description attribute.
• internal (Optional, boolean): Mark this component as internal. Internal components will not be exposed over Zigbee. Only specifying an id without a name will implicitly set this to true. Use this if you run out of Zigbee endpoints.

Only on ESP32:

• report (Optional, enum): Report the state. One of coordinator, enable, force. coordinator uses the configuration from the coordinator, enable activates reporting with default settings and uses the configuration from the coordinator if possible. force ignores the coordinator configuration and reports every change. On nRF52 the coordinator configuration is always used. Defaults to coordinator.

NOTE

ZHA sets the minimum reporting interval to 30 seconds for most sensor devices. If you need faster responses set report to force.

Supported Components

The following components are exposed over Zigbee if they have a name and if they are not marked as internal:

• Binary Sensor: only state and name are exposed over Zigbee.

• Sensor: state, name and unit_of_measurement are exposed over Zigbee. If no unit is given or if it is not supported it will fall back to unitless.

Only on nRF52:

• Switch: only state and name are exposed over Zigbee.

• Number: state, name, unit_of_measurement, min_value, max_value, and step are exposed over Zigbee. If no unit is given or if it is not supported it will fall back to unitless.

Component Implementation Details

Binary Sensor

Binary Sensors are implemented as binary input clusters with description and present_value attributes.

Sensor

Sensors are implemented as analog input clusters with description, engineering_units, and present_value attributes. On ESP32 additionally the application type attribute is set if applicable.

Additional configuration variables

• unit_of_measurement (Optional, string): Manually set or overwrite the unit. By default the unit of the component is used and if the component does not set a unit, values are unitless. Only a limited set of units is supported. Unsupported units will revert to unitless. This is exposed as the Zigbee engineering units attribute.

Switch

Switches are implemented as binary output clusters with description and present_value attributes. Available only on nRF52 platforms.

Number

Numbers are implemented as analog output clusters with description, engineering_units, and present_value attributes. Available only on nRF52 platforms.

Additional configuration variables

• unit_of_measurement (Optional, string): Manually set the unit. By default, values are unitless. Only a limited set of units is supported. Unsupported units will revert to unitless. This is exposed as the Zigbee engineering units attribute.
• min_value (Optional, float): The minimum value this number can be. This is exposed as the Zigbee min present value attribute.
• max_value (Optional, float): The maximum value this number can be. This is exposed as the Zigbee max present value attribute.
• step (Optional, float): The granularity with which the number can be set. This is exposed as the Zigbee resolution attribute.

See Also

• Zigbee2MQTT
• Zigbee Home Automation