Zigbee2MQTT

Zigbee2MQTT is a universal and open-source solution for running a Zigbee mesh network for a smart home. It can be operated both within Home Assistant and completely standalone.

I assume you are already familiar with the basics of Zigbee and so you should start by choosing a coordinator suitable for Zigbee2MQTT.

Choosing a Coordinator - Recommended Hardware

Zigbee2MQTT supports all three types of coordinator firmware - EZSP, DECONZ, and ZSTACK.

1. Coordinators Based on EmberZNet from Silicon Labs - EZSP

The best choice currently is coordinators based on the EFR32MG21 chip and using the EZSP protocol. The chip should allow and support the Thread protocol in the future. This chip is also used by the creators of Home Assistant for their products.

Sonoff Zigbee 3.0 USB Dongle Plus E

USB adaptér pro připojení Zigbee zařízeních k chytré domácnosti.

799 Kč

Alza.cz

Zigbee ZB-GW04 Adapter

231 Kč

Aliexpress

Home Assistant SkyConnect

USB adaptér pro připojení Zigbee / Thread zařízeních k chytré domácnosti od tvůrců Home Assistanta.

999 Kč

Alza.cz

Which EFR32MG21 Products Do I Use?

I currently use SkyConnect from Home Assistant mainly because I wanted to be prepared for Thread support directly in Home Assistant as soon as possible.

End of Support for EZSP Firmware 6.x and < 7.4

In future versions of Zigbee2MQTT, support for the ezsp driver for adapters with EZSP firmware 6.x and < 7.4 will be discontinued. It is therefore advisable to update the firmware now (if needed) and switch the driver to ember. It may seem complicated, but fortunately, it is not that difficult, and you will not need to disassemble anything. How to do it can be found below in the chapter Updating Firmware of EZSP Coordinators

ezsp: Deprecated driver 'ezsp' currently in use, 'ember' will become the officially supported
EmberZNet driver in the next release

2. Coordinators Based on deCONZ from Dresden Elektrik - DECONZ

Phoscon ConBee III

New version of USB dongle using EFR32MG21

40,6 EUR

Amazon.de

Phoscon ConBee II

USB dongle

25 EUR

Amazon.de

Phoscon RaspBee II

Raspberry PI shield

32,5 EUR

Amazon.de

Which deCONZ Products Do I Use?

I have both II generation products from deCONZ, but if you don't have a specific reason, I recommend the ConBee III today.

3. Coordinators from Texas Instruments - ZSTACK

The oldest chips, which I recommend only if you really want to save money. Firmware needs to be flashed, so it is not suitable for regular users.

• CC2652P/R/RB USB dongle with flashed firmware coordinator from Z-stack
• CC1352P/R USB dongle with flashed firmware coordinator from Z-stack

Which Texas Instruments Products Do I Use?

In the past, I used the CC2531, which is now outdated, and its range was not the best. Currently, I do not use any product from this range.

Updating Firmware of EZSP Coordinators

info

This chapter only applies to EZSP coordinators. If you plan to or have another one, you can skip it and continue with the next Installing the Coordinator.

If you have a Zigbee adapter from Sonoff or ZB-GW04, I recommend checking the firmware version installed in this adapter. If you have a version lower than 7.4, you may soon have a problem. The new version also offers faster response and improved network stability.

EZSP Sonoff or ZB-GW04

1. Connect the adapter to the computer via USB.

2. Make sure no application or process is using this adapter on the computer.

3. Open a Chrome-based browser and go to darkxst.github.io/silabs-firmware-builder

4. Find your adapter - for EFR32MG21, you need to find out the version 1.1 or 1.2 - it is written directly on the adapter board.

5. Click on Connect, and after a while, a dialog with your version and the latest available should appear. Click on Upgrade.

   

6. The new firmware will start installing - do not disconnect the adapter or turn off the computer!

   

7. It's done!

EZSP Home Assistant ZBT-1 (SkyConnect)

This adapter should already have EZSP 7.x, but for Zigbee2MQTT and ember, you will need at least 7.4. I recommend updating through the Silicon Labs Flasher add-on.

1. Install the Silicon Labs Flasher add-on

   

2. Disable the ZHA integration or turn off Zigbee2MQTT, depending on what you are using.

3. In the add-on settings, select the adapter.

   

4. Run the add-on and check the logs to see if everything went well. The add-on will turn off automatically.

5. Re-enable ZHA or start Zigbee2MQTT.

6. It's done!

Adapters with EZSP 7.4 and higher use the ember setting in Zigbee2MQTT instead of the original ezsp. Zigbee2MQTT does not allow simultaneous use of Zigbee and Thread, i.e., adapters with multiprotocol EZSP firmware are not supported.

Installing the Coordinator

I will assume you have chosen one of the USB coordinators, and then the installation is quite simple. Just insert the USB coordinator into one of the USB ports.

In the case of Raspberry, I recommend using USB 2.0 ports (the black ones), and it is generally better to connect the coordinator to the computer via a USB extension cable - both to reduce interference.

Vention USB 3.0 Male to Female Extension Cable 0.5m Black

Prodlužovací kabel USB 3.0

119 Kč

Alza.cz

Installing Software in Home Assistant

The installation is quite multi-step and can get stuck at several steps. However, if you follow the manual below, you should not be surprised.

1. Installing the HA MQTT Add-on

First, we will install the broker (message catcher), which is essential for Zigbee2MQTT.

1. In Home Assistant, select Settings -> Add-ons -> Add-on Store and find MQTT in the list and click Install.

   

2. Switch to the add-on settings and in the logins section, add username and password for MQTT:

   - username: smarthome
     password: smarthome

3. Start the add-on.

2. Installing the HA Zigbee2MQTT Add-on

1. In Home Assistant, select Settings -> Add-ons -> Add-on Store and in the menu in the top right corner with three dots, select Repositories and add: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt

   Zigbee2MQTT Repository

   Zigbee2MQTT is not part of the standard add-on repositories in Home Assistant

   Or click on:

   

2. Find Zigbee2MQTT in the list and click Install.

   

3. Switch to the add-on settings and in the mqtt section, change the settings to:

   server: mqtt://core-mosquitto:1883
   user: smarthome
   password: smarthome

   and also adjust the serial section - enter the ID of your USB dongle in the port.

   Example for Phoscon ConBee II

   serial:
   port: >-
       /dev/serial/by-id/usb-dresden_elektronik_ingenieurtechnik_GmbH_ConBee_II_DEXXXXXX-if00
   adapter: deconz

   Example for Zigbee ZB-GW04 Adapter with older firmware EZSP 6.x and less than 7.4

   port: /dev/serial/by-id/usb-1a86_USB_Serial-if00-port0
   adapter: ezsp

   If you still have this firmware, you should definitely upgrade, as support for ezsp will be removed in the future.

   Example for Zigbee ZB-GW04 Adapter with newer firmware EZSP 7.4 and newer

   port: /dev/serial/by-id/usb-1a86_USB_Serial-if00-port0
   adapter: ember
   Settings for Different Coordinators

   The port name can be found, for example, using the menu in Home Assistant - Settings -> System -> Hardware -> All hardware and find the ttyU item

   

   The adapter setting varies depending on the chip used (category see above list of coordinators):

   • EmberZNet from Silicon Labs - ezsp for firmware EZSP 6.x and < 7.4, ember for firmware 7.4 >= (SkyConnect, Sonoff ...)
   • deCONz - deconz (ConBee coordinators)
   • Zstack - zstack
   Zigbee2MQTT 2.0>

   The adapter setting is mandatory in Zigbee2MQTT from version 2.0. If you are using a previous version and did not have this attribute set, you need to add it, otherwise, Zigbee2MQTT will not start. zstack is no longer the default value.

   Details of the changes

4. Start the add-on and set it to be in the sidebar.

   In the logs, we should see:

   Zigbee2MQTT:info  2023-12-30 18:51:54: Zigbee2MQTT started!

3. Integration into Home Assistant

Integration into Home Assistant is done indirectly through the MQTT add-on. If we did everything correctly, MQTT should automatically appear among the discovered integrations, and we just need to click on set up.

If it doesn't work, we can add MQTT manually and fill in the details:

Pairing a New Device

While the installation into Home Assistant for Zigbee2MQTT is a bit more complicated, pairing new devices is the easiest.

Just select Zigbee2MQTT in the sidebar and click Permit join (All) on the main screen. The new device should appear in the list within a few seconds.

Device Naming System

Unfortunately, the default naming system is not very smart and contains a unique device address, which is not very descriptive.

Similarly, pairing a battery-powered Aqara motion sensor from the Chinese manufacturer Xiaomi will work.

Displaying the Zigbee Network Diagram

Once you have more Zigbee devices, it will become more difficult to keep track of them. Here, Zigbee2MQTT lags a bit and seems to be the worst of all solutions.

The Zigbee network diagram needs to be regenerated each time in the Map menu and the Load map option. This can take several seconds to minutes, depending on the size of the network.

• Coordinator - blue star
• Zigbee devices under constant power - blue circle with a device photo
• Battery-powered Zigbee devices - green circle with a device photo

Enabling Device Availability Polling

By default, Zigbee2MQTT disables device availability polling in the network to reduce traffic on the Zigbee network. However, if you don't have an extremely large network, it can be useful to have this feature enabled. For example, I use it to receive notifications about device outages directly from Home Assistant automation.

We can enable the feature directly from the Zigbee2MQTT UI. Go to Settings -> Availability, check the Enabled option, and confirm with the Submit button.

Or we can make the change directly in the configuration.yaml file.

availability:
  enabled: true

Temporarily Disabling a Device in the Zigbee Network

If a device in the Zigbee network becomes unavailable, for example, if you use it only seasonally, and you have the device availability polling feature enabled, it will have the undesirable effect of constantly displaying an error message.

We can get rid of this problem by disabling the device in the Zigbee network. In the specific device settings, check the Disabled option.

The device will be excluded from all status queries (including the network map), and we will get rid of the above error. In the device list, we can recognize the disabled device by the strikethrough on the image and the Disabled status.

If you prefer to write directly to the configuration.yaml file, you can do so in the devices section by adding the disabled: true option.

devices:
  ...
  '0xa4c1381a9e6ce8fc':
    friendly_name: '0xa4c1381a9e6ce8fc'
    disabled: true
  ...

Changing the Zigbee Channel

Properly setting the Zigbee network channel is crucial to minimize interference from WiFi networks, which operate on the same frequency band.

Channel overlap can lead to a significant reduction in the performance of both networks and problems with poor response from individual devices in the smart home. I recommend finding out which channel has the most WiFi networks and choosing the one that is least occupied.

WiFi channels are much wider, so we only have three in the 2.4GHz band, while there are 16 Zigbee channels. I recommend choosing channels at the interface of WiFi channels, i.e., Zigbee channels 11, 15, 20, or 25.

Mapping WiFi vs. Zigbee Channels

Setting in Home Assistant

1. In the main left menu of Home Assistant, click on Zigbee2MQTT and select Settings

2. Click on the Advanced item

3. Manually enter the Zigbee channel.