How to setup local ZHA quirks

Configuration Zigbee
6

UPDATE #1 See this community guide thread here → Zigbee Guide: How-to setup local custom device handler quirks in ZHA integration

UPDATE #2 Now also submitted a pull request for ZHA Device Handlers (zha-quirks) readme file → 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

FYI, I wrote a guide for adding a custom quirk to ZHA as a pull request for the ZHA integration docs but it was not accepted → https://github.com/home-assistant/home-assistant.io/pull/23884

Manually add and use a not yet merged custom ZHA quirk

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 ZHA quirk or code your own quirks. Tip is to search using Zigbee device signature Issues · zigpy/zha-device-handlers · GitHub
  2. 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/
  1. Restart Home Assistant to make the quirk take effect.
7 Likes