How should you add the Level Control cluster to the Device node example? Here is what I did.

[potto216]

I want to modify the example /packages/examples/src/device-onoff/DeviceNode.ts which implements either the on/off plug or on/off light to also include the level control cluster for either the light or plug in the same endpoint. I'm not sure how to properly implement the dependency relationships described in "Matter Application Cluster Specification -- 1.6. Level Control Cluster". The purpose of this work is for a Medium article describing this process for hobbiest who are intrested in using Matter in their projects.

My changes are summarized in this commit of my forked copy of matter.js.

I created the file packages/examples/src/device-onoff-with-level/DeviceNodeWithLevel.ts to add the the level control cluster with:

    const OnOffPlugInUnitDeviceWithLevel = OnOffPlugInUnitDevice.with(OnOffLightRequirements.LevelControlServer);
    const OnOffLightDeviceWithLevel = OnOffLightDevice.with(OnOffLightRequirements.LevelControlServer);

and to test I printed the value in the level control cluster changed event

    endpoint.events.levelControl.currentLevel$Changed.on(value => {
        console.log(`!@#$ Level is now ${value}%`);
    });

Then I started the program with changed I made to package.json and ran

npm run matter-device-with-level --  --storage-clear --loglevel debug

and I could see the cluster was added

2024-11-09 15:10:29.547 INFO   EndpointSt~ureLogger ⎸       Cluster-Server "LevelControl" (0x8) (Features: onOff, lighting)
2024-11-09 15:10:29.547 INFO   EndpointSt~ureLogger ⎸         Global-Attributes:
2024-11-09 15:10:29.547 INFO   EndpointSt~ureLogger ⎸           "clusterRevision" (0xfffd): value = 5
2024-11-09 15:10:29.547 INFO   EndpointSt~ureLogger ⎸           "featureMap" (0xfffc): value = {"onOff":true,"lighting":true,"frequency":false}
2024-11-09 15:10:29.547 INFO   EndpointSt~ureLogger ⎸           "attributeList" (0xfffb): value = [0,15,17,65533,65532,65531,65529,65528,1,16384]
2024-11-09 15:10:29.547 INFO   EndpointSt~ureLogger ⎸           "acceptedCommandList" (0xfff9): value = [0,1,2,3,4,5,6,7]
2024-11-09 15:10:29.547 INFO   EndpointSt~ureLogger ⎸           "generatedCommandList" (0xfff8): value = []
2024-11-09 15:10:29.547 INFO   EndpointSt~ureLogger ⎸         Attributes:
2024-11-09 15:10:29.547 INFO   EndpointSt~ureLogger ⎸           "currentLevel" (0x0): value = null
2024-11-09 15:10:29.547 INFO   EndpointSt~ureLogger ⎸           "options" (0xf): value = {"executeIfOff":false,"coupleColorTempToLevel":false}
2024-11-09 15:10:29.547 INFO   EndpointSt~ureLogger ⎸           "onLevel" (0x11): value = null
2024-11-09 15:10:29.547 INFO   EndpointSt~ureLogger ⎸           "remainingTime" (0x1): value = 0
2024-11-09 15:10:29.548 INFO   EndpointSt~ureLogger ⎸           "startUpCurrentLevel" (0x4000): value = null
2024-11-09 15:10:29.548 INFO   EndpointSt~ureLogger ⎸         Commands:
2024-11-09 15:10:29.548 INFO   EndpointSt~ureLogger ⎸           "moveToLevel" (0x0/0x0)
2024-11-09 15:10:29.548 INFO   EndpointSt~ureLogger ⎸           "move" (0x1/0x1)
2024-11-09 15:10:29.548 INFO   EndpointSt~ureLogger ⎸           "step" (0x2/0x2)
2024-11-09 15:10:29.548 INFO   EndpointSt~ureLogger ⎸           "stop" (0x3/0x3)
2024-11-09 15:10:29.548 INFO   EndpointSt~ureLogger ⎸           "moveToLevelWithOnOff" (0x4/0x4)
2024-11-09 15:10:29.548 INFO   EndpointSt~ureLogger ⎸           "moveWithOnOff" (0x5/0x5)
2024-11-09 15:10:29.548 INFO   EndpointSt~ureLogger ⎸           "stepWithOnOff" (0x6/0x6)
2024-11-09 15:10:29.548 INFO   EndpointSt~ureLogger ⎸           "stopWithOnOff" (0x7/0x7)
2024-11-09 15:10:29.548 INFO   EndpointSt~ureLogger ⎸         Events:

I then started the shell program to commission the device and sent a command to the level control cluster

npm run shell 2 -- -loglevel debug
commands levelcontrol movetolevel '{ "level": 56, "transitionTime": 10, "optionsMask": 0,  "optionsOverride": 0 }' 5470083840827545916 1

And saw both that the command was sent

2024-11-09 14:48:05.013 INFO   Behavior             Invoke 1731180547838.onoff.levelControl.moveToLevel online#99772c9@5ac81f9ae9d3a256 level: 56 transitionTime: 10 optionsMask: { executeIfOff: false, coupleColorTempToLevel: false } optionsOverride: { executeIfOff: false, coupleColorTempToLevel: false }
2024-11-09 14:48:05.013 DEBUG  Transaction          Transaction online#99772c9@5ac81f9ae9d3a256 locked 1731180547838.onoff.levelControl.state
2024-11-09 14:48:05.015 DEBUG  Transaction          Transaction online#99772c9@5ac81f9ae9d3a256 committed and unlocked 1 resource

And the device displayed the event from the console.log command

!@#$ Level is now 56%

I would like feedback if I set up everything correctly and any suggestions on improvement. The tutorial is focused on adding a cluster to a preexisting example.

[lauckhart]

Hi @potto216, looks good to me!

One thing that might be relevant for an article... In the latest release you can do npm init @matter to bootstrap a new project based on one of the examples. npm init @matter help gives instructions.

[Apollon77]

I would have one important addition: I personally would not add LevelControl as "optional extra adapter to an OnOff Light/PlugIn" because in fact you do not really know what controllers do with it!
In the case of "a Light/PlugIn with levelControl" there are indeed correct device types for it - DimmableLight and DimmablePlugInUnit. It is much better to use these. Then yiou also do not need to add the LevelControl yourself because in these device types it is mandatory.

Basically The rule of thumb for me is: If you want a certain functionality, first check if there is a device type defined that has anything "mandatory" that you want to use, then Use this device type rather then adding optional or additional clusters.

[potto216]

Thanks for both comments! npm init @matter simplifies the getting started process for the article I am writing. I also modified the output file from the command to use the DimmableLightDevice device as shown in the code below.

Is it possible to specify the discriminator for pairing with npm run shell? The command commission pair does not take a discriminator argument and always looks for 3840. This means I cannot use it to pair with the default program created by npm init @matter.

import { ServerNode } from "@matter/main";
import { DimmableLightDevice } from "@matter/main/devices/dimmable-light";

const passcode = 20202021
const discriminator = 3840

const uniqueId="123456"

const node = await ServerNode.create({
    id: uniqueId,
    commissioning: {
        passcode,
        discriminator,
    },}

);

// Create the light "endpoint".  In Matter an "endpoint" is a component of a node
const light = await node.add(DimmableLightDevice);

// Add an event handler to log the light's current status

light.events.identify.startIdentifying.on(() => {
    console.log(`!@#$ Run identify logic, ideally blink a light every 0.5s ...`);
});

light.events.identify.stopIdentifying.on(() => {
    console.log(`!@#$ Stop identify logic ...`);
});

light.events.onOff.onOff$Changed.on(value => {
    console.log(`!@#$ OnOff is now ${value ? "ON" : "OFF"}`);
});

light.events.levelControl.currentLevel$Changed.on(value => {
    console.log(`!@#$ Level is now ${value}%`);
});



// Run our server
await node.start();

[Apollon77]

First of all check the "commission pair" help :-))

matter> commission pair --help
commission pair

Pair with a matter device

Positionals:
  node-id  node id                                                                                                                                                                                                                                                                                                 [string]
  ip       ip address                                                                                                                                                                                                                                                                                              [string]
  port     ip port                                                                                                                                                                                                                                                                                                   [Zahl]

Optionen:
      --help                Hilfe anzeigen                                                                                                                                                                                                                                                                        [boolean]
      --pairingCode         pairing code                                                                                                                                                                                                                                                                           [string]
      --setupPinCode        setup pin code                                                                                                                                                                                                                                                      [Zahl] [Standard: 20202021]
  -i, --instanceId          instance id                                                                                                                                                                                                                                                                            [string]
  -d, --discriminator       Long discriminator                                                                                                                                                                                                                                                                       [Zahl]
  -s, --shortDiscriminator  Short discriminator                                                                                                                                                                                                                                                                      [Zahl]
  -b, --ble                 Also discover over BLE                                                                                                                                                                                                                                              [boolean] [Standard: false]
Done.

But ideally just use the pairingCode you get logged and use it with "--pairingCode ..."

[potto216]

Perfect! I needed help with that:)