Help build a community database of real Zigbee device capabilities

hsolgaard · July 26, 2026, 3:27pm

Zigbee manufacturers rarely tell us exactly what their devices support, and I’m sure I’m not the only one who bought a Zigbee device, hoping it would allow me to directly control a specific feature.
A datasheet might describe something as a relay, dimmer or motion sensor, but it often does not tell us:

which Zigbee commands the device actually implements;
whether it works with direct binding or Zigbee groups;
whether it reports state changes automatically;
whether capabilities differ between firmware versions;
why a structurally valid binding may still fail in practice.

I have therefore started building Zigbee Capabilities: an open, community-built database based on scans from real devices running real firmware.

The aim is to document what Zigbee devices actually support, using community evidence rather than assumptions or manufacturer claims.

A separate project, but connected to ZHA Bindings Manager:

https://community.home-assistant.io/t/zha-bindings-manager-visual-manager-for-zha-zigbee-direct-bindings-graph-table-view-drag-and-drop-bind-unbind

That thread remains the place for discussion of the bindings card itself: visualising, diagnosing, creating and removing ZHA bindings.

I have created this separate thread because the aim is to make Zigbee Capabilities becoming a community resource in its own right, with its own purpose and standalone website.

ZHA Bindings Manager provides the current scanning and contribution workflow, and also contains a built-in Capability Explorer. However, the resulting dataset is open and can be used independently of both the card and Home Assistant.

Browse the standalone Capability Explorer

The public database can be explored here without installing anything:

Zigbee Capabilities — community device capability database

It currently allows you to:

find devices by practical uses such as on/off control, dimming and scene control;
search by manufacturer, model, cluster, command, attribute or firmware;
inspect the capabilities confirmed for a device;
see the strength and recency of the supporting community evidence;
compare two observed firmware versions and see what changed.

The interface tries to explain capabilities in user-friendly terms while keeping the underlying Zigbee commands and evidence available for anyone who wants the technical detail.

This only becomes valuable if people contribute

This is the most important part.

A single scan tells us what one physical device running one firmware version reported.

Repeated scans:

strengthen confidence in the result;
reveal inconsistencies or device variations;
identify firmware-dependent changes;
improve coverage across different manufacturers and models;
make searches more useful for the next person.

A missing result does not mean that a device lacks a capability. It generally means that nobody has yet contributed suitable evidence for it.

There is inevitably a chicken-and-egg problem: people will use the database when it contains good coverage, but good coverage only develops when people contribute.

That is why I am asking other ZHA users to help.

How ZHA users can contribute

The Capability Explorer and contribution workflow are built into ZHA Bindings Manager v0.29.0 or later.

Repository and installation instructions:

https://github.com/hsolgaard/zha-bindings-manager

To contribute:

Open the device in ZHA Bindings Manager.
Run Check supported commands (found under Explode in the Devices tab)
Review the discovered capabilities.
Choose to contribute the scan.
Review and submit the prepared GitHub issue.

Nothing is uploaded automatically.

The contribution deliberately excludes local information such as:

IEEE addresses;
entity IDs;
Home Assistant areas;
local device names;
binding information.

Only the technical device, firmware and capability information that you review and choose to share is submitted.

You do not need to own an unusual device. Repeat scans of common products are valuable because they strengthen the evidence and may uncover firmware or hardware variations.

What would be particularly helpful

I would welcome:

devices not currently represented;
repeat scans of existing models;
alternative firmware versions;
multi-endpoint devices;
feedback where a plain-English capability description is unclear;
reports of capabilities that appear incorrectly grouped or translated;
suggestions for practical searches people would genuinely use.

The longer-term aim is not simply to produce another list of raw Zigbee commands.

It is to help answer practical questions such as:

Can this device directly control a light?
Does this relay support timed-off behaviour?
Will it report its state without polling?
Did a firmware update add or remove capabilities?
Which devices support the feature I need?

If you use ZHA, please consider contributing even one device. Every scan makes the database more useful and trustworthy for the next person.

Standalone Explorer:

Zigbee Capabilities — community device capability database

Contribution tool and documentation:

https://github.com/hsolgaard/zha-bindings-manager

Thank you in advance!

ShadowFist · July 26, 2026, 6:21pm

Silly question:
If you want to grab the capabilities/clusters of a bunch of devices, why not scrape the Z2M website or the zigbee-herdsman converters github?
Granted, just because a device has a specific cluster support in Z2M does not mean it has the same support in ZHA, but that’s a ZHA limitation, not a device one.

hsolgaard · July 26, 2026, 8:14pm

That’s a good question, thank you, and it’s something I considered when starting the project.

Under the hood, the capability data isn’t coming from ZHA itself. It’s collected using zha_toolkit.scan_device , which actively interrogates the device and records the endpoints, clusters, commands and attributes that the device reports through the Zigbee protocol.

The aim isn’t to build another database of what a particular stack (Z2M, ZHA, etc.) supports. It’s to build a database of what real devices actually advertise and implement, based on live capability scans and community observations.

Zigbee2MQTT converters are an excellent resource, but they describe how Zigbee2MQTT interacts with a device rather than providing raw capability observations. They also don’t naturally capture things like repeated community observations or firmware-to-firmware differences.

My hope is that this becomes an evidence-based reference that complements existing projects rather than replacing them. If a device advertises a capability, multiple people observe the same thing and a firmware update changes it, that’s useful information regardless of which Zigbee stack someone uses.

ShadowFist · July 26, 2026, 8:28pm

Playing devil’s advocate here, but what’s the point in getting what a device advertises when the underlying integration (ZHA in this case) has no support for it because whoever wrote the quirk left it out? It’ll just frustrate the many users who say “but Z2M has support for it!”.

It defeats the purpose of asking “Which devices support the feature I need?” because you won’t be sure that that specific feature is implemented in ZHA/Z2M until you buy that device and find out for yourself. You should be aware by now that the vast majority of zigbee devices do not follow the standard at all - the supported devices all rely on people actually sniffing the traffic and writing custom quirks/converters for them.

Don’t get me wrong - it’s a great start, but it’s still a start. Calling zha_toolkit.scan_device will not reflect what is actually currently supported in the user’s preferred zigbee integration. Won’t this just lead to user frustration and complaints if your integration advertises a feature which turns out to be unsupported when they buy it?

hsolgaard · July 26, 2026, 9:01pm

Thanks - helpful challenge!

A zha_toolkit.scan_device scan tells us what the device reports through its endpoints, clusters, commands and attributes. It doesn’t, by itself, prove that every reported capability works correctly or is currently exposed in ZHA or Z2M. Those are different things, and I should probably make that clearer in both the wording and the UI.

The project really grew out of my own frustrations using Zigbee (after a crash course!). I first built the Bindings Manager because I found direct bindings complex to manage, visualise and troubleshoot. As I explored devices more deeply, I realised the same complexity existed around clusters, commands and attributes, which led to the Capability Explorer. The aim has always been to make that information easier to understand without needing to be a Zigbee expert, not to compete with Z2M converters, ZHA quirks or other databases.

Rather than showing users a wall of technical detail, the Explorer tries to explain what reported capabilities are commonly associated with, while still exposing the underlying evidence.

I completely take your point that terms like “supports” or “good for” could imply more than the current evidence proves, so I need to tighten that language.

Thanks again for the feedback - really appreciate it!

tom_l · July 26, 2026, 9:48pm

This already exists.

RedKing · July 27, 2026, 12:17am

Not really. The Blakadder database doesn’t offer much detail beyond “works with…”. This project sounds more like the Z2M database of devices.

Very ambitious, though - there has always been a very large number of people contributing to Z2M; ZHA is more of an out-of-the-box user thing. With the best will in the world, it will take a while to gain momentum.

tom_l · July 27, 2026, 12:32am

It does if people have provided it:

RedKing · July 27, 2026, 10:16am

Using the card (v0.29.0) my devices seem to be timing out when I try an “exploded” scan. This applies to mains and battery devices, and I’m doing a normal bindings scan first, so they are available. I just get “No response to discovery”.

Edit I get these errors:

This error originated from a custom integration.

Logger: custom_components.zha_toolkit.scan_device
Source: custom_components/zha_toolkit/scan_device.py:404
Integration: ZHA 🧰 Toolkit (documentation, issues)
First occurred: 11:49:36 (11 occurrences)
Last logged: 11:51:21

got Status.UNSUP_GENERAL_COMMAND status for discover_commands starting 0

This error originated from a custom integration.

Logger: custom_components.zha_toolkit.scan_device
Source: custom_components/zha_toolkit/scan_device.py:339
Integration: ZHA 🧰 Toolkit (documentation, issues)
First occurred: 11:49:36 (11 occurrences)
Last logged: 11:51:21

got Status.UNSUP_GENERAL_COMMAND status for discover_commands starting 0

This error originated from a custom integration.

Logger: custom_components.zha_toolkit.scan_device
Source: custom_components/zha_toolkit/scan_device.py:199
Integration: ZHA 🧰 Toolkit (documentation, issues)
First occurred: 11:49:36 (13 occurrences)
Last logged: 11:51:21

got Status.UNSUP_GENERAL_COMMAND status for discover_attribute starting 0xfc04/0x0000
got Status.UNSUP_GENERAL_COMMAND status for discover_attribute starting 0x0000/0x0000
got Status.UNSUP_MANUF_GENERAL_COMMAND status for discover_attribute starting 0x0000/0x0000
got Status.UNSUP_GENERAL_COMMAND status for discover_attribute starting 0x0003/0x0000
got Status.UNSUP_MANUF_GENERAL_COMMAND status for discover_attribute starting 0x0003/0x0000

This error originated from a custom integration.

Logger: custom_components.zha_toolkit.scan_device
Source: custom_components/zha_toolkit/scan_device.py:395
Integration: ZHA 🧰 Toolkit (documentation, issues)
First occurred: 11:51:19 (1 occurrence)
Last logged: 11:51:19

Failed to discover generated 0x0019 commands starting 0. Error:

This error originated from a custom integration.

Logger: custom_components.zha_toolkit.scan_device
Source: custom_components/zha_toolkit/scan_device.py:331
Integration: ZHA 🧰 Toolkit (documentation, issues)
First occurred: 11:50:47 (1 occurrence)
Last logged: 11:50:47

Failed to discover 0x0019 commands starting 0. Error:

This error originated from a custom integration.

Logger: custom_components.zha_toolkit.scan_device
Source: custom_components/zha_toolkit/scan_device.py:187
Integration: ZHA 🧰 Toolkit (documentation, issues)
First occurred: 11:50:16 (1 occurrence)
Last logged: 11:50:16

Failed 'discover_attributes_extended' starting 0x0019/0x0000. Error:

hsolgaard · July 27, 2026, 5:24pm

That’s very helpful data - thank you.

Quick summary of what’s going on with your Hue bulb, and what the card does about it:

Your bulb answers basic “what are you, what do you have” questions from Home Assistant just fine - that’s how the card already knew it has clusters like On/Off and Level Control, and why the normal bindings scan worked.

“Check supported commands” queries each of those clusters “which exact commands do you support?” That’s an optional extra question in the Zigbee standard - a device can fully support On/Off without also supporting the separate “please list what you support” question. Your bulb doesn’t implement that optional question, and rather than staying silent, its firmware correctly replies with a standard “not implemented” response.

On the Bindings Manager side, the card’s “Check supported commands” button runs through zha-toolkit (the integration doing the actual scanning), which in turn uses zigpy (the underlying Zigbee library Home Assistant’s ZHA is built on) to send the request and decode whatever comes back over the air. In your case, zigpy decoded your bulb’s reply as a real Zigbee status code, Status.UNSUP_GENERAL_COMMAND - a standard code meaning “device understood the request but doesn’t support it.” zha-toolkit then logged that to Home Assistant’s own log, confirming this came from the bulb itself, not a card bug that I can fix unfortunately.

The problem for me is that zha-toolkit can tell the difference between “device explicitly said not supported” and “device genuinely never answered” (a real timeout) - it logs each case differently. But that distinction only goes into Home Assistant’s log, not into the data zha-toolkit hands back to the card. So the card itself can’t see which of the two happened - it only sees “nothing came back” either way.
I have made a chance (to be published at v0.30.1) that when a scan comes back with literally nothing confirmed across every cluster on an endpoint (like yours), it now shows one clear note explaining this is usually a firmware limitation rather than a temporary problem, and that re-checking probably won’t help - instead of repeating the same vague “no response” message on every single cluster row like before. Not ideal tbh.

RedKing · July 28, 2026, 7:15am

Yup. Upgraded to v0.30.1 and got a sensible message: “This scan didn’t confirm any commands…” etc. Similar errors in the logs, though. That’s a pity - presumably it means some devices can’t be included in the database?

hsolgaard · July 28, 2026, 8:45am

As is stands, yes - however we could do something different:

For devices like your Hue bulb, where the scan can’t confirm individual commands, we could still record which clusters the device declares having (On/Off, Level Control, etc.) - that part’s already known and reliable, just not currently surfaced. It’d show up clearly separate from confirmed capabilities though - something like “Also declares these clusters (not confirmed)” - so it’s never confused with commands we’ve actually verified work.

The upside would be that devices like yours wouldn’t just disappear from the database with nothing to show. The tradeoff is that it’s weaker evidence than what the database is meant to capture, and it adds a bit more nuance to the UI (two tiers instead of one).

Would that be useful at all or just clutter??

RedKing · July 28, 2026, 9:52am

Well… It’s your database so that’s for you to decide. Are you aiming it at all users (like the Blakadder database) or at people with some knowledge (like the Z2M database). The Z2M one is a bit two-tier, with picture/summary then an “exposes” section.

Do you have a feeling for how many products are affected like this? It would be a shame if major suppliers like Philips didn’t appear, particularly as their devices are extremely reliable.

From the point of view of collecting the information with the card, I don’t think the extra detail would be a problem for anyone who gets as far as contributing. And it’s always worth collecting extra even if the database doesn’t expose it to start with.