[RELEASE] Zigbee2MQTT Routing Driver v2

Now with control of switches!

For the full story, take a look at the post for v1.

Fully 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.

Installation on Hubitat

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.

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 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 "Zigbee2MQTT Generic Device" though a few of my drivers (IKEA, Tuya and Xiaomi) do include a processMQTT method and at the moment they are chosen automatically. This will likely change in the future to all devices being generic by default.

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 name 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 (usually incorrectly) printed on the case of your device. Switch or relay "1" will refer to the electrical construction of the circuit, and not how the button may have been labelled. Please check!

Deletions

The only thing not kept in sync is deletion. If you delete a device in Z2M, you must remove it manually in Hubitat. If you re-pair a device in Z2M it may not always receive the same network address, so check for duplicates.

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:

4 Likes

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