Beginners Guide To Home Assistant Zigbee2MQTT Setup

When used together, Zigbee2MQTT and Home Assistant allow you to easily control and automate your Zigbee devices, such as lights, switches, thermostats, and sensors, using Home Assistant’s user-friendly interface and powerful automation capabilities.

By using Zigbee2MQTT as a bridge between Zigbee devices and Home Assistant, you can avoid the need for a proprietary hub, which can provide cost savings as well as more flexibility and control over your home automation system.

In this blog post, I will guide you through the requirements of the Zigbee2MQTT Home Assistant add-on setup and provide step-by-step instructions on how to get Zigbee2MQTT installed and fully working with Home Assistant.

What is Zigbee2MQTT?

Zigbee2MQTT is an open-source software that allows you to connect Zigbee devices to your home automation system using MQTT (Message Queuing Telemetry Transport) protocol. It serves as a bridge between Zigbee devices and your home automation software, allowing you to control and automate your devices without the need for a proprietary hub.

What is Home Assistant?

Home Assistant is an open-source home automation platform that allows you to control and automate various devices and services in your home. It supports a wide range of devices and protocols, including Zigbee through the use of add-ons or integrations.

The benefits of using a Zigbee-based home automation system

A Zigbee-based home automation system offers several benefits, including:

• Interoperability: Zigbee devices are designed to work together, regardless of the brand or manufacturer. This allows for a more flexible and expandable system, as you can mix and match devices from different vendors.
• Low power consumption: Zigbee devices use very little power, which makes them ideal for battery-powered devices such as sensors and remotes.
• Long-range communication: Zigbee devices can communicate over longer distances than other wireless protocols, such as Bluetooth or Wi-Fi, which makes them suitable for larger homes or buildings.
• Reliability: Zigbee operates on a mesh network, which means that data is passed from device to device until it reaches its destination. This improves the reliability of the network, as the data can be rerouted if one device fails.
• Cost-effective: Zigbee devices are generally less expensive than other smart home devices that use different protocols such as Z-Wave or WiFi.
• Security: Zigbee devices use advanced security features to protect against unauthorized access and tampering, which makes them a secure option for home automation systems.

Why use Zigbee2MQTT with Home Assistant?

To interact with Zigbee devices in Home Assistant you have two choices, the built-in ZHA integration or Zigbee2MQTT.

The inbuilt ZHA integration is good and I use it myself after switching from Zigbee2MQTT in late 2022. I switched over because I no longer wanted to use MQTT, which Zigbee2MQTT depends on.

Zigbee2MQTT offers superior device compatibility support and more advanced configuration. It would suit homes with a large Zigbee network, homes with a wide range of devices, and more technical users.

Zigbee2MQTT Hardware Requirements

Hardware needed to set up Zigbee2MQTT

To set up Zigbee2MQTT, you will need the following hardware:

1. Zigbee USB dongle: This is the device that connects your computer or single-board computer (such as Raspberry Pi) to the Zigbee network. Some popular options include the Texas Instruments CC2531 USB dongle and the Conbee II USB dongle.
2. Compatible devices: Zigbee2MQTT supports a wide range of Zigbee devices, including lights, switches, thermostats, and sensors. To ensure compatibility, it’s best to check the list of compatible devices on the Zigbee2MQTT GitHub page before purchasing any devices.
3. Micro-USB cable: This is used to connect the Zigbee USB dongle to the computer or single-board computer. It is recommended to use a cable of 1.5 meters or longer to allow you to place the Zigbee USB dongle further away from your computer to reduce interference.

Zigbee2MQTT requires an MQTT broker to operate, therefore you need to have one running in your network or you can use the cloud-based one like CloudMQTT. If you are using Home Assistant OS then the Mosquitto broker addon would be the perfect choice for your MQTT needs.

How to determine if your devices are compatible with Zigbee2MQTT

To determine if your devices are compatible with Zigbee2MQTT, you can check the list of compatible devices on the Zigbee2MQTT documentation page. This list includes a wide range of devices from various manufacturers that have been tested and confirmed to work with Zigbee2MQTT.

You can also check the compatibility of your devices by checking the Zigbee device’s technical specifications. The device should support the Zigbee Home Automation (ZHA) profile, which is the profile that Zigbee2MQTT uses to communicate with devices.

Even if a device is not officially listed as compatible with Zigbee2MQTT, it may still be possible to get it to work with the software. Many users have successfully integrated unsupported devices by using device handlers or other community-developed solutions.

Zigbee2MQTT Software Requirements

Software needed to set up Zigbee2MQTT with Home Assistant

To set up Zigbee2MQTT, you will need the following software:

1. Zigbee2MQTT: This is the software that runs on your computer or single-board computer and acts as a bridge between your Zigbee devices and the MQTT broker. You can download the latest version of Zigbee2MQTT from the GitHub page or install it via the Home Assistant addon store.
2. MQTT broker: This is the software that allows Zigbee2MQTT to communicate with your devices. It acts as a message broker and facilitates the transfer of data between devices. You can use a local MQTT broker such as Mosquitto, or a cloud-based one such as CloudMQTT.
3. Home Assistant (optional): This is an open-source home automation platform that allows you to control and automate your devices. If you want to use Home Assistant to control your Zigbee devices, you will need to install and configure it on your computer or single-board computer.
4. Add-ons (Optional): Zigbee2MQTT can be integrated with other software such as Node-RED, a programming tool for wiring together hardware devices, APIs, and online services in new and interesting ways.

How to connect Zigbee2MQTT to Home Assistant

Download and install the Zigbee2MQTT HA Add-on

For this article, we are going to install the Zigbee2MQTT add-on using the Home Assistant add-on store.

Zigbee2MQTT is not available in the official add-on store so we first need to add the required repository to make it available for installation.

1. Log in to Home Assistant and go to “Settings” then “Add-ons” and click on the blue button labeled “Add-on Store”.
2. At the top right of the screen click on the 3 dots button then choose the repositories link.
3. In the “manage add-on repositories” screen add the following URL then click add, once added click close to return to the add-on store where you should see the Zigbee2MQTT add-ons.
   
   https://github.com/zigbee2mqtt/hassio-zigbee2mqtt
   
   
4. Click on Zigbee2MQTT then click Install.

You should now have the Zigbee2MQTT add-on installed on Home Assistant OS but before we start it there are some configuration steps required in the next section.

Zigbee2MQTT Home Assistant Add-on Configuration

How to connect Zigbee2MQTT to Home Assistant

For the Zigbee2MQTT add-on to function it needs to be able to communicate directly with a Zigbee USB dongle such as the Conbee II or Sonoff Zigbee 3.0 USB Dongle Plus. We need to tell the add-on where the dongle is (its device path) and add it to the add-on’s configuration.

To find the device path to your dongle follow these steps.

1. Inside Home Assistant, go to “Settings” then “System” then “Hardware“.
2. Click on the All Hardware link and scroll down until you find your USB dongle then click on it to expand further details.
   
   
3. Look for the line that starts with “Device path:” and copy the value from the right. The screenshot above illustrates my device path as /dev/ttyACM0
4. Now head back to the Zigbee2MQTT add-on and go to the configuration page
5. Enter port: /dev/your-device-path in the serial section and enter server: mqtt://core-mosquitto:1883 in the MQTT section (if using the MQTT add-on) then click save.
   
6. Head back to the Info page from the links at the top of the screen then click Start to turn on the add-on.

How to add Zigbee devices to Zigbee2MQTT

Once Zigbee2MQTT is running, you can use the built-in web interface to pair your devices. To do this, go to the web interface by clicking on the Open Web UI button from the add-on info screen.

By default, Zigbee2MQTT does not permit new devices to join your network.

To pair a device, click on the Permit join (All) button from the top right menu bar then follow your Zigbee devices pairing procedure to complete the process. New devices that join the Zigbee network will automatically appear in the main table in the devices section.

These are general steps and the exact process may vary depending on your specific setup and the version of the software you are using. I try to keep this article up to date with changes but It is recommended to refer to the official documentation provided by the software developers for the most accurate and up-to-date instructions.

Troubleshooting the Zigbee2MQTT Home Assistant Add-on

Common solutions for troubleshooting issues that may arise during setup

Here are some common solutions for troubleshooting issues that may arise during the Home Assistant Zigbee2MQTT setup process:

Devices not pairing

• Make sure that the device is in pairing mode and within range of the Zigbee USB dongle.
• Ensure that the device is supported by Zigbee2MQTT, by checking the list of compatible devices on the GitHub page or the device’s technical specifications.
• Check if the device’s firmware is up-to-date.
• Try resetting the device to factory settings, as this may resolve pairing issues.

Connectivity issues

• Check that the MQTT broker is running and that the settings in the Zigbee2MQTT configuration file are correct.
• Make sure that the computer or single-board computer running Zigbee2MQTT has internet access and is not blocked by a firewall.
• Check that the Zigbee USB dongle is properly connected to the computer or single-board computer and that it has power.
• Try resetting the Zigbee network by going to the web interface and clicking on the “Reset network” button.

Integration issues with Home Assistant

• Make sure that you have correctly configured the MQTT integration in the Home Assistant configuration file. Double-check the hostname, port number, and username/password for the MQTT broker.
• Check that the Home Assistant and Zigbee2MQTT are running on the same network.
• Make sure that the devices are paired with Zigbee2MQTT and properly configured in the configuration.yaml file.

General Troubleshooting

• Check the log files of the software, the logs often contain useful information about errors and issues that may arise during setup.
• Check the community forum of Zigbee2MQTT or other smart home device forums to see if other users have had similar issues and if they have found a solution. You can also report bugs with the Zigbee2MQTT Home Assistant add-on from the GitHub repository page.
• Try updating the software to the latest version, as this may resolve issues that have been fixed in newer releases.

It is also important to note that, some issues might be caused by other factors, such as hardware failure, network issues, or software bugs, so it is important to be persistent and explore all possible solutions.

FAQ

Additional Resources and Documentation

Zigbee2MQTT Home Assistant Documentation – This page describes how to integrate Home Assistant with Zigbee2MQTT.

Zigbee2MQTT Official GitHub Repository – Source code of the Zigbee2MQTT Home Assistant addon.

Home Assistant MQTT documentation – Documentation for help with integrating MQTT in Home Assistant.

Conclusion

In summary, the article discussed the Home Assistant Zigbee2MQTT setup process from start to finish and once completed it will allow you to control and automate Zigbee devices in your home.

Once set up you will be able to create automations and advanced controls for all of your Zigbee devices directly inside Home Assistant.