From 1b640acee48c13b85b50ec26a79debbaf0f861dc Mon Sep 17 00:00:00 2001 From: Hedda Date: Mon, 22 Sep 2025 10:52:45 +0200 Subject: [PATCH 1/2] Added a guide on howto test custom quirks in zha Added a guide for how-to add a custom zha quirk for testing. --- how_to_test_custom_quirks_in_zha.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 how_to_test_custom_quirks_in_zha.md diff --git a/how_to_test_custom_quirks_in_zha.md b/how_to_test_custom_quirks_in_zha.md new file mode 100644 index 0000000000..440882e679 --- /dev/null +++ b/how_to_test_custom_quirks_in_zha.md @@ -0,0 +1,19 @@ +The intruction-guide below is written with the assumed premises that you are and end-user of Home Assistant's [ZHA integration](https://www.home-assistant.io/integrations/zha), however please note that this guide is meant to be useful regardless if you are an ZHA end-user or first-time zha-quirk developer. + +# How to 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 + 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 From bc42364e39d28218d7028286c060479dfd9c147a Mon Sep 17 00:00:00 2001 From: Hedda Date: Mon, 22 Sep 2025 11:00:11 +0200 Subject: [PATCH 2/2] spelling and corrections --- how_to_test_custom_quirks_in_zha.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/how_to_test_custom_quirks_in_zha.md b/how_to_test_custom_quirks_in_zha.md index 440882e679..884b067cb3 100644 --- a/how_to_test_custom_quirks_in_zha.md +++ b/how_to_test_custom_quirks_in_zha.md @@ -1,10 +1,10 @@ -The intruction-guide below is written with the assumed premises that you are and end-user of Home Assistant's [ZHA integration](https://www.home-assistant.io/integrations/zha), however please note that this guide is meant to be useful regardless if you are an ZHA end-user or first-time zha-quirk developer. +The instruction-guide below is written with the assumed premises that you are and end-user of Home Assistant's [ZHA integration](https://www.home-assistant.io/integrations/zha), however please note that this guide is meant to be useful regardless if you are an ZHA end-user or first-time zha-quirk developer. # How to 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 +1. Get a copy of an existing "custom quirk" that is meant for your specific Zigbee 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 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 @@ -14,6 +14,6 @@ zha: 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. +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 was the last custom quirk that you added. -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 +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 the community discussion thread at https://github.com/zigpy/zha-device-handlers/discussions/693