Quirks V2 use

[Ben3094]

Hello,
I tried to create a quirk for a IKEA VINDSTYRKA to add the tVOC (Volatile Organic Compounds) value using the method described here. But I am lost...

The previous method was to add this code :

class VOCIndex(CustomCluster):
    """VOC index value as reported by the Senserion SEN54 inside VINDSTYRKA."""

    cluster_id: Final[t.uint16_t] = 0xFC7E
    name: Final = "VOC Index"
    ep_attribute: Final = "voc_index"

    MEASURED_VALUE_ID = 0x0000
    MIN_MEASURED_VALUE_ID = 0x0001
    MAX_MEASURED_VALUE_ID = 0x0002

    class AttributeDefs(BaseAttributeDefs):
        measured_value: Final = ZCLAttributeDef(id=0x0000, type=t.uint16_t, access="rp", mandatory=True)
        min_measured_value: Final = ZCLAttributeDef(id=0x0001, type=t.uint16_t, access="rp", mandatory=True)
        max_measured_value: Final = ZCLAttributeDef(id=0x0002, type=t.uint16_t, access="rp", mandatory=True)


class IkeaVINDSTYRKA(CustomDeviceV2):
    """IKEA of Sweden VINDSTYRKA Air quality sensor."""

    def __init__( self, application, ieee: t.EUI64, nwk: t.NWK, replaces) -> None:
        registry = DeviceRegistry()
        entry = add_to_registry_v2(IKEA, MODEL, registry=registry).adds(VOCIndex.cluster_id).sensor(VOCIndex.AttributeDefs.measured_value.name, VOCIndex.cluster_id)
        super().__init__(application, ieee, nwk, replaces, )

    signature = {
        MODELS_INFO: [(IKEA, MODEL)],
        ENDPOINTS: {
            # <SimpleDescriptor endpoint=1 profile=260 device_type=770
            # device_version=0
            # input_clusters=[0, 3, 4, 1026, 1029, 1066, 64599, 64636, 64638]
            # output_clusters=[3, 25, 32, 514]>
            1: {
                PROFILE_ID: zha.PROFILE_ID,  # 260
                DEVICE_TYPE: zha.DeviceType.TEMPERATURE_SENSOR,  # 0x0302
                INPUT_CLUSTERS: [
                    Basic.cluster_id,  # 0x0000
                    Identify.cluster_id,  # 0x0003
                    Groups.cluster_id,  # 0x0004
                    TemperatureMeasurement.cluster_id,  # 0x0402
                    RelativeHumidity.cluster_id,  # 0x0405
                    PM25.cluster_id,  # 0x042a
                    WWAH_CLUSTER_ID,  # 0xfc57
                    IKEA_CLUSTER_ID,  # 0xfc7c
                    VOCIndex.cluster_id,  # 0xfc7e
                ],
                OUTPUT_CLUSTERS: [
                    Identify.cluster_id,  # 0x0003
                    Ota.cluster_id,  # 0x0019
                    PollControl.cluster_id,  # 0x0020
                    Fan.cluster_id,  # 0x0202
                ],
            },
            # <SimpleDescriptor endpoint=242 profile=41440 device_type=97
            # device_version=0
            # input_clusters=[]
            # output_clusters=[33]>
            242: {
                PROFILE_ID: 0xA1E0,
                DEVICE_TYPE: 0x0061,
                INPUT_CLUSTERS: [],
                OUTPUT_CLUSTERS: [GreenPowerProxy.cluster_id],  # 0x0021
            },
        },
    }
    replacement = {
        ENDPOINTS: {
            1: {
                PROFILE_ID: zha.PROFILE_ID,  # 260
                DEVICE_TYPE: zha.DeviceType.TEMPERATURE_SENSOR,  # 0x0302
                INPUT_CLUSTERS: [
                    Basic.cluster_id,  # 0x0000
                    Identify.cluster_id,  # 0x0003
                    Groups.cluster_id,  # 0x0004
                    TemperatureMeasurement.cluster_id,  # 0x0402
                    RelativeHumidity.cluster_id,  # 0x0405
                    PM25.cluster_id,  # 0x042a
                    WWAH_CLUSTER_ID,  # 0xfc57
                    IKEA_CLUSTER_ID,  # 0xfc7c
                    VOCIndex,
                ],
                OUTPUT_CLUSTERS: [
                    Identify.cluster_id,  # 0x0003
                    Ota.cluster_id,  # 0x0019
                    PollControl.cluster_id,  # 0x0020
                    Fan.cluster_id,  # 0x0202
                ],
            },
            242: {
                PROFILE_ID: 0xA1E0,
                DEVICE_TYPE: 0x0061,
                INPUT_CLUSTERS: [],
                OUTPUT_CLUSTERS: [GreenPowerProxy.cluster_id],  # 0x0021
            },
        },
    }

This code went well to read the cluster but to add an entity was a nightmare... (creation of a new cluster that does not really exist, defining buses and listeners, ...) Especially because this device does not report value as a classic VOC meter and I did not find where to define the value unit.

I find the Quirks V2 option much easier but I struggle to make it work...
When I try to simply add:

registry = DeviceRegistry()
(
    add_to_registry_v2(IKEA, MODEL, registry=registry)
    .adds(VOCIndex.cluster_id)
    .sensor(VOCIndex.AttributeDefs.measured_value.name, VOCIndex.cluster_id)
)

I get "IKEA of Sweden VINDSTYRKA is not a quirks v2 device - skipping discover_quirks_v2_entities"

When I try to turn the device in CustomDevice in CustomDeviceV2, I get "CustomDeviceV2.init() missing 1 required positional argument: 'quirk_metadata'"

[TheJulianJES]

With the newer Home Assistant / ZHA versions, you want just this in a file:

(
    QuirkBuilder(IKEA, "model/device name here")
    .replaces(VOCIndex)  # no `cluster_id`, because we want to implement our custom cluster, use `replaces` to replace the existing one
    .sensor(VOCIndex.AttributeDefs.measured_value.name, VOCIndex.cluster_id)
    .add_to_registry()
)

See this as an example: https://github.com/zigpy/zha-device-handlers/blob/5c4e08d94091a4c5f37cea7b21fd918474e98f82/zhaquirks/ikea/plug.py
You do not want to create a new DeviceRegistry, that's only for tests.

There's a bit of (older) info here: https://github.com/zigpy/zha-device-handlers/pull/3019/files

[Ben3094]

Now it works !!! 🥳
Thank you very much ! I will start to contribute to Quirks. 😉

[Ben3094]

As my entity is an index, do you know how to make it appear as a graph but still without unit ?

[TheJulianJES]

Can you post a screenshot of how it shows at the moment?

[Ben3094]

And can you explain how to rename the entity and how to change the reporting delay ? 😅😶‍🌫️
(I think it is "manual" for now as it is updated when I query the cluster...)

[TheJulianJES]

For naming, a translation key will need to be added to HA. By default, the translation key name is the attribute name. When added to HA, we'll add the key in the bump PR. I think there's also another parameter for the default name in the quirks v2 sensor function. This may no longer be true. I'd just rename the sensor manually in HA for now.
I'll have to look at the graph thing later. I think it's fully HA deciding when to show a graph.

[Ben3094]

Wow, I did not know naming is that difficult... Bad point for Home Assistant...
Can you add a new SensorDeviceClass to map a type that Home Assistant would graph ?
Do you know why the entity reports "manually" ?
Sorry if my questions bother you, I try to understand the Home Assistant system in order to contribute to it. Thank you for your time.