Install Zigbee2MQTT on Home Assistant simply

How to use Zigbee2MQTT on Home Assistant with a Mosquitto MQTT broker

After having shown you several solutions to install MQTT on a home automation box, it is high time to communicate our broker Mosquitto with another home automation must-have: the ZigBee protocol. To do this, we will simply install Zigbee2MQTT on Home Assistant.

NB: as is usually the case with home automation systems, there are several methods. We don't claim it's the best, but it's the one that we think is the easiest and quickest to set up.

What is Zigbee2MQTT?

If you are interested in the automation DIY, you must have heard of the ZigBee protocol. It must be said that with his network mesh and low consumption, it has everything to please. Normally, a ZigBee coordinator (gateway, hub, dongle, etc.) sends information from its network using HTTP requests, but even if it works perfectly, it's still not the most efficient method.

This is where the MQTT protocol comes in. In effect, MQTT is a much lighter protocol than HTTP, which does not require querying a server and requires much less data. It therefore allows faster and less greedy exchanges. Concretely, it is 90 times faster than HTTP protocol, need 10 times less energy to send messages and even up to 170 times less to receive them.

Hence the idea of ​​combining ZigBee and MQTT. To do this, we have Zigbee2MQTT, a gateway capable of receiving information from our ZigBee coordinator and send them to our MQTT broker in topic form. This allows different customers like Home Assistant, Homey, Jeedom or Domoticz to subscribe to these topics and read them.

In summary, Zigbee2MQTT is an interpreter that will translate the ZigBee protocol into MQTT language.

Requirements for Zigbee2MQTT

To work, Zigbee2MQTT will require a ZigBee coordinator and an MQTT broker.

  • An MQTT broker : we chose the broker Mosquito MQTT because it has always given us full satisfaction, but there are many others. As this is probably the most used in home automation, we can only advise you to do the same, especially since it is open source and therefore free.
  • A ZigBee coordinator : we are going to use the latest Sonoff ZigBee 3.0 dongle, because in addition to being offered at an unbeatable price, it proves to be particularly effective with its aluminum alloy case reducing interference and its high gain antenna of 20dBm. Nevertheless, you can absolutely turn to the well-known Phoscon Conbee 2 (very appreciated because plug & play), the famous ZiGate USB-TTL (its compatibility is still considered experimental to this day) or to CC2531 or CC2652 dongles (cheaper, but you will sometimes have to flash them). You will find the full list of compatible Zigbee2MQTT coordinators here.
Sonoff ZigBee Dongle Plus Review

Install Mosquitto MQTT on Home Assistant

Configure a broker

Before proceeding with the installation of Zigbee2MQTT, you must have an operational MQTT broker. With Home Assistant, nothing could be simpler, since there is an official add-on.

You will find it in:

 Supervisor > Add-ons > Add-ons Store

However, we advise you to install your Mosquitto MQTT broker separately. Indeed, in case of failure of your Home Assistant installation, your MQTT broker will remain operational. You can also use it with other applications and home automation systems such as Jeedom, Domoticz or even Homey Pro, to recite nobody else but them.

We have already addressed the issue several times and therefore invite you to consult the tutorial corresponding to your equipment:

Tutorial: install Mosquitto MQTT on Raspberry Pi
Tutorial: Install Mosquitto MQTT on Synology NAS

Import Zigbee2MQTT repository to Home Assistant

Installing Zigbee2MQTT on Home Assistant is really easy, you just need to click here.

Otherwise, go to:

Settings > Add-ons > Add-ons Store

Then, click on the three dots top right then select “Deposits” and enter the following address:

Install Zigbee2MQTT on Home Assistant

Two new add-ons have appeared in our add-ons, but Zigbee2mqq Edge being a version intended for developers, we will settle for the first one.

  • Select Zigbee2mqtt ;
  • Click on "Install";
  • Wait a few seconds.
There you go, the installation of Zigbee2MQTT is already complete! Don't turn it on yet, because we need to configure it first.

Configure Zigbee2MQTT

Let's talk about serious things ! It's time to plug your ZigBee dongle into a USB port of your Raspberry pi, Odroid, NUC or NAS.

For us, we will use the Sonoff ZBDongle-P which we highly recommend, but you can use a CC2531 or CC2652 dongle, Conbee II dongle, ZiGate USB-TTL, etc. The advantage of the Sonoff ZigBee 3.0 dongle is to be pre-flashed with the correct firmware and equipped with a 20 dBm antenna. It is also very stable and not subject to interference.

Here is our configuration for the Sonoff ZigBee 3.0 dongle:

homeassistant: false permit_join: true mqtt: base_topic: zigbee2mqtt server: 'mqtt://xxxxxxx' user: xxx password: xxxxxxx serial: port: /dev/ttyUSB0

For a ConBee II, RaspBee II or ZiGate key you can add:

serial: adapter: deconz 


serial: adapter: zigate

With that done, all we have to do is:

  • Click on Start Zigbee2MQTT ;
  • Click on "open web UI".

Wait a bit, it may be that the button of theZigbee2MQTT user interface takes a few minutes to arrive, but if all goes well you should have something that looks like this:

Of course, it's still empty. Let's see if everything works well by adding a few connected objects...

Pairing a Zigbee2MQTT device

To pair a device, nothing could be simpler, just click on the "Activate pairing (All)" button at the top right.

You now have 2 minutes 15 seconds precisely to put your device in pairing mode. In general, it is enough to hold a small button for 5 seconds or to press in a small hole using a needle. The association is then done very quickly and you will see one or more green notifications appear on the right of your screen.

Finally, we find our devices, here the brand new Aqara Motion Sensor P1:

We let you discover all the possible settings for each device, but you will see that they are often much more numerous than with proprietary hubs.

Finally, you can view the mesh of your ZigBee network in "Schematic" or "Map" if you are on an English version.

Here, we have so far only installed three devices and a coordinator, but you will find:

  • Blue Star : the coordinators or ZigBee Coordinators (ZC) who manage the network;
  • blue circle : the routers or ZigBee Routers (ZR) which will be able to send and receive information on their behalf and on behalf of the terminal devices;
  • green circle : terminals or ZigBee End Devices (ZED) which only send information and receive commands.
That's it, it's over! Your server Zigbee2MQTT is now operational. All you have to do is add all your ZigBee devices and enjoy the responsiveness of this system combining ZigBee and MQTT product for home automation without latency, without cloud and without worries!
Fascinated by Alexa since the day I received it in beta test, I gradually became passionate about the subject, before deciding to go further by creating a site with Jean-Christophe. An activity that allows me to quench my thirst for new technologies and share my discoveries about the nicest of communities: Les Alexiens.