diff --git a/README.md b/README.md index 6539114137..c8f7777772 100644 --- a/README.md +++ b/README.md @@ -557,6 +557,26 @@ def test_ts0121_signature(assert_signature_matches_quirk): assert_signature_matches_quirk(zhaquirks.tuya.ts0121_plug.Plug, signature) ``` +# 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 in Home Assistant's ZHA integration but someone have already written and shared a experimental "custom quirk" (ZHA Device Handler) that not get been merged into a "[ZHA Device Handlers"](https://github.com/zigpy/zha-device-handlers)" library release then you as an end-user can still manually add that to your Home Assistant instance for testing 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 speific decive (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 https://github.com/zigpy/zha-device-handlers/issues?q=is%3Aissue+is%3Aopen and https://github.com/zigpy/zha-device-handlers/pulls?q=is%3Aopen+is%3Apr +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. Restart Home Assistant to make the quirk take effect. +6. If and when a better ZHA Device Handler quirk is merged into the zha-quirks package then remove the custom quirk you added and possibly the whole folder if it is the last one. Make sure to revert at least `enable_quirks: true` to `false` in the settings then reboot Home Assistant. + +Note! If your Home Assistant is running inside a container then you must then you must edit and add or remove the file inside that container, see https://github.com/zigpy/zha-device-handlers/discussions/693 + # Thanks - Special thanks to damarco for the majority of the device tracker code