[RELEASE] Zigbee Monitor Driver - Like XRAY Vision for Zigbee Repeaters and simple Switches

Intro
I bought 4 dedicated USB mini Zigbee repeaters a few months ago to bolster my network. I’m the author of Tile Builder and it irked me that such a critical component of the network offered almost nothing in terms of insights. What I wanted to know was:

  1. To which repeater were my battery devices connected. (Parent -> Child)
  2. How strong were the connections between devices on my network.
  3. What did the Zigbee routing table look like.
  4. Is the repeater online and operational.

There are several tools available but they all have their shortcomings.

  1. http://ip/hub/zigbee/getChildAndRouteInfo gives me the hubs perspective and is quite useful, but doesn't usually include all devices and I can only see the first hop. The same is true of the Zigbee Network Graph tool which is based on the same information and has the same limitations.
  2. XBEE Network Assistant is quite useful but an XBee module is now $140 on Amazon (plus another $10 for the adapter) which is pretty huge barrier. Also, the XBee Network Assistant software only displays nodes using a 6 digit network address making it painful to use as you must constantly be reconciling addresses to names when you are trying to figure things out.

The Zigbee Monitor Driver requests information from the device at configurable intervals to provide precise details of the Zigbee network as seen from the device. There are two primary groups of information gathered from the device. A) Neighbor info which includes relationships with LQI data and B) Route info

Device Neighbor Info


Neighbor info key points.
hubDataCollectionMode: Only Addresses - The driver is configured to get a list of addresses from the Hub and then resolves Zigbee addresses back to their device names for easier comprehension.
deviceNeighbors: This is a list of ALL neighbors retrieved from the the device along with their LQI value and sorted with the highest LQI first (configurable).
deviceParent: This is the parent device of this repeater along with the LQI. A repeater that connects directly with the Hub will list the HUB as the parent device. A repeater that lists "None", ONLY routes to the Hub via another repeater.
deviceSiblings: These are sibling devices or more plainly, other Zigbee repeaters along with their LQI.
deviceChildren: These are child devices with their LQI. These are battery devices and do not repeat. ALL data between the child device and the Zigbee network gets routed via this device.

Device Route Info


The route data is the less illuminating of the two and and by default it is turned off.
The display of routes is in the format Device via Repeater but can be changed to Repeater :arrow_right: Device if desired.

Hub Data Collection
By default the driver will attempt to retrieve a list of all Zigbee devices and addresses from the Hub. These are used to provide name resolution and make the driver a lot more user friendly. This behaviour can be modified in preferences. Unless you are adding new devices you really only need to run this once to download the list of names but by default it runs every 24 hours to catch any new devices.

If you wish to expose more Hub Zigbee information you can change the Data Collection Mode as shown below and the Save Preferences.


This will expose the following Hub information:

These attributes can then be accessed in whichever way you see fit. You only need to run this configuration on one device and it could be a virtual device if desired. For all others the Collect Zigbee Address Information is all that is required.

Installation
You can install the Zigbee Monitor Driver via HPM under the Zigbee category. Once installed simply re-assign your device to this driver and hit Save Device. Now perform these steps:

  1. Wipe: Removes all settings, state, current state and scheduled jobs.
  2. Initialize: Configures the default values for the Preferences.
  3. Refresh Browser (F5): Will show the default Preference Settings.
  4. Modify Preferences and Save
  5. Perform Get Hub Info: Retrieve the information from the hub according to preferences.
  6. Perform Get Device Info: Retrieve the information from the device according to preferences.
    You can repeat this process as many times as you wish.

If you wish to return the device to the prior driver simply do a Wipe and then re-assign the old driver and configure any required preferences.

Device Compatibility
I have 4 unique types of Repeater and three of them support the retrieval of both the neighbor and routing information. However, one of them only supports neighbor info, not routing. This is hardware dependant so your results may vary. Please PM me with your own compatibility and I will maintain a list of repeaters\switches along with which functions work and which don't. You can find that list in the next post.

Switch Compatibility
While the driver is primarily intended for use with dedicated Zigbee repeaters it also incorporates On/Off behaviour that allows it to work as a switch. If you have a simple switch with no other functions (power management for example) then you can use this driver as a replacement to provide more permanent insight into your Zigbee network.

Zigbee Repeaters
It is worth noting that the repeating function of Zigbee devices occurs at the firmware level and works regardless of the Hubitat driver that you choose. This driver is no different and only queries the available information from the device and has no influence on the routing of Zigbee packets.

Accuracy
How accurate is the Zigbee Monitor Driver? The short answer is very accurate. The more complete answer is that it only provides a point in time picture based upon the polling frequency of the repeaters. However, in my own experience while the LQI and routes vary, the relationship between the parent\child is quite strong and does not change readily.

Health Status
This driver implements the normal Health Status capability with a configurable timeout period.

Tile Builder Multi-Attribute Monitor Advanced
For those of you with Tile Builder Advanced you can bring all of the driver data to your dashboard.
This is a detail view of a single Repeater.

This is the view across all of my repeaters showing the precise parent\child relationship for all of my end devices along with the signal strength.

This latter table answers my most pressing questions, which devices are connected to which repeaters and how strong is the connection. For background, Repeaters M1 - M4 are mini USB repeaters. Repeater S1 - S2 are Sylvania plugs. Light Strip 1 - 2 are Third Reality plugs and the XBEE is self evident. All my other devices are Tasmota on WiFi and not shown in this table.

How to get the Zigbee Monitor Driver
The device driver is located here: Link or you can install it using HPM.

15 Likes

Device Compatibility Info:

This post will be used to maintain a list of devices that work with this driver. I hope others will submit the info as shown here so that this list can be maintained. Hopefully the information available via this driver will provide a more scientific basis for assessing the performance of Zigbee repeaters and aid in purchasing decisions.

Tuya Mini USB.
Picture: Amazon
Supports Neighbor Info: True
Supports Routing Info: True
Driver Data Manufacturer: _TZ3000_gszjt2xx
Driver Data Model: TS0207
Note: For their small size they perform decently well and can outperform some much larger devices.

Sylvania Smart Plug
Picture: Amazon
Supports Neighbor Info: True
Supports Routing Info: True
Driver Data Manufacturer: LEDVANCE
Driver Data Model: PLUG
Note: These are by far my best performing repeaters (not including XBEE) maintaining an LQI in excess of 200 with most other repeaters within 30ft through walls and floors.

Third Reality Smart Plug
Picture: Amazon
Supports Neighbor Info: True
Supports Routing Info: False
Driver Data Manufacturer: Third Reality, Inc
Driver Data Model: 3RSP02028BZ
Note: These are my poorest performing repeaters. 10ft from my Hub in open space and I get less than 100 LQI on both of these devices.

XBEE: XB3-24Z8ST-J RF Transceiver Module
Picture: Amazon
Supports Neighbor Info: True
Supports Routing Info: True
Driver Data Manufacturer: N/A
Driver Data Model: N/A
Note: This performs very well, but I bought it for diagnostic reasons and it has a 6" antenna on it so it's not a fair comparison.

IKEA: TRADFRI signal repeater
Picture: IKEA
Supports Neighbor Info: True
Supports Routing Info: True
Driver Data Manufacturer: IKEA of Sweden
Driver Data Model: TRADFRI signal repeater

SONOFF: Zigbee 3.0 USB Dongle
Picture: Amazon
Supports Neighbor Info: True
Supports Routing Info: False
Driver Data Manufacturer: ??
Driver Data Model: ??

Sinope: Water Heater Controller
Picture: Amazon
Supports Neighbor Info: True
Supports Routing Info: True
Driver Data Manufacturer: Sinope Technologies
Driver Data Model: RM3500ZB

Sinope: Thermostat for Electric Heating
Picture: Amazon
Supports Neighbor Info: True
Supports Routing Info: True
Driver Data Manufacturer: Sinope Technologies
Driver Data Model: TH1124ZB

Sonoff: ZB Mini
Picture: Amazon
Supports Neighbor Info: True
Supports Routing Info: True
Driver Data Manufacturer: SONOFF
Driver Data Model: 01MINIZB

4 Likes

The purpose of this post is to demonstrate that the Zigbee Monitor Driver uses the exact same information as an XBee does and can be a budget way of examining\diagnosing your Zigbee network.

The image below show Repeater M1 as it displays within the XBee Network Assistant vs the information retrieved by the Zigbee Monitor Driver.

End Devices

The devices are listed in the same order from top to bottom. As you can see the LQI values from the driver are 100% consistent with the color coding ranges defined in the app.

In XBee Network Assistant you can click on a link to get more information on the properties. This is the top device (Sunroom Remote) and you can see the LQI matches exactly in this case, although I would typically expect there a variance between them as they are sampled at different intervals.
image

Route Links
You can see in the image below that XBee shows repeater M1 having 4 connections (Hub, S2, M2, XBEE) to other repeaters. However the driver shows 7 repeaters in the neighbor table and 8 active routes. Why the discrepancy?

Neighbors are a list of devices that are only 1 hop away. Routes are a list of known paths to devices more than one hop away. What XBee displays is Repeater Neighbors with an entry in the Routes table. In this case the four repeaters marked in green in Routes are ALSO present in the neighbors list and are the 4 links displayed in the XBee image. Again you will see the route color codes between M1 and repeater partners are pretty consistent given they were taken 15 minutes apart.

I hope this helps people understand the information available and give an appreciation of its significance.

1 Like

The final post on this topic is on how to use this data to troubleshoot or improve your network.
I'm fortunate in that I can run this driver on all of my Zigbee repeaters and see my whole network at once. For devices that don't need instantaneous response I use Tasmota.

End Devices
On the left I could see two devices that were not optimally paired, Gary Remote and Bathroom Sensor. Neither of these were pairing with the nearest and best repeater which was Repeater S2.

By bringing the device close to the desired repeater and then going through a Zigbee re-pairing process I was able to move them to a better repeater and improve their connection considerably.

In the process of doing this I briefly powered off the M1 repeater and as you can see the Mailbox sensor jumper over to the M2 repeater on it's own volition.

Note 1: When you re-pair an existing device to Hubitat it is issued a new 4 digit Zigbee ID so my Repeater S2 looked like this until such time as the device retrieved new address information from the Hub at which time it resolves.
image

Ghosts As you can see both Repeater M1 and Repeater M2 both consider themselves to be the parent of the Mailbox Sensor. When M1 stops hearing from the device it will eventually disappear from the neighbor table. The LQI value of 0 indicates it sees connectivity to that device as broken.

Routes
I will add some content on Routing in a little while.

1 Like

Clicking on the Preferences Hub: Community Thread Link goes to https://www.gitpod.io

I just fixed that. Couldn’t add those until I created the topics in the community.
Please update.

1 Like

Thanks for creating this, looks very interesting!

Not finding the driver in HPM, searched using the entire driver name and different combinations of "Zigbee," "Monitor," and "Driver" and it's not coming up for some reason for me.

EDIT: The driver is now available via HPM in the Zigbee category.

2 Likes

Sorry - managed to totally miss this! :slight_smile:

1 Like

This definitely bugged me too!

Then you might be interested to know there is an option in the driver where you can turn on appending the 4 digit Hubitat ID or the last 6 digits of the network address which is what the XBEE displays.

So then the display looks like this.

Thanks for your amazing work. Can you please explain what numbers in front of each device stand for? (For instance: repeater,184)

That number is the LQI which means Link Quality Indicator. It is a range from 0 to 255 with higher numbers being better. I shoot for 100+. There is no hard line for good vs bad but around 60 or less would be a weak signal.

1 Like

Sonoff repeater causing errors

I've taken a closer look at the logic and I don't find anything wrong with it. Please follow the reset instructions (don't skip step 3) and let me know if that works or not. Seems like it is working for others with the same repeater.

It's that the USB dongle repeater?

This is pretty amazing. You developer types are one of the main reasons I love coming here. I'm supposed to be going to bed now, but I'm really too excited to sleep, like a little kid... With grey hair and lots of wrinkles.

I know @Tony will love seeing this
And @kkossev too

5 Likes

If this is with a Sonoff USB dongle, I'm not seeing any log errors following @garyjmilne's directions testing with one of my Sonoff dongles.

Trying this on my exbee and a number of basic switch devices. Get this error which seems like its pointing in the wong place?

Yes and on both.l of them when i turn on device routing data i get the error and this

Do the dongles not support getting device routing?