[RELEASE] Zigbee Map app

This application allows you to visualize the topology and connectivity of your Zigbee network.


  • The app requires at least Platform Version since it uses a functionality released with this version!
  • Use at least version 1.9.2 of Hubitat Package Manager (HPM) to install the app. Older versions sometimes fail to correctly add the zigbee-map.html file in the File Manager.

How it works

Each Zigbee device keeps a list of other devices that are within direct radio range. This list is called the Neighbors Table. Each Zigbee device also keeps a list of devices that are connected to it as children. This list is called the Child Table.

The Neighbors Table and the Child Table help the device to discover and maintain routes to other devices on the Zigbee network. They also store information about the device type, relationship, capability, and link quality of each neighbor or child. This information is used to optimize the network performance and reliability.

The Zigbee Map application allows you to visualize the topology and connectivity of your Zigbee network. It works by first querying the Zigbee Coordinator (Hubitat hub) for its LQI information, which contains both the Neighbors Table and the Child Table. The LQI information reflects the quality and reliability of the wireless link between two devices.

The application then adds all the neighbors and children of the hub to an Interview Queue, which ensures that only one device is queried at a time.

The application repeats this process for each device in the queue, asking for its LQI information and adding its neighbors and children to the queue, until all devices are interviewed and the queue is empty.

The application then combines all the responses and displays a graph with nodes representing devices and edges representing links. The map reflects the current state of the Zigbee network, as the data is gathered in real time.

Important: Be patient; each interview require multiple interactions between the application and the device, so getting the full LQI information for a single Zigbee device might take up-to 20 seconds.

Additional notes

  • Some Zigbee Router devices may not comply with the Zigbee specification and fail to provide their LQI information when requested (colored as magenta - Interview Failed). These devices are not recommended for use in your Zigbee network.

  • The application waits for 25 seconds for each device to respond to the interview request. If there is no response, the device is marked as unresponsive and the application moves on to the next device in the queue.

  • Zigbee End Devices (typically battery-powered devices that enter sleep mode to conserve energy) are not queried for their LQI information, as they are unlikely to respond while sleeping or may not have this information available.

  • Some Zigbee End Devices may be incorrectly identified as Zigbee Routers by their neighbors or children. The application attempts to interview these devices, but will likely encounter a timeout.

  • After the Zigbee Map is fully rendered, you can update the network information of any device by right-clicking on its node to add it back to the Interview Queue. This may be useful for devices that were previously unresponsive or have changed their status.

How to install

Install using Hubitat Package Manager

To install the Zigbee Map app using the Hubitat Package Manager (and receive automatic updates), follow these steps:

  1. Go to the Apps menu in the Hubitat interface.
  2. Select Hubitat Package Manager from the list of apps.
  3. Click Install and then Search by Keywords.
  4. Type Zigbee Map in the search box and click Next.
  5. Choose Zigbee Map by Dan Danache and click Next.
  6. Read the license agreement and click Next.
  7. Wait for the installation to complete and click Next.
  8. Go back to the Apps menu in the Hubitat interface.
  9. Click the Add user app button in the top right corner.
  10. Select Zigbee Map from the list of apps.


To use the Zigbee Map app, follow these steps:

  1. Go to the Apps menu in the Hubitat interface.
  2. Select Zigbee Map from the list of apps.
  3. Click the View Zigbee map option.
  4. Watch the app build the map of your Zigbee network.
  5. The map is ready when the Interview Queue is empty.

How to uninstall

How to uninstall using Hubitat Package Manager

Follow these steps in order to completely uninstall the Zigbee Map application from your Hubitat hub:

  1. Go to the Apps menu in the Hubitat interface.
  2. Select Zigbee Map from the list of apps.
  3. Click the Remove red button
  4. Click OK
  5. Click OK again (confirm removing of the helper device)
  6. Open Hubitat Package Manager
  7. Select Uninstall
  8. Check the Zigbee Map entry from the list of installed apps
  9. Click Next to confirm your selection
  10. Click Next to start the uninstall process
  11. Click Next to complete the uninstall process


Have fun!


Frequently Asked Qustions

I cannot remove the "Zigbee Map Helper" device

The Zigbee Map Helper device is automatically removed when the Zigbee Map app instance is removed. It cannot be removed on its own because the app depends on it.

If you find yourself in the situation where the Zigbee Map app was removed but the Zigbee Map Helper device is still present, follow the steps below to remove the orphaned device:

  1. Go to Devices list
  2. Make a note of the Zigbee Map Helper device Id
  3. Enter the following URL in the browser Address bar, then press Enter

Very cool app. I can’t change tabs using Safari on iOS 17.4. I know it’s not the best screen size for using this app, but thought I should report it.

1 Like

Thank you for the report and for the map screenshot!

From the map, it looks like you really, really avoid using battery-powered Zigbee devices :slight_smile:

1 Like

So, it worked after closing and trying again. It also worked without any issues on my other C-8 (home to most of my end devices).

There are a few Sonoff contact sensors and a Linkind contact sensor that don’t want to check in.
BTW, the main repeaters are 3 Samsung Zigbee 3.0 outlets and 3 Sonoff Zigbee 3.0 dongles.
Once again: Extremely high on the cool factor. Really nice.
@danabw and @aaiyar where you at on this?


One feature request: There is no way to close out the app on iOS.

1 Like

thanks @dandanache great addition


as oprah winfrey said 'that. was. COOL!'


Very impressive app. Saw your other app "Zigbee Pairing Helper" and wow, finally!!


@dandanache You're amazing. Works great on my C-3.

Only anomaly (just a nit) I see is that although it correctly shows the link to my hub's lone child device (an Aqara 2-button) that end device also shows a link to another router (other end devices just show single links to their parents, as expected).

Terrific app!


Nice work @dandanache !

FYI none of the SONOFF battery-powered motion/temp/buttons are found. I tried waking them up before & after starting the map, re-interviewing the most likely router, no dice. Hue, ThirdReality, Aqara and Xfinity sensors show up just fine.

1 Like

Now we need a Zwave map.... if that is even possible


There is a built-in zwave map on the C-7 and beyond, but all of my zwave devices are directly connected.

4 of my Sonoff contact sensors are found, 2 aren't. Also, 1 of 4 Linkind contact sensors isn't found. Somehow, one time everything was found. The sensors were $7 each, so I'm not complaining. They have been working well for 2 years now.

1 Like

C5 hubs dont have this.... I have 3 C5 hubs and 1 C7.

They work great here. They are super stingy on messages so batteries will likely last forever (ish). I was just looking to meet their parents :wink:


This is what is really needed!

I just installed and opened the app, and I got this error (on my C-7):

HubitatConnection.fetchDevicesList() - Failed to fetch data: Unexpected token '<', "<!doctype "... is not valid JSON

1 Like

I just installed it from HPM. When I tried building the map I got this error on my C8
{"error":true,"type":"java.lang.Exception","message":"An unexpected error occurred."}

1 Like

What are the top left buttons Status, Devices, Config? Nothing happens when I click on Devices or Config.

1 Like

That happened to me the first time I ran it, but after closing and restarting the app I was able to open those tabs.

1 Like

Nope, did not work for me.

1 Like