Be Smart, Go Local.

How To Use Zigbee2MQTT and ZHA with a Single Coordinator

This article covers how to run both Z2M and ZHA on a single NETWORK coordinator in Home Assistant, complimenting each others features and device support.

While tinkering with the ZigStar UZG-01 PoE coordinator recently, I came across an interesting line in the device status overview window: Socket client connected: Yes, 1 connections.

Okay, why would the dashboard tell me how many connections are currently active? Could it be that I can connect multiple software instances like Zigbee2MQTT and ZHA to this single Zigbee coordinator at the same time? It got me interested enough to google around and do some testing.

And as it turns out yes, you can connect multiple applications to most LAN coordinators and the same time. In this article, I cover how to connect both integrations to the ZigStar UZG-01 gateway.

Running Zigbee2MQTT and ZHA on One Coordinator Featured Image SmartHomeScene

Why use more than one Zigbee application?

I’ve been thinking about this constantly since I tried it and I honestly cannot come up with a truly beneficial reason in the most basic sense of the word. ZHA in Home Assistant does the job for most people, while Zigbee2MQTT is the king of supported devices. However, here’s why you might want to do this:

  • Unsupported devices:
    • Let’s say you use ZHA as your daily driver, but that one switch is not yet supported by ZHA, but it is in Zigbee2MQTT. Pair it to Zigbee2MQTT and you can use it in Home Assistant with the same coordinator.
  • Missing features:
    • In a similar vein, let’s assume some features for a particular device are missing from Zigbee2MQTT, but you found are available in ZHA. Add the device and utilize its full functionality.
  • Testing:
    • Both integrations offer a different way of interacting and controlling devices, you can test them both and compare their pros and cons in a live setup
  • Why not?
    • Why… not?

How does this work?

When you set up a network with a Zigbee coordinator in ZHA or Zigbee2MQTT, the Zigbee application and network protocol stack are stored on the dongle itself. This dongle then handles most of the Zigbee network tasks, while the Zigbee integration you’re using just talks to the dongle to send and receive commands to and from devices in the network.

So, when setting up the second integration you are telling it to keep existing radio settings and just use the coordinator as is, without forming a second network.

Requirements

ZigStar UZG-01 Coordinator Featured SmartHomeScene

Here’s a short list of some conditions and requirements that need to be met before you can proceed:

  • LAN/PoE/Wi-Fi Coordinator
  • Zigbee2MQTT Add-on Installed
    • If you already have an existing network, you can simply add ZHA to your coordinator
    • Your existing devices will continue to function
    • Your existing devices will be added to ZHA as well
  • Coordinator configured in LAN mode
    • Example: port: tcp://192.168.0.32:6638
  • Static IP address set for the coordinator

This method works ONLY with NETWORK (LAN/PoE/Wi-FI) coordinators, and NOT USB coordinators. The second integration will not be able to access the USB port in question once it’s in use by the first one, so the process will fail.

Known compatible network coordinators:

It’s possible other network coordinators are capable of using both applications at the same time, such as TubeZS’s lineup. I have not tried them personally and I’m not aware if someone else has.

Adding ZHA and Zigbee2MQTT to the UZG-01

Assuming you already have Zigbee2MQTT running and the coordinator connected in LAN mode, you will notice it already says there is one active socket connection in the dashboard. For the ZigStar UZG-01, you can see this in the status page accessible at its IP address, e.g. 192.168.0.32

ZigStar UZG-01 Dashboard Number of Socket Connections

For the purpose of this tutorial, I’ve nuked my development and testing network and setup the ZigStar UZG-01 with Zigbee2MQTT, removing any devices and resetting the network settings completely. If you need to know how to setup the ZigStar UZG-01 in LAN mode, check out my deep dive review of the device. I cover the process extensively, including firmware updates for the Zigbee radio and ESP32 board.

With that out of the way, here’s how to add ZHA to an existing Zigbee2MQTT setup on the same coordinator:

  1. Navigate to Settings > Devices & Services
  2. Click + Add Integration
  3. Search for Zigbee Home Automation and select it
  4. Select the ZigStar UZG-01 Coordinator (or your LAN coordinator)
  5. If it doesn’t show up, click Enter Manually
  6. Under Radio type, select ZNP – Texas Instruments
  7. Under Serial device path, enter the IP and Port of your coordinator
    • Example: socket://192.168.0.32:6638
  8. Leave data flow control and port speed to their default values
  9. When prompted to Choose the network settings for your radio:
    • Select Keep radio network settings (IMPORTANT)
  10. Click Finish
  11. Here’s a few screenshot from my setup:
Adding ZHA to the same coordinator as Zigbee2MQTT - Step 1
Enter IP:Port
Adding ZHA to the same coordinator as Zigbee2MQTT - Step 2
Select Keep radio network settings

If you get an error and ZHA asks you to choose between restoring a previous network backup or keeping the current one (meaning the current Zigbee2MQTT network), select to keep it. Restart Home Assistant and check the dashboard of the UZG-01 again:

ZigStar UZG-01 Dashboard Number of Socket Connections: two

Pairing and testing devices

If I pair different devices in Zigbee2MQTT or ZHA while they are both connected to the same coordinator, the features each integration support for the device will show up as usual. Here are a couple of example of two devices I tested this with.

Example 1: Pairing in Zigbee2MQTT

If I press Permit Join in Zigbee2MQTT and add a device, it will be automatically added in ZHA as well. Whatever features Zigbee2MQTT supports for the device will be available as usual, and whatever ZHA supports will be available there. For example, here’s how pairing the BSEED Smart Socket looks like:

Running Zigbee2MQTT and ZHA on One Coordinator: Pairing Example 1 Z2M
BSEED Socket added in Z2M
Running Zigbee2MQTT and ZHA on One Coordinator: Pairing Example 1 ZHA
BSEED Socket added in ZHA

You will notice the device information is the same, labelled as TS011F by manufacturer _TZ3000_b28wrpvx in both integrations. However, what’s more important here, you will notice the network address is also identical in both [0xB1DD], meaning it belongs to the same network operated by the same coordinator, used by both applications.

This particular smart socket if fully supported in Zigbee2MQTT and ZHA and exposes identical entities from both integrations, so it’s completely obsolete to have entities from both exposed in Home Assistant.

Example 2: Pairing in ZHA

In the same manner, if you pair a device in ZHA, it will get automatically added to Zigbee2MQTT. If the device is unsupported in one integration but supported in the other, it will get identified as such. For example, here’s how a cheap 5.8GHz presence sensor looks like, paired in ZHA first:

Running Zigbee2MQTT and ZHA on One Coordinator: Pairing Example 2 ZHA
5GHz mmWave sensor added in ZHA
Running Zigbee2MQTT and ZHA on One Coordinator: Pairing Example 2 Z2M
5GHz mmWave sensor added in Z2M
Running Zigbee2MQTT and ZHA on One Coordinator: Pairing Example 2 Z2M Entities
5GHz mmWave sensor added in Z2M: Entities

Again, their identifiers are the same as is the network address [0x2ECD]. The device changes the state of the main presence/motion entity in both integrations at the same time.

However, you will notice ZHA does not have any entities for configuring the sensor. You cannot set the sensitivity, clear time or detection distance while in Zigbee2MQTT you can tweak everything. In this case, both integrations compliment each other and enable the full functionality of this device. The sensor itself is complete trash, but that’s irrelevant here.

Example 3: Using both integrations at the same time

To showcase how a device behaves when controlled through one integration only, I recorded a short video, triggering and changing settings on the BSEED Control Outlet.

Final Thoughts

Again, I’m not really sure if this is really beneficial for the average user. I believe running one integration is enough to cover most devices and use cases in Home Assistant.

However, for enthusiasts and tinkerers this is truly great. For example, I run two development networks with different coordinators when I test devices for the purposes of SmartHomeScene’s reviews channel. This way, I can only pair it once and test how it behaves and operates in both.

Missing clusters and exposes is usually a ZHA thing, so if you have devices that are partially supported in ZHA, attaching Z2M on the same coordinator will allow you to utilize the full functionality of the device, provided it is supported in Z2M. You can enable/disable duplicate entities exposed in Home Assistant, to keep your setup clean.

24 thoughts on “How To Use Zigbee2MQTT and ZHA with a Single Coordinator”

  1. Pretty interesting!,

    Too bad it can’t be used with USB coordinators because I am migrating from ZHA to Z2M and this method would be gold for me.

  2. Interesting post. A shame it cannot be done with USB coordinators. You might wish to put ‘network coordinator’ in the title as currently it’s a bit misleading.

  3. IV been using both zha and zigbee2mqtt on the same tubes network controller for over a year now. lots of flexibility

  4. If the network coordinator is just taking the same data that’d be over the (virtual) serial connection and putting it over TCP connections, you could probably convert a USB coordinator into a network one easily enough.

    Or, for that matter, duplicate the virtual serial port with some sort of serial port mux software.

    Although if either ZHA or Z2M have any state of their own, if that gets desync’d, I’d expect some interesting-to-debug issues with both of them talking to the same coordinator (regardless of how that’s done). Like, what happens if you make changes like adding/removing a device via ZHA while Z2M is down (or vice versa). Or change device bindings, especially to the coordinator. Does it get confused?

    • Just removes it from the other one too, no confussion.

      Not sure about the USB thing you are suggesting though, most likely it will introduce a lot of issues with minimal benefits

    • Yeah I think youโ€™re right, these networked dongles are just exposing the USB to serial connection over TCP – itโ€™s basically just a mini computer sharing the dongle.

      The same thing can be achieved with socat, which is a tool for exposing sockets over the network. I do this for my Z-Wave dongle where I have a spare RPi exposing the socket over TCP to my Z-Wave JS UI instance in a different room using socat.

  5. Great article, thanks SHS! I was happily using ZHA with a Sonoff USB coordinator for 6 months but then discovered when adding a presence sensor (Tuya ZY-M100) that it didn’t give me any config info in ZHA (as your article illustrated perfectly). I bought another Sonoff USB coordinator, config’d Zigbee2MQTT on it and paired the ZY-M100 to that. It gave me the ability to configure every little feature so I could tweak this perfectly to work in my environment. It is a little weird to use both ZHA and Zigbee2MQTT but is working fine.

    Unfortunately I am using a USB, not network coordinator so I had to buy a 2nd USB coordinator to use Zigbee2MQTT in addition to ZHA. ZHA was great at first and still works well for most stuff, but I find Zigbee2MQTT has much better device support and has a well designed user interface too. I like having both, so I know any Zigbee device I purchase going forward is likely to work in either ZHA or Zigbee2MQTT. ๐Ÿ™‚

  6. Two questions: Is coincidental that you installed in the order Z2M first and then ZHA or could it be done the other way around and still work? I’m asking because I cannot remember being asked about “keeping my existing network config” when installing Z2M.
    Second question; will this work on a Yellow?

  7. Thanks for the insightful article!

    I curious about the zigbee2mqtt instance- Do you have it connected to a mqtt server and publishing to the homeassistant topic aka home assistant integration?

  8. Comments are closed on the BSEED socket review, so please don’t mind me commenting on this article ๐Ÿ™‚

    I’d like to share that recent purchase of this socket (made in February 2024) are identified with different id : TS011F by _TZ3000_o1jzcxou

    And power monitoring does not work despite being at last firmware version (192 – 0x000000c0)

    Regarding this article, thanks for sharing ! I think for troubleshooting purpose it could be great, for example in my case I had to install a new HA instance to verify if this Bseed socket was working better on Z2M… Which is not ๐Ÿ™

  9. I didn’t know a PoE Powered Zigbee GW existed!
    Fantastic!

    But! I cannot decide what chipset to go for.
    The ZigStar UZG looks fantastic, but “only” has the CC2652P chip
    That is the same as my old Conbee II stick uses isn’t it?
    Isn’t purchasing a GW using the EFR32MG21 chip more future proof?

    Thanks

    • No, the Conbee II uses the ATSAMR21B18 module by Microchip, which is reaaaaly outdated by this point.
      The CC2652P is all you ever need for Zigbee only.
      If you want Matter/Thread, you can get the EFR32MG21.
      Although, I highly suggest you use a separate dongle for Thread.

  10. hey, is there an easy way how to migrate from conbee ii to zigstar coordinator (ZHA) without re-pairing all devices ?

    • No, In my experience there isn’t.
      You will have to re-pair most anyway, even if you restore the backup successfully.
      The only time a backup would work is if you use the same coordinator.

  11. Thanks for the tutorial. Worked like a charm with SLZB-06. The Aqara vibration sensors works like shit with z2m and I’ve been told it has some extra options with ZHA, so I wanted to try it.

    Is there any good practice regarding HA and having all the devices duplicated? Should I disable all devices I’m not planning to use with ZHA to avoid the clutter?

  12. After reading your amazing article I bought a SLZB-06M and easily migrated my 120+ devices from ZHA on skyconnect. Now I’m trying to install Z2M.
    -> It work, and during a minute I can see 2 sockets on the SLZB web interface, but Z2M crashes!

    What I did is:
    1)remove coordinator_backup.json
    2)modify configuration.yaml adding the following info:
    – channel: 20
    – pan_id: 0x89fb
    – ext_pan_id: [0xd2, 0x05, 0x8c, 0xdc, 0x93, 0x70, 0xac, 0x2d]
    – network_key: [ 0xe6, 0xff, 0x52, 0x32, 0x44, 0xb6, 0xed, 0x97, 0xcc, 0x00, 0x8d, 0x94, 0x89, 0x7c, 0x64, 0x12 ]
    I reversed the order of the 2 last lists.

    Unfortunately z2m crashes with those errors. Any idea of what I missed ?

    [2024-05-23 08:38:11] error: zh:ezsp:uart: –> Error: Error: Recv NAK frame
    [2024-05-23 08:38:11] error: zh:ezsp:uart: -!- break waiting (1)
    [2024-05-23 08:38:11] error: zh:ezsp:uart: Can’t send DATA frame (0,1,0): 00000004
    [2024-05-23 08:38:22] error: z2m: Error while starting zigbee-herdsman
    [2024-05-23 08:38:22] error: z2m: Failed to start zigbee
    [2024-05-23 08:38:22] error: z2m: Check https://www.zigbee2mqtt.io/guide/installation/20_zigbee2mqtt-fails-to-start.html for possible solutions
    [2024-05-23 08:38:22] error: z2m: Exiting…
    [2024-05-23 08:38:22] error: z2m: Error: Failure send version:{“type”:”Buffer”,”data”:[0,0,0,4]}
    at /app/node_modules/zigbee-herdsman/src/adapter/ezsp/driver/ezsp.ts:686:23
    at Queue.execute (/app/node_modules/zigbee-herdsman/src/utils/queue.ts:35:20)
    at Ezsp.version (/app/node_modules/zigbee-herdsman/src/adapter/ezsp/driver/ezsp.ts:466:24)
    at Driver.startup (/app/node_modules/zigbee-herdsman/src/adapter/ezsp/driver/driver.ts:173:9)
    at Controller.start (/app/node_modules/zigbee-herdsman/src/controller/controller.ts:124:29)
    at Zigbee.start (/app/lib/zigbee.ts:62:27)
    at Controller.start (/app/lib/controller.ts:109:27)
    at start (/app/index.js:107:5)

    • After some more testing I realized that Z2M work fine while ZHA is disabled.
      The crash I described occurs as soon as ZHA and Z2M are up together.

      Did you do somethig special in your Z2M config ?

      Thanks again

Comments are closed.