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 #

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):

  discovery: true
  broker: [YOUR MQTT BROKER]  # Remove if you want to use builtin-in MQTT broker
  # birth_message and will_message is not required anymore for Home Assistant 0.113 >=
    topic: 'hass/status'
    payload: 'online'
    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

Customizing discovery #

The device specifc configuration allows you to modify the discovery payload. Here you can also prevent a device from being discovered. See Device specific configuration for the available options.

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

Responding to button clicks #

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

MQTT device trigger is the recommended way to respond to button clicks. Note that it atleast requires Home Assistant 0.106.0.

The MQTT device triggers are discovered by Zigbee2MQTT once the event is triggered on the device once.

  - alias: Respond to button click
    - device_id: ad44cabee4c646f493814306aa6446e1
      discovery_id: 0x000b57fffecb472d action_arrow_left_click
      domain: mqtt
      platform: device
      subtype: arrow_left_click
      type: action
      entity_id: light.my_bulb_light
      service: light.toggle

If you only plan to use this and want to disable the Via Home Assistant entity integration below, set homeassistant_legacy_triggers: false (see Configuration for more info).

Via Home Assistant entity #

  - alias: Respond to button click
      platform: state
      entity_id: sensor.my_switch_click
      to: 'single'
      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.

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

Groups #

Groups are not auto-discovered. With the configuration below, grouped devices in Zigbee2MQTT will be exposed as a single device in Home Assistant. The following example will show you how to add a group of lights to Home Assistant. It has to be added to the Home Assistant configuration.yaml.

  - platform: mqtt
    schema: json
    name: MY_GROUP_NAME
    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.

You can add it to the appropriate section of your configuration.yaml, or you can add it as a Home Assistant Package by adding the following to zigbee2mqtt.yaml in your packages folder.

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

# Input text to input Zigbee2MQTT friendly_name for scripts
    name: Zigbee2MQTT Old Name
    name: Zigbee2MQTT New Name
    name: Zigbee2MQTT Remove

# Scripts for renaming & removing devices
    alias: Zigbee2MQTT Rename
      service: mqtt.publish
        topic: zigbee2mqtt/bridge/config/rename
        payload_template: >-
            "old": "{{ states.input_text.zigbee2mqtt_old_name.state | string }}",
            "new": "{{ states.input_text.zigbee2mqtt_new_name.state | string }}"
    alias: Zigbee2MQTT Remove
      service: mqtt.publish
        topic: zigbee2mqtt/bridge/config/remove
        payload_template: "{{ states.input_text.zigbee2mqtt_remove.state | string }}"

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

  # Sensor for monitoring the bridge state
  - platform: mqtt
    name: Zigbee2MQTT Bridge state
    state_topic: "zigbee2mqtt/bridge/state"
    icon: mdi:router-wireless
  # Sensor for Showing the Zigbee2MQTT Version
  - platform: mqtt
    name: Zigbee2MQTT Version
    state_topic: "zigbee2mqtt/bridge/config"
    value_template: "{{ value_json.version }}"
    icon: mdi:zigbee
  # Sensor for Showing the Coordinator Version
  - platform: mqtt
    name: Coordinator Version
    state_topic: "zigbee2mqtt/bridge/config"
    value_template: "{{ value_json.coordinator }}"
    icon: mdi:chip

# Switch for enabling joining
  - 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"

  # Automation for sending MQTT message on input select change
  - id: zigbee2mqtt_log_level
    alias: Zigbee2MQTT log level
    initial_state: "on"
      platform: state
      entity_id: input_select.zigbee2mqtt_log_level
      - service: mqtt.publish
          payload_template: "{{ states('input_select.zigbee2mqtt_log_level') }}"
          topic: zigbee2mqtt/bridge/config/log_level
  # Automation to start timer when enable join is turned on
  - id: zigbee_join_enabled
    alias: Zigbee Join Enabled
      platform: state
      entity_id: switch.zigbee2mqtt_main_join
      to: "on"
      service: timer.start
      entity_id: timer.zigbee_permit_join
  # Automation to stop timer when switch turned off and turn off switch when timer finished
  - id: zigbee_join_disabled
    alias: Zigbee Join Disabled
      - platform: event
        event_type: timer.finished
          entity_id: timer.zigbee_permit_join
      - platform: state
        entity_id: switch.zigbee2mqtt_main_join
        to: "off"
      - service: timer.cancel
          entity_id: timer.zigbee_permit_join
      - service: switch.turn_off
        entity_id: switch.zigbee2mqtt_main_join
  - id: "zigbee2mqtt_create_notification_on_successfull_interview"
    alias: Zigbee Device Joined Notification
      platform: mqtt
      topic: 'zigbee2mqtt/bridge/log'
      condition: template
      value_template: '{{trigger.payload_json.type == "pairing" and trigger.payload_json.message == "interview_successful"}}'
      - service: persistent_notification.create
          title: Device joined the Zigbee2MQTT network
          message: "Name: {{trigger.payload_json.meta.friendly_name}},
                    Vendor: {{trigger.payload_json.meta.vendor}},
                    Description: {{trigger.payload_json.meta.description}}"

The following is an example lovelace card configuration.

title: Zigbee2MQTT
type: entities
show_header_toggle: false
  - entity: sensor.zigbee2mqtt_bridge_state
  - entity: sensor.zigbee2mqtt_version
  - entity: sensor.coordinator_version
  - entity: input_select.zigbee2mqtt_log_level
  - type: divider
  - entity: switch.zigbee2mqtt_main_join
  - entity: timer.zigbee_permit_join
  - type: divider
  - entity: input_text.zigbee2mqtt_old_name
  - entity: input_text.zigbee2mqtt_new_name
  - entity: script.zigbee2mqtt_rename
  - type: divider
  - entity: input_text.zigbee2mqtt_remove
  - entity: script.zigbee2mqtt_remove

Zigbee Network Map (Custom Card) #

Zigbee Network Map Home Assistant Custom Card.

Zigbee Network Map (Custom Component) #

Zigbee Network Map Home Assistant addon.

NOTE: This addon is not password protected (if you have provided external access to your Home Assistant instance EVERYONE can access your Network Map).

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.