This application allows you to visualize the topology and connectivity of your Zigbee network.
Important:
- The app requires at least Platform Version 2.3.8.117 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.htmlfile 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:
- Go to the Apps menu in the Hubitat interface.
- Select Hubitat Package Manager from the list of apps.
- Click Install and then Search by Keywords.
- Type Zigbee Map in the search box and click Next.
- Choose Zigbee Map by Dan Danache and click Next.
- Read the license agreement and click Next.
- Wait for the installation to complete and click Next.
- Go back to the Apps menu in the Hubitat interface.
- Click the Add user app button in the top right corner.
- Select Zigbee Map from the list of apps.
Usage
To use the Zigbee Map app, follow these steps:
- Go to the Apps menu in the Hubitat interface.
- Select Zigbee Map from the list of apps.
- Click the View Zigbee map option.
- Watch the app build the map of your Zigbee network.
- 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:
- Go to the Apps menu in the Hubitat interface.
- Select Zigbee Map from the list of apps.
- Click the Remove red button
- Click OK
- Click OK again (confirm removing of the helper device)
- Open Hubitat Package Manager
- Select Uninstall
- Check the Zigbee Map entry from the list of installed apps
- Click Next to confirm your selection
- Click Next to start the uninstall process
- Click Next to complete the uninstall process
Links
Have fun!
