Is it possible to add custom attributes to an existing cluster?

[masaki-sugitani]

For example, is it possible to add an attribute called time—which does not exist in the Matter specification—to the ReportingOnOffServer class in examples/device-onoff-light?
If this is possible, could you kindly provide a sample code?

[Apollon77]

What exactly is your goal? The clusters defined by the specification are defined. I would need to check specification if "defined clusters" (like OnOff) can have vendor specific enhancements - meaning custom attributes in vendor-id scoped number ranges, but usually such enhancements are only allowed matter wise in vendor specific custom clusters.

So from this regard I need to know what exactly you plan ad why?

[Apollon77]

Ok when reading Specification then in 7.21.2 and 7.21.3 it sounds like that also custom vendor specific attribute could be possible in standard clusters. They would need to get an Attribute Id in the relevant vendor Id range, so when vendor Id is 0xFFF1 then the normal first attribute Id would be 0xFFF10001 ... but still what's your use case for it? because no one beside an vendor specific app or controller would do anything with this. Please provide more information

[Apollon77]

But I currently clarify if such an extra attribute would be allowed for standard clusters. So stay tuned on this.

But still what exactly is the benefit of having it there as a debug information? if there is any client connected to it and subscribes he would get subscription update for the state changes - then you know the timestamp. Or you can just log these things and use the information from that log.

[masaki-sugitani]

Thank you for your clarification and for checking the specification!
Just to clarify my question: the time attribute was only an example. What I really want to know is whether the current version of matter.js supports adding a vendor-specific attribute to an existing standard cluster (such as OnOff).
If this is supported, could you please share how to implement it, ideally with a small code example?
My goal is not about the specification itself, but about what is currently possible in matter.js.

[Apollon77]

Ok, so in fact Matter specification wise it is allowed when the attribute IDs are in the Vendor specific number areas as discussed above.
To do that in matter.js (and I never did exactly this till now!) you need to ideally create a class extending the OnOffServer class and then you need to:
1.) Adjust the OnOff Tlv Schema
2.) Adjust the internal class schema

And in both add this attribute.

Right now both would be needed. We work on simplifying this but we are not yet there (in fact we already have ways to enhance the internal "state" of a cluster but this only works for "non-matter relevant" data. So for the time being it would be like that.

I do not have a ready to use example but some pointers:
1.) The example of a complete custom cluster which basically shows how to define the both schemas can be found at https://github.com/matter-js/matter.js/blob/main/docs/MIGRATION_GUIDE_08.md#add-owncustom-defined-clusters and respectively code wise https://github.com/matter-js/matter.js/blob/main/packages/examples/src/device-onoff-advanced/cluster/MyFancyOwnFunctionality.ts

Instead of defining this completely fresh as in that example you need to "extend" the existing schemas. This ends in like

2.) In

matter.js/packages/node/src/behaviors/administrator-commissioning/AdministratorCommissioningServer.ts

Lines 40 to 58 in 63c3532

	AdministratorCommissioning.Cluster.commands = {
	...AdministratorCommissioning.Cluster.commands,
	openCommissioningWindow: Command(
	0x0,
	TlvObject({
	commissioningTimeout: TlvField(0, TlvUInt16),
	pakePasscodeVerifier: TlvField(1, TlvByteString),
	discriminator: TlvField(2, TlvUInt16.bound({ max: 4095 })),
	iterations: TlvField(3, TlvUInt32),
	salt: TlvField(4, TlvByteString),
	}),
	0x0,
	TlvNoResponse,
	{
	invokeAcl: AccessLevel.Administer,
	timed: true,
	},
	),
	};

you see an example how the Tlv Model can be patched on the example of a command. basically for your attribute it would work the same just with "OnOff.Cluster.attributes" and add the relevant new tlv entry there.
3.) Then you need to do the same for the Model schema. You extend this like here

matter.js/packages/node/src/behaviors/switch/SwitchServer.ts

Lines 29 to 50 in 63c3532

	const schema = SwitchServerBase.schema.extend({
	children: [
	FieldElement({
	name: "longPressDelay",
	type: "duration",
	conformance: "MSL",
	default: DEFAULT_LONG_PRESS_DELAY,
	}),
	FieldElement({
	name: "multiPressDelay",
	type: "duration",
	conformance: "MSM",
	default: DEFAULT_MULTIPRESS_DELAY,
	}),
	FieldElement({
	name: "momentaryNeutralPosition",
	type: "uint8",
	conformance: "[MS]",
	default: 0,
	}),
	],
	});

- just mpt use FieldElement but AttributeElement ... and then install it like

matter.js/packages/node/src/behaviors/switch/SwitchServer.ts

Line 78 in 63c3532

static override readonly schema = schema;

into your derived class
4.) it might be needed that you also need to enhance the state of your cluster variant to install the new attribute name like

matter.js/packages/node/src/behaviors/switch/SwitchServer.ts

Line 331 in 63c3532

export class State extends SwitchServerBase.State {

... but for matter attribjte could work without that ... not 100% sure right now.

This should then enable you to have this exposed.

We are here to support if you run into problems or issues.

[masaki-sugitani]

Thank you so much for the detailed explanation and the pointers!
I’ll check the migration guide and the examples you shared.
I’ll try this out and come back if I run into issues.
Thanks again for your support!

[Apollon77]

WOuld be also cool if you could post how you did it when it worked to have it as a "reference" for others if needed

[masaki-sugitani]

I got it working! Here’s the full implementation for adding a vendor-specific attribute (customText) to the existing OnOff cluster in matter.js:

import { OnOff } from "@matter/types/clusters/on-off";
import { OnOffServer } from "@matter/main/behaviors/on-off";
import { Attribute, TlvString, ClusterType } from "@matter/main/types";
import { AttributeElement } from "@matter/main/model";

const CUSTOM_TEXT_ID = 0xFFF10001;

const ExtendedOnOffCluster = ClusterType({
    ...OnOff.Base,
    id: OnOff.Base.id,
    name: "OnOff",
    revision: OnOff.Base.revision,
    attributes: {
        ...OnOff.Base.attributes,
        customText: Attribute(
            CUSTOM_TEXT_ID,
            TlvString,
            { 
                default: "",
                persistent: true,
            }
        )
    }
});

const ExtendedOnOffServerBase = OnOffServer.for(ExtendedOnOffCluster);
const schema = ExtendedOnOffServerBase.schema?.extend({
    children: [
        AttributeElement({
            name: "customText",
            id: CUSTOM_TEXT_ID,
            type: "string",
            access: "R VA",
            conformance: "M",
            default: "",
        }),
    ],
});

export class ExtendedOnOffServer extends ExtendedOnOffServerBase {
    declare state: ExtendedOnOffServer.State;
    static override readonly schema = schema;
    override initialize() {
        this.state.customText = "default-text";
    }
    override async [Symbol.asyncDispose]() {
        return super[Symbol.asyncDispose]?.();
    }
}
export namespace ExtendedOnOffServer {
    export class State extends ExtendedOnOffServerBase.State {
        customText: string = "";
    }
}

export class AppImpl_OnOffServer extends ExtendedOnOffServer {
    override initialize() {
        super.initialize();
        this.state.customText = "OnOff-CustomText-Value";
    }
}

//////////////////////////////////////////////////

import { ServerNode } from "@matter/main";
import { OnOffLightDevice } from "@matter/main/devices/on-off-light";

const ExampleLight = OnOffLightDevice.with(AppImpl_OnOffServer);
const node = await ServerNode.create();
await node.add(ExampleLight);
await node.run();

This approach:

Extends the OnOff cluster with a vendor-specific attribute (customText).
Updates both the TLV schema and the internal model schema.
Provides a custom server implementation that initializes the new attribute.

Thanks again for your guidance! Hopefully this helps others who want to do something similar.

[Apollon77]

Thanks a lot for sharing and good luck. If you have any more questions or such feel free to ask or also join the Discord server