Initial quirks v2 documentation thoughts

[dmulcahey]

Proposed change

Additional information

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 87.85%. Comparing base (e4d0663) to head (a97ee3b).
Report is 308 commits behind head on dev.

Additional details and impacted files

@@           Coverage Diff           @@
##              dev    #3019   +/-   ##
=======================================
  Coverage   87.85%   87.85%           
=======================================
  Files         301      301           
  Lines        9217     9217           
=======================================
  Hits         8098     8098           
  Misses       1119     1119           

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

[Hedda]

FYI, this PR is also linked from this old discussion thread which is asking for a how-to guide on create new quirks for ZHA:

• We need a complete howto about create new quirks #2467

Maybe include reference to "quirk-generator" (stub quirk generator for zha-quirks)? -> https://github.com/zigpy/quirk-generator

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

[TheJulianJES]

Maybe include reference to "quirk-generator"

No, that was only relevant for generating "v1" quirks.
For v2 quirks, you don't need the whole signature in the quirk normally. For example, here's how a quirk for an IKEA remote looks that replaces two clusters:

(
    add_to_registry_v2("IKEA of Sweden", "TRADFRI remote control")
    .replaces(PowerConfig1CRCluster)
    .replaces(ScenesCluster, cluster_type=ClusterType.Client)
)

I'll update the docs for the quirk generator later to mention it doesn't generate v2 quirks. It's still useful in certain scenarios though, as long as we have v1 quirks too.

[vinzent]

I think I've got a working quirk v2 for a Zigbee/Tuya device ZG-204ZS ("_TZE200_3towulqd", "TS0601") following this documentation here.

• Is there a way to change the DeviceType from IAS_ZONE to OCCUPANCY_SENSOR?
• Enum configs are exposed, just the name is "NONE". Is there a way to configure the name?
  
• The number config option is missing. Probably not yet implemented in the GUI?
• Reloading the ZHA integration fails with an error stating there is a duplicate device in the registry (Multiple matches found for device ....). Full restarting of HA required.

(tried this on HA Green 2024.5.5)

[vinzent]

Probalby the DeviceType from IAS_ZONE to OCCUPANCY_SENSOR conversion is not required at all. Still learning. :)

i've implemented another one with quirk v2: https://gist.github.com/vinzent/2cd645b848fd3b6a0c3e5762956ec89f

Looks like this in HA 2024.6.1:

Issues:

• ZHA integration fails to reload
• All sensor/config entities have "none" or the name of the device displayed
• Some tuya data points report None instead of a real value if they are on default. For example near_detection attribute is none and fails the config entity because its not an integer.

[Hedda]

@TheJulianJES wondering if you would consider merging this PR as-is? Having some documentation merged that others can then add to + build upon is usually better than having to start from writting documentation scratch (even if not complete or outdated).

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

PS: This was also indirectly mentioned by yourself in this other discussion:

Originally posted by @TheJulianJES in #14

On another note, we clearly need to add/improve our docs, especially for v2 quirks. I still hope to get to this soon, but time has been an issue so far. This would already be a huge help for new contributors and also AI.

[Hedda]

FYI, @CalamityDeadshot has now written a guide 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 two related discussions here:

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

• We need a complete howto about create new quirks #2467