|
| 1 | +[<< Back to TOC](../README.md) |
| 2 | + |
| 3 | +# ZCL Advanced Platform (ZAP) Tool for Matter |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +EFR32 example applications provide a baseline demonstration of a lock device, |
| 8 | +built using the Matter SDK and the Silicon Labs GeckoSDK. It can be controlled |
| 9 | +by a CHIP controller over Openthread network. |
| 10 | + |
| 11 | +The EFR32 device can be commissioned over Bluetooth Low Energy (BLE) where the |
| 12 | +device and the CHIP controller will exchange security information with the |
| 13 | +Rendez-vous procedure. Thread Network credentials are provided to the EFR32 |
| 14 | +device which will then join the network. |
| 15 | + |
| 16 | +The LCD on the Silicon Labs WSTK shows a QR Code containing the needed |
| 17 | +commissioning information for the BLE connection and starting the Rendez-vous |
| 18 | +procedure. |
| 19 | + |
| 20 | +The lock example is intended to serve both as a means to explore the workings of |
| 21 | +CHIP, and a template for creating real products on the Silicon Labs platform. |
| 22 | + |
| 23 | +Each Matter application consists of the following layers: |
| 24 | + |
| 25 | +- Matter SDK: Source code necessary to communicate through the Matter network |
| 26 | + over Thread or Wifi |
| 27 | +- Data model layer in the form of clusters. There are two types of clusters: |
| 28 | + - Utility Clusters: |
| 29 | + - They represent common management and diagnostic features of a Matter |
| 30 | + endpoint |
| 31 | + - Identify cluster is an example of a Utility Cluster. Given a Node |
| 32 | + ID, it can be used to Blink LED0 to the corresponding Silicon Labs |
| 33 | + WSTK |
| 34 | + - Application Clusters: |
| 35 | + - These clusters represent functionalities specific to a given |
| 36 | + application |
| 37 | + - Door Lock Cluster is an example of an Application specific cluster. |
| 38 | + This cluster contains commands to lock and unlock a door(door-lock |
| 39 | + is represented by an LED), with options to set passwords and lock |
| 40 | + schedules |
| 41 | + |
| 42 | +<br> |
| 43 | + |
| 44 | +## Clusters |
| 45 | + |
| 46 | +Every Matter Application uses multiple clusters leveraged from the Zigbee |
| 47 | +Cluster Library(ZCL). A cluster can be seen as a building block for the Data |
| 48 | +Model of a Matter application. Clusters contains attributes, commands, and |
| 49 | +events. Attributes are customizable variables specified by the Zigbee Advanced |
| 50 | +Platform(ZAP) tool. Commands are sent to the application, which may respond with |
| 51 | +data, LED flickering, lock actuation, etc. Events are notifications sent out by |
| 52 | +the server. |
| 53 | + |
| 54 | +An application can have multiple Matter endpoints. Application endpoints |
| 55 | +generally refer to one device, and inherits its information from the "cluster" |
| 56 | +it belongs to. Utility clusters are required to be on the endpoint with ID 0. |
| 57 | +Application clusters are assigned to endpoints with IDs 1 and higher. |
| 58 | + |
| 59 | +Some applications have callbacks that are left to be implemented by the device |
| 60 | +manufacturer. For example, the storage and mangement of users and credentials in |
| 61 | +the lock-app is left up to the application developer. |
| 62 | + |
| 63 | +<br> |
| 64 | + |
| 65 | +## ZAP Tool |
| 66 | + |
| 67 | +The ZAP tool is built and maintained by Silicon Labs and developers in the ZAP opensource community. It inherits its name and |
| 68 | +features from the Zigbee Cluster Library, which was the starting point for the Matter data model. ZAP is used |
| 69 | +for generating code for Matter applications based on the Zigbee Cluster |
| 70 | +Library and associated Matter code templates. |
| 71 | + |
| 72 | +The ZAP tool can be cloned using the following git command. This will create a |
| 73 | +root level matter folder in your current directory. All following commands |
| 74 | +should be run from the matter folder. |
| 75 | + |
| 76 | +> `$ git clone https://github.com/SiliconLabs/matter.git` |
| 77 | +
|
| 78 | +The `run_zaptool.sh` script can be invoked |
| 79 | +without arguments, or, you can provide the path to a ZAP file to be opened upon |
| 80 | +launch. |
| 81 | + |
| 82 | +In the following examples, the ZAP file for the lock-app has been chosen. |
| 83 | + |
| 84 | +> `$ ./scripts/tools/zap/run_zaptool.sh ($PATH_TO_ZAP_FILE)` |
| 85 | +
|
| 86 | +This shows the output of the run_zaptool script with no arguments. To load a new |
| 87 | +zap file, click the application menu for Electron (Upper left corner of the |
| 88 | +screen for macs), then click "Open File". Then navigate to the desired .zap |
| 89 | +file. |
| 90 | + |
| 91 | + |
| 92 | + |
| 93 | +This shows the output of the run_zaptool script with a zap file given as an |
| 94 | +argument, or after a .zap file has been opened in the ZAP UI. An Electron |
| 95 | +application will open, pre-loaded with the information from the .zap file |
| 96 | +provided as a command line argument. |
| 97 | + |
| 98 | + |
| 99 | + |
| 100 | +The Out of the box(OOB) example lock application has 2 endpoints. Endpoint 0 is |
| 101 | +called the root node. It contains all Service and Device management clusters. In |
| 102 | +general, any cluster or feature that is not specific to a device type belongs in |
| 103 | +Endpoint 0. Examples of clusters one might find in Endpoint 0: Device Descriptor |
| 104 | +cluster, Network Diagnostics cluster. |
| 105 | + |
| 106 | +Endpoint 1 contains information specific to the device type. Conveniently, the |
| 107 | +ZAP tool offers a Door lock cluster, which contains Commands(lock, unlock, set |
| 108 | +credential, etc..) and Attributes(Lock state, Require PIN) that a standard door |
| 109 | +lock application might use. |
| 110 | + |
| 111 | +More endpoints can be added. Each endpoint acts like a port on a network interface. |
| 112 | + |
| 113 | +Endpoints contain clusters which are bundles of device functionality. Clusters have both a Client and a Server interface. In general the Client interface sends commands and the Server interface receives them. For instance a Light would implement the Server side of the on/off clusters. A Switch would implement the Client side of the same cluster. |
| 114 | + |
| 115 | +Click on Endpoint 1 on the left hand side of the application. The door lock |
| 116 | +cluster should already be enabled as "Server". |
| 117 | + |
| 118 | + |
| 119 | + |
| 120 | +<br> |
| 121 | + |
| 122 | +## Attributes |
| 123 | + |
| 124 | +Attributes are analogous to member variables of a class. Each attribute is |
| 125 | +provided with generated setter/getter code from the ZAP tool. They can be |
| 126 | +enabled or disabled for each cluster on a Matter endpoint. Some attributes are |
| 127 | +required to be enabled, else the application will not function properly. There |
| 128 | +is an option to add attributes to either the server code or client code. The ZAP |
| 129 | +tool also allows you choose a storage space for attributes. Attributes can be |
| 130 | +stored in standard RAM, Non-volatile memory or external memory. Each attribute |
| 131 | +has a type, some are standard C types and some have specially defined enums. |
| 132 | +Each attribute can be provided with a default starting value value. |
| 133 | + |
| 134 | +Click the settings wheel to enable/disable, choose a storage option, and choose |
| 135 | +a default value for attributes, commands and events for Endpoint 1. |
| 136 | + |
| 137 | + |
| 138 | + |
| 139 | +<br> |
| 140 | + |
| 141 | +## Commands |
| 142 | + |
| 143 | +Commands can be enabled/disabled like attributes. Some commands are required for |
| 144 | +an application to function properly. Many of the functions run when a command is |
| 145 | +received are implemented on the server side. But some of these are left up to |
| 146 | +the application to define. In the EFR32 lock example, the set/get user and |
| 147 | +credential functions are customizable as each implementation of a lock might |
| 148 | +store these differently. |
| 149 | + |
| 150 | + |
| 151 | + |
| 152 | +<br> |
| 153 | + |
| 154 | +## Generation of Code |
| 155 | + |
| 156 | +Once desirable cluster options are chosen for an application, one must save the |
| 157 | +current zap configuration using the application menu in the upper left corner. |
| 158 | +Then click generate in the top menu bar. The user will be prompted to choose a |
| 159 | +save location for the generated ZAP code. In the Silicon Labs Matter repository, |
| 160 | +the lock-app generated files belong in |
| 161 | +matter/zzz_generated/lock-app/zap-generated . |
0 commit comments