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
sethomeassistant: 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.
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
- 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 afriendly_name
incustomize.yaml
). If not changed via the Home Assistant web interface, it is equal to the Zigbee2mqttfriendly_name
. Is updated if the Zigbee2mqttfriendly_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.
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
input_select:
zigbee2mqtt_log_level:
name: Zigbee2mqtt Log Level
options:
- debug
- info
- warn
- error
initial: info
icon: mdi:format-list-bulleted
# Input text to input Zigbee2mqtt friendly_name for scripts
input_text:
zigbee2mqtt_old_name:
name: Zigbee2mqtt Old Name
zigbee2mqtt_new_name:
name: Zigbee2mqtt New Name
zigbee2mqtt_remove:
name: Zigbee2mqtt Remove
# Scripts for renaming & removing devices
script:
zigbee2mqtt_rename:
alias: Zigbee2mqtt Rename
sequence:
service: mqtt.publish
data_template:
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 }}"
}
zigbee2mqtt_remove:
alias: Zigbee2mqtt Remove
sequence:
service: mqtt.publish
data_template:
topic: zigbee2mqtt/bridge/config/remove
payload_template: "{{ states.input_text.zigbee2mqtt_remove.state | string }}"
# Timer for joining time remaining (120 sec = 2 min)
timer:
zigbee_permit_join:
name: Time remaining
duration: 120
sensor:
# 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
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"
automation:
# Automation for sending MQTT message on input select change
- alias: Zigbee2mqtt Log Level
initial_state: "on"
trigger:
platform: state
entity_id: input_select.zigbee2mqtt_log_level
action:
- service: mqtt.publish
data:
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
hide_entity: true
trigger:
platform: state
entity_id: switch.zigbee2mqtt_main_join
to: "on"
action:
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
hide_entity: true
trigger:
- platform: event
event_type: timer.finished
event_data:
entity_id: timer.zigbee_permit_join
- platform: state
entity_id: switch.zigbee2mqtt_main_join
to: "off"
action:
- service: timer.cancel
data:
entity_id: timer.zigbee_permit_join
- service: switch.turn_off
entity_id: switch.zigbee2mqtt_main_join
The following is an example lovelace card configuration.
title: Zigbee2mqtt
type: entities
show_header_toggle: false
entities:
- 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.