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

Configuration Zigbee
1

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

Summary; the discussion includes a new API concept that will allow ZHA-quirks developers to add support for a new device that uses non-standard Zigbee clusters and attributes without having to both create a quirk and modify both the codebase of the ZHA component in the Home Assistant code. 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."

2 Likes
2

FYI, while ”quirks v2” is still being worked on the initial support for it has been implemented so you can now expose some entities via a new quirk without having to modify ZHA component code in HA core, see:

and

1 Like
3

FYI, ZHA/zigpy developers have now introduced initial support for what they call ”quirks v2 ” and dmulcahey begun documentation for quirk development in zha-device-handlers (zha-quirks) here:

Again, ”quirks v2” allow quirk developers to expose attributes as entities under ZHA in Home Assistant to automatically create switches, sensors, etc. without having to modify the ZHA component code inside Home Assistant core.

That PR with new docs will initially add a separate quirks_v2.md file to difference v1 from quirks v2:

# 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

...
1 Like
4

if using custom quirks v2, the ZHA integration can’t be reloaded. Manual HA core restart required to fix it.

1 Like