[RELEASE] Zigbee2MQTT Routing Driver v2

This driver lets you use remote Zigbee radios with Hubitat via Zigbee2MQTT.

You can use it across multiple Hubitat hubs and with multiple remote radios on the same hub. I think it's pretty cool. For the full story, take a look at the opening post for v1.

Version 2 is backwards compatible with v1. Check the instructions below for switching over.

What?

This "routing driver" pulls in MQTT messages sent by Zigbee2MQTT and creates matching devices in Hubitat. By default these will show basic attributes such as healthStatus, lqi and powerSource, but the messages can be routed to other custom drivers implementing a processMQTT method simply by installing that driver and changing the device type.

This gives Hubitat access to the massive array of devices supported by Z2M in a very standardised manner (JSON over MQTT) which makes driver development far easier than dealing with the intricacies of Zigbee every time. We can just lean on the work of others! :tada:

Using the native Zigbee features of Hubitat is always the preference as it reduces potential points of failure. However, when you have issues, where there's no driver support, or you require the messages be relayed to multiple devices, Z2M is fantastic.

Setup

Preflight

Before installing the routing driver you will need a working Zigbee2MQTT system. I'm using a Raspberry Pi 4 and a Sonoff Zigbee 3.0 USB Dongle-P, but you really can run Z2M on a Pi 1 with no issues and there are many supported adapters.

Under Settings > MQTT you must tick the "Include device information" option near the bottom of the page. Otherwise... well, there's not enough device information for things to work. :slight_smile:

Feel free to also enable the "Availability" feature under Settings > Availability. The default settings are completely fine. If you're using Home Assistant a completely separate MQTT feed is generated for that platform if you enable it. This won't interfere with the routing driver as we use the primary feed.

Installation

Search for the keyword "zigbee2mqtt" on Hubitat Package Manager and you should see "Zigbee2MQTT Routing from BirdsLikeWires". Requires HPM v1.8.7 or later. Or install manually using the links below. All files are required.

Configuration

After installing the driver, on your Hubitat system:

  1. Click "Devices" on the left navigation bar.
  2. Choose "Add Device" in the top-right.
  3. Click "Virtual".
  4. Name the virtual device whatever you like, it'll get changed. :slight_smile:
  5. Choose "Zigbee2MQTT" in the "Type" dropdown.
  6. Click "Save".
  7. Click "Devices" on the left navigation bar again, scroll down until you find "Zigbee2MQTT" and give it a click.
  8. Enter your MQTT broker IP address and, optionally, the username and password for it.
  9. Click "Save Preferences".

Upgrading from v1

  1. Follow the Installation instructions above, making sure all four parts are installed (this is automatic with HPM) but don't bother with the Configuration section. The new driver will not interfere with the old one.
  2. Click the Zigbee2MQTT device in your Hubitat Devices list, scroll down to Device Information and click the Type dropdown.
  3. You'll find two entries for Zigbee2MQTT. The old version is highlighted, so choose the other one and click "Save Device".

You can now safely uninstall the old driver, which was part of "General Drivers from BirdsLikeWires". Use the Modify option in HPM to remove it, or delete the driver from the "Drivers code" page if installed manually.

Usage

Your Z2M devices appear as children of the Zigbee2MQTT virtual device. They'll default to being a generic "Zigbee2MQTT Device" showing only the basic attributes such as healthStatus, lqi and powerSource reported by all Z2M devices.

If your device has switching capabilities then a nested child device will be created to handle those switches. Feel free to change the Device Label on these from their switch number to something more descriptive. This is the only occasion that a Hubitat label will be retained over data presented by Z2M, as it has no direct equivalent.

Note: Z2M and the Routing Driver care not about what is (often incorrectly) printed on the case of your device. Switch or relay "1" will refer to the electrical construction of the circuit and the device firmware, and not how the physical button may have been labelled. Please check!

Deletions

Other than the names of nested child devices, the only other thing not kept in sync is deletion. If you delete a device in Z2M, you must remove it manually in Hubitat.

You can merrily delete any child device, but it will reappear if Z2M sends out data for it. Device "friendly names" in Z2M always override labels in Hubitat.

Device Configuration

Everything should be done at source on Z2M. The Routing Driver does not duplicate any features such as debouncing, as these are far better dealt with at source.

Multi-Hub Use

Install this on as many hubs as you like; it's essentially Hub Mesh for remote Zigbee radios. Snazzy, I know!

When Is Best To Use This?

The Routing Driver is ideal for handling devices not yet natively supported in Hubitat, or those which are problematic on your Hubitat Zigbee mesh. It's also ideal to cheaply extend a Zigbee mesh to a remote location. That could be somewhere within network cable reach, or anywhere you can route network traffic. :wink:

5 Likes

Nabbing post 2 for updates. Not that I've ever used it. :sweat_smile:

Now tested with Zigbee2MQTT v2.0.0 and all is still working well. :+1:

3 Likes

Andrew, This is fantastic, thank you. This first link is 404 and I don't trust myself to do this manually.

I’ll try to fix it this evening!

I’d hold off installing until then as I have a somewhat breaking update coming. Be much easier starting once that’s out. :+1:

1 Like

Hey no rush, please. It's incredible the amount of devices supported on Z2M. I still try to keep my mission critical devices(flood/siren/security) on HE alone, but honestly Z2M is so rock solid there's really no worries.

No worries! I've finished testing on this end and just need to throw out some warnings to anybody using this, because I've had to make a change to the way the Device Network ID (DNI) is generated for HE from Z2M. I should have caught the problem with the v2 update, but... well, didn't. :man_shrugging:

I'll sort the warnings and update the links. Looks like GitHub tweaked the raw format for their URLs. :roll_eyes:

1 Like

BREAKING CHANGE

Watch out everyone, I've broken something!

With the v2.07 update I have altered how Device Network IDs are generated for HE from Z2M. They're now based upon the full 64-bit hardware ID of the device and not Z2M's 16-bit network address.

You might be able to see how I fluffed that up given I was using the Z2M "network address" to generate HE's "network ID". The trick is that the network address can change on Z2M under certain circumstances; re-pairing being the main one. This would result in a new, duplicate device being generated in HE and your automations silently failing.

The bad news is that the change will generate new, duplicate devices for everything and your automations not-so-silently failing. The good news is that duplicate devices will be a thing of the past from now on, as the ID is unique to the physical device, not its place on your Zigbee mesh.

What you need to do.

If you update to v2.07 you will need to swap all automations from any device with a DNI in the XXXX-01234 format to the newly generated devices with a DNI in the XXXX-0x0123456789abcdef format.

Duplicate devices with the new DNIs will begin to appear as they report in to Z2M. Devices with switch capabilities don't always report those capabilities in the first message, so it may take a little while. Or you can just go and turn them on and off to force the message.

Hubitat's "In Use By" feature is incredibly useful for finding and updating rules. My technique has been to append "OLD" to the previous device, then use "In Use By" to scour the rules and swap them over.

Then you need to manually delete the old device. If you accidentally delete the new one, don't worry. It'll regenerate the next time a message is received.

Apologies for the monumental faff, but this really needed to be done.

4 Likes

Would be sweet to see this same thing with a remote zwave js server…

I've managed to avoid the pain of Z-Wave in my life, but I'm sure someone could do it. :laughing:

1 Like

Again huge thanks. I have a dumb question, would this support a button controller paired to Z2M? Like an alarm keyfob

Is it supposed to be showing like the following?

It certainly could... :slight_smile:

The buttons I use are supported with my Xiaomi drivers, but I'd like to build out the generalised drivers installed alongside the routing driver to support some other device classes out of the box.

Would you be able to post the MQTT JSON output of one of your key fobs having each of the buttons pressed? I can use that to create a generic button driver. I could likely do it without, but seeing the output of a device a don't own would be a good sanity check.

Yup, that's spot on. The "1" devices are the switches of the physical device. You can name them whatever you want, they won't be changed now that they've been detected. If the device had multiple switches available they'd all be listed under the parent device.

Sweet!

So what type of devices are supported? I noticed it's not bringin in my Sonoff Valve, just two switches.

*** Disregard, it showed up after manually activating it. ***

Basically, stuff I use! :grin:

Everything in Z2M should appear as a "Zigbee2MQTT Device" at minimum once a message has been received from it, but the basic states are only whether it's online, what its power source is and the LQI.

Any device that has switch functionality should have that switch available, but if it does anything special (like report temperature or power) then that won't currently appear. My IKEA and Xiaomi drivers do add those states for those devices, but I'd like to build out the device support with some generic drivers so more random stuff works.

If you have something you'd like supported, if you could post the MQTT JSON messages of the device doing things, that would be helpful. I can't make promises as I've got so little time to devote to this these days - but in theory I can potentially support many devices with relatively few drivers because the Z2M output is so nicely standardised.

Awesome work!

1 Like

Sure, let me locate the swann One Keyfob ("SWO-KEF1PA"). It's quite an odd device supposedly already supported on Z2M.
More info here:Swann One Key Fob SWO-KEF1PA - Driver Request

In any event I'll locate it and pair to Z2M

2 Likes

Looks like zwave js ui can work with mqtt.

The structure of the MQTT messages for zigbee2mqtt and ZWaveJS are totally different. It would require a whole new interpretation layer to be written for @birdslikewires' Zigbee2MQTT routing driver to work for devices paired to ZWaveJS.

2 Likes