From ed20dbf43375b3b01fca2567dbd4647dd629d936 Mon Sep 17 00:00:00 2001 From: Hedda Date: Thu, 1 Jun 2023 13:47:54 +0200 Subject: [PATCH 1/6] Add guide for adding a custom quirk to ZHA Add a guide for how end-users can add/test a custom quirk that have not yet been merged. --- README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/README.md b/README.md index fc1b49f998..068da93e6a 100644 --- a/README.md +++ b/README.md @@ -557,6 +557,22 @@ 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 https://github.com/zigpy/zha-device-handlers/issues?q=is%3Aissue+is%3Aopen +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: + custom_quirks_path: /config/zha_quirks/ +``` +5. 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 https://github.com/zigpy/zha-device-handlers/discussions/693 + # Thanks - Special thanks to damarco for the majority of the device tracker code From ee2f704cfac1d158a00467d9dcfda9591022a607 Mon Sep 17 00:00:00 2001 From: Hedda Date: Thu, 1 Jun 2023 13:50:49 +0200 Subject: [PATCH 2/6] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 068da93e6a..216d29accb 100644 --- a/README.md +++ b/README.md @@ -561,7 +561,7 @@ def test_ts0121_signature(assert_signature_matches_quirk): 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 https://github.com/zigpy/zha-device-handlers/issues?q=is%3Aissue+is%3Aopen +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 From 018eb1379d872c4f2a4cc11ff3949b74751f458c Mon Sep 17 00:00:00 2001 From: Hedda Date: Fri, 15 Mar 2024 15:49:54 +0100 Subject: [PATCH 3/6] Update README.md --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 216d29accb..b0c6587fc6 100644 --- a/README.md +++ b/README.md @@ -567,7 +567,10 @@ If you have bought a non-standard Zigbee device that is not yet supported in Hom 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. From 481db44a6f46762ad064fda37ef78a85790e6575 Mon Sep 17 00:00:00 2001 From: Hedda Date: Thu, 7 Nov 2024 16:16:43 +0100 Subject: [PATCH 4/6] Update README.md Co-authored-by: storm1er --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 47d96fe5f7..bfa9653d6b 100644 --- a/README.md +++ b/README.md @@ -576,6 +576,9 @@ zha: 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 https://github.com/zigpy/zha-device-handlers/discussions/693 +6. Once the quirk is merge + +Remove the custom quirk and possibly the whole folder if it's the last one. Make sure to revert at least `enable_quirks: true` to `false` in the settings then reboot home assistant # Thanks - Special thanks to damarco for the majority of the device tracker code From c3893b23b2497dddf25d48312b4b301294141b4c Mon Sep 17 00:00:00 2001 From: Hedda Date: Thu, 7 Nov 2024 16:20:08 +0100 Subject: [PATCH 5/6] Added step and info on removing custom quirk in howto Added step and info on removing custom quirk in howto --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index bfa9653d6b..0596bf287f 100644 --- a/README.md +++ b/README.md @@ -574,11 +574,10 @@ zha: ``` 5. 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 https://github.com/zigpy/zha-device-handlers/discussions/693 +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. Once the quirk is merge +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 -Remove the custom quirk and possibly the whole folder if it's the last one. Make sure to revert at least `enable_quirks: true` to `false` in the settings then reboot home assistant # Thanks - Special thanks to damarco for the majority of the device tracker code From a7c00899fda760289b840379b9b9fa654e6e16ee Mon Sep 17 00:00:00 2001 From: Hedda Date: Thu, 7 Nov 2024 16:24:10 +0100 Subject: [PATCH 6/6] Fix lint. Fix lint. --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 0596bf287f..c8f7777772 100644 --- a/README.md +++ b/README.md @@ -573,8 +573,7 @@ zha: ``` 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 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