Zigbee Guide: How-to setup local custom device handler quirks in ZHA integration

Community Guides
,
1

If your new Zigbee device is not showing all expected entities (attributes) in the ZHA integration even after re-pairing it then chances are it will need custom ZHA Device Handlers (also known as “zha-quirk”) for that specific device, but even if someone has already written a such custom it can take a sometimes long time before that specific quirk is merged into the mainline ZHA Device Handlers (“zha-quirks”) repository for automatic inclusion in Home Assistant releases, so until then you will need to manually add the quirk yourself.

How to do this is not documented in the ZHA integration documentation, which is sad because if you keep buying new Zigbee devices then chances are that you sooner or later will probably need to use a manually install a custom ZHA Device Handler (zha quirk) as it can sometimes take a long time before new experimental quirks get added after you have submitted a new device request properly → https://www.home-assistant.io/integrations/zha#how-to-add-support-for-new-and-unsupported-devices

Anyway, below is a summary of what you need to do to install a custom quirk after you download it:

How end-users can test a not yet merged custom quirk in ZHA

If you have bought a non-standard Zigbee device that is not yet supported by ZHA but someone have written a ZHA “quirk” module (ZHA Device Handler/Zigbee Converter) that not get been merged into a “ZHA Device Handlers"” library release then you can add that manually as a custom ZHA quirk to your Home Assistant instance, (using something like File Editor or Samba share add-ons in Home Assistant).

  1. Get a copy of an existing “custom quirk” that is meant for your specific device (or code your own custom quirks). Tip is to search for the specific Zigbee device signature among open issues and open pull requests as those might contain experimental custom quirk that have not yet been merged for your Zigbee device, see Issues · zigpy/zha-device-handlers · GitHub and Pull requests · zigpy/zha-device-handlers · GitHub
  2. Inside your Home Assistant instance, create a directory/folder for your custom quirks (for example /config/zha_quirks/)
  3. Copy or create a quirk file in this directory (called it for example “devicemodelzyz_devicetypexyz.py”). This file should contain the Python script for the quirk and its specific Zigbee device signature unique to it.
  4. Add configuration with the full path to the directory that now containing custom quirk module(s) that will override and take precedence over any built-in quirks matching any device that has the same Zigbee device signature. to Home Assistant’s config.yaml
    zha:
   database_path: /config/zigbee.db
   enable_quirks: true
   custom_quirks_path: /config/zha_quirks/
  5. Use Home Assistant configuration check to make sure the config will not break your configuration.
  6. Restart Home Assistant to make the quirk take effect.

Note! If your Home Assistant is running inside a container then you must then you must edit and add the file inside that container, see Editing (ZHA) quirks in a (HA) container or local. · zigpy/zha-device-handlers · Discussion #693 · GitHub

Back-stopy, I initially wrote a guide for how-to manually adding a custom quirk to the ZHA locally as a pull request for the ZHA integration docs but it was not accepted with the argument that it is too advanced for the ZHA integration so I and then resubmitted an update of it for the readme in ZHA Device Handlers (zha-quirks) repository on GitHub, but that has not yet been accepted/merged either → Add a how-to guide for how end-users can use a custom quirk in ZHA by Hedda · Pull Request #2419 · zigpy/zha-device-handlers · GitHub

PS: This question have been asked hundreds of times in the community and previously discussed here:

5 Likes
2

Note! If there is not already a quirk (ZHA Device Handler) for your specific Zigbee device in the ZHA integration and/or there already is a quirk there but it is still not exposing all expected attributes as entities inside ZHA UI in Home Assistant you need to then begin by submitting a new device support request as an issue to the ZHA Device Handlers repository on GitHub,requesting a new custom quirk (ZHA Device Handler) in that new issue by filling out the template there with requested information to open a dialogue custom ZHA Device Handler developers with the ZHA quirks community → https://www.home-assistant.io/integrations/zha/#how-to-add-support-for-new-and-unsupported-devices

HOW TO ADD SUPPORT FOR NEW AND UNSUPPORTED DEVICES

If your Zigbee device pairs/joins successfully with the ZHA integration but does not show all of the expected entities

  1. Try to re-pair/re-join the device several times.
  2. Checkout the troubleshooting section.
  3. Still not working? You may need a custom device handler. This handler will have exception handling code to work around device-specific issues.

For devices that do not follow the standard defined in the CSA’s ZCL (Zigbee Cluster Library), the ZHA integration relies on a project called “ZHA Device Handlers (also known as “zha-quirk”)”. It contains device-specific Python scripts called “quirks”. These scripts can resolve compliance and interoperability issues by implementing on-the-fly conversion of custom Zigbee configurations or by implementing manufacturer-specific features for specific devices.

People familiar with other Zigbee gateway solutions for home automation may know similar concepts of using custom Zigbee device handlers/converters for non-standard devices. For example, Zigbee2MQTT (and IoBroker) uses zigbee-herdsman converters and SmartThings Classics (Legacy) platform has Hub Connected Device Handlers.

If you do not want to develop such a “quirk” Python script yourself, you can submit a “device support request” as a new issue to the ZHA Device Handlers project repository on GitHub.

What the heck is a quirk

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. A quirk comprises several parts:

  • Signature - To identify and apply the correct quirk
  • Replacement - To allow Zigpy and ZHA to correctly work with the device
  • device_automation_triggers - To let the Home Assistant Device Automation engine and users interact with the device

Note! Best to first search existing issues with device signature and track open device support requests:

PS: Note that submitting a new “device support request” does not guarantee that someone else will develop a custom “quirk” for ZHA. The project relies on volunteering developers. However, without “device support requests”, the developers may not be aware that your specific Zigbee device is not working correctly in ZHA.

1 Like
3

FYI, @Regenbui also wrote a very detailed instruction on adding a custom quirk in this other thread: