Link Clusters Feature Map values to attributes or commands conformance

[jmartinez-silabs]

Discussed in https://github.com/project-chip/zap/discussions/1188

Some commands, attributes, and attribute values are dependent on or linked to the cluster feature map value.

We need a way to associate a feature map value to attributes and commands. I would like to have some part of this dependency to be automated but at a minimum, we need to be able to warn the User that his configuration is not spec-compliant.

In the Matter implementation, Some cluster functionalities are gated by their feature map value. An external device should also be able to read the feature map value of any cluster from a device to determine what those devices support.

Here are a few examples:

• The user is configuring the color control cluster. He enables the currentX, currentY attributes and the moveToCorlor, MoveColor, StepColor and StopMoveStep commands. All of those are linked to the XY conformance. The feature map attribute shall be changed to set bit 3. Nothing prevents or warns the user to change the feature map value. It would be great if the right feature map bit was automatically set when enabling one for those attributes or commands. But at least a Warning/error message should be presented to the user

• Another case I can think of is some attributes default value/limit can change based on the featuremap. For the level control cluster, the MinLevel default value is 0 but if the Lighting bit is set in the feature map then it shall be 1

from Table 2. Attributes of the Level Control Server Cluster

Level control Cluster feature map

Basic Suggestion: have a requiredIf="featuremap & BIT(X)==true" and or requireFeaturemapBit=X that we can add to an attribute or command in the xml definition to trigger different behaviours.

Details from the spec From the Matter spec:

7.13.2. FeatureMap Attribute
The FeatureMap attribute SHALL indicate whether the server supports zero or more optional cluster features. A cluster feature is a set of cluster elements that are mandatory or optional for a defined feature of the cluster. If a cluster feature is supported by the cluster instance, then the corresponding bit SHALL be set to 1, otherwise the bit SHALL be set to 0 (zero). All undefined bits in this attribute SHALL be set to 0 (zero).
The set of cluster elements that are designated as mandatory (M) are implicitly part of the mandatory cluster feature set, and do not have a bit in the FeatureMap attribute.
A cluster specification SHALL support this attribute if the cluster supports features. If a cluster specification is revised to support features (and so this attribute), each bit in the FeatureMap attribute SHALL have a defined default value (1 or 0), to conform with the previous revision of the cluster specification, that did not support the FeatureMap attribute. The value of 1 means the feature elements were mandatory (M) in the previous revision. The value of 0 (zero) means the elements were optional in the previous revision.
Any newly created feature set of a cluster SHALL be dependent on that cluster.
Feature sets are revision controlled as part of a cluster using the ClusterRevision attribute. The cluster specification is the independent element that is revision controlled. A remote application reading the FeatureMap Attribute and ClusterRevision Attribute will then know exactly what features are supported in the cluster instance.
Each feature set SHALL be well defined within the cluster specification. Each feature SHALL be mapped to a short capitalized code name for the feature set to be referenced as a conformance tag in the cluster specification text, including the Conformance columns defining the elements of the cluster.
If a cluster defines more than 32 feature sets, then it will be necessary to add another feature bitmap attribute. Any client trying to reference the new feature set will know about the new bitmap, because it knows about the new feature set(s). Legacy products will not know about the new feature set nor the new bitmap.
For a cluster whose definition which does not define a FeatureMap, the server SHALL set this attribute to 0 (zero).

About the conformance (matter spec)

Allowable Conformance for a bit in a bitmap:
• Mandatory
• Dependent upon a Feature supported in the FeatureMap attribute.
• Dependent upon the support of an attribute.

More about conformance can be found in the spec. There is a chapter about it (7.3. Conformance in the main.pdf) or the link below: https://github.com/CHIP-Specifications/connectedhomeip-spec/blob/master/src/data_model/Data-Model.adoc#3-conformance

[tecimovic]

Feature description

• the exiting "tags" (which is how feature map is currently implemented in zap), need to be associated with entities (attributes, commands, events) inside the XML file.
• user interface then needs to make some use of it, in form of warnings, suggested actions, and so on.

Work plan

• Update XML schema, to allow "tag" values to be attached to attributes, commands and events. (More than one tag can be attached to each of them).
• Update DB schema to create junction tables between ZCL entities and TAGs.
• Fix the loader to properly load all this.
• Modify the UI, so that for each cluster that has tags, the list of tags is presented somewhere at the top of Cluster UI, as some sort of checkboxes or something, basically allowing the user to select/unselect these tags.
• Make sure that the FeatureMap attribute has some data-driven way to be tied to the tags. This can't be hard-coded.
• Modify the UI logic, so that whenever tags are enabled/disabled, the appropriate entities are enabled.
• Modify the UI logic, so that whenever things get out of sync, some warnings are displayed.
• Add to generation whatever needs to be added to generation for this. Not sure if anything, at this point.

[brdandu]

Feature description

• the exiting "tags" (which is how feature map is currently implemented in zap), need to be associated with entities (attributes, commands, events) inside the XML file.
• user interface then needs to make some use of it, in form of warnings, suggested actions, and so on.

Work plan

• Update XML schema, to allow "tag" values to be attached to attributes, commands and events. (More than one tag can be attached to each of them).
• Update DB schema to create junction tables between ZCL entities and TAGs.
• Fix the loader to properly load all this.
• Modify the UI, so that for each cluster that has tags, the list of tags is presented somewhere at the top of Cluster UI, as some sort of checkboxes or something, basically allowing the user to select/unselect these tags.
• Make sure that the FeatureMap attribute has some data-driven way to be tied to the tags. This can't be hard-coded.
• Modify the UI logic, so that whenever tags are enabled/disabled, the appropriate entities are enabled.
• Modify the UI logic, so that whenever things get out of sync, some warnings are displayed.
• Add to generation whatever needs to be added to generation for this. Not sure if anything, at this point.

In this case the tags are actually associated with the featureMap attribute but our xml does not relay this information. We need to associate the tag with an attribute as well from what I understand to link all the information together i.e. featureMapAttr<->tag<->attributes/commands. This will future proof it more such that if we ever need to associate another attribute with a set of attributes and commands then our logic handles that as well.

[tecimovic]

@brdandu : If you look at matter XML, you see things like this:

        <!-- Cluster feature map -->
        <globalAttribute side="server" code="0xFFFC" value="0x0001">
            <featureBit tag="PIN" bit="0">true</featureBit>
            <featureBit tag="RID" bit="1">false</featureBit>
            <featureBit tag="FGP" bit="2">false</featureBit>
            <featureBit tag="LOG" bit="3">false</featureBit>
            <featureBit tag="SCH" bit="4">true</featureBit>
            <featureBit tag="DPS" bit="5">true</featureBit>
            <featureBit tag="FACE" bit="6">false</featureBit>
            <featureBit tag="COTA" bit="7">true</featureBit>
            <featureBit tag="USR" bit="8">true</featureBit> <!-- TODO: Depend on PIN | RID | FGP | FACE -->
            <featureBit tag="NOT" bit="9">false</featureBit>
        </globalAttribute>

This associates the tags with the given attribute. This was already done, and is in the database.

So the feature map attributes have known associations where each bit is assigned a tag. A missing link is that this is then not attached to any attributes and such.

[tecimovic]

See GLOBAL_ATTRIBUTE_BIT table and TAG tables. TAG table defines the per-cluster tags, and GLOBAL_ATTRIBUTE_BIT associates them with individual bits for global attributes.

[tecimovic]

Feature description

• the exiting "tags" (which is how feature map is currently implemented in zap), need to be associated with entities (attributes, commands, events) inside the XML file.
• user interface then needs to make some use of it, in form of warnings, suggested actions, and so on.

Work plan

• Update XML schema, to allow "tag" values to be attached to attributes, commands and events. (More than one tag can be attached to each of them).
• Update DB schema to create junction tables between ZCL entities and TAGs.
• Fix the loader to properly load all this.
• Modify the UI, so that for each cluster that has tags, the list of tags is presented somewhere at the top of Cluster UI, as some sort of checkboxes or something, basically allowing the user to select/unselect these tags.
• Make sure that the FeatureMap attribute has some data-driven way to be tied to the tags. This can't be hard-coded.
• Modify the UI logic, so that whenever tags are enabled/disabled, the appropriate entities are enabled.
• Modify the UI logic, so that whenever things get out of sync, some warnings are displayed.
• Add to generation whatever needs to be added to generation for this. Not sure if anything, at this point.

[tecimovic]

@bzbarsky-apple @vivien-apple @mrjerryjohns @tcarmelveilleux : there is some lack of functionality around "feature map" bits, because the user-configuration of things was not a priority.

Can some of you please look at my previous comment and comment if we're missing something around the feature maps, that I don't know needs to happen?

[jmartinez-silabs]

@tecimovic @brdandu Can we add the featuremap name to the global attribute? Right now we are just listing the code 0xFFFC. <globalAttribute side="server" code="0xFFFC" value="0x0001">

Make sure that the FeatureMap attribute has some data-driven way to be tied to the tags. This can't be hard-coded. Not sure what this means or how it is done can you elaborate? Isn't it done with what you exposed as<featureBit tag=...

Right now this format is used to generate an enum that can be used in matter code

    <bitmap name="DoorLockFeature" type="BITMAP32">
        <cluster code="0x0101" />
        <field name="PINCredentials" mask="0x01" />
        <field name="RFIDCredentials" mask="0x02" />
        <field name="FingerCredentials" mask="0x04" />
        <field name="Logging" mask="0x08" />
        <field name="AccessSchedules" mask="0x10" />
        <field name="DoorPositionSensor" mask="0x20" />
        <field name="FaceCredentials" mask="0x40" />
        <field name="CredentialsOTA" mask="0x80" />
        <field name="UsersManagement" mask="0x100" />
        <field name="Notifications" mask="0x200" />
    </bitmap>

Could it be directly generated from the detailed tags in the global attribute without having to recreate that bitmap?

[paulr34]

Work Plan:

add attribute tag to schema table add code that checks feature map tag and enables everything with that tag

@tecimovic

[cecille]

Just a heads up - the conformances are more complex than just feature tags. Things can have conformances marked for other things in their table, and can have multiple conformance requirements. Features themselves can also have conformances.

The model used in the SDK for checking conformance is available here: https://github.com/project-chip/connectedhomeip/blob/master/src/python_testing/conformance_support.py

[brdandu]

Just an update here. Since this is a complicated issue, I will be breaking this into smaller increments. We can keep this issue open meanwhile. I am currently looking into the feature map attribute conformance as per the device type selection.