# 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](https://github.com/danielwelch/hassio-zigbee2mqtt) 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](https://www.home-assistant.io/docs/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`: ```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' ``` 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](https://developers.home-assistant.io/docs/en/device_registry_index.html). 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](../images/home_assistant_change_name.png) ![Device registry](../images/home_assistant_device_registry.png) ## 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 the following Home Assistant configuration: {% raw %} ```yaml automation: - alias: Respond to button clicks trigger: platform: mqtt topic: 'zigbee2mqtt/