How To Use Zigbee2MQTT and ZHA with a Single Coordinator

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.

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

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:

• ZigStar UZG-01
  • Elecrow | Tindie
• HamGeek HMG-01 (ZigStar clone)
  • AliExpress 1 | AliExpress 2
• SMLight SLZB-06
  • AliExpress 1 | AliExpress 2

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

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:

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:

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:

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:

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.