|
| 1 | +# Custom Matter Device Development |
| 2 | + |
| 3 | +Build a customizable lighting app using the Matter protocol |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +This guide will cover the basics of building a customizable lighting application |
| 8 | +using Matter. |
| 9 | + |
| 10 | +## Using Matter with Clusters |
| 11 | + |
| 12 | +In Matter, commands can be issued by using a cluster. A cluster is a set of |
| 13 | +attributes and commands which are grouped together under a relevant theme. |
| 14 | + |
| 15 | +Attributes store values (think of them as variables). Commands are used to |
| 16 | +modify the value of attributes. |
| 17 | + |
| 18 | +For example, the "On/Off" cluster has an attribute named "OnOff" of type |
| 19 | +boolean. The value of this attribute can be set to "1" by sending an "On" |
| 20 | +command or it can be set to "0" by sending an "Off" command. |
| 21 | + |
| 22 | +The C++ implementation of these clusters is located in the clusters directory. |
| 23 | +Note that you can also create your own custom cluster. |
| 24 | + |
| 25 | +## ZAP configuration |
| 26 | + |
| 27 | +From the matter repository, run the following command in a terminal to launch |
| 28 | +the ZAP UI. This will open up the ZAP configuration for the EFR32 lighting |
| 29 | +application example. |
| 30 | + |
| 31 | +> `$ ./scripts/tools/zap/run_zaptool.sh examples/lighting-app/lighting-common/lighting-app.zap` |
| 32 | +
|
| 33 | +On the left hand side of the application, there is a tab for Endpoint 0 and |
| 34 | +Endpoint 1. Endpoint 0 is known as the root node. This endpoint is akin to a |
| 35 | +"read me first" endpoint that describes itself and the other endpoints that make |
| 36 | +up the node. Endpoint 1 represents a lighting application device type. There are |
| 37 | +a number of required ZCL clusters enabled in Endpoint 1. Some clusters are |
| 38 | +common across most device types, such as identify and group clusters. Others, |
| 39 | +such as the On/Off, Level Control and Color Control clusters are required for a |
| 40 | +lighting application device type. |
| 41 | + |
| 42 | +Clicking on the blue settings icon on the right hand side of the application |
| 43 | +will bring you to the zap configuration settings for that cluster. Each cluster |
| 44 | +has some required attributes that may cause compile-time errors if they are not |
| 45 | +selected in the zap configuration. Other attributes are optional and are allowed |
| 46 | +to be disabled. Clusters also have a list of client-side commands, again some |
| 47 | +are mandatory and others are optional depending on the cluster. ZCL offers an |
| 48 | +extensive list of optional attributes and commands that allow you to customize |
| 49 | +your application to the full power of the Matter SDK. |
| 50 | + |
| 51 | +For example, if one was building a lighting application which only includes |
| 52 | +single color LEDs instead of RGB LEDs, it might make sense to disable the Color |
| 53 | +Control cluster in the ZAP configuration. Similarly, if one were to build a |
| 54 | +lighting application that doesn't take advantage of the Level Control cluster, |
| 55 | +which allows you to customize current flow to an LED, it might make sense to |
| 56 | +disable the Level Control cluster. |
| 57 | + |
| 58 | +Each time a modification is made to the ZAP UI, one must save (Electron→Save on |
| 59 | +a Mac toolbar) the current ZAP configuration and run the following command to |
| 60 | +generate ZAP code. |
| 61 | + |
| 62 | +> `$ ./scripts/tools/zap/generate.py examples/lighting-app/lighting-common/lighting-app.zap -o zzz_generated/lighting-app/zap-generated/` |
| 63 | +
|
| 64 | +## Receiving Matter commands |
| 65 | + |
| 66 | +All Matter commands reach the application through the intermediate function |
| 67 | +MatterPostAttributeChangeCallback(). When a request is made by a Matter client, |
| 68 | +the information contained in the request is forwarded to a Matter application |
| 69 | +through this function. The command can then be dissected using conditional logic |
| 70 | +to call the proper application functions based on the most recent command |
| 71 | +received. |
| 72 | + |
| 73 | +## Adding a cluster to a ZAP configuration |
| 74 | + |
| 75 | +In the ZAP UI, navigate to the Level Control cluster. Make sure this cluster is |
| 76 | +enabled as a server in the drop down menu in the "Enable" column. Then click on |
| 77 | +the blue settings wheel in the "Configure" column. This cluster can be used to |
| 78 | +gather power source configuration settings from a Matter device. It contains a |
| 79 | +few required attributes, and a number of optional attributes. |
| 80 | + |
| 81 | +## Adding a new attribute |
| 82 | + |
| 83 | +In the Level Control cluster configurations, ensure the CurrentLevel attribute |
| 84 | +is set to enabled. Set the default value of this attribute as 1. |
| 85 | + |
| 86 | +## Adding a new command |
| 87 | + |
| 88 | +Navigate to the commands tab in zap and enable the MoveToLevel command. Now save |
| 89 | +the current zap configuration, and run the aforementioned generate.py script. |
| 90 | + |
| 91 | +## React to Level Control cluster commands in ZclCallbacks |
| 92 | + |
| 93 | +In the MatterPostAttributeCallback function in ZclCallbacks, add the following |
| 94 | +line of code or similar. This will give the application the ability to react to |
| 95 | +MoveToLevel commands. The developer can define platform specific behavior for a |
| 96 | +MoveToLevel action. |
| 97 | + |
| 98 | + else if (clusterId == LevelControl::Id) |
| 99 | + { |
| 100 | + ChipLogProgress(Zcl, "Level Control attribute ID: " ChipLogFormatMEI " Type: %u Value: %u, length %u", |
| 101 | + ChipLogValueMEI(attributeId), type, *value, size); |
| 102 | + |
| 103 | + if (attributeId == LevelControl::Attributes::CurrentLevel::Id) |
| 104 | + { |
| 105 | + action_type = LightingManager::MOVE_TO_LEVEL; |
| 106 | + } |
| 107 | + |
| 108 | + LightMgr().InitiateActionLight(AppEvent::kEventType_Light, action_type, endpoint, *value); |
| 109 | + } |
| 110 | + |
| 111 | +## Send a MoveToLevel command and read the CurrentLevel attribute |
| 112 | + |
| 113 | +Rebuild the application and load the new executable on your EFR32 device. Send |
| 114 | +the following mattertool commands and verify that the current-level default |
| 115 | +attribute was updated as was configured. Replace {desired_level} with 10, and |
| 116 | +node_ID with the node ID assigned to the device upon commissioning |
| 117 | + |
| 118 | +> `$ mattertool levelcontrol read current-level 1 1 // Returns 1` |
| 119 | +
|
| 120 | +> `$ mattertool levelcontrol move-to-level {desired_level} 0 1 1 {node_ID} 1` |
| 121 | +
|
| 122 | +> `$ mattertool levelcontrol read current-level 1 1 // Returns 10` |
| 123 | +
|
| 124 | +More Information Silicon Labs lighting example on a Thunderboard Sense 2 - |
| 125 | +[sl-newlight/efr32](../../../silabs_examples/sl-newLight/efr32/README.md) |
| 126 | + |
| 127 | +--- |
| 128 | + |
| 129 | +[Table of Contents](../README.md) | [Thread Demo](../thread/DEMO_OVERVIEW.md) | |
| 130 | +[Wi-Fi Demo](../wifi/DEMO_OVERVIEW.md) |
0 commit comments