You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: sld601-matter-application-development/matter-application-cluster-logic.md
+27-25Lines changed: 27 additions & 25 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,64 +1,66 @@
1
1
# Matter Application Cluster Logic
2
2
3
-
The architecture of a Matter application is organized into layers, with the application layer sitting on top of the network transport layer (such as Thread or Wifi). This application layer is where the device’s behavior is defined, using a structured data model to describe what the device can do. At the core of this model are clusters, which group together related attributes, commands, and events to represent specific features. For instance, a cluster might handle turning a device on or off, adjusting brightness, or reporting temperature. These clusters are standardized and reusable, which helps ensure consistent behavior across different devices and manufacturers. More information on the matter data model can be found [here](https://docs.silabs.com/matter/latest/matter-fundamentals-data-model/).
3
+
The architecture of a Matter application is structured in layers, with the application layer positioned above network transport layer (such as Thread or Wi-fi). This application layer defines the device's behavior using a structured data model that describes its capabilities. At the core of this model are clusters, which group together related attributes, commands, and events to represent specific features. For example, a cluster might control power (on/off), adjust brightness, or report temperature. These clusters are standardized and reusable, ensuring consistent behavior across different devices and manufacturers. For more information, see the [Matter data model](https://docs.silabs.com/matter/latest/matter-fundamentals-data-model/) documentation.
To organize these features within a device, Matter introduces the concept of endpoints. An endpoint represents a specific functional part of the device and can include one or more clusters. For example, a smart light might have an endpoint that includes both the On/Off and Level Control clusters. More complex devices can have multiple endpoints to represent different capabilities—like a thermostat that also includes a fan controller or a humidity sensor.
7
+
To organize these features within a device, Matter introduces the concept of endpoints. An endpoint represents a specific functional part of the device and can include one or more clusters. For example, a smart light might have an endpoint that includes both the On/Off and Level Control clusters. More complex devices may use multiple endpoints to represent different capabilities, such as a thermostat that also includes a fan controller or a humidity sensor.
8
8
9
-
To make it easier to define and configure these endpoints and clusters, developers use a tool called the ZCL Advanced Platform, or ZAP. ZAP provides a user-friendly interface for selecting clusters, assigning them to endpoints, and configuring their attributes and commands. It also generates the necessary code to integrate with the Matter SDK, streamlining the development process. In the sections that follow, we’ll walk through how to extend the functionality of an existing door lock endpoint by adding the On/Off cluster.
9
+
To simplify the process of defining and configuring endpoints and clusters, developers use the ZCL Advanced Platform (ZAP). ZAP offers a user-friendly interface for selecting clusters, assigning them to endpoints, and configuring their attributes and commands. It also generates the necessary code to integrate with the Matter SDK, streamlining development.
10
+
11
+
The following sections demonstrate how to extend the functionality of an existing door lock endpoint by adding the On/Off cluster.
10
12
11
13
## Step 1: Create the Application
12
14
13
-
Before getting started, users must ensure that they have Simplicity Studio installed in a PC and have downloaded the Simplicity SDK along with the matter extension. More instructions on these requirements can be found[here](https://docs.silabs.com/matter/1.0.5/matter-studio/).
15
+
Before you begin, ensure that Simplicity Studio is installed on your PC and you have downloaded the Simplicity SDK and the Matter extension. For more information on these requirements, see[here](https://docs.silabs.com/matter/1.0.5/matter-studio/).
14
16
15
-
To create the Matter Door Lock App, open up Simplicity Studio and connect a supported Silicon Labs development board (e.g. EFR32MG2x) to your computer via USB. This guide will use an MG24 as the platform. Navigate to the *Launcher* tab, select your device, and select the correct SDK.
17
+
To create the Matter Door Lock App, launch Simplicity Studio and connect a supported Silicon Labs development board (for example, EFR32MG2x) to your computer via USB. This guide uses MG24 as the platform. Next, navigate to the **Launcher** tab, select your connected device, and select the correct SDK.
Select *Create New Project*, filter by "Matter", and locate the Matter - SoC Lock over Thread with External Bootloader project. Select "Next" then Click finish.
21
+
Select **Create New Project**, then use the filter to search for "Matter". Locate the "Matter - SoC Lock over Thread with External Bootloader" project. Click **Next**, then select **Finish**.
20
22
21
23
22
24
23
-
The sample application has now been created by Studio and you can move on to step 2.
25
+
The sample application has been successfully created in Simplicity Studio. You can now proceed to Step 2.
24
26
25
27
## Step 2: Add and Modify the On/Off Cluster
26
28
27
-
After step 1, your project's .slcp file should automatically be opened. Navigate to "Configuration Tools" then scroll down to "ZCL Advanced Platform (ZAP)" and select "Open".
29
+
After step 1, your project's `.slcp` file should automatically be opened. Navigate to **Configuration Tools**, scroll down to "ZCL Advanced Platform (ZAP)", and click **Open**.
28
30
29
31
30
32
31
-
This opens up the project's .zap configuration file. There should be two endpoints enabled already:
32
-
- 0: Reserved exclusively for Utility Clusters. These special clusters are specifically used for enclosing a node’s servicing functionality: the discovery process, addressing, diagnostics, and software updates.
33
-
- 1: Endpoint is configured to be a Matter Door Lock. It has mandatory clusters along with the Door Lock cluster (0x0101).
33
+
This opens the project's .zap configuration file. You should see two endpoints already enabled:
34
+
-Endpoint 0: Reserved exclusively for Utility Clusters. These special clusters are specifically used for enclosing a node’s servicing functionality such as the discovery process, addressing, diagnostics, and software updates.
35
+
-Endpoint 1: Configured to be a Matter Door Lock. It has mandatory clusters along with the Door Lock cluster (0x0101).
34
36
35
-
Click on Endpoint #1 then open the "General Tab".
37
+
Click on Endpoint #1 then open the **General Tab**.
Enable the On/Off cluster (0x0006) as both a Server and Client. This should add mandatory attributes and commands as required by the spec for this cluster, these can be viewed by selecting the "Configure" icon.
41
+
Enable the On/Off cluster (0x0006) as both a Server and Client. This should add mandatory attributes and commands as required by the specification for this cluster. You can view these by selecting the **Configure** icon.
By configuring both a client and server for the On/Off cluster, the device should be able to transmit On/Off commands and store On/Off attributes. Normally, a light bulb acts as a server because it holds the On/Off state and responds to commands to change it. A light switch acts as a client because it sends commands to the bulb to turn it on or off, but doesn't store the state itself. For this guide, we will mainly focus on the attribute storing and manipulation.
45
+
By configuring both client and server roles for the On/Off cluster, the device can transmit On/Off commands and store On/Off attributes. Normally, a light bulb acts as a server because it stores the On/Off state and responds to commands to change it. A light switch acts as a client because it sends commands to the bulb to turn it on or off but doesn't store the state itself. This guidemainly focuses on attribute storing and manipulation.
44
46
45
-
Save the .zap file. The tool will automatically generate the necessary code files for your application, reflecting the new cluster configuration. For more information, reference[ZCL Advanced Platform (ZAP) Tool for Matter](https://docs.silabs.com/matter/latest/matter-references/matter-zap).
47
+
Finally, save the `.zap` file. The tool will automatically generate the necessary code files to reflect your updated cluster configuration. For more information, see[ZCL Advanced Platform (ZAP) Tool for Matter](https://docs.silabs.com/matter/latest/matter-references/matter-zap).
46
48
47
49
48
50
## Step 3: Analyze the Auto-generated Code
49
51
50
-
Now that the new On/Off cluster has been added to the Sample Door Lock project, it's time to leverage the new features/code. Here's a summary of what happens following the cluster addition:
52
+
Now that the On/Off cluster has been successfully added to the Sample Door Lock project, it's time to leverage the new features/code. Here's a summary of what happens after the cluster is added:
51
53
52
54
- Attributes, commands, and events for the cluster are added to your application’s data model.
53
55
- Code is generated for attribute storage, command handling, and event notification.
54
56
- Callback stubs are generated for you to implement application-specific behavior.
55
57
- You interact with the cluster by filling in these stubs and using the generated data structures.
56
58
57
-
You will also notice that following the cluster enablement, a corresponding component is automatically added to your project. This happens because enabling a cluster in ZAP updates your project configuration to include the necessary software components and libraries required to support that cluster’s functionality. For clusters, this functionality is implemented in the <matter_extension>/third_party/matter_sdk/src/app/clusters directory. For the On/Off cluster, the server command handlers and related logic can be found in the /on-off-server/on-off-server.cpp file.
59
+
Additionally, a corresponding component is automatically added to your project. This occurs because enabling a cluster in ZAP updates your project configuration to include the necessary software components and libraries required to support that cluster’s functionality. For clusters, this functionality is implemented in the `<matter_extension>/third_party/matter_sdk/src/app/clusters` directory. For the On/Off cluster, the server command handlers and related logic can be found in the `/on-off-server/on-off-server.cpp` file.
58
60
59
61
## Step 4: Add Application Logic
60
62
61
-
Locate your project's src/AppTask.cpp file. This file acts as the central hub for application-specific logic, initialization, and event processing in a Matter application on Silicon Labs platforms. We will begin by creating two helper functions, one that starts a one-shot timer to expire in 10 seconds and the handler function, **OnOffTmrExpiryHandler**.
63
+
Locate your project's `src/AppTask.cpp` file. This file acts as the central hub for application-specific logic, initialization, and event processing in a Matter application on Silicon Labs platforms. Start by adding two helper functions: a one-shot timer to expire in 10 seconds and the `OnOffTmrExpiryHandler`handler function.
This function will have to be defined in AppTask.h as well as part of the AppTask class.
100
102
101
-
Now, locate the MatterPostAttributeChangeCallback() function in the src/ZclCallbacks.cpp file. This function is invoked by the application framework after an attribute value has been changed. Since we are modifying the OnOff attribute in the OnOffTmrExpiryHandler(), this callback will be used to re-initiate the timer so that the attribute continues to toggle. To achieve this, you can call AppTask::OnOffAttributeWriteStartTimer(), which is part of the AppTask context.
103
+
Now, locate the `MatterPostAttributeChangeCallback()` function in the `src/ZclCallbacks.cpp` file. This function is invoked by the application framework after an attribute value has been changed. Because you are modifying the OnOff attribute in the `OnOffTmrExpiryHandler()` function, use this callback to re-initiate the timer so that the attribute continues to toggle. To achieve this, call `AppTask::OnOffAttributeWriteStartTimer()`, which is part of the AppTask context.
102
104
103
-
To implement this functionality, you must first obtain the AppTask instance using AppTask::GetAppTask(). Modify the MatterPostAttributeChangeCallback() function as shown below:
105
+
To implement this functionality, first obtain the AppTask instance using `AppTask::GetAppTask()`. Modify the `MatterPostAttributeChangeCallback()` function as shown below:
Make sure to #include "AppTask.h" at the top of ZclCallbacks.cppto call the AppTask::GetAppTask() function. For more information on the AppTask, reference AppTask.h.
122
+
Make sure to #include "AppTask.h" at the top of the `ZclCallbacks.cpp` file to call the `AppTask::GetAppTask()` function. For more information on the AppTask, refer to AppTask.h.
121
123
122
-
The last step is to add a call to OnOffTmrStart() at the end of the AppTask::AppInit() function to start the attribute write sequence. Below is the code flow:
124
+
Finally, add a call to `OnOffTmrStart()` at the end of the `AppTask::AppInit()` function to start the attribute write sequence. The following image illustrates the code flow:
123
125
124
126
125
127
126
-
In the flow chart above, OnOffAttributeWriteStartTimer() calls OnOffTmrStart() to restart the timer.
128
+
In the flowchart above, `OnOffAttributeWriteStartTimer()` calls `OnOffTmrStart()` to restart the timer.
127
129
128
130
## Step 5: Interact with the On/Off Cluster
129
131
130
132
After building your project, flash the compiled firmware onto your target board. Once the device is running, you should observe log messages approximately every 10 seconds indicating that the OnOff cluster's OnOff attribute is being written to. This confirms that the cluster is active and functioning as expected.
131
133
132
-
The next step is to commission the device to a Matter hub and begin interacting with the OnOff cluster. To do this, follow the instructions outlined in the Creating the Matter Network section of the [Silicon Labs Matter Light Switch Example Guide](https://docs.silabs.com/matter/2.6.0/matter-light-switch-example/02-thread-light-switch-example#creating-the-matter-network).
134
+
Next, commission the device to a Matter hub and begin interacting with the OnOff cluster. To do this, follow the instructions in the **Creating the Matter Network** section of the [Silicon Labs Matter Light Switch Example Guide](https://docs.silabs.com/matter/2.6.0/matter-light-switch-example/02-thread-light-switch-example#creating-the-matter-network).
133
135
134
136
Once the custom Door Lock node is successfully commissioned to the network, you can read the value of the OnOff attribute using the following command:
0 commit comments