Be Smart, Go Local.

How To Bridge ZigBee With Home Assistant

A beginner friendly guide answering all questions related to Zigbee in Home Assistant. Coordinators/bridges talk, installation and setup of ZHA & Zigbee2MQTT.

When new smart home enthusiasts decide to try out Home Assistant, they often have a lot of unanswered questions or binary dilemmas. These new users are frequently migrating from proprietary smart home systems such as Google Home, Amazon Alexa, IFTTT or Apple’s Homekit. If you are one of those people, finding the right answer to your many questions in the Home Assistant community forums can prove troublesome, unfruitful or raise even more questions.

Zigbee bridge with Home Assistant Connect your zigbee devices to Home Assistant

For ZigBee users, some of those questions are:

  • How do I bridge my ZigBee devices with Home Assistant?
  • What is the best ZigBee bridge or hub for Home Assistant?
  • Do I need different hubs for different brands?
  • Which Home Assistant Integration should I use?

This is a beginner friendly, yet full and comprehensive guide answering all the questions you could possibly have regarding ZigBee in Home Assistant.

Prerequisites

If you’ve reached this article somehow, than you’ve probably already decided to give Home Assistant a try. If you haven’t installed it already, click here and follow the official installation tutorial. For complete beginners, I suggest going the Raspberry Pi + Home Assistant OS route.

To bridge your existing ZigBee devices with Home Assistant, you are going to need a couple of things:

  • Home Assistant Instance Installed and Running
  • Zigbee Coordinator
  • USB 2.0 Extension Cable (Important)
  • Zigbee Integration in Home Assistant

Zigbee Coordinator

This section answers one the questions you might have about ZigBee in Home Assistant: Which hub you should use? Which is the best and universal Zigbee bridge to Home Assistant? And the answer? You don’t need any hubs.

If you already own any proprietary hubs or bridges (Hue Zigbee Hub, Aqara Hub etc.) stash them in a box somewhere as you will be moving all your devices under one single umbrella: Home Assistant with a Zigbee USB dongle and you wont be needing them.

In Home Assistant, Zigbee hubs are referred to as coordinators. Even though they are not the same piece of hardware, they carry out the same function . A coordinator is like the general manager of your ZigBee mesh network. It coordinates your devices when they try to talk to each other so they are always heard when they have something to say (eg. Turn on a light switch, report a temperature reading etc.)

You might wonder, what about my devices from different brands? Will my Phillips HUE motion sensors work with with my Aqara devices on the same coordinator? Although there are exceptions, the answer is YES, they will work without issues, cloud and app dependence or any other manufacturer specific requirement.

For a stable and solidified Zigbee network, you must acquire a good coordinator. We recommend the following as the best Zigbee coordinators for Home Assistant currently on the market:

Conbee II

Conbee II stick for Home Asssitant ZHA, Zigbee2MQTT and Deconz
  • Chip: ATSAMR21E18A
  • Frequency: 2.4GHz
  • Standard: IEEE 820.15.4 / Zigbee 3.0
  • Power Supply: DC 5.0 V
  • Transmit Power: 10dBm
  • Length: 60mm
  • Supports:
    • ZHA
    • Zigbee2MQTT
    • Deconz

AliExpress | Amazon

Sonoff ZBDongle-P

Sonoff ZBDongle-P usb stick for Home Assistant ZHA, Zigbee2MQTT
  • Chip: Texas Instruments CC2652P
  • Frequency: 2.4GHz
  • Standard: IEEE 820.15.4 / Zigbee 3.0
  • Power Supply: DC 5.0 V
  • Transmit power: 20dBm
  • Length: 63mm
  • Supports:
    • ZHA
    • Zigbee2MQTT
    • /

AliExpress | Amazon

Sonoff ZBDongle-E

Sonoff ZBDongle-E usb stick for Home Assistant ZHA, Zigbee2MQTT
  • Chip: Silicon Labs EFR32MG21
  • Frequency: 2.4GHz
  • Standard: IEEE 820.15.4 / Zigbee 3.0
  • Power Supply: DC 5.0 V
  • Transmit Power: 20dBm
  • Length: 52mm
  • Supports:
    • ZHA
    • Zigbee2MQTT
    • Thread (Matter)

AliExpress | Amazon

The Conbee II is one the most used and known pieces of hardware among Home Assistant tinkerers. It’s setup, configuration and firmware updates have been well documented in the community. However, It’s older and has a weaker chip than newer devices. We are listing it here as the safe choice for simple and smaller ZigBee networks.

The Sonoff ZBDongle-P is newer than the Conbee and is based on the Texas Instruments CC2652P chip. The CC2652P is considerably more powerful, capable and compatible with ZHA and Zigbee2MQTT. It’s has been widely reported by the community for having excellent performance, stability and a large number of maximum devices on a single stick.

The Sonoff ZBDongle-E is the latest and greatest kid on the block. It’s based on the Silicon Labs EFR32MG21 chip which is Thread (Matter) capable. Although Matter is not fully released yet, the module supports it and will be rendered Matter compatible with a future firmware update. We suggest picking this USB dongle.

Home Assistant Sky Connect is an upcoming Zigbee, Thread and Matter enabled stick for Home Assistant Its currently on preorder and is also based on the Silabs EFR32MG21 chip which is very powerful and OTA updatable. It has a transmit power of 20dBm operating on 2.4GHz frequency. Specs are almost identical as the Sonoff ZBDongle-E, so if you don’t want to wait we suggest getting the Sonoff.

Home Assistant skyconnect ZHA usb stick zigbee2mqtt zigbee home automation
SkyConnect EFR32MG21

An important thing you would also need is an USB 2.0 extension cable [Amazon, AliExpress]. This is used to stick out your coordinator at least 1 meter from your Home Assistant server to avoid interference. Zigbee is notorious for succumbing to adjacent USB ports chatter, so using an extension cable ensures everything runs smoothly and without obstruction.

NOTE: Don’t skip over this requirement, use an old cable if you have one lying around otherwise you are bound to have problems.

Zigbee Integration

This section answer the main question of this article, which is how to bridge my zigbee devices with Home Assistant? Well, once you have your Home assistant server running with a Zigbee dongle on a USB extension cable, you can pick your Zigbee Integration for Home Assistant. Essentially, you have three options:

  • ZHA (Zigbee Home Automation)
  • Zigbee2MQTT
  • Deconz

ZHA and ZigBee2MQTT are compatible with a bunch of zigbee coordinators, including the top three currently on the market we listed above. Deconz on the other hand, is compatible only with one: the Conbee II stick.

ZHA Zigbee Home Automation

ZHA stands for ZigBee Home Automation and is the built in ZigBee integration in Home Assistant itself. Managing devices in ZHA is the same as managing devices in Home Assistant, it feels farmiliar, easy and native.

Installation and Setup ZHA

First, plug your new coordinator to a USB 2.0 port on an extension cable and restart Home Assistant. From the side menu navigate to Settings > Devices & Services:

  • Your new stick should be automatically discovered
  • Click Configure
  • Click Submit
  • Assign an Area if you want and click Finish
  • Done

To add new devices to your Zigbee Network, click + Add Integration and select Add Zigbee Device. This will put the coordinator in permit mode and allow new devices to join your network. Put your device in pairing mode and it will be automatically discovered.

If you run into any problems, check out the official ZHA documentation for possible solutions.

Zigbee2MQTT

Zigbee2MQTT is a nodejs Gateway application that connects Zigbee networks to MQTT networks. Z2M allows you to use your Zigbee devices without the vendor’s bridge or gateway. Its as standalone application developed to be used in any smart home infrastructure and not only Home Assistant.

Installation and Setup Zigbee2MQTT

Unlike ZHA, Zigbee2MQTT is not part of the official addon list in Home Assistant. We need to add custom repository to be able to install it. We also need an MQTT broker, which allows Zigbee to communicate through MQTT with Home Assistant. We will also create a user for MQTT in Home Assistant.

Add a new MQTT User in Home Assistant

  • Navigate to Settings > People
  • Click + Add Person at the bottom right
  • Name it however you like
  • Toggle Allow person to login
  • Set a username and password to be used in Mosquitto broker
  • Toggle Can only login from my local network
  • Click Create

Installing Mosquitto MQTT Broker

  • Navigate to Settings > Add-ons
  • Click Add-on Store on the bottom right
  • Select Mosquitto Broker from the list and install it
  • Select the Watchdog and Start on Boot toggles and click Start
  • Navigate to Settings > Devices & Services
  • Click + Add Integration on the bottom right
  • Search for MQTT and add it
  • Click Finish

Installing Zigbe2MQTT

  • Navigate to Settings > Add-ons
  • Click Add-on Store on the bottom right
  • Click on the three dots in the top right corner and select repositories
  • Add the following repo: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt
  • Click Close
  • Refresh the page and click Zigbe2MQTT
  • Click Install
  • Select the Watchdog, Start on Boot and Show in sidebar Toggles
  • Don’t click start, and click the Configuration tab at the top
  • In the MQTT field, put the following data:
    • server: mqtt://core-mosquitto:1883
    • user: username
    • password: password
  • In the Serial field, put the following data
    • port (General): /dev/ttyACM0
    • port (By Id): /dev/serial/by-id/usb-dresden_elektronik_ingenieurtechnik_GmbH_ConBee_II_DE2196238-if00
    • adapter: deconz (for Conbee), ezsp (for Sonoff ZBDongle-E)
  • Go back go Info tab
  • Click Start

You can find you particular serial id by navigating to: Settings > System > Hardware > Three dots > All system hardware. Search here for “tty” and you can copy your serial ID which starts with “/dev/serial/by-id…

To add devices to your Zigbee network, click Zigbee2MQTT from the sidebar and click Permit Join (All) from the top. Put your device in pairing mode and it will be discovered and added in Z2M.

ZHA vs Zigbee2MQTT: Which one is for you?

This question has been asked many times in the Home Assistant community and unfortunately there is no definitive answer that would fit most users. Both integrations are very capable and well documented, support a variety of devices and are supported in Home Assistant. However, there are some differences between the two:

ZHA
  • Easier to Setup
  • Natively Supported in HA
  • Fewer Devices Supported than Z2M
  • Slower Support for New Devices than Z2M
  • Fewer device entities exposed to Home Assistant
  • More suitable for beginners
  • Hard to create custom quirks for unsupported devices
Zigbee2MQTT
  • Harder to Setup
  • Can run independently from HA
  • More Devices Supported than ZHA
  • Faster Support For New Devices than ZHA
  • Requires MQTT Broker
  • Most device entities exposed to Home Assistant
  • More suitable for advanced users
  • Easy to create herdsman converters for unsupported devices

As you can see from this simple list, both Zigbee integrations have their pros and cons. ZHA is easier to setup and use, but a little limited in device support, especially for obscure and weird devices.

Zigbee2MQTT on the other hand, requires an MQTT Broker to setup which adds complexity, but can run independently from Home Assistant on a spare Raspberry Pi for example. New devices are added almost instantly in Zigbee2MQTT while ZHA usually follows close behind. We suggest following this simple guide:

  • If you use weird and unbranded cheap Chinese devices, choose Zigbee2MQTT.
  • If you use known brands and manufacturers, choose ZHA
  • If you like to experiment and tinker, choose Zigbee2MQTT
  • If you like to not be bothered with setup, choose ZHA
  • If you like to run your Zigbee network independently from Home Assistant, choose Zigbee2MQTT

Please remember: These bullet points are only suggestions to try and ease your decision, not factual guidelines that you should abide by. There is absolutely no reason why an advanced user should not install ZHA instead of Zigbee2MQTT. At the beginning of things, ZHA crawled behind Zigbee2MQTT by a large margin. Now, things are more or less equal.

Summary

Hopefully by reading this article things have become clearer for bridging the Zigbee and Home Assistant gap. With Thread and Matter around the corner, we are looking at all an new generation of devices and products being released in the near future.

People often wonder whether Thread will replace Zigbee and make it obsolete: It probably will, but your existing Zigbee devices can continue to operate for as long as you want them too. Matter is meant to streamline the “all devices under one umbrella” process and make things easier.

For now, we suggest picking up the Sonoff ZBDongle-E [AliExpress, Amazon] version, which be rendered Thread and Matter compatible in the near future with a firmware update to future-proof your setup.

13 thoughts on “How To Bridge ZigBee With Home Assistant”

  1. Having seen my Zigbee network, which currently has the ConBee II as the coordinator, do you think it would be wise of me to “upgrade” to one of the SonOff devices? Or am I okay where I am?

    • Hey Ben,

      Your network can benefit of the Sonoff ZBDongle-E. Link quality will rise as It’s antenna transmit power is double that of the Conbee. It will eliminate that little lag/delay some devices have, toggling plugs and lights will feel instant. The overall health of the network will be better.

      However, the ZBDongle-E is not yet OFFICIALLY supported by Zigbee2MQTT because of its Ezsp stack. It is listed as experimental. I would wait a while before it gets sorted out and official support is added.

      I’ve been using it with Z2M no issues whatsoever after upgrading the firmware though, so If you are feeling like tinkering go for it 🙂

      Cheers

      P.S. Two additional plugs as routers are good idea in your network too.

  2. Still working through the transition from ZHA to Zigbee2MQTT to see if that works better for me. The guide has been very helpful so far but you have a typo in the Zigbee2MQTT Serial adapter setup for Zonoff. It says “eszp” and should be “ezsp” 🙂

      • The only other thing I noticed in the setup was the “port” doesn’t clarify that your listing is probably for the Conbee and doesn’t work with the Zonoff? After failing to start, I discovered that in my case (using Zonoff E), the entry was much simpler and I just had to put “/dev/ttyACM0” in the port section.

        I found that info in the help docs here under “What port should I use for Texas Instruments”: https://www.zigbee2mqtt.io/guide/installation/20_zigbee2mqtt-fails-to-start.html

        I ran the command “ls -l /dev/serial/by-id” to make sure my device matched the documentation and then I was all set. Hopefully this will help others that end up here in the future. 🙂

        • You are correct, my example is for my particular Conbee II stick. You should always use serial ID ( /dev/serial/by-id) intead or port number (/dev/tty/ACM0) though, the integration will fail to start if you change ports.

          You can find you particular serial id by navigating to:
          Settings > System > Hardware > Three dots > All system hardware

          Search here for “tty” and you can copy your serial ID which starts with “/dev/serial/by-id…”

          Cheers!

  3. Hi Guys,
    I have old MSI cube hardware (conbee II, deconz) and docker. I have few containers (nodered, ESP HOME, pihole, ups one, deconz, ha).

    I’ve just purchased sky connect. Do you think it’s worth to change my hardware to standalone (dedicated raspberry), or remove docker and install HA on the MSI itself?

    As far as I know, it’s not possible to use any plug-ins in HA on docker. So ZHA is not an option for me without architecture change. What about Zigbee2MQTT?

    • Hello,

      If you don’t need the MSI for anything else, the way I see it you have two options:

      1. Run HA OS on the MSI itself
      2. Run Promox and install HA OS as a separate container.

      With the second option, you can still separate Zigbee2MQTT, ESPHome, Pihole etc. Oh and definitely migrate to Zigbee2MQTT, it’s far superior to either ZHA or Deconz. The SkyConnect is labelled as experimental in Zigbee2MQTT, but many people use it with any issues whatsoever.

      Cheers

      • Thank you! I saw your great articles for Proxmox and Zigbee2MQTT migration.

        I do not need MSI for anything else than is doing now. As I understand, with Proxmox I would need to maintain separated OS (with all pros and cons of virtualisation vs contenerisation).

        Is it possible to use HA plug-ins with HA OS on Proxmox?

        • Yes, the HA OS on Proxmox is a full deployment of Home Assistant. Any Add-ons or Integrations can be used normally as you would on a dedicated install.
          Regarding maintenance, I find it incredibly simple. You can set it and forget it without ever updating anything in Proxmox itself if that’s what you want.

          You can only manage your Home Assistant like you normally would.
          Cheers

Comments are closed.