LuisLlamas Logo
conectar-dispositivos-zigbee-home-assistant-zha-vs-zigbee2mqtt

How to Connect Zigbee Devices: ZHA or Zigbee2MQTT

  • 7 min
  • Beginner

Connecting Zigbee devices to Home Assistant requires a radio coordinator and software to manage the network.

To create this mesh network, we will connect a coordinator like the Sonoff Zigbee 3.0 or the Home Assistant Connect ZBT-2 to our Mini PC or Raspberry Pi. It is advisable to separate it from the server with the included cable or a USB extension cable to reduce interference.

But hardware alone does nothing. We need software that acts as a “driver,” capable of communicating via the serial port (UART) with the Dongle’s chip, interpreting Zigbee protocol frames, and converting them into Entities within Home Assistant.

Here we face the great technical decision of the maker community. There are two main paths to manage our network: ZHA (Zigbee Home Automation) and Zigbee2MQTT. Let’s analyze the architecture of both in depth to decide which one to implement.

ZHA: The Integrated Path

ZHA is the official Home Assistant integration for Zigbee networks. It is included in the core, meaning it requires installing no additional container or application.

ZHA Architecture

At the software architecture level, ZHA is a Python component that runs directly within the same Home Assistant process.

The data flow is direct and monolithic:

  1. ZHA opens a connection via the serial port (e.g., /dev/ttyUSB0) to the Dongle.
  2. It listens for Zigbee events (e.g., “Door sensor opened”).
  3. It directly transforms that event into a state change in the Home Assistant state machine (binary_sensor.door changes to on).
  • Extreme simplicity (Plug & Play): When you connect the USB Dongle, Home Assistant automatically detects it through the graphical interface. A couple of clicks and you are already pairing light bulbs.
  • Visual integration: All network management (topology map, OTA updates, device configuration) is done directly from the native Home Assistant Settings menus.
  • Fewer points of failure: By not relying on external services or intermediaries, there are fewer software pieces that can fail or become misconfigured.
  • Coupling with Home Assistant: Being integrated into the Core, ZHA stops processing events while Home Assistant restarts. Direct links between compatible devices can still work, but automations that depend on Home Assistant are paused.
  • Support for new devices: When a manufacturer deviates from the standard, ZHA may require specific rules called quirks. Their availability depends on someone adding and testing the model, so it is advisable to check compatibility before buying.

Zigbee2MQTT: An Independent Architecture

On the other end, we have Zigbee2MQTT, an independent, community-maintained open-source project that has become the preferred tool for advanced users and system integrators.

Zigbee2MQTT Architecture

Z2M is independent software, generally run via a HAOS add-on or in its own container. Its architecture is decoupled from Home Assistant.

The technical concept is very robust and relies on using an MQTT Broker (like Mosquitto):

  1. Z2M takes exclusive control of the USB Dongle via the serial port.
  2. Z2M translates complex Zigbee frames into a universal text format (JSON payloads).
  3. Z2M publishes those JSON messages to an MQTT server.
  4. Home Assistant, through its MQTT integration, reads those messages and updates its Entities.

If you are not familiar with MQTT, don’t worry. It is the standard messaging protocol in the IoT industry. We will dedicate a full article to understanding how an MQTT Broker works later in the Maker level.

  • Decoupling: Since Z2M is an independent service, it can continue managing the radio while Home Assistant restarts. Home Assistant automations will not run during that interval, but Z2M and the broker continue receiving messages.
  • Broad catalog: Zigbee2MQTT supports thousands of models and publishes a detailed device list. Support for a new device depends on the existence of a compatible converter, so we must also check this before buying.
  • Distributed topology: Thanks to using MQTT, you can have Home Assistant installed on a server in the basement, and have a Raspberry Pi with Z2M and the USB Dongle in the center of the living room. They will communicate over your home’s Ethernet/WiFi network.
  • Advanced administration interface: Z2M includes its own web control panel (accessible from the HA sidebar) that offers very powerful diagnostic tools, detailed network maps, and exhaustive control of Over-The-Air (OTA) firmware updates for devices.
  • Initial learning curve: It requires setting up three different pieces: Install the MQTT Broker add-on (Mosquitto), install the Zigbee2MQTT add-on, and configure the MQTT Integration in Home Assistant so they can communicate.
  • Higher resource consumption: Running services in separate containers consumes slightly more RAM than ZHA (not a concern on a Mini PC, but worth considering on a very old Raspberry Pi).

Which Option to Choose

Both options are excellent and fully functional. The decision depends strictly on your technical profile and long-term goals:

  • If you want easy, quick, and hassle-free home automation: Use ZHA. It is the path of least resistance, works very well for 90% of homes, and is officially supported.
  • If you are a technical user, have a large house, or plan to integrate dozens of obscure sensors from AliExpress: Go straight for Zigbee2MQTT. The extra time you invest in setting up MQTT will be more than saved in future stability and compatibility.

Due to our preference for decoupled architectures, we will use Zigbee2MQTT. Learning to handle MQTT will also open the doors for integrating our own systems later in the course.

It is not advisable to switch back and forth between ZHA and Zigbee2MQTT once the house is already set up. Migrating a Zigbee network is not like changing the dark theme of an app. It sometimes involves re-pairing devices, rebuilding entity names, and reviewing automations. Better to choose wisely from the start.

And an important detail: a single Zigbee dongle can only be controlled by one piece of software at a time. You cannot have ZHA and Zigbee2MQTT simultaneously using the same USB coordinator.

The Pairing Process

Regardless of the software you choose, the physical process for adding devices to the network is identical:

  1. You activate the “Permit join” mode in the ZHA or Z2M interface. This temporarily opens the network (usually for 5 minutes).
  2. You put the physical device into pairing mode (usually by holding down a button for 5 seconds until an LED blinks).
  3. The Coordinator and the device negotiate security keys over the air.
  4. The device appears on the screen and its Entities are generated in Home Assistant.

Pair your devices in their final location whenever possible. If you pair all the sensors right next to the coordinator and then spread them around the house, some will stay associated with suboptimal routes until the mesh recalculates. It works, yes, but sometimes it causes trouble.

Once we have our WiFi sensors (Shelly, Sonoff) and our Zigbee mesh reporting data in real-time to the server, the Home Assistant database starts filling up with useful information.

On this page