ZHA Bindings Manager 1.0: see, diagnose and manage Zigbee direct bindings in ZHA

Share your Projects! Custom Integrations
, ,
1

ZHA Bindings Manager shows you what’s really going on with direct Zigbee bindings in ZHA: which switch controls which light, which bindings are stale or broken, and what each device can actually do. It also lets you create and remove bindings without hand-writing zha_toolkit service calls.

image
image2820×1528 319 KB

Why?

Direct bindings let devices talk to each other without Home Assistant. A switch bound to a light keeps working even when HA is down. That’s great until something goes wrong, because bindings are invisible in HA’s normal UI.

It started for me with an outside light that kept turning on from the wrong switch. Nothing in Home Assistant was triggering it. An old binding, left behind by re-pairing, was. Once the map showed it, the cause was obvious.

ZHA Bindings Manager helps answer questions like:

  • What does this switch control, and what controls this light?
  • Has re-pairing left an old or duplicate binding behind?
  • Which endpoint on a multi-gang device is involved?
  • Is a binding pointing at a device, endpoint or group that no longer exists?
  • Does the target device’s firmware actually support the command being sent?

What it does

  • Map. Every ZHA device and group, with arrows for each binding, colour-coded by cluster. Drag one device onto another to create a binding; click an arrow to inspect or remove it. You can also lay devices over your own floor plan.
  • Bindings table. Every binding in one searchable list, with Binding Health checks that explain problems in plain English: what’s wrong, why it matters, and what to do. Click a device to see both what it controls and what controls it. Export to CSV, JSON or PDF.
  • Devices and endpoints. An “exploded” view of any device, endpoint by endpoint: clusters, bindings in and out, groups, firmware and quirk. Run a live check of which commands a device really supports.
  • Clean-up. Finds bindings left behind when you remove a device, and removes them with Unbind all. Scans of devices you’ve removed are forgotten automatically.
  • Zigbee Capability Explorer. A community database built from real device scans, answering “can this device do X, on this firmware, from which endpoint?” Useful before you buy a remote or switch you want to bind directly.

Two ways to install

Both run the same card and share one version number. Install one or the other, not both.

Requirements: ZHA, zha-toolkit, and Home Assistant 2024.7 or newer for the integration (2023.7 for the card on its own).

The capability database needs you

The Capability Explorer is only as good as the scans people share. After a supported-command check, the card can prepare a GitHub submission for you to review. It contains no IEEE addresses, entity IDs, areas, device names or bindings, and nothing is uploaded automatically. Common devices are just as useful as unusual ones, because repeat scans raise confidence.

Feedback

Ideas, bug reports and testing are very welcome. GitHub issues are best for bugs, so the diagnostic detail doesn’t get lost. Thanks to everyone in the original thread, especially @RedKing in the original thread and MattWestb on GitHub, whose testing shaped a lot of this.

This continues the original Dashboards & Frontend thread: [Link to original thread]

3 Likes
ZHA Bindings Manager - visual manager for ZHA Zigbee direct bindings (graph/table view + drag-and-drop bind/unbind)
2

What’s new in 1.0, for anyone who knew the earlier versions

Two ways to install, one version number. The card on its own works exactly as before. The new integration grew out of the optional “backend” and includes the card, adding:

  • a ZHA Bindings sidebar page (admins only), with no dashboard YAML;
  • shared storage, so scans, floor plan and settings are the same on every device;
  • a notification when you remove a device that others are bound to;
  • updates that just load: the integration serves the card itself, so no more stale browser caches. One tester’s production system kept running an older card than his test system, which is what prompted this.

If you end up with both installed, the integration raises a Repairs notice telling you which to remove. Load the card on every page is off by default: you only need it to put the card on your own dashboards, and it would otherwise load a 380 KB card on every page, including on family phones.

Cleaning up bindings to devices that are gone. This turned out to be two separate problems:

  • Bindings from a removed device. The card never forgot devices you had removed from ZHA, so their old bindings sat in the table permanently, with an Unbind button that couldn’t work. A full scan now clears them, and until then each row has a Forget button.
  • Bindings to a removed device. Remove a bulb, and the switch bound to it still holds that binding. It uses one of the switch’s few binding-table slots (often only 8 to 16) and keeps sending commands to nothing. A banner above the Bindings table counts these, and Unbind all removes them, then rescans to confirm.

Nothing is unbound automatically: a device you remove only to pair it again keeps its address, and its bindings simply work again.

Smaller things

  • The Bindings tab shows both directions. Click any device to see what it controls and what controls it. Target names are clickable too.
  • Search works on the Devices tab, and the search box is hidden where it does nothing.
  • Open in Home Assistant from the exploded device view.
  • The version is shown in the toolbar.
  • The Capability Explorer leads each device with a plain-English overview (what it can be told to do, what it reports, whether it can control another device directly), plus Input/Output badges, product photos and Blakadder/manufacturer links.

Big thanks to MattWestb on GitHub, whose testing and feedback drove a good part of this release.

3

@hsolgaard，Thanks for your great work on this! Making Zigbee bindings easier to see and manage looks really useful.

I have a setup with Zigbee downlights, a wireless dimmer remote, and Home Assistant Green. I’ll try your tool with this setup and would be happy to share the results.

What kind of feedback or diagnostic data would be most helpful to you?

1 Like
4

Thanks very much! I’d really appreciate you giving it a try.

As a starting point, you could check whether your downlights and wireless remote are already listed in the Zigbee Capabilities Database. That should give you an indication of whether they support the Zigbee commands needed for direct binding.

If they’re not listed, you can install ZHA Bindings Manager, run a supported-command scan and contribute the results to the database. That would be really helpful!

Once you’ve installed the integration (or standalone card if you prefer), I’d be interested in whether it correctly identifies your devices and endpoints, whether you can create and manage bindings between them, and whether the resulting direct control works as expected.

And of course, any feedback on the interface, confusing behaviour or features you’d like to see would be very welcome.

If you encounter any problems, feel free to raise a GitHub issue with the device models, relevant technical details and any error messages.

Thanks again for offering to test it!