Zigbee is a wireless protocol, like WiFi, but developed specifically for (battery powered) Internet-of-Things devices. Devices connect in a mesh network, where mains powered devices (e.g. light bulbs and smart plugs) act as repeaters to extend the range of the network. The Zigbee coordinator is at the heart of the Zigbee network and allows interconnectivity with non-Zigbee devices.

Home Assistant offers 2 Zigbee integrations: the built-in ZHA, and deCONZ which works via an add-on. Another popular alternative is Zigbee2MQTT which makes use of Home Assistant’s MQTT Discovery to create devices and entities in Home Assistant.

Which coordinator you use is up to you. I advise to check the Zigbee Device Compatibility Repository by Blakadder to check which coordinator supports the device you plan to buy.

This post will discuss the installation of Zigbee2MQTT as it makes use off a Docker container for the coordinator (we already installed the MQTT broker).

Note: This post got delayed somewhat because I had to wait for my USB extension cable to arrive. Without it, my Zigbee controller was experiencing interference from my 2.4GHz WiFi on my miniPC.

Install Zigbee2MQTT container

Locate Zigbee coordinator

In our Docker compose config, we’ll need to assign the Zigbee coordinator, which’ll be connected via USB, to the Docker container.

Plug in your Zigbee coordinator (e.g. Conbee II, Sonof Zigbee 3.0 Plus, …) into your machine. Then run the following command to get the unique path to the device.

ls -l /dev/serial/by-id/
usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_eexxxxxxxxxxxxxxxxxxxxxxxxxxxx52-if00-port0 -> ../../ttyUSB0

We’ll use this unique by-id path in our config later instead of the typical /dev/ttyUSB0 bevause there’s always a risk of the device getting a new TTY assigned after a reboot, espcially with other devices pluggin in as well.


We expand our docker-compose.yaml with the config for the Zigbee2MQTT container.


    container_name: zigbee2mqtt
    image: koenkk/zigbee2mqtt
    restart: unless-stopped
      - "8099:8099/tcp"
      - TZ=Europe/Brussels
      - /opt/zigbee2mqtt/data:/app/data
      - /run/udev:/run/udev:ro
      - /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_eexxxxxxxxxxxxxxxxxxxxxxxxxxxx52-if00-port0:/dev/ttyACM0

Note that I changed the port mapping for this container. Port 8080 is already in use by adminer so I changed the Zigbee2MQTT front-end port to 8099 (see below) and mapped that one in my Docker configuration.

We won’t start our container just yet, as we first want to setup our configuration.

Create MQTT user

When we set up the Mosquitto MQTT broker, I said I prefer to create a MQTT user per service. So let’s create a user for our Z2M container.

docker exec -it mosquitto mosquitto_passwd /mosquitto/config/mqttuser z2m_mqtt
Password:          # Enter a password
Reenter password:  # Repeat the password

cat mosquitto/config/mqttuser

Zigbee2MQTT config

To get a copy of the default config, run sudo wget in the folder where the config will be stored (/opt/zigbee2mqtt/data). Then open and edit it using sudo nano /opt/zigbee2mqtt/data/configuration.yaml.

We’ll tell Z2M to connect to our MQTT broker, use the syntax Home Assistant device detection understands, set up the webserver, and let Z2M generate some keys used to setup the Zigbee network.

More info on what the settings in this config do, can be found in the Z2M docs.

# Adapter settings
  port: /dev/ttyACM0

  base_topic: zigbee2mqtt
  server: '!secret server'
  user: '!secret user'
  password: '!secret password'
  client_id: zigbee

# Zigbee network
permit_join: false # Do not allow random devices to connect automatically

# Webserver
  port: 8099 # Custom port
  url: 'http://<>:8099' # Update IP here

# Devices and groups
# Extract config to separate files
devices: devices.yaml
groups: groups.yaml

# Home Assistant integration
homeassistant: true

  # Zigbee network - auto-generate new keys
  pan_id: GENERATE
  network_key: GENERATE
  # Zigbee network - set channel to avoid interference with 2.4GHz WiFi
  channel: 24

With this configuration in place, we can start the container using docker-compose up -d zigbee2mqtt.

If you check the logs via Portainer or docker-compose logs zigbee2mqtt, you’ll see our container start up nicely:

Using '/app/data' as data directory
Zigbee2MQTT:info  2022-10-04 12:09:47: Logging to console and directory: '/app/data/log/2022-10-04.12-09-47' filename: log.txt
Zigbee2MQTT:info  2022-10-04 12:09:47: Starting Zigbee2MQTT version 1.28.0 (commit #03ba647)
Zigbee2MQTT:info  2022-10-04 12:09:47: Starting zigbee-herdsman (0.14.62)
Zigbee2MQTT:info  2022-10-04 12:09:48: zigbee-herdsman started (resumed)
Zigbee2MQTT:info  2022-10-04 12:09:48: Coordinator firmware version: '{"meta":{"maintrel":1,"majorrel":2,"minorrel":7,"product":1,"revision":20220219,"transportrev":2},"type":"zStack3x0"}'
Zigbee2MQTT:info  2022-10-04 12:09:48: Currently 0 devices are joined:
Zigbee2MQTT:info  2022-10-04 12:09:48: Zigbee: disabling joining new devices.
Zigbee2MQTT:info  2022-10-04 12:09:48: Connecting to MQTT server at mqtt://<>:1883
Zigbee2MQTT:info  2022-10-04 12:09:48: Connected to MQTT server
Zigbee2MQTT:info  2022-10-04 12:09:48: MQTT publish: topic 'zigbee2mqtt/bridge/state', payload '{"state":"online"}'
Zigbee2MQTT:info  2022-10-04 12:09:48: Started frontend on port
Zigbee2MQTT:info  2022-10-04 12:09:48: MQTT publish: topic 'zigbee2mqtt/bridge/state', payload '{"state":"online"}'

Home Assistant

Repeating what we did in Part 3, Part 5, Part 6, Part 7, and Part 9, we add an entry for ESPHome to the sidebar of our Home Assistant dashboard using panel-iframe.

Add the following lines to configuration.yaml and restart Home Assistant.

  portainer:     # part 3
  nodered:       # part 5
  configurator:  # part 6
  duplicati:     # part 7
  esphome:       # part 9
    title: Zigbee2MQTT
    icon: mdi:zigbee
    require_admin: true
Zigbee2MQTT dashboard
Zigbee2MQTT dashboard without devices

Pressing the Permit join button on the top-right will temporarily allow any Zigbee device set to pairing mode to be picked up by our coordinator.

Permit Zigbee to join
Permit Zigbee to join

Controlling Z2M

Since Zigbee2MQTT’s configuration can be adapted over MQTT, we can control Z2M not only from the Frontend we just exposed, but also from within our dashboard. This is also explained in the Z2M Home Assistant integration docs.

First, we add some more YAML to our configuration.yaml via the Configurator. Copy and paste this code add the end of the file. If you’re used to splitting up your config and/or working with packages, you can put it in a zigbee2mqtt.yaml package file as well.

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

# Input number for joining time remaining (in minutes)
    name: "Zigbee2MQTT join minutes"
    initial: 2
    min: 1
    max: 5
    step: 1
    mode: slider

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

# Input boolean to set the force remove flag for devices
    name: Zigbee2MQTT Force Remove
    initial: false
    icon: mdi:alert-remove

# Scripts for renaming & removing devices
    alias: Zigbee2MQTT Rename
      service: mqtt.publish
        topic: zigbee2mqtt/bridge/request/device/rename
        payload_template: >-
            "from": "{{ states.input_text.zigbee2mqtt_old_name.state | string }}",
            "to": "{{ states.input_text.zigbee2mqtt_new_name.state | string }}"
    alias: Zigbee2MQTT Remove
      service: mqtt.publish
        topic: zigbee2mqtt/bridge/request/device/remove
        payload_template: >-
            "id": "{{ states.input_text.zigbee2mqtt_remove.state | string }}",
            "force": {% if states.input_boolean.zigbee2mqtt_force_remove.state == "off" %}false{% else %}true{% endif %}

# Timer for joining time remaining (254 sec)
    name: Time remaining
    duration: 254

    # Sensor for monitoring the bridge state
    - name: Zigbee2MQTT Bridge state
      unique_id: zigbee2mqtt_bridge_state_sensor
      state_topic: "zigbee2mqtt/bridge/state"
      icon: mdi:router-wireless
    # Sensor for Showing the Zigbee2MQTT Version
    - name: Zigbee2MQTT Version
      unique_id: zigbee2mqtt_version_sensor
      state_topic: "zigbee2mqtt/bridge/info"
      value_template: "{{ value_json.version }}"
      icon: mdi:zigbee
    # Sensor for Showing the Coordinator Version
    - name: Zigbee2MQTT Coordinator Version
      unique_id: zigbee2mqtt_coordinator_version_sensor
      state_topic: "zigbee2mqtt/bridge/info"
      value_template: "{{ value_json.coordinator.meta.revision }}"
      icon: mdi:chip
    - name: Zigbee2mqtt Networkmap
      unique_id: zigbee2mqtt_networkmap_sensor
      # if you change base_topic of Zigbee2mqtt, change state_topic accordingly
      state_topic: zigbee2mqtt/bridge/networkmap/raw
      value_template: >-
        {{ now().strftime('%Y-%m-%d %H:%M:%S') }}        
      # again, if you change base_topic of Zigbee2mqtt, change json_attributes_topic accordingly
      json_attributes_topic: zigbee2mqtt/bridge/networkmap/raw
  # Switch for enabling joining
    - name: "Zigbee2MQTT Main join"
      unique_id: zigbee2mqtt_main_join_switch
      state_topic: "zigbee2mqtt/bridge/info"
      value_template: '{{ value_json.permit_join | lower }}'
      command_topic: "zigbee2mqtt/bridge/request/permit_join"
      payload_on: "true"
      payload_off: "false"

  # Automation for sending MQTT message on input select change
  - 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/request/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
        duration: "{{ '00:0%i:00' % (states('input_number.zigbee2mqtt_join_minutes') | int ) }}"
  # 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_successful_interview"
    alias: Zigbee Device Joined Notification
      platform: mqtt
      topic: 'zigbee2mqtt/bridge/event'
      condition: template
      value_template: '{{trigger.payload_json.type == "device_interview" and == "successful" and}}'
      - service: persistent_notification.create
          title: Device joined the Zigbee2MQTT network
          message: "Name: {{}},
                    Vendor: {{}},
                    Model: {{}},
                    Description: {{}}"

Check your YAML config in the developer tools and restart Home Assistant.

Once that’s done, you can add a custom card to your Dashboard containing the following entries:

title: Zigbee2MQTT
type: entities
show_header_toggle: false
  - entity: sensor.zigbee2mqtt_bridge_state
  - entity: sensor.zigbee2mqtt_version
  - entity: sensor.zigbee2mqtt_coordinator_version
  - entity: input_select.zigbee2mqtt_log_level
  - type: divider
  - entity: switch.zigbee2mqtt_main_join
  - entity: input_number.zigbee2mqtt_join_minutes
  - 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: input_boolean.zigbee2mqtt_force_remove
  - entity: script.zigbee2mqtt_remove
Manage Zigbee2MQTT from Home Assistant
Manage Z2M from Home Assistant

Network map

Another nice thing to add to Home Assistant is a map of your connect Zigbee devices.

Since we don’t have any devices connected yet, this map will be fairly empty. However, you’ll enjoy seeing your network grow each time you add a new device :)

This will require you to add a custom card, either manually or using HACS. I suggest you have a look at the documentation of both to decide which method you prefer.

Zigbee2MQTT network map
Zigbee2MQTT network map

Don’t see the map or got an error about the custom card not existing? Clear your cache and refresh the page before trying again.