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])

[MiguelAngelLV]

Hi!

I have a development enviorement, I used the same to develop components ( https://developers.home-assistant.io/docs/development_environment/ ) so I don't need docker-compose or Raspberry Pi and I can restart HA in few seconds.

But, I don't know how "develop a quirk". I can create a quirk using another as template and get the device load using model and signature, but I don't know how debug it, what I need change or how should convert the device signature to "usable signature".

[salzix]

That's where I'm stuck too. I'm using trial and error method and googling :)
Currently I'm focusing on this part of device log:

input_clusters=[61184, 0], output_clusters=[25, 10]

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.

I'll push my experiments to github in the evening so you could look into it.

[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.

[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

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

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, ZHA/zigpy developers have now introduced initial support for what they call ”quirks v2” and dmulcahey begun how-to documentation:

#3019

Note! That documention only applies to ”quirks v2” (and not to how existing 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 information about ”quirks v2” (next-generation quirk functionality for ZHA) please see all of these for reference:

zigpy/zigpy#1312

zigpy/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:

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