Home Assistant

NOTE 1: This file has been generated, do not edit this file manually!

NOTE 2: If you are using the Zigbee2mqtt Hass.io add-on use their documentation

MQTT discovery

At least Home Assistant >= 0.84 is required!

NOTE: Groups are not auto-discovered, see configuration below.

The easiest way to integrate Zigbee2mqtt with Home Assistant is by using MQTT discovery. This allows Zigbee2mqtt to automatically add devices to Home Assistant.

To achieve the best possible integration (including MQTT discovery):

In your Zigbee2mqtt configuration.yaml set homeassistant: true

In your Home Assistant configuration.yaml:

mqtt:
discovery: true
broker: [YOUR MQTT BROKER]  # Remove if you want to use builtin-in MQTT broker
birth_message:
  topic: 'hass/status'
  payload: 'online'
will_message:
  topic: 'hass/status'
  payload: 'offline'

Mind you that if you want to use the embedded broker of Home Assistant you have to follow this guide.

Zigbee2mqtt is expecting Home Assistant to send it’s birth/will messages to hass/status. Be sure to add this to your configuration.yaml if you want Zigbee2mqtt to resend the cached values when Home Assistant restarts

Home Assistant device registry

When using Home Assistant MQTT discovery, Zigbee2mqtt integrates with the Home Assistant device registry. This allows you to change the Home Assistant device_id and friendly_name from the web interface without having to restart Home Assistant. It also makes it possible to show which entities belong to which device.

Changing name and device ID via web interface

Device registry

I’m confused about the different device IDs, names and friendly names

Home Assistant device_id: determined on first discovery of the device, can only be changed via the Home Assistant web interface afterwards. Used to control/read the state from the device (e.g. in automations)
Zigbee2mqtt friendly_name: used to change the MQTT topic where the device listens and publishes to.
Home Assistant name: name shown in the Home Assistant UI (unless overridden via a friendly_name in customize.yaml). If not changed via the Home Assistant web interface, it is equal to the Zigbee2mqtt friendly_name. Is updated if the Zigbee2mqtt friendly_name changes (requires restart of Home Assistant)
Home Assistant friendly_name (customize.yaml): overrides the name in the Home Assistant web interface.

Responding to button clicks

To respond to button clicks (e.g. WXKG01LM) you can use one of the following two Home Assistant configurations.

Via Home Assistant entity

automation:
  - alias: Respond to button click
    trigger:
      platform: state
      entity_id: sensor.my_switch_click
      to: 'single'
    action:
      entity_id: light.my_bulb_light
      service: light.toggle

Via MQTT

As an alternative to the above way of integrating, you can also listen to MQTT topics.

automation:
  - alias: Respond to button clicks
    trigger:
      platform: mqtt
      topic: 'zigbee2mqtt/<FRIENDLY_NAME'
    condition:
      condition: template
      value_template: '{{ "single" == trigger.payload_json.click }}'
    action:
      entity_id: light.bedroom
      service: light.toggle

Groups

Groups are not auto-discovered. Use the following configuration:

- platform: mqtt
  schema: json
  name: MY_GROUP
  command_topic: "zigbee2mqtt/[GROUP_FRIENDLY_NAME]/set"
  state_topic: "zigbee2mqtt/[GROUP_FRIENDLY_NAME]"

  // Modify according to features supported by all devices in group
  color_temp: true
  brightness: true
  rgb: true

Controlling Zigbee2mqtt via Home Assistant

The following Home Assistant configuration allows you to control Zigbee2mqtt from Home Assistant.

# Group
group:
  zigbee_group:
    view: false
    control: hidden
    name: Zigbee2mqtt
    entities:
      - input_boolean.zigbee_permit_join
      - timer.zigbee_permit_join
      - sensor.zigbee2mqtt_bridge_state
      - switch.zigbee2mqtt_main_join
      - automation.enable_zigbee_joining
      - automation.disable_zigbee_joining
      - automation.disable_zigbee_joining_by_timer
      - input_select.zigbee2mqtt_log_level
      - automation.zigbee2mqtt_log_level

# Input select for Zigbee2mqtt debug level
input_select:
  zigbee2mqtt_log_level:
    name: Zigbee2mqtt Log Level
    options:
     - debug
     - info
     - warn
     - error
    initial: info
    icon: mdi:format-list-bulleted

# Input boolean for enabling/disabling joining
input_boolean:
  zigbee_permit_join:
    name: Allow devices to join
    initial: off
    icon: mdi:cellphone-wireless

# Timer for joining time remaining (120 sec = 2 min)
timer:
  zigbee_permit_join:
    name: Time remaining
    duration: 120

# Sensor for monitoring the bridge state
sensor:
  - platform: mqtt
    name: Zigbee2mqtt Bridge state
    state_topic: "zigbee2mqtt/bridge/state"
    icon: mdi:router-wireless

# Switch for enabling joining
switch:
  - platform: mqtt
    name: "Zigbee2mqtt Main join"
    state_topic: "zigbee2mqtt/bridge/config/permit_join"
    command_topic: "zigbee2mqtt/bridge/config/permit_join"
    payload_on: "true"
    payload_off: "false"

# Automations
automation:
  - alias: Zigbee2mqtt Log Level
    initial_state: 'on'
    trigger:
      - platform: state
        entity_id: input_select.zigbee2mqtt_log_level
        to: debug
      - platform: state
        entity_id: input_select.zigbee2mqtt_log_level
        to: warn
      - platform: state
        entity_id: input_select.zigbee2mqtt_log_level
        to: error
      - platform: state
        entity_id: input_select.zigbee2mqtt_log_level
        to: info
    action:
      - service: mqtt.publish
        data:
          payload_template: '{{ states(''input_select.zigbee2mqtt_log_level'') }}'
          topic: zigbee2mqtt/bridge/config/log_level

  - id: enable_zigbee_join
    alias: Enable Zigbee joining
    hide_entity: true
    trigger:
      platform: state
      entity_id: input_boolean.zigbee_permit_join
      to: 'on'
    action:
    - service: mqtt.publish
      data:
        topic: zigbee2mqtt/bridge/config/permit_join
        payload: 'true'
    - service: timer.start
      data:
        entity_id: timer.zigbee_permit_join

  - id: disable_zigbee_join
    alias: Disable Zigbee joining
    hide_entity: true
    trigger:
    - entity_id: input_boolean.zigbee_permit_join
      platform: state
      to: 'off'
    action:
    - data:
        payload: 'false'
        topic: zigbee2mqtt/bridge/config/permit_join
      service: mqtt.publish
    - data:
        entity_id: timer.zigbee_permit_join
      service: timer.cancel

  - id: disable_zigbee_join_timer
    alias: Disable Zigbee joining by timer
    hide_entity: true
    trigger:
    - platform: event
      event_type: timer.finished
      event_data:
        entity_id: timer.zigbee_permit_join
    action:
    - service: mqtt.publish
      data:
        topic: zigbee2mqtt/bridge/config/permit_join
        payload: 'false'
    - service: input_boolean.turn_off
      data:
        entity_id: input_boolean.zigbee_permit_join

Zigbee Network Map (Custom Component)

https://github.com/rgruebel/ha_zigbee2mqtt_networkmap

Configuration when NOT using Home Assistant MQTT discovery

Visit the device page ((Supported devices, click on the model number)) to see the Home Assistant configuration when not using MQTT discovery.

zigbee2mqtt.io

📘 Zigbee2mqtt documentation