Add a how-to guide for how end-users can use a custom quirk in ZHA

[Hedda]

Proposed change

Add a how-to guide for end-users to add custom quirks to ZHA that has not yet been merged into the zha-device-handlers repo.

To clarify; this is short step-by-step instructions on how someone can test a not-yet-merged custom quirk someone else made.

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"" 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:
  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 the file inside that container, see #693

Additional information

FYI, have now also submitted a detailed variant of these howto step-by-step instructions as living-document and community-guide in Home Assistant forum for feedback/input and hopefully to help some end users looking to use and test not-yet-merged custom ZHA Device Handlers (zha-quirks) with the ZHA integration in their own personal Home Assistant instance, see:

• https://community.home-assistant.io/t/zigbee-guide-how-to-setup-local-custom-device-handler-quirks-in-zha-integration/683473

How-to add a custom ZHA Device Handler (zha-quirk) someone else has written is a question that gets asked a lot in Home Assistant’s community forum and today we can not point those to any officially documentation. See example number of clicks here where it has been viewed several hundreds of times:

• https://community.home-assistant.io/t/how-to-setup-local-zha-quirks/341226

Note that my similar pull request was not accepted to downstream Home Assistant's ZHA integration documentation with the argument that a such guide for adding not yet merged custom quirks to ZHA does not being in end-user's documentation but should instead belong in the developer documentation for in the Home Assistant's ZHA integration, see:

• Add guide for adding a custom quirk to ZHA home-assistant/home-assistant.io#23884

I think that a summarized step-by-step guide like this is at least needed in the readme.

Checklist

• The changes are tested and work correctly
• pre-commit checks pass / the code has been formatted using Black
• Tests have been added to verify that the new code works

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 89.44%. Comparing base (8317dc6) to head (a7c0089).
Report is 73 commits behind head on dev.

Additional details and impacted files

@@            Coverage Diff             @@
##              dev    #2419      +/-   ##
==========================================
+ Coverage   88.18%   89.44%   +1.25%     
==========================================
  Files         301      311      +10     
  Lines        9412    10033     +621     
==========================================
+ Hits         8300     8974     +674     
+ Misses       1112     1059      -53     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[ChujieChen]

I suggest changing the example directory to /config/zha-device-handlers/zhaquirks. People usually would pull this repo into /config directly.

[Hedda]

I suggest changing the example directory to /config/zha-device-handlers/zhaquirks. People usually would pull this repo into /config directly.

Should it then not be /config/zha-device-handlers-master/zhaquirks or /config/zha-device-handlers-dev/zhaquirks depending if the user downloads the master or dev branch of zha-device-handlers from GitHub? ...or /config/zha-quirks-version/zhaquirks if the user instead download from PyPI project at https://pypi.org/project/zha-quirks/ ?

Anyway, it is just an example so think OK to leave it as it is,

[drueppela]

Can somebody help?

#2662 (comment)

[dtromain]

These explanations are helpful getting started with zigphy and implementing new devices.
Just a small recommandation, before Step 5 (Restart home assistant), please add a step to invite people to use Home Assistant configuration check to make sure it will not break their configuration.

[Hedda]

Again, this just an example so think OK to leave it ”as is”. IMHO it would be good to merge this to at least have something and it can later always be improved.

[jclsn]

I would also appreciate an extended guide on how to write quirks. This would make contributions easier for new developers!

[Hedda]

I would also appreciate an extended guide on how to write quirks. This would make contributions easier for new developers!

It is understandable that you want such a guide but that is off-topic here because the actual development of quirks not relative to this guide and as such out of scope for this pull request, but suggest that you instead contribute to this other discussion that is a request for a guide on to how-to write quirks here -> #2467

[jclsn]

@Hedda Thanks, unfortunately this does not describe how to implement the corresponding cluster handlers in the core, which I am currently trying to do for the Bosch Thermostat 2. I also think that your guide should extend the readme in the repository and not be posted in the HA forum, where it is hard to find.

[Hedda]

I also think that your guide should extend the readme in the repository and not be posted in the HA forum, where it is hard to find.

That is what this pull request would do. It will be a guide for how-to add existing not yet merged quirks to ZHA. This will only be initial instructions for how an end user can manually custom quirk that someone else written but is not merged and included in the repo.

unfortunately this does not describe how to implement the corresponding cluster handlers in the core

That is not what this PR is about. This PR is only to create a guide for how someone can add a custom quirk that someone else already written but has not yet been merged into this repository. As such this mostly a guide for end-users and not only developers as it is not meant to cover anything about actually writting a quirk.

[jclsn]

I think in the long run some doxygen documentation would probably be a better choice. Having everything on one page can be kind of overwhelming

[Hedda]

I think in the long run some doxygen documentation would probably be a better choice.

No way that code inline is better for this specific guide in this PR that is meant as quirk installation instructions for end users.

Again, this is not a guide on how to code quirks, this specific guide is really just a guide for how a user can add a custom quirk that someone else have already coded, as such is should not require any coding experince to read and follow this specific guide.

I guess that your reply is out of context since sound as if it was really for the people asking how to write code for quirks, but again that is off topic for this PR.

For how to code/write quiks you will need a different how-to guide that is not this, see related discussion about that here instead -> #2467

[Hedda]

For reference, storm1er added suggested that might need a howto spot and remove custom ZHA Device Handers quirks that users have manually added themselves if and when an official ZHA Device Hander quirk is added later to this zha-quirks package:

• Docs: How to remove local quirk once it's released #3488

@storm1er Thanks for adding the additional step on how-to remove the custom quirk if better one is added to official package.

[Hedda]

@TheJulianJES @prairiesnpr @mrrstux Any chance one of you guys would be willing to review this to hopefully get it merged?

PS: Off-topic but please note #3019 is another documentation PR that needs to be revieved and merged to help every new dev.