In this post, we will look at how you can set up a Zigbee2MQTT with Home Assistant. You will learn the basics of ZigBee, How to install Zigbee2MQTT into Home Assistant and adding ZigBee devices.
What is Zigbee? Everything you need to know
ZigBee is a lightweight protocol designed for communication between smart home devices like sensors, lights, plugs, and dimmers. Popular smart home products from brands like Philips Hue, IKEA TRÅDFRI, and Xiaomi operate using the ZigBee protocol. One of ZigBee’s key advantages is its low energy consumption, making it ideal for battery-powered sensors and devices. A typical ZigBee network consists of three main components:
ZigBee Coordinator (ZC): This is the central hub of the network. Each network has a single ZigBee Coordinator responsible for managing the network’s internal operations.
ZigBee Router (ZR): The router forwards data between end devices and the coordinator. Devices such as smart plugs or lights can serve as routers, acting as signal boosters to extend the network’s range. Routers require a continuous power supply (220V or 110V).
ZigBee End Device (ZED): These devices send and receive messages, and include items like motion detectors, lights, smoke alarms, temperature sensors, or even automated blinds. They are often battery-powered.
Typically, a ZigBee device connected to a power outlet also functions as a ZigBee Router. Other ZigBee End Devices can receive messages from the central coordinator through this router. By using smart lights like Philips Hue or TRÅDFRI, the network’s range is automatically extended.
By connecting Home Assistant to a ZigBee coordinator, most ZigBee devices can be controlled directly through Home Assistant, eliminating the need for separate bridges or hubs like the Philips Hue Bridge, IKEA TRÅDFRI hub, or Xiaomi gateway. Managing all ZigBee devices through Home Assistant also alleviates privacy and security concerns associated with products like Xiaomi. All ZigBee communication remains local, without routing through external clouds like Xiaomi’s.
You can follow the simple steps outlined in the next section to install ZigBee.
Requirements for ZigBee2MQTT in Home Assistant
To enable ZigBee in Home Assistant, you’ll need USB stick. There are many affordable Zigbee USB dongle available. A highly recommended Zigbee USB stick for Zigbee2MQTT is the Sonoff ZigBee 3.0 USB Dongle Plus, available from Smart Gateways. With this USB stick, you can get started using ZigBee in Home Assistant right away.
Since this ZigBee gateway functions as the central hub for all ZigBee devices, it’s equipped with an antenna to boost its range. This antenna is especially important for installations on devices like the Raspberry Pi, which can cause interference due to poor shielding. To mitigate this, the ZigBee USB dongle can be extended with a USB extension cable if needed. The gateway has an indoor range of about 30 meters, which is adequate for most homes.
Install Mosquitto MQTT Broker onto Home Assistant
To use Zigbee2MQTT, an MQTT broker is required. This broker handles the data exchange between all ZigBee devices. You can install the MQTT broker as a Home Assistant add-on. Follow these instructions to get it set up. The installation takes about 10 minutes.
The installation manual can be found here: https://haprofs.com/setting-up-mqtt-mosquitto-broker-home-assistant/
Install Zigbee2MQTT in Home Assistant
To install Zigbee2MQTT as a Home Assistant add-on, go to the “Add-ons” section in Home Assistant settings. Then, click on “Add-on Store” in the bottom right corner. Next, click on the three dots in the top right corner and select “Repositories.”
Add the following repository URL and click “Add”
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt
Select CLOSE.
Refresh the UI and you should be able to see Zigbee2MQTT.
Two add-ons will be visible: Zigbee2MQTT and Zigbee2MQTT Edge. The latter is a beta version with the latest support but may be unstable, so install it only if you know what you’re doing. I recommend installing the Zigbee2MQTT add-on instead. To do this, click on it and then choose “INSTALL.” The installation might take a little time. Do not start Zigbee2MQTT yet; we’ll do that later.
After Zigbee2MQTT is installed, you have to do some additional configuration. First we need to know in which usb port the ZigBee Dongle is installed.
How to find the usb port where the Zigbee Dongle is installed
Finding the usb port where the ZigBee dongle is installed is easy. Just go to Settings -> Hardware -> Click on ALL HARDWARE:
Enter sonoff in the search bar:
The port is visible as /dev/ttyUSB0
Go back to Settings -> Add-ons -> Click Zigbee2MQTT and select the Configuration tab, and add the USB port where your Sonoff Zigbee 3.0 Usb Dongle Plus is installed.
Click SAVE and (RE)START the zigbee2MQTT Add-on
Zigbee2MQTT should now be up and running. If you check the logs tab, you should be able to see that Zigbee2MQTT has started
Running Zigbee2Mqtt in a Docker Container
To run the Zigbee2Mqtt in a docker container, you can start it with docker compose.
For this create a file called docker-compose.yaml and add the following content
version: '3'
services:
zigbee2mqtt:
container_name: zigbee2mqtt
restart: unless-stopped
devices:
- /dev/ttyACM0:/dev/ttyACM0
ports:
- "8080:8080"
volumes:
- ./data:/app/data
- /run/udev:/run/udev:ro
environment:
- TZ=Europe/Amsterdam
image: koenkk/zigbee2mqtt
Specify the location of the Zigbee dongle in the devices property.
To find the location of your Zigbee stick, make sure you have connected the dongle to your machine, create a file called find-usb.sh and paste the following content
for sysdevpath in $(find /sys/bus/usb/devices/usb*/ -name dev); do
(
syspath="${sysdevpath%/dev}"
devname="$(udevadm info -q name -p $syspath)"
[[ "$devname" == "bus/"* ]] && exit
eval "$(udevadm info -q property --export -p $syspath)"
[[ -z "$ID_SERIAL" ]] && exit
echo "/dev/$devname - $ID_SERIAL"
)
done
Make the file executable file using the following command
chmod +x find-usb.sh
Next, run this file using the ./ command as below
./find-usb.sh
As you can see in the image above, the dongle location is /dev/ttyACM0 and we will use this value in the docker-compose.yaml file from above.
Now we will create the configuration file for Zigbee2Mqtt
Create a datafolder in the same directory where your docker-compose.yaml file is present and then create a configuration.yaml file inside the data folder with the following content
permit_join: true
mqtt:
server: mqtt://192.168.0.43:1883
serial:
port: /dev/ttyACM0
frontend: true
advanced:
homeassistant_legacy_entity_attributes: false
legacy_api: false
legacy_availability_payload: false
device_options:
legacy: false
devices: {}
homeassistant:
legacy_entity_attributes: true
legacy_triggers: true
Specify the IP address of the MQTT server. In our case, it was 192.168.0.43:1883
You are ready to start the Zigbee2Mqtt server.
From the location where the docker-compose.yaml is located, run the command docker compose up
You can now access the Zigbee2MQTT interface using the IP address of your machine and port 8080 as shown.
Add ZigBee devices to Home Assistant using Zigbee2MQTT
Now it’s time to add your first ZigBee device. We can add a ZigBee Smart Plug with Power Management so you can switch on or off a device and monitor it’s power usage. You can buy a recommended smart plug at Smart Gateways:
You can access the Zigbee2MQTT view using the option on the left panel.
New devices can be paired using the method prescribed by the manufacturer. For example, with a Philips Hue light, you might need to turn it on and off five times, after which it will start blinking slowly. Xiaomi devices often have a small reset button that can be pressed with a paperclip. New devices will then automatically appear in the overview.
Note the Friendly Name of the new device to be added. Then go to Settings -> Integrations. Under the MQTT integration, the new device should appear.
Click on the number of devices:
Select the newly added device. All the details should now be visible:
Frequently asked questions (FAQ) about Zigbee2MQTT
What is Zigbee2MQTT and why do I need it? Zigbee2MQTT is a tool that allows you to integrate Zigbee devices with MQTT, enabling you to control and monitor Zigbee devices through your MQTT broker. It acts as a bridge between your Zigbee network and Home Assistant or other MQTT-based systems.
How do I find the location of my Zigbee dongle in Home Assistant? Connect the Zigbee dongle to your machine and go to to Settings -> Hardware -> Click on ALL HARDWARE. Enter sonoff in the search bar and the port should be visible. You can find detailed instructions here.
Where should I specify the location of my Zigbee dongle when using Docker? You should specify the dongle’s location in the devices section of the docker-compose.yaml file. The typical path is /dev/ttyACM0, but it might differ based on your setup.
How do I find the location of my Zigbee dongle in Docker? Connect the Zigbee dongle to your machine and run the provided find-usb.sh script. This script will help you locate the dongle’s device path, which you should then use in the docker-compose.yaml file.
What if the find-usb.sh script doesn’t find my dongle when using Docker? Ensure the dongle is properly connected and recognized by your system. Verify that you have the correct permissions to access USB devices. If the script still doesn’t work, check for potential issues with the dongle or try connecting it to a different USB port.
How do I set up the MQTT server? You can find an instruction on how to setup Mosquitto MQTT Broker in Home Assistant here.
How long does the installation and setup of the Zigbee2MQTT process take? The installation and setup process should take approximately 10 minutes. This includes creating configuration files, finding the Zigbee dongle, and starting the Docker container.
Can I access the Zigbee2MQTT interface after starting the Docker container? Yes, once the container is running, you can access the Zigbee2MQTT interface by navigating to the IP address of your machine and port 8080 in a web browser.
What if I encounter issues starting the Zigbee2MQTT container? If the container fails to start, check the logs for error messages using docker logs zigbee2mqtt. Verify that the docker-compose.yaml and configuration.yaml files are correctly configured. Ensure your MQTT broker is running and accessible.
Do I need to restart the Zigbee2MQTT container after making changes? Yes, after making changes to the configuration.yaml or docker-compose.yaml files, restart the Zigbee2MQTT container using docker compose restart to apply the new settings.
Conclusion
Integrating Zigbee2MQTT with Home Assistant provides a powerful way to manage your Zigbee devices through MQTT. By following the steps, you can seamlessly connect and control your Zigbee network. Remember to check the MQTT integration points to the right usb path in Home Assistant to ensure your zigbee dongle is found. With this setup, you’ll be able to add zigbee devices from Ikea, Philips Hue, Tuya and many other brands. Zigbee is one of the most reliable ways to automate your home.
Track Water consumption in Home Assistant with the Watermeter Gateway
The Water Meter Gateway from Smart Gateways upgrades your traditional water meter into a smart device, offering real-time data on your water usage. You’ll be able to monitor your water consumption during various activities like showers, baths, handwashing, or garden irrigation via an intuitive dashboard. This clear overview helps you track usage and spot areas where you might reduce costs.
Installation is straightforward, and the gateway is designed to work with most analog water meters, including those from brands such as Itron, Actaris, Elster, and Honeywell. It integrates seamlessly with popular home automation platforms like Home Assistant, Domoticz, and Homey. For additional functionality, you can leverage open standards such as REST-API and MQTT for secure data transfer.
If you prefer not to use home automation software, you can opt for the Online Energy Dashboard subscription. With the provided installation guide, you can set up the gateway on your own. The sensor has an extendable range of up to 15 meters and is compatible with both version A and B water meters, depending on your model.
For more details, click here .
Monitor energy consumption with Home Assistant by connecting your Smart Meter with P1 port
In this guide, I’ll explain how you can connect your smart meter with Home Assistant. Home Assistant offers several options for adding a smart meter and monitoring energy consumption in real-time and by hour, day, week, month, and year. Recently, Home Assistant introduced the Energy Dashboard, which displays the energy consumption of the Smart Meter, Gas consumption, and water consumption in beautiful overviews. The beauty of smart meters in the Netherlands and Belgium is that they also provide gas consumption data. So, you can immediately display both gas and electricity consumption in Home Assistant using a single smart reader or P1 meter.
