Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
wants to merge 8 commits into
base: dev
Choose a base branch
from
Open
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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, 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.

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

Hedda marked this conversation as resolved.
Show resolved Hide resolved
# Thanks

- Special thanks to damarco for the majority of the device tracker code
Expand Down