How to Run Zigbee2MQTT on Raspberry Pi? Step By Step Explained!

Zigbee is a low-power, low-cost wireless protocol commonly used in home automation devices like smart lights, sensors, switches and thermostats. Zigbee2MQTT is an open-source software solution that bridges Zigbee devices to a MQTT broker allowing integration with popular smart home platforms.

This guide covers the complete process of installing Zigbee2MQTT on a Raspberry Pi and connecting Zigbee devices to be controlled locally or remotely.

Prerequisites

Before we get started, make sure you have the following:

• Raspberry Pi OS installed on your Raspberry Pi. The Lite version is recommended.
• Raspberry Pi connected to your home network over Ethernet or WiFi.
• MQTT Broker installed. This can be a software like Mosquito on the same Pi or a cloud MQTT provider.
• Zigbee Coordinator (CC2531, CC1352P/CC2652P based) connected to the Pi over USB.

Steps to Install Zigbee2MQTT

With the prerequisites ready, let’s install Zigbee2MQTT:

1. SSH into your Raspberry Pi if using the headless Lite version or open a terminal on the desktop version.
2. Update apt repo and install some dependencies:

sudo apt update

sudo apt install git make gcc g++

1. Clone the Zigbee2MQTT repository:

git clone https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt

2. Navigate into the downloaded source folder:

cd /opt/zigbee2mqtt

3. Edit data/configuration.yaml file to configure your setup:

nano data/configuration.yaml

Some important things to configure:

• serial: section: Specify port for your Zigbee coordinator.
• mqtt: section: MQTT broker details.
• permit join: Allow or disallow pairing of new devices.

4. Once configuration is done, build and install the service:

npm ci && npm run build

sudo npm link

This will create a zigbee2mqtt command we’ll use later.

Starting Zigbee2MQTT

Now that Zigbee2MQTT is installed, we can start it:

sudo zigbee2mqtt -d

The -d flag runs it daemonized in the background.

Connect your Zigbee devices like smart lights or sensors and they will automatically get discovered and show up in the logs.

To allow devices to pair, set permit join to true in configuration. New devices will get assigned friendly names and aliases automatically.

Integrating with Home Automation

A key benefit of Zigbee2MQTT is that it bridges your Zigbee devices to MQTT topics allowing integration with various home automation platforms.

You can now control the connected devices from MQTT panels in software like Home Assistant or Node-RED which auto discover published device information.

No need to manually configure every device separately. This allows building home automation rules and scenes across different devices irrespective of the underlying wireless protocol.

Reliability Tips

Here are some recommendations to ensure maximum reliability with your Zigbee mesh network:

• Use a Power Supply – Avoid low voltage conditions by using a 5V power supply for the Raspberry Pi and Zigbee Coordinator instead of USB power.
• Centralized Location – Ideally place the Pi with Zigbee Coordinator central to where most of your devices are located acting as the hub.
• Minimize Interference – Have minimum interference from other wireless devices in the 2.4GHz frequency that Zigbee operates on. 5GHz WiFi bands are preferred.
• Avoid Reboots – Unplugging or rebooting the Pi should be avoided as the Zigbee network information will be lost requiring repairing.
• Zigbee Repeaters – For larger homes, use Zigbee routers or devices that can act as repeaters between the coordinator and distant devices.

Conclusion

Installing the open-source Zigbee2MQTT software stack transforms your Raspberry Pi into a controller for Zigbee lighting and sensors in your smart home or office setting. It unleashes the capabilities of these devices for easy integration with your desired home automation solution creating new possibilities for home control and automation without being dependent on cloud infrastructure or single vendor hubs.

FAQs

Q: Which Raspberry Pi models are supported?
A: Any RPi model with four cores is recommended – RPi 4, RPi 400, RPi 3/3+ can comfortably run Zigbee2MQTT. For older models, you may encounter performance issues with multiple devices.

Q: Can I run Zigbee2MQTT on the same Raspberry Pi running Home Assistant?
A: Yes, absolutely! Many people successfully run Home Assistant OS or Home Assistant Supervised to manage automation flows on the same Pi running Zigbee2MQTT as the bridge.

Q: How many devices can be paired simultaneously with Zigbee2MQTT?
A: There is no set limit and depends on your RPi model. Typically 100-150 devices including direct children and routers for meshing should work reliably on a Pi 4.

Q: Which CC2531 USB adapter works best?
A: The CC2531 stick from Slash is strongly recommended. Avoid cheap clones which can have compatibility issues.

Q: Can I directly control Zigbee lights and devices from the Raspberry Pi?
A: Yes, connected devices can be controlled locally with MQTT tools like mqtt-explorer. But integration with a home automation platform is recommended for easy control and automation.

Q: How do I backup or migrate Zigbee2MQTT between Raspberry Pis?
A: Stop the Zigbee2MQTT service, copy over the entire /opt/zigbee2mqtt folder to the new system and restore service using the same configuration.yaml. This will retain all existing devices without needing to repair.

Q: Can I extend the range of my Zigbee network?
A: Yes, adding Zigbee routers which act as repeaters between your coordinator and end devices allows you to extend the range for a large house.

Q: Do Xiaomi Aqara devices work with Zigbee2MQTT?
A: Yes, Aqara sensors and button devices are fully compatible. Some pairing Specific steps may be required for certain models to join properly.

Q: How do I allow newly added devices to join the Zigbee network?
A: Set permit join: true in configuration.yaml, restart Zigbee2MQTT service. New devices will show up in logs when trying to pair.

Q: Can I connect multiple Zigbee coordinators to a single instance of Zigbee2MQTT?
A: Unfortunately, no. You would need to run separate instances of Zigbee2MQTT, each with their own data folder and configuration.

Q: What debug options are available in case of issues with my devices or network?
A: zigbee2mqtt -d runs the service with increased debug logging. You can also tail logs with zigbee2mqtt logs command for troubleshooting.

Q: Will factory resetting Zigbee devices require repairing with Zigbee2MQTT?
A: Yes, a factory reset wipes out the network link and configuration requiring the device to go through pairing again to reconnect.

Q: How do I uninstall Zigbee2MQTT cleanly?
A: Stop the service with sudo zigbee2mqtt stop, then delete the /opt/zigbee2mqtt folder, remove the npm linked binary using sudo npm unlink zigbee2mqtt.

Q: Can Son off Zigbee devices connect directly to the CC2531 stick?
A: No, the Son off Zigbee devices use a separate protocol. You would need a Son off Zigbee Bridge connecting over serial to use them with Zigbee2MQTT

Q: Does every Zigbee device need repeating for mesh reliability?
A: No, while lights mostly would need, battery-powered sensors should be configured as end Device in configuration to maximize their battery life.

Q: Can ZWave devices also connect to Zigbee2MQTT software?
A: No. ZWave is a totally separate protocol using its own hardware bridge. Stick to connecting only Zigbee standard devices with Zigbee2MQTT.

Q: Which MQTT topics can be used to control devices via Zigbee2MQTT?
A: Connected devices publish their state to zigbee2mqtt/{friendly Name}/state and can be controlled via zigbee2mqtt/{friendly Name}/set MQTT topics.