If your new Zigbee device is not showing all expected feature/function entities (attributes) in the ZHA integration (native Zigbee gateway component that is built-in to Home Assistant), even after trying multiple times to re-pair/re-join your new Zigbee device to the ZHA integration, then there is a big chance that your new Zigbee device will either need a new custom ZHA Device Handler (also known as a “zha-quirk”) for that specific device model or modify existing ZHA Device Handlers (also known as a “zha-quirks”) to make it use it to expose all and any entity (attribute) that is now not yet showing by default in the current version on the ZHA integration. Other times all that is needed is to add the device signature (model) of a new device to an existing ZHA Device Handler (quirk) if it basically the same device with different model number.
Sometimes someone else has already written or modified such a custom ZHA Device Handler (zha-quirk) to expose the missing entity/entities it can sometimes still take quite a long time before that specific “quirk” is merged into the mainline ZHA Device Handlers (“zha-quirks”) repository and for it to get added to Home Assistant’s core for automatic inclusion in Home Assistant releases so it is seen by default, therefore until then you will need to manually add the ZHA Device Handler (zha-quirk) yourself to your own instance of Home Assistant.
How to add a ZHA Device Handler (zha-quirk) is not documented in the ZHA integration documentation, which is sad because if you as an end-user is an early-adopter that keep buying the latest brand new Zigbee devices as soon as manufacturers make them available then it is a huge chance are that you sooner or later will probably need to use a manually install a custom ZHA Device Handler (zha quirk), because new experimental ZHA Device Handlers (zha-quirks) will only be 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 (and even then you have to wait until someone in the community steps-up to code that quirk and submit it for merger).
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).
- 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
- Inside your Home Assistant instance, create a directory/folder for your custom quirks (for example
/config/zha_quirks/
) - 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. - 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/
- Use Home Assistant configuration check to make sure the config will not break your configuration.
- 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:
Link to this and other helpful tips also found in the HA Cookbook: