Zigbee Map - Visualize your mesh network

Timsche2210 · February 4, 2026, 5:46am

hi
whats the correct image type?

I tried jpg and png

or is the URL wrong?

mmstano · February 4, 2026, 6:29am

you use “local” instead of “/homeassistant/www”

dandanache · February 5, 2026, 7:51pm

Released version 2.10.1 with teh following small fixes:

Fixed

Fix top menu rendering on 2026.2.0
Catch and display Z2M exceptions in the “Console” tab (issue #7)

Have fun!

aruffell · February 6, 2026, 7:53pm

@dandanache - I really love your work! While a visualization map for Zigbee has been added a while back in ZHA, I feel like ZHA is lacking on the troubleshooting tools. I don’t use Zigbee2MQTT because of the MQTT requirement… if it had websocket support, I would in a heartbeat given the added tools and features.

It’s fun to watch the map form - reminds me of popping popcorn, but I was wondering whether there was away to have it persist - and just update when viewing in the interest of time.

Also, I noticed it said something about probing 40 or so devices, and in the log I think I counted 46, however I have 95. I did not count the ones shown on the map, but my guess is all 95 are there. Is the probing only for routers?

This will be fun to hunt down, but I was unaware so great to see this feature. I randomly see log entries about unknown devices and wonder whether something is not working right or it is devices from my neighbor.

To make up for some shortcomings of ZHA, I use this table a lot when troubleshooting issues. I was wondering whether a few additional - user selectable - columns could be added to your device list. The partial snapshot below shows all the columns that are available in this table:

(credit: custom:zha-network-card by dmulcahey - I believe one of the awesome ZHA developers)

The online column is an easy way to find devices with issues. NWK is how the logs reference the device so it is useful to figure out what device the logs are referring to. RSSI is helpful in the same context of when LQI is. IEEE would be nice in its own column for readability. And… it would be awesome if the data could be exported in a comma delimited file (csv) - but that is me being greedy

I have lots of space to fill with more data

dandanache · February 6, 2026, 9:44pm

This is actually one of the reasons I like Z2M: my Zigbee mesh keeps humming along even when I restart HA. And MQTT is awesome for creating virtual entities and devices through its discovery topics. What I really don’t like though, is that my Zigbee devices end up listed under the MQTT integration together with unrelated Wi‑Fi devices that also use MQTT

Since I get all the information needed to build the map in a single call to ZHA, I can build it instantly. I just reused the Z2M mechanism that queries each device one by one, and the “popcorn effect” exists purely because of that. It’s actually mesmerizing to watch the map come into existence, but I get it… we live in the age of speed and shrinking attention spans. I’ll try to improve this.

The app keeps a processing queue. It starts with 1 (the coordinator), so initially you’ll see “Mapping… 1 device to go”
After the coordinator is queried, it is removed from the queue and all its neighbors are added. So if the coordinator has 25 neighbors, the message becomes “Mapping… 25 devices to go”
As it processes each neighbor, it discovers more devices and updates the queue accordingly. Sometimes the number goes up. There’s no way around this with Z2M.

This looks like a very healthy Zigbee network, very few reddish lines. Nice!

I probably need to add something about this in the “About” tab, or maybe just hide the warning message entirely. This has come up earlier in the thread. These aren’t your neighbor’s devices, but are old devices that used to be part of your mesh but are now gone. Ghosts that are angry you removed them and have come back to haunt your mesh!

You are right, the device list needs some love: more columns, maybe some grouping, etc. I’ll see what I can.

Thanks for the feedback!

aruffell · February 6, 2026, 10:02pm

That is indeed a nice advantage, however I see the MQTT layer as an additional failure point that I can avoid by going direct. Anyway, just like ZwaveJS UI did, I hope Zigbee2MQTT will also gain a websocket connection so users can pick what they prefer.

Lol, it is indeed now that I am relaxed. When trying to figure out why a part of the house went unresponsive, I might not be in the mood for ‘cute’. For some reason random devices - usually Jasco - tend to freeze traffic in portions of the house. By power cycling that part of the house (or the device if possible), things start working again. I thought Zigbee would pick a different route if one stops working but it doesn’t seem to work in these occasional cases. What has helped is removing Jasco devices, and updating to newer/better devices such as Inovelli’s products. Given most rooms have ceiling fans, I switched all my ceiling fan switches to Inovelli Blue fan controller switches thus creating a solid zigbee backbone with devices that can’t be unplugged.

Most are from a Sonoff mmwave presence sensor that I am not even using. It appears that the red lines are often caused by specific devices. Whether that is true or not, I’ve been replacing them with alternative solutions. Seems like the strategy is working… for now, lol. Just jinxed myself!

I forget the details but I used to have bad issues with that. I believe it used to be with Zwave though… Any way for me to vanquish those ghosts? Rather than having the log entry hidden, I’d like to fix the issue before I end up living in a haunted house

Again, awesome work!!! Love it!

dandanache · February 6, 2026, 10:32pm

Zigbee can heal pretty quickly if a repeater goes offline, but a single misbehaving repeater can wreak havoc in its vicinity. I avoid Tuya devices like the plague for exactly this reason.

The repeater that reported them still thinks they’re part of the mesh. Sometimes they clear on their own, sometimes a simple power cycle of the repeater is enough. Other times you need to reset the repeater (re‑pair it without removing it from the mesh so it gets rediscovered).

But the ghosts are most likely harmless, and you can do more damage in the process of removing them.

dandanache · February 8, 2026, 8:16pm

Released version 2.11.0 with the following changes:

Added

Add “Export” functionality in Zigbee Map devices list - @aruffell
Add “Group by” functionality in Zigbee Map devices list
Add “Group by” functionality in Zigbee Log messages list

Fixed

Fix “Sort” dropdown rendering on 2026.2.0

Have fun!

JJW.AU · February 8, 2026, 11:33pm

Dumb questions but:

Is there an export button in the device list? I can’t seem to find it on the mobile app?
Any reason why the ZigBee log option is always greyed out/disabled for me?

mmstano · February 9, 2026, 12:49am

1 - It’s available on mobile, but you have to turn the phone sideways (landscape view)

2 - How did you install Zigbee Map? Manually? GPM? HACS?

dandanache · February 9, 2026, 11:30am

It’s hidden in the mobile/compact view, the idea being that nobody really wants to deal with CSV files on their phone. Rotating the phone works if you’ve got one that has more pixels, like @mmstano; on mine I get the same view

Zigbee Log isn’t available for ZHA for the simple reason that I don’t know how to access those logs, if they even exist. I don’t run ZHA myself, so I am a bit at a loss here.

JJW.AU · February 9, 2026, 1:20pm

Cool thanks that makes sense. I thought I had a cache issue. I managed to force desktop view in my phone’s browser to see the button .

When I was deep in debugging my ZigBee network I used AI to help write a script to bulk download the ZHA diagnostics logs from all the mains powered router devices. It is probably junk code but works for me. I’ve shared here

Homerssistant · February 17, 2026, 4:22pm

Dear all,
Please kindly have a look at my following issue. I have no idea where to search for the root cause.

Situation:
I installed “Zigbee Map” with HACS and it worked and looked great when I started using it about two weeks ago.
Since a couple of days I see only a blank page in “Zigbee Map” and “Zigbee Log”.

When I try to open “Zigbee Map” , the log shows this message afterwards:

Logger: frontend.js.modern.202601286
Quelle: components/system_log/__init__.py:331
Erstmals aufgetreten: 15. Februar 2026 um 17:36:02 (15 Vorkommnisse)
Zuletzt protokolliert: 21:26:57

Uncaught error from Chrome 142.0.0.0 on Windows 10 TypeError: Cannot convert undefined or null to object /api/panel_custom/zigbee_map/zigbee-map-panel.js:195:17
Uncaught error from Chrome 142.0.0.0 on Windows 10 TypeError: Cannot convert undefined or null to object /api/panel_custom/zigbee_map/zigbee-log-panel.js:152:16
Uncaught error from Chrome 144.0.0.0 on Windows 10 TypeError: Cannot convert undefined or null to object /api/panel_custom/zigbee_map/zigbee-map-panel.js:195:17
Uncaught error from Chrome 144.0.0.0 on Windows 10 TypeError: Cannot convert undefined or null to object /api/panel_custom/zigbee_map/zigbee-log-panel.js:152:16

(BTW: I’m not running Win 10 but that’s just a side issue.)

HA, Z2M Add-on and Zigbee Map are installed in their latest versions.

Home Assistant:

Core: 2026.2.2
Supervisor: 2026.02.2
Operating System: 17.1
Frontend: 20260128.6

Z2M Add-on: 2.8.0-1
Zigbee Map: 2.11.0

I have tried the following with no success:

clear the browser cache,
used a different browser
tried a browser on different PC
removed and reinstalled “Zigbee Map”

So I assume the problem might by a server side one…
I have no clue where to look at in order to search for a root cause.

Is there anything I can do to support resolving this?

Many thanks in advance.

dandanache · February 17, 2026, 5:54pm

This is weird. try this:

Open Home Assistant UI in your browser (any page)
Press F12 on your keyboard to open the browser console / developer tools
Go to the Console tab

Type the following lines, one by one, in the console prompt (>) then press Enter:

> customElements.get("ha-panel-lovelace")
> JSON.stringify([...customElements.h.keys()])

Paste the output here. From the looks of it, for some reason, customElements.get("ha-panel-lovelace") returns undefined on your browser.

This is how it looks on my Brave browser:

Thank you for your help!

Edit: does it work on your mobile in the Companion app?

Homerssistant · February 18, 2026, 8:45pm

Hi Dan,

Thanks for your fast reply.

Here you go.

customElements.get("ha-panel-lovelace")
undefined

JSON.stringify([...customElements.h.keys()])

'["ha-panel-config","wa-icon","ha-drawer","partial-panel-resolver","home-assistant-main","wa-spinner","ha-spinner","wa-button","ha-button","ha-init-page","home-assistant","action-handler","wa-animation","ha-fade-in","ha-svg-icon","ha-icon","mwc-ripple","mwc-icon-button","ha-icon-button","ha-md-list","md-focus-ring","md-item","md-ripple","ha-ripple","ha-md-list-item","ha-user-badge","ha-sidebar","h…'

As you already anticipated, the first command returned “undefined”.

I had to install the Companion App first… but sorry to say: it shows the blank page there as well.

Update:
I tried a 3rd PC today.
A Surface Pro 5 running Windows 11 and the Vivaldi browser (same as on my other PCs).
Strange enough: on the Surface Pro, the Zigbee Map and Zigbee Log work as normal!
That confuses me even more.

On PC 1: Blank page in Vivaldi and Firefox
On PC 2: Blank page in Vivaldi
On Mobile (Android): Blank page in HA Companion App
On Mobile (Android): Blank page in Vivaldi Browser
On Mobile (Android): Blank page in Firefox

Only the Surface Pro with Vivaldi does show the “Zigbee Map” and “Zigbee Log”.

Really weird, isn’t it?

mgrn0 · February 21, 2026, 7:01am

I just want to say thank you for this addon, it’s incredible useful. Tool me a while to realize that the network takes some time to show all available nodes, it was much better representing the grid after a night of waiting for a newly setup network.

jjross · February 22, 2026, 8:50pm

I am also having this issue. Same error. Same undefined on:

customElements.get("ha-panel-lovelace")

dandanache · February 22, 2026, 9:34pm

I tried to shave a few KB off the JS files by dropping the dependency on lit and relying on the version bundled with the HA front‑end.

It seemed like a glorious idea at the time, but looks like the results are hit and miss. And since we don’t treat the kilobyte as sacred anymore like we did in the old days, I’ll add the dependency back in when I get a bit of time.

Thanks for reporting this!

dandanache · February 24, 2026, 8:14pm

Released version 2.12.0 with the following changes:

Added

Add “Sort by” functionality in Zigbee Log messages list

Changed

Build ZHA Zigbee map instantly - @aruffell

Fixed

Fix slug config option (#3) - @hippoo
Don’t use the Lit version that is shipped with Home Assistant - @Homerssistant, @jjross

Have fun!

aruffell · February 24, 2026, 9:40pm

@dandanache - Don’t see it yet, but I am sure it will pop up shortly in HACS. Thank you for adding the instant feature… the other day I was troubleshooting a zigbee issue that required seeing the message path from a troublesome device to the controller and waiting for the map to populate each time (as much as I enjoy watch it pop) was a bit too long of a process.

An issue that became apparent was that finding the device in the map was quite difficult on my phone. A dropdown or search box for the device name would be awesome.

In my case, the device was not even there as it was disconnected. Other maps then to show disconnected devices in red with now connections. Have you considered doing that too?

Is there a way to show what the last path for any disconnected device was? Given it is a mesh, maybe this doesn’t make sense, but I often find dead devices caused by another hung device causing issues. The hung device often shows as online so it is quite hard to find… but now I know my usual culprits so I start by power cycling those… and things start working again.

Hope I am not being greedy here Thanks for sharing your work with us!

Edit: Just saw the super snappy mesh map, thanks! Unless too time consuming, an option for fast/slow might be appreciated by those needing a zigbee popcorn fix