Update zha-device-handlers repo description + all readme files to match migrations in 2.0.0 releases?

[Hedda]

Pull requests with major changes that came with zha-device-handlers, zha, and zigpy 2.0.0 releases migrated the quirks API out of zigpy and instead moved it into ZHA and zha-device-handlers, inverting the quirks dependency chain, which means that quirks in ZHA Device Handlers are no longer limited to the gap of only translating Zigbee messages from devices to ZHA.

• Bump ZHA to 2.0.0 home-assistant/core#174586

  • Move the quirks API out of zigpy #5113
  • Migrate quirks out of zigpy and provide direct entity access zha#762
  • Move quirks API out of zigpy zigpy#1846

  "Our quirks API is now fully revamped: complex ZHA entities can now be created entirely within with quirks, allowing for faster community support of new devices and new complex devices."

Does that not mean that both zha-device-handlers repository description as well as readme files for all the three repos need updating?

That is, a ZHA Device Handler quirk is no longer only "fixes" for broken devices. ZHA Device Handlers still work to compensate in case when manufacturers deviate from the ZCL specification by using quirks. Quirks can now add entirely new functionality and entities + better expose gaps between manufacturer-specific clusters to allow access to their attributes as entities in zha for Home Assistant. I think that this important to note in the description and readme files + documentation because advanced support for most complex Zigbee devices can now be added in zha-device-handlers itself, instead of requiring architectural work across multiple repositories (i.e. zha, zigpy, and Home Assistant's core). So with the bump to 2.0.0 version of zha-device-handlers, zha, and zigpy 2.0.0 releases, quirks can now more or less act as self-contained device integrations built on top of ZHA, enabling support for complex devices without always also having to make changes to zigpy or Home Assistant's Core. I believe this arguably part of one of the biggest conceptual change that ZHA advanced users and new potential contributors to zha and zigpy will need to understand. However, this distinction is currently not yet obvious from the existing documentation and I think adding more information about this would help set expectations for the future direction of quirks in ZHA Device Handlers. These need for these changes is by the way also tracked in the Open Home Foundation roadmap here:

• Improve APIs to make adding new devices simpler so that the ZHA community can support new devices more quickly OpenHomeFoundation/roadmap#194

Also see related draft PR what will add quirks v2 builder cluster binding + reporting without entity:

• Add quirks v2 builder cluster binding + reporting without entity #5128

And for additional reference, I also submitted a PR with a suggested similar change for Home Assistant's ZHA documentation here:

• Updated ZHA device handlers and quirks details home-assistant/home-assistant.io#46445

Anyway, the https://github.com/zigpy/zha-device-handlers "About" description currentlly reads:

"ZHA device handlers bridge the functionality gap created when manufacturers deviate from the ZCL specification, handling deviations and exceptions by parsing custom messages to and from Zigbee devices."

And te current introduction description README.md file in the ZHA Device Handlers repositories does not reflect this migration of quirks API to move most to the zha-device-handlers repo and the fact that it now does more than just fix deviations from ZCL standard clusters:

• https://github.com/zigpy/zha-device-handlers/blob/dev/README.md
• https://github.com/zigpy/zha/blob/dev/README.md
• https://github.com/zigpy/zigpy/blob/dev/README.md

ZHA Device Handlers For Home Assistant

ZHA Device Handlers are custom quirks implementations for Zigpy, the library that provides the Zigbee support for the ZHA component in Home Assistant.

ZHA device handlers bridge the functionality gap created when manufacturers deviate from the ZCL specification, handling deviations and exceptions by parsing custom messages to and from Zigbee devices. Zigbee devices that deviate from or do not fully conform to the standard specifications set by the Zigbee Alliance may require the development of custom ZHA Device Handlers (ZHA custom quirks handler implementation) to for all their functions to work properly with the ZHA component in Home Assistant.

Custom quirks implementations for zigpy implemented as ZHA Device Handlers are a similar concept to that of Hub-connected Device Handlers for the SmartThings Classics platform as well that of Zigbee-Herdsman Converters (formerly Zigbee-Shepherd Converters) as used by Zigbee2mqtt, meaning they are virtual representation of a physical device that expose additional functionality that is not provided out-of-the-box by the existing integration between these platforms. See Device Specifics for details.

Note

This README primarily documents v1 quirks and will be updated.
For v2 quirks documentation (recommended for new quirks), see copilot-instructions.md.

For supporting Tuya devices, see using the TuyaQuirkBuilder.

Ping @TheJulianJES

PS: IMHO it would btw also be good to make a new Home Assistant developers blog-post to high-light these major changes to ZHA! 😀