We need a complete howto about create new quirks

[MiguelAngelLV]

I think we need a complete guide, with examples for standar and special cases.
Hi, my name is Miguel Ángel. I am developer for ten years (java, kotlin and web mainly). For about five years, I am Home Assistant user.

I have created four Home Assistant components but now I want create a ZHA quirk and I don't know how. I don't find a complete guide about how make it or debug it.

I am triying create a quirk for Tuya TS0049 water valve ( #2377 ) and I have not idea how start.

I can use others quirks as examples, but some things are "magic", as special cluster for tuya for example... what it does? why tuya has a especial cluster?

I think we need a complete guide, with examples for standar and special cases.

[salzix]

Hi, I also want to create quirk for TS0049, and I don't know where to start. I agree with you Miguel, complete process guide is needed.
I've set up dev environment (probably?), found device logs, but I don't know how and where to deploy my code.

Btw if you'll find out how to deploy quirk please let me know :) I'll also let you know if I make any progress, I really need quirk for this valve working.

[salzix]

@MiguelAngelLV in case you are still interested in developing this quirk, I've gathered some information from the internet and was able to install custom quirk in HA. I could use some help with development of TS0049.
I'm using RPi host and HA is dockerized. I'm using my docker-compose template: https://github.com/salzix/homeassistant-docker-template which stores HA config directory on volume mounted from host, so I can access it easily.

Quirk installation steps:

1. On HA host create a directory in HA /configs/, called e.g. "zha_quirks"
2. Add to configuration.yaml section:

zha:
  custom_quirks_path: /config/zha_quirks/

3. Copy one of the files from this project /zhaquirks/tuya/ to dir mentioned above
4. Change the name of the file to something like "ts_0049_valve.py"
5. Restart HA. You should see in HA logs something like: "Loaded custom quirks. Please contribute them to https://github.com/zigpy/zha-device-handlers"

Now it's the development part. I've read somewhere in docs to remove and add this device, to see in logs device discovery data required for development. It worked for me, my valve describes itself as:

2023-07-10 12:07:19.622 INFO (MainThread) [zigpy.endpoint] [0x95e8:1] Discovered endpoint information: SizePrefixedSimpleDescriptor(endpoint=1, profile=260, device_type=0, device_version=1, input_clusters=[61184, 0], output_clusters=[25, 10])

[dmulcahey]

The readme in the quirks repo has a full tutorial. What’s missing?

[salzix]

@dmulcahey in my case I didn't know how to set up dev environment and install quirk in HA.
I think a short step-by-step guide would be useful. Something like: go to this link to set up development environment, then use this example "hello world" quirk, then add this sections to HA config, copy/symlink quirk there and there, restart HA and look into logs and Zigbee devices to see your quirk.
Something about debugging and logs would also be useful.

[masi]

@dmulcahey It's a simple example. It does not tell me what clusters "types" are available.

https://smarthomescene.com/reviews/aeotec-multipurpose-sensor-im6001-mpp-review/

Eg this device has X/Y/Z axis sensors which are not exposed but are in Zigbee2MQTT. Tamper and Moving exposed by Zigbee2MQTT my be virtual or not.

Anyway, the short rundown in the README is way to terse. Maybe some elite hackers with enough time to browse through all the source code might find it enough, but mere mortals are stuck.

PS: Yeah, I know writing docs is a PITA.

[CalamityDeadshot]

@dmulcahey You mean this? https://github.com/zigpy/zha-device-handlers/blob/dev/README.md I read it and don't really know what to actually do afterwards. I am a hands-on-learner: I have an actual issue at hand and want to solve it. In this case: I have a device, I want to integrate. How do I approach this? What are the first steps?

See the last post in this discussion, it links to a guide I've written.

[AndreasHoffmann2]

Thank you for the reply!
Just to avoid confusion about where my question is: Half an hour after the question, I found the thread myself and since the new PR is close to being merged, I did just delete the question to avoid unnecessary effort. Obviously, I was too late. Sorry!

[salzix]

@MiguelAngelLV here's my fork I'm working on: https://github.com/salzix/zha-device-handlers/blob/ts0049-tuya-family-valve/zhaquirks/tuya/ts0049_valve.py
Feel free to work on this fork if you'd like.

I've copied code from ts0601_valve.py as starting point and made some cleanup and basic changes.
I've found a discussion about TS0049 that describes datapoints and Zigbee2MQTT integration code that may be useful: Koenkk/zigbee2mqtt#15124

[Hedda]

Especially on input_clusters, as they are controlling clusters. 61184 is hex 0xEF00 and I've found it in a Tuya Connection Standard PDF described as Private Cluster. As input_cluster 0 is Basic Cluster and only provides vendor information, I think I'll focus on understanding what is Private Cluster and how to deal with it.

Also check out Zigbee2MQTT's documentation on supporting new Tuya devices:

https://www.zigbee2mqtt.io/advanced/support-new-devices/02_support_new_tuya_devices.html

it links to that Zigbee Connection Standard (Tuya Smart Documentation) as well:

https://github.com/Koenkk/zigbee-herdsman/blob/master/docs/Zigbee%20Connection%20Standard_Tuya%20Smart_Documentation.pdf

Plus there are Tuya specific tests

https://github.com/zigpy/zha-device-handlers/tree/dev/tests

That is covered in the readme section about setting up the development environment:

https://github.com/zigpy/zha-device-handlers/blob/dev/README.md#setting-up-the-development-environment

@dmulcahey in my case I didn't know how to set up dev environment and install quirk in HA.
I think a short step-by-step guide would be useful.

PS: FYI, while off-topic as not meant for only developers but more for end-users, also see PR which at least adds a "guide for installing an already made custom quirk to ZHA" to the readme -> #2419

[Hedda]

FYI, missed it and just noticed that dmulcahey & TheJulianJES has created a "Quirk Generator for zha-quirks" (quirk-generator project) here:

• https://github.com/zigpy/quirk-generator

Note! The "Quirk Generator for zha-quirks" (quirk-generator project) currently is only for "Quirks V1" (and not for "Quirks V2").

• Generate a standard Tuya magic-spell/magic-packet if known to be Tuya device? quirk-generator#2

UPDATE! New (quirk v2) TuyaQuirkBuilder ("Tuya QuirkBuilder) is in the main zha-device-handlers repo here:

• https://github.com/zigpy/zha-device-handlers/tree/dev/zhaquirks/tuya/builder

Quirk Generator for zha-quirks

This is a tool to generate stub quirks for a specific devices using their device signature or a diagnostics file.

Note: This tool will not generate a full quirk that magically makes your device work. It will only generate a stub quirk that you can use as a base for your own quirk.

The base for the quirk generator was made by dmulcahey.

Note

This tool is still work-in-progress. If you have any issues or suggestions, please open an issue.

So be sure to post any related issues and suggestions/requests as issues there -> https://github.com/zigpy/quirk-generator/issues

PS: They also have a dedicated community discussion section for that project -> https://github.com/zigpy/quirk-generator/discussions

[Hedda]

FYI, zigpy/zha developers have introduced initial support for what they call ”quirks v2” and dmulcahey begun how-to documentation. See:

• Initial quirks v2 documentation thoughts #3019

dmulcahey's current draft for Quirks v2 documentation:

• https://github.com/zigpy/zha-device-handlers/blob/a97ee3baa790b13b7e468f5489233d6b1ed558c1/quirks_v2.md

Note! That documention only applies to ”quirks v2” (and not to how existing old "V1" quirks work today, also referred to as ”quirks v1”).

This ”quirks v2” is a huge change since will allow quirk developers to add new entities to Home Assistant via quirks alone without having to modify ZHA code in HA core (which is/was a must with the existing quirks the way that the ZHA integration component worked before).

For more background information about ”quirks v2” (next-generation quirk functionality for ZHA) please read all of these for reference:

• [RFC] Quirks v2 zigpy#1312

and

• Quirks V2 zigpy#1329

(also see zigpy/zigpy#1350 and zigpy/zigpy#1362 for related quirks changes added to zigpy after the initial "quirks v2" pull request).

This ”quirks v2” was first added to Home Assistant 2023.3 release and significantly changes how ZHA makes use of the entity API in HA:

• Add support for ZHA entities exposed by Zigpy quirks home-assistant/core#111176

Anyway, that documentation PR above will initially add a separate quirks_v2.md file to difference v1 from quirks v2 how-tos -> #3019

# Quirks v2

## Introduction

Quirks v2 use a fluent interface style. While this isn't common in python it was done to improve the readability of the source code and to make it human-friendly for non developers. The amount of boilerplate code has been significantly reduced and the need to specify a signature dictionary and a replacement dictionary has been removed. This should make it much easier for the community to contribute quirks.

## Goals

- Significantly reduce the amount of boilerplate code required to write a quirk
- Make it easier for the community to contribute quirks
- Make it easier to read and understand quirks
- Make it easier to maintain quirks
- Expose entities from a quirk
- Allow custom logic to determine if a quirk should be applied to a device
- Allow custom binding, reporting configuration or any sort of initialization logic without hacking the bind or configure_reporting methods

## Breakdown of a minimal example

...

So again note that for now the existing tutorial in the zha-device-handlers's README.md will only apply to old "quirks v1" funtionality.

PS: Also check out summarized back-story and more links here in the Home Assistant community forum which more targets end-users:

• https://community.home-assistant.io/t/zha-device-handlers-version-2-zha-quirks-v2-architectural-design-developer-discussion/666460

[Mayhem-SWE]

So here we are almost a year later, and there still is barely any documentation about how to write v2 quirks or am I just not looking in the right place? I would for example like to attempt a workaround for what I believe to be a firmware bug in the IKEA Styrbar remotes (long press left/right also triggers turn on), but looking at the current quirk it is pretty much impossible for an outsider to understand what any of the current code does.

[masi]

I haven't found any either.

It's clear to me that those who want docs must write them. Writing good documentation takes time and skill, so I won't blame the ZHA devs.

Anyone is interested to compile docs on a sharing platform (Google docs etc)? My hope is that @Hedda, @dmulcahey and @TheJulianJES will answer questions to help us getting things right.

[Hedda]

FYI, @CalamityDeadshot has now written a guide (.md file) PR on how to write a quirk which includes very detailed step-by-step instructions:

• Added a guide on writing V2 quirks #4349

PS: Also see the related discussions here:

• How to actually write a quirk - a complete(?) guide #4339