Adding Zigbee2MQTT to Home Assistant lets you connect Zigbee devices without using separate brand hubs.
This can help you control lights, plugs, sensors, switches, and buttons from different brands in one place.
This setup needs an MQTT broker, a Zigbee coordinator, and the Zigbee2MQTT add-on.
Fortunately, the setup is not too difficult if you follow the steps carefully.
These include installing Mosquitto broker, installing Zigbee2MQTT, setting the adapter path, and starting the add-on.
In this guide, you will learn how to add Zigbee2MQTT to Home Assistant and what to check if it does not show up properly.
How To Add Zigbee2MQTT To Home Assistant
1. Plug In Your Zigbee Coordinator
Zigbee2MQTT needs a Zigbee coordinator before it can work.
Plug your Zigbee dongle into your Home Assistant device.
Use the USB extension cable if you have one.
Keep the dongle away from USB 3.0 ports.
Do not place it beside your Wi-Fi router.
Restart Home Assistant if the dongle is not detected.
2. Install Mosquitto Broker
Zigbee2MQTT uses MQTT, so you need an MQTT broker first.
Open Home Assistant.
Go to Settings.
Select Add-ons.
Open the Add-on Store.
Search for Mosquitto broker.
Click Install.
Start the add-on.
3. Install Zigbee2MQTT Add-on
After MQTT is ready, you can install Zigbee2MQTT.
Open Home Assistant.
Go to Settings > Add-ons.
Open the Add-on Store.
Add the Zigbee2MQTT repository if it is not already there.
Search for Zigbee2MQTT.
Click Install.
Wait until the installation is complete.
4. Find The Zigbee Adapter Path
You need the correct adapter path for Zigbee2MQTT.
Open Home Assistant.
Go to Settings > System.
Open Hardware.
Check All Hardware.
Look for your Zigbee dongle.
Copy the serial path.
Use the /dev/serial/by-id path if available.
5. Add The Adapter To Zigbee2MQTT
Now you need to tell Zigbee2MQTT which adapter to use.
Open the Zigbee2MQTT add-on.
Go to Configuration.
Find the serial section.
Paste the adapter path.
Add the correct adapter type if needed.
Save the configuration.
6. Start Zigbee2MQTT
After saving the settings, you can start the add-on.
Open the Zigbee2MQTT add-on.
Click Start.
Open Logs.
Wait for Zigbee2MQTT to start.
Check for any red error messages.
Open the Web UI if it starts properly.
7. Connect Zigbee2MQTT To Home Assistant
Zigbee2MQTT should show devices through MQTT.
Open Home Assistant.
Go to Settings > Devices & Services.
Check if MQTT is discovered.
Open the MQTT integration.
Make sure discovery is enabled.
Restart Home Assistant if devices do not appear.
8. Add Your First Zigbee Device
Once Zigbee2MQTT is running, you can pair your first device.
Open Zigbee2MQTT Web UI.
Click Permit Join.
Put the Zigbee device into pairing mode.
Wait for it to appear.
Rename the device.
Test it in Home Assistant.
Conclusion
Adding Zigbee2MQTT to Home Assistant is simple once the MQTT broker and Zigbee coordinator are ready.
You only need to install the add-on, set the adapter path, and start Zigbee2MQTT.
If something does not work, check the logs, adapter path, and MQTT broker.
Following these steps should help you add Zigbee2MQTT to Home Assistant.
Additional Reading
Zigbee2MQTT With Home Assistant: Complete Setup Guide
Zigbee2MQTT Not Starting In Home Assistant: How To Fix It
Sonoff Zigbee 3.0 USB Dongle Plus With Home Assistant Zigbee2MQTT
Brianna is based in Minnesota in the US at the moment, and has been writing since 2017. She is currently a 3rd Year med student at the time of writing this.
