Add support for Third Reality plug private cluster ID

[hwzolin]

Proposed change

Add support for the "reset summation delivered" attribute for Third Reality plugs.

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 88.20%. Comparing base (9ccb69a) to head (15f4ed7).
Report is 69 commits behind head on dev.

Additional details and impacted files

@@            Coverage Diff             @@
##              dev    #3078      +/-   ##
==========================================
+ Coverage   87.90%   88.20%   +0.29%     
==========================================
  Files         300      301       +1     
  Lines        9222     9412     +190     
==========================================
+ Hits         8107     8302     +195     
+ Misses       1115     1110       -5     

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

[hwzolin]

This code adds the private cluster ID to the Third Reality plug. Please help with it, thank you.

[weihuan1111]

@dmulcahey @TheJulianJES Could you help to review the merge require, thanks.

[TheJulianJES]

Please remove all cluster id comments like # 0x0000.
It's inconsistent with most of our codebase.

[TheJulianJES]

There's a zgp profile for this.

PROFILE_ID: zgp.PROFILE_ID,
DEVICE_TYPE: zgp.DeviceType.PROXY_BASIC,

[TheJulianJES]

Also use the zgp profile/constants here.

[TheJulianJES]

Using a write_attr_button from quirks v2, a button would be added to HA that would set the attribute to CLEAR.
I'm assuming the plug automatically resets it back to NOT afterwards?

[hwzolin]

We only need to clear the summation delivered of PLUG to zero when the button is pressed.

[hwzolin]

Hello, is there any case of related projects that you mentioned in this functional code?

[TheJulianJES]

The NOT and CLEAR parts don't really have an effect, as this is not an enum.
There's a longer discussion here: #2723 (comment)

I'd just remove this section for now and set type=t.uint8_t for the attribute.
(When the button is later exposed to HA, it'll be clear that 1 means reset.)

[hwzolin]

OK

[hwzolin]

Hello, please check it out again, thanks.

[hwzolin]

@TheJulianJES
Hello, what we added to our code this time is the ability to clear the summation delivered of the plug.
The cluster_id of this function is 0xFF03, and the attribute_id is 0x0000, and we need to send a value of 1 to achieve the effect of zeroing.
So far, I've taken care of some formatting issues as you've requested. As for what you said about implementing the function of a button through write_attr_button, I don't know how to call this function, can you please help me deal with it?

[hwzolin]

@TheJulianJES Hello, what we added to our code this time is the ability to clear the summation delivered of the plug. The cluster_id of this function is 0xFF03, and the attribute_id is 0x0000, and we need to send a value of 1 to achieve the effect of zeroing. So far, I've taken care of some formatting issues as you've requested. As for what you said about implementing the function of a button through write_attr_button, I don't know how to call this function, can you please help me deal with it?

@TheJulianJES @dmulcahey

[TheJulianJES]

There's an example in the quirks v2 docs PR and/or similar in the open Bosch PR.
I can help you better soon.

[hwzolin]

@TheJulianJES @dmulcahey
Hello, I would like to use the zha quirk v2 implementation to zero out the value of summation delivered by clicking the button on the page. But there are relatively few projects that can be referred to on the Internet, and I didn't find the open PR code you said earlier, so the result is as shown in the gif, although the button was clicked, but the program reported an error “Failed to call service button/press. 'reset_summation_delivered'”.

I put the code below. Could you please help me see if the code is written wrong? Thank you!

"""Third Reality Plug devices."""

from typing import Final

from zigpy.profiles import zha
from zigpy.quirks import CustomDevice
import zigpy.types as t
from zigpy.zcl.clusters.general import (
    Basic,
    GreenPowerProxy,
    Groups,
    Identify,
    OnOff,
    Ota,
    Scenes,
)
from zigpy.zcl.clusters.homeautomation import ElectricalMeasurement
from zigpy.zcl.clusters.smartenergy import Metering
from zigpy.zcl.foundation import BaseAttributeDefs, ZCLAttributeDef
from zigpy.quirks.v2 import add_to_registry_v2,CustomDeviceV2,EntityMetadata
from zigpy.quirks.registry import DeviceRegistry
from zhaquirks import CustomCluster
from zigpy.quirks.v2 import ClusterType
from zhaquirks.const import (
    DEVICE_TYPE,
    ENDPOINTS,
    INPUT_CLUSTERS,
    MODELS_INFO,
    OUTPUT_CLUSTERS,
    PROFILE_ID,
)
from zhaquirks.thirdreality import THIRD_REALITY

THIRD_REALITY_PLUG_CLUSTER_ID = 0xFF03
RESET_SUMMATION_DELIVERED_ATTR_ID = 0x0000

class ControlMode(t.uint8_t):
    """Reset mode for clear summation delivered."""

    CLEAR = 1


class ThirdRealityPlugCluster(CustomCluster):
    """ThirdReality Acceleration Cluster."""

    cluster_id = THIRD_REALITY_PLUG_CLUSTER_ID
    

    class AttributeDefs(BaseAttributeDefs):
        """Attribute definitions."""

        reset_summation_delivered: Final = ZCLAttributeDef(
            id=RESET_SUMMATION_DELIVERED_ATTR_ID,
            type=ControlMode,
            is_manufacturer_specific=True,
        )
    
registry = DeviceRegistry()
(
    add_to_registry_v2(
        THIRD_REALITY, "3RSP02028BZ"
    )
    .adds(ThirdRealityPlugCluster.cluster_id)
    .write_attr_button(
        attribute_name=ThirdRealityPlugCluster.AttributeDefs.reset_summation_delivered.name,
        attribute_value=RESET_SUMMATION_DELIVERED_ATTR_ID,
        cluster_id=ThirdRealityPlugCluster.cluster_id,
        cluster_type=ClusterType.Server,
        endpoint_id=1
    )
)

quirked_device = registry.get_device()
write_attribute_button: EntityMetadata = quirked_device.exposes_metadata[
    (1, ThirdRealityPlugCluster.cluster_id, ClusterType.Server)
][0]

[puddly]

Replacing .adds(ThirdRealityPlugCluster.cluster_id) with .adds(ThirdRealityPlugCluster) creates a button for me:

"""Third Reality Plug devices."""

from typing import Final

import zigpy.types as t
from zigpy.zcl.foundation import BaseAttributeDefs, ZCLAttributeDef
from zigpy.quirks.v2 import add_to_registry_v2
from zhaquirks import CustomCluster
from zigpy.quirks.v2 import ClusterType
from zhaquirks.thirdreality import THIRD_REALITY


class ThirdRealityPlugCluster(CustomCluster):
    cluster_id = 0xFF03

    class AttributeDefs(BaseAttributeDefs):
        reset_summation_delivered: Final = ZCLAttributeDef(
            id=0x0000,
            type=t.uint8_t,
            is_manufacturer_specific=True,
        )


(
    add_to_registry_v2(THIRD_REALITY, "3RSP02028BZ")
    .adds(ThirdRealityPlugCluster)
    .write_attr_button(
        attribute_name=ThirdRealityPlugCluster.AttributeDefs.reset_summation_delivered.name,
        attribute_value=0x01,
        cluster_id=ThirdRealityPlugCluster.cluster_id,
        cluster_type=ClusterType.Server,
        endpoint_id=1,
        translation_key="reset_summation_delivered"
    )
)

[hwzolin]

@puddly Thank you for your patience, now the code works. But I still have a question, that is, how to set the default name of the button control that appears on the page? As you can see, the current name is "Third Reality, Inc 3RSP0202...".

[TheJulianJES]

@hwzolin A translation key (default: attribute name) for Home Assistant/ZHA itself needs to be added.
This will be done when we merge the "quirks bump PR" into Home Assistant/ZHA. We just need to know the translation keys and default English translations.
As an example for another quirk, see: matt-sullivan/home-assistant-core@1dff881

[hwzolin]

@hwzolin A translation key (default: attribute name) for Home Assistant/ZHA itself needs to be added. This will be done when we merge the "quirks bump PR" into Home Assistant/ZHA. We just need to know the translation keys and default English translations. As an example for another quirk, see: matt-sullivan/home-assistant-core@1dff881

@TheJulianJES Do you mean like this: https://github.com/hwzolin/core/blob/dev/homeassistant/components/zha/strings.json?

[hwzolin]

@TheJulianJES Hello, I have updated the code about zha quirk v2, please check it out. If there is no problem, please merge it.

[TheJulianJES]

You can use .also_applies_to(THIRD_REALITY, "3RSPE01044BZ") to make this quirk apply for both plugs.
The second quirk below can be removed then.

[TheJulianJES]

I think ZHA should already use the attribute name as the translation key by default. Since it's the same, this isn't needed IIRC.

[hwzolin]

@TheJulianJES
I'm sorry, I've been so busy lately, so I didn't pay attention to your reply in time.
I've made some changes to the code as you asked, and the modified code looks like this:

"""Third Reality Plug devices."""

from typing import Final

from zigpy.quirks import DeviceRegistry
from zigpy.quirks.v2 import ClusterType, add_to_registry_v2
import zigpy.types as t
from zigpy.zcl.foundation import BaseAttributeDefs, ZCLAttributeDef

from zhaquirks import CustomCluster
from zhaquirks.thirdreality import THIRD_REALITY


class ThirdRealityPlugCluster(CustomCluster):
    """The private cluster id of Third Reality's PLUG."""

    cluster_id = 0xFF03

    class AttributeDefs(BaseAttributeDefs):
        """Attribute of private cluster id."""

        reset_summation_delivered: Final = ZCLAttributeDef(
            id=0x0000,
            name="reset_summation_delivered",
            type=t.uint8_t,
            is_manufacturer_specific=True
        )


(
    add_to_registry_v2(THIRD_REALITY, "3RSP02028BZ")
    .also_applies_to(THIRD_REALITY, "3RSPE01044BZ")
    .adds(ThirdRealityPlugCluster.cluster_id)
    .replaces(ThirdRealityPlugCluster)
    .write_attr_button(
        attribute_name=ThirdRealityPlugCluster.AttributeDefs.reset_summation_delivered.name,
        attribute_value=0x01,
        cluster_id=ThirdRealityPlugCluster.cluster_id
    )
)

I'm not sure if the code changes are the same as you were asking for at the time, but the results don't work as expected. The name of this button in HA is still "Third Realtiy, Inc" + the model id of the device.

As shown in the following GIF, the button click function has been realized. So I don't know what is not enough to improve? Where do I need to modify? Can you please take some time out of your busy schedule to help me fix the imperfections.

There will be other devices that need to be supported in the future. I think if one device can realize the function, then there will be something to consider later.

[TheJulianJES]

The cluster_type is already Server by default, so this can be removed.

[TheJulianJES]

endpoint_id=1 is default, so this can be removed.

[hwzolin]

@TheJulianJES Hello, due to the busy work of the previous project, this project has been put on hold for the time being.
I didn't quite understand the solution you were offering at the time. Can you provide a complete project example of implementing a private cluster that supports devices with Quirks v2, I'd like to refer to it.

[hwzolin]

@TheJulianJES Hello, due to the busy work of the previous project, this project has been put on hold for the time being. I didn't quite understand the solution you were offering at the time. Can you provide a complete project example of implementing a private cluster that supports devices with Quirks v2, I'd like to refer to it.

@TheJulianJES