ZHA Device Handlers version 2 (ZHA-Quirks V2) architectural design developer discussion

[Hedda]

FYI, just want to raise awareness to any Zigbee device makers here that might also be ZHA Device Handler (a.k.a. quirk) developers for those devices that you might be interested in following this architectural proposal and zigpy developer's discussion about changing how to decouple entities exposed in Home Assistant's built-in ZHA integration (native Zigbee Home Automation gateway component embedded inside the Home Assistant core) from underlying Zigbee devices, clusters, and endpoints to make it easier to develop ZHA Device Handlers (a.k.a. quirks). So if interested please see:

zigpy/zigpy#1312

Summary; Home Assistant's ZHA integration (the built-in native Zigbee gateway implementation) depends on the zigpy library/framework which strictly follows the Zigbee specifications and that means that non-standard Zigbee devices require ZHA Device Handlers (ZHA-quirks) are needed as translate/convert custom clusters and attributes into standard Zigbee clusters and attributes, and this discussion includes the idea of introducing a new/changed zigpy API concept that will allow ZHA-quirks developers to add support for a new device that uses custom Zigbee clusters and attributes without having to both create a quirk and modify both the codebase of the ZHA component code inside the Home Assistant core. The proposed idea was raised now by puddly with a suggestion on how to make quirks easier and less complicated to create and edit by new ZHA-quirks developers.

For further reference on what this is about read:

https://www.home-assistant.io/integrations/zha#how-to-add-support-for-new-and-unsupported-devices

and

https://www.home-assistant.io/integrations/zha#knowing-which-devices-are-supported

plus

/~https://github.com/zigpy/zha-device-handlers/blob/dev/README.md#what-the-heck-is-a-quirk

"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."

"In human terms you can think of a quirk like Google Translate. I know it's a weird comparison but let's dig in a bit. You may only speak one language but there is an interesting article written in another language that you really want to read. Google Translate takes the original article and displays it in a format (language) that you understand. A quirk is a file that translates device functionality from the format that the manufacturer chose to implement it in to a format that Zigpy and in turn ZHA understand. The main purpose of a quirk is to serve as a translator."

[Hedda]

FYI, ZHA/zigpy developers have now introduced initial support for what they call ”quirks v2” and dmulcahey begun how-to documentation:

zigpy/zha-device-handlers#3019

This is a huge change since will allow adding new entities to Home Assistant via quirks alone without having to modify ZHA code in HA core.

For more information see these for reference:

zigpy/zigpy#1312

zigpy/zigpy#1329

home-assistant/core#111176

That PR with new docs will initially add a separate quirks_v2.md file to difference v1 from quirks v2 -> zigpy/zha-device-handlers#3019

# Quirks v2

## Introduction

Quirks v2 use a fluent interface style. While this isn't common in python it was done to improve the readability of the source code and to make it human-friendly for non developers. The amount of boilerplate code has been significantly reduced and the need to specify a signature dictionary and a replacement dictionary has been removed. This should make it much easier for the community to contribute quirks.

## Goals

- Significantly reduce the amount of boilerplate code required to write a quirk
- Make it easier for the community to contribute quirks
- Make it easier to read and understand quirks
- Make it easier to maintain quirks
- Expose entities from a quirk
- Allow custom logic to determine if a quirk should be applied to a device
- Allow custom binding, reporting configuration or any sort of initialization logic without hacking the bind or configure_reporting methods

## Breakdown of a minimal example

...

PS: Also check out summarized back-story and more links here:

https://community.home-assistant.io/t/zha-device-handlers-version-2-zha-quirks-v2-architectural-design-developer-discussion/666460