Silicon Labs documentation on Silicon Labs ZAP version 1.2.0. Documentation source: https://docs.silabs.com/zap-tool/1.2.0 # Silicon Labs ZAP ## ZAP ZAP is a generic code generation engine and user interface for applications and libraries based on the Zigbee Cluster Library from Zigbee or the Data Model from Matter. The specification is developed by the [Connectivity Standards Alliance](https://csa-iot.org). ZAP allows you to perform the following operations: - Perform SDK-specific customized generation of all global artifacts (constants, types, IDs, and so on) based on the ZCL/Data-Model specification. - Perform SDK-specific customized generation of all user-selected configuration artifacts (application configuration, endpoint configuration, and so on) based on ZCL/Data-Model specification and customer-provided application configuration. - Provide UI for the end-user to select a specific application configuration (endpoints, clusters, attributes, commands, and so on). ![ZAP Summary](/zap-start/0.1/images/silicon-labs-zap.png) The content in these sections describes how to develop Zigbee and Matter applications by configuring the ZCL (Zigbee) or Data Model (Matter) Layers using ZAP. ## ZCL/Data-Model (ZAP) Version v2026.06.17 (Jun 22, 2026) Release Notes Zigbee Cluster Configurator (ZAP) is a code generation tool and configuration UI for applications based on the Zigbee Cluster Library (ZCL) and the Matter data model. It generates application code and configuration artifacts from project-defined endpoints, clusters, attributes, and commands. ### Release Summary This release adds enhanced configuration validation, improved Matter data model support, ARM64 platform support, and significant generation performance improvements. It also includes usability improvements, Electron 41 support, and several stability and validation fixes. #### Key Features - Added comprehensive `.zap` file validation in the UI, CLI, and REST API. - Added ARM64 support for Linux and Windows. - Added an **Open All** option to expand all UI sections. - Added Matter support for fabric-sensitive attributes. - Improved template generation performance through parallel processing. - Added new template helpers for Matter feature bitmap handling. #### Bug Fixes - Fixed feature toggle issues for descriptor-based features. - Fixed NVM attribute ordering inconsistencies. - Fixed SQL trigger error reporting in the UI. - Fixed multiple validation issues, including endpoint, storage, floating-point attributes, and IEEE hexadecimal handling. - Fixed stale cluster warnings that could remain after successful component installation. - Improved reliability of template rendering for large and complex projects. #### Removed or Deprecated Features - None. #### Known Issues and Limitation - No new known issues identified in this release. ## Getting Started ### ZAP Getting Started #### Getting Started with ZAP These sections describe different methods to create Zigbee and Matter applications. Note that Simplicity Studio provides a way to create your Zigbee and Matter applications from end to end where all tools come pre-installed along with Simplicity Studio (including ZAP). You may also decide to explore other ways of creating your applications, as described here. ##### Zigbee Development Zigbee application developers can build their applications using [Simplicity Studio](https://docs.silabs.com/zigbee/latest/zigbee-getting-started-overview/), which already includes ZAP and other tools that help you build your application from end to end. ##### Matter Development Matter Application developers can build their applications using the following methods: - [Simplicity Studio](https://docs.silabs.com/matter/2.1.1/matter-overview/): This includes ZAP and other tools which are needed to build the Matter application end to end. - [Github (Silicon Labs)](https://siliconlabs.github.io/matter/latest/) - [Github (CSA)](https://github.com/project-chip/connectedhomeip) Note: To update ZAP outside the Simplicity Studio release cycle, see [update ZAP in Simplicity Studio](zap-users-guide-update-zap) and [ZAP Installation Guide](zap-installation) #### ZAP Installation The following sections describe ZAP installation and how to update ZAP in Simplicity Studio IDE. ##### Downloading the ZAP Executable (Recommended) This is the recommended way of getting started with ZAP. You can get the latest ZAP binaries from [https://github.com/project-chip/zap/releases](https://github.com/project-chip/zap/releases). Prebuilt binaries come in two different versions. - Official release: Verified builds with dedicated Matter and Zigbee test suites. The release name format is vYYYY.DD.MM. - Pre-release: Builds with the latest features and bug fixes but these builds are NOT verified with dedicated Matter and Zigbee test suites. The release name format is vYYYY.DD.MM-nightly. ##### Installing ZAP from Source ###### Basic instructions to Install ZAP Because this is a node.js application, you need the node environment installed. The best way to do this is download the latest install of [node](https://nodejs.org/en/download/), which includes node and npm. If you have an older version of node installed on your workstation, it may cause issues, particularly if it's very old. Make sure you have the latest node v16.x version with the npm that's included. Run `node --version` to check which version is picked up. v18.x is recommended. After you have a desired version of node, you can run the following: ###### Install the Dependencies (heading level 7) Use the following commands to install dependencies: ```bash npm install ``` Note: For Windows-specific ZAP installation, see [ZAP Installation for Windows OS](zap-installation-windows) It is not uncommon to run into native library compilation problems at this point. There are various `src-script/install-*` scripts for different platforms. See [FAQ](faq) information about which script to run on different platforms and then rerun `npm install`. ###### Start the Application (heading level 7) Use the following commands to start up the application: ```bash npm run zap ``` ###### Start the Front-End in Development Mode (heading level 7) Supports hot-code reloading, error reporting, and so on. Use the following commands to start the front-end in development mode: ```bash quasar dev -m electron ``` or ```bash npm run electron-dev ``` #### ZAP Installation for Windows OS ##### 1. Windows Powershell In the desktop search bar, input `Windows Powershell` and run as administrator. Run all the following commands inside Powershell. ##### 2. Chocolatey Install from [https://chocolatey.org/install](https://chocolatey.org/install). Check if installed properly with the following commands: ```bash choco -v ``` Install pkgconfiglite package with the following commands: ```bash choco install pkgconfiglite ``` ##### 3. Install Node Run the following commands to install: ```bash choco install nodejs-lts ``` *The version has to be 18 to pass version check test, after install, check with `node -v` *If you have installed Node already, and fail some tests similar to `cannot find Node`, reinstall Node with chocolatey again. ##### 4. Follow the Basic Instructions to Install ZAP Follow the ZAP installation instructions from source in [ZAP Installation](zap-installation). While following the basic instructions for installing ZAP watch out for the following errors and how to resolve them: ###### sqlite3 When running ZAP (e.g., `npm run zap`), if you see an error about `sqlite3.node` in a pop up window, run: ```bash npm rebuild sqlite3 ``` ###### electron-builder When doing npm install, in post-install, if an error occurs on the following command related to `electron-builder install-app-deps`, `npx electron-rebuild canvas failed` or `node-pre-gyp`, the current `canvas` version is not compatible with Windows and the installation error will not cause a failure in running ZAP. node-canvas is working on the solution now and the issue will be solved in the near future. ```bash "postinstall": "electron-builder install-app-deps && husky install && npm rebuild canvas --update-binary && npm run version-stamp" ``` ###### Canvas If `npm run test` fails because of the error `Test suite failed to run. Cannot find module '../build/Release/canvas.node'` or `\zap\node_modules\canvas\build\Release\canvas.node is not a valid Win32 application.`, rebuild canvas as follows: ```bash npm rebuild canvas --update-binary ``` ###### get index.html or Other Server Issues If `npm run test` fails because of the error `get index.html request failed with status code 404` in unit tests or having server connection issues in e2e-ci tests, run the following commands: ```bash npm run build ``` ###### Other Check if the node version is v18 and try to install it with Chocolatey. #### Frequently Asked Questions **Q: How to start up UI in a development mode?** **A:** You can start the UI in a development mode, which will result in a following setup: - Separate quasar development HTTP server, which does live refresh on port 8080 - ZAP back end running on port 9070 - Chrome or other browser, running independently To get to that setup, follow the instructions below. 1. First, run the ZAP development server, which starts on port 9070. ```bash npm run zap-devserver ``` 2. Next, run the quasar development server, which starts on port 8080. ```bash quasar dev ``` 3. Point your browser or run one against the proper URL with the `restPort` argument: ```bash google-chrome http://localhost:8080/?restPort=9070 ``` --- **Q: How to make this work on Mac/Linux OS?** **A:** `npm install` is used to download all required dependency packages. If you see errors related to `node-gyp` and missing local libraries, like `pixman`, and so on, you are missing native dependencies to satisfy to compile non-prebuilt node binaries for some combination of platforms and versions. Npm on the cloud is constantly updating the list of provided binaries, so it's possible that you will pick them up just fine, but if you don't, these are instructions for different platforms: **Fedora Core** with `dnf`: ```bash dnf install pixman-devel cairo-devel pango-devel libjpeg-devel giflib-devel ``` or run script: ```bash src-script/install-packages-fedora ``` **Ubuntu** with `apt-get`: ```bash apt-get update apt-get install --fix-missing libpixman-1-dev libcairo-dev libsdl-pango-dev libjpeg-dev libgif-dev ``` or run script: ```bash src-script/install-packages-ubuntu ``` **OSX on a Mac** with Homebrew `brew`: ```bash brew install pkg-config cairo pango libpng jpeg giflib librsvg ``` or run script: ```bash src-script/install-packages-osx ``` --- **Q: How to make this work on Windows OS?** **A:** Make sure it's always up to date and there are no changes that haven't been committed. Tip: git pull, git status & git stash are your friends. You must use Chocolately to make Zap work on Windows OS. Make sure to download the pkgconfiglite package. ```bash choco install pkgconfiglite ``` If you have issues with cairo, for example if you get an error about cairo.h': No such file or directory, do the following: 1. Check if your computer is 32 or 64 bit. 2. Depending on that, download the appropriate package from this site [https://github.com/benjamind/delarre.docpad/blob/master/src/documents/posts/installing-node-canvas-for-windows.html.md](https://github.com/benjamind/delarre.docpad/blob/master/src/documents/posts/installing-node-canvas-for-windows.html.md). 3. Create a folder on your C drive called GTK if it doesn't already exist. 4. Unzip the downloaded content into C:/GTK. 5. Copy all the dll files from C:/GTK/bin to your node_modules/canvas/build/Release folder in your zap folder. 6. Add C:/GTK to the path Environment Variable by going to System in the Control Panel and doing the following: - Click on Advanced System Settings. - In the advanced tab click on Environment Variables. - In the section System Variables, find the PATH environment variable and select it. - Click Edit and add C:/GTK to it. - If the PATH environment variable does not exist, click New. If jpeglib.h is not found, try the following: 1. On the terminal, run: choco install libjpeg-turbo 2. Make sure it's clean by using: git clean -dxff and run npm install again 3. if no errors occur and only warnings appear, try to use npm audit fix 4. if you can't run ZAP, go to file src-script/zap-start.js 5. Change 6. `const { spawn } = require('cross-spawn')` to `const { spawn } = require('child_process')` 7. Run npm and run zap. References: - [https://github.com/fabricjs/fabric.js/issues/3611](https://github.com/fabricjs/fabric.js/issues/3611) - [https://github.com/benjamind/delarre.docpad/blob/master/src/documents/posts/installing-node-canvas-for-windows.html.md](https://github.com/benjamind/delarre.docpad/blob/master/src/documents/posts/installing-node-canvas-for-windows.html.md) - [[https://chocolatey.org/packages/libjpeg-turbo#dependencies](](https://chocolatey.org/packages/libjpeg-turbo#dependencies]()[https://chocolatey.org/packages/libjpeg-turbo#dependencies](https://chocolatey.org/packages/libjpeg-turbo#dependencies)) --- **Q: I get an error "sqlite3_node" not found or similar.** **A:** Rebuild your native sqlite3 bindings. To fix this in most cases, run: - `npm install` - `./node_modules/.bin/electron-rebuild -w sqlite3 -p` If it still doesn't get fixed, do: - `rm -rf node_modules` and then try the above commands again. Occasionally upgrading your `npm` also makes a difference: - `npm install -g npm` --- **Q: I get an error "The N-API version of this Node instance is 1. This module supports N-API version(s) 3. This Node instance cannot run this module."** **A:** Upgrade your node version. The solution for this is discussed in this Stack Overflow thread: [https://stackoverflow.com/questions/60620327/the-n-api-version-of-this-node-instance-is-1-this-module-supports-n-api-version](https://stackoverflow.com/questions/60620327/the-n-api-version-of-this-node-instance-is-1-this-module-supports-n-api-version) --- **Q: My development PC doesn't work with ZAP for whatever reason. Can I use a docker container?** **A:** Yes you can. TBD. --- **Q: How do I run ZAP inside VSCode?** **A:** If you VSCode in your path enter the `zap` repo and type `code .` This will open ZAP in VSCode. To run ZAP in debug mode, select the ZAP workspace and click on the `Run` icon on the left hand toolbar. You will have a couple of options to choose from to run ZAP, choose `Node.js Debug Terminal`. This will open a terminal window from which you can enter `npm run zap`, which will attach the debugger and run ZAP as you would normally from the command line. Congratulations, you should now see ZAP running in the debugger. You can set breakpoints in VSCode as you would in any other IDE. --- **Q: UI unit test fails with some errors around canvas not build for the right version of node. What do I do?** **A:** If you see the following error: ```bash FAIL test/ui.test.js ● Test suite failed to run The module 'canvas.node' was compiled against a different Node.js version using NODE_MODULE_VERSION 80. This version of Node.js requires NODE_MODULE_VERSION 72. Please try re-compiling or re-installing the module (for instance, using `npm rebuild` or `npm install`). at Object. (node_modules/canvas/lib/bindings.js:3:18) ``` then run: `npm rebuild canvas --update-binary` ## Fundamentals ### ZCL/Data-Model (ZAP) Fundamentals This section contains information for new ZAP users. - Click on the tutorial icon on the top right corner of the ZAP UI, which shows how to create a ZAP configuration. The tutorial will guide you through the following: - Create an endpoint - Select a device type - Configure a cluster - Configure an attribute - Configure a command - For detailed reference, see [Zigbee Cluster Configurator Guide](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-developing-with-project-configurator/zigbee-cluster-configurator) ## User's Guide ### ZAP User's Guide #### ZAP User's Guide The sections under this guide provide more details about the different features provided by ZAP. #### Custom XML ##### Adding Custom XML from the ZAP UI - Click on "Extensions" icon in the ZAP UI. - Click on the "+" add button to select a custom xml file - The custom clusters, attributes, commands, etc should show up in the ZAP UI once the custom xml has been added. ##### Creating your own custom XML in Zigbee The section shows how to create your own custom clusters and extend existing standard clusters with custom attributes and commands for Zigbee. ###### Manufacturer-Specific Clusters in Zigbee You can add manufacturer-specific clusters to a standard profile. We provide an example of this below. In order to do this you must satisfy two obligations: - The cluster ID MUST be in the manufacturer-specific range, 0xfc00 - 0xffff. - The cluster definition must include a manufacturer code which will be applied to ALL attributes and commands within that cluster and must be provided when sending and receiving commands and interacting with attributes. - Example: ```xml Sample Mfg Specific Cluster General This cluster provides an example of how the Application Framework can be extended to include manufacturer-specific clusters. 0xFC00 ember sample attribute ember sample attribute 2 A sample manufacturer-specific command within the sample manufacturer-specific cluster. ``` ###### Manufacturer-Specific Commands in Standard Zigbee Cluster You can add your own commands to any standard Zigbee cluster with the following requirements: - Your manufacturer-specific commands may use any command id within the command id range, 0x00 - 0xff. - You must also provide a manufacturer code for the command so that it can be distinguished from other commands in the cluster and handled appropriately. - Example of extending the On/Off cluster with manufacturing commands: ```xml Client command that turns the device off with a transition given by the transition time in the Ember Sample transition time attribute. Client command that turns the device on with a transition given by the transition time in the Ember Sample transition time attribute. Client command that toggles the device with a transition given by the transition time in the Ember Sample transition time attribute. Client command that turns the device on with a transition given by the transition time in the Ember Sample transition time attribute. Client command that toggles the device with a transition given by the transition time in the Ember Sample transition time attribute. ``` ###### Manufacturer-Specific Attributes in Standard Zigbee Cluster You can add your own attributes to any standard Zigbee cluster with the following requirements: - Your manufacturer-specific attributes may use any attribute id within the attribute id range, 0x0000 - 0xffff. - You must also provide a manufacturer code for the attribute so that it can be distinguished from other attributes in the cluster and handled appropriately. - Example of extending the On/Off cluster with manufacturing attributes: ```xml Sample Mfg Specific Attribute: 0x0000 0x1002 Sample Mfg Specific Attribute: 0x0000 0x1049 Sample Mfg Specific Attribute: 0x0001 0x1002 Sample Mfg Specific Attribute: 0x0001 0x1040 ``` ##### Creating your own custom XML in Matter The section shows how to create your own custom clusters and extend existing standard clusters with custom attributes and commands for Matter. ###### Manufacturer-Specific Clusters in Matter You can add manufacturer-specific clusters to in Matter. We provide an example of this below. - The `` is a 32-bit combination of the manufacturer code and the id for the cluster. (**required**) - The most significant 16 bits are the manufacturer code. The range for test manufacturer codes is 0xFFF1 - 0xFFF4. - The least significant 16 bits are the cluster id. The range for manufacturer-specific clusters are: 0xFC00 - 0xFFFE. - In the following example, the combination of the vendor ID (Test Manufacturer ID) of 0xFFF1 and the cluster ID of 0xFC20 results in a `` value of 0xFFF1FC20. - The commands and attributes within this cluster will adopt the same Manufacturer ID. - Example: ```xml General Sample MEI 0xFFF1FC20 SAMPLE_MEI_CLUSTER The Sample MEI cluster showcases a cluster manufacturer extensions FlipFlop Response for AddArguments that returns the sum. Command that takes two uint8 arguments and returns their sum. Simple command without any parameters and without a response. ``` ###### Manufacturer-Specific Attributes in Standard Matter Clusters You can add manufacturer specific attributes to any standard Matter cluster with the following requirements: - The cluster that the attributes are being added to must be specified - `` - The `code` of the attribute is a 32-bit combination of the manufacturer code and the id for the attribute. - The most significant 16 bits are the manufacturer code. The range for test manufacturer codes is 0xFFF1 - 0xFFF4. - The least significant 16 bits are the attribute ID. The range for non-global attributes is 0x0000 - 0x4FFF. - Example of extending On/Off Matter cluster with manufacture-specific attributes: ```xml Sample Mfg Specific Attribute 2 Sample Mfg Specific Attribute 4 ``` ###### Manufacturer-Specific Commands in Standard Matter Clusters You can add manufacturer specific commands to any standard Matter cluster with the following requirements: - The cluster that the commands are being added to must be specified - `` - The `code` of the command is a 32-bit combination of the manufacturer code and the id for the command. - The most significant 16 bits are the manufacturer code. The range for test manufacturer codes is 0xFFF1 - 0xFFF4. - The least significant 16 bits are the command ID. The range for non-global commands is 0x0000 - 0x00FF. - Example of extending On/Off Matter cluster with manufacture-specific clusters: ```xml Client command that turns the device on with a transition given by the transition time in the Ember Sample transition time attribute. Client command that toggles the device with a transition given by the transition time in the Ember Sample transition time attribute. ``` #### Custom XML Tags for Zigbee The following document talks about each of the xml tags associated with Zigbee. - Each xml file is listed between the `configurator` tags: ```xml ``` - Data types can be defined within the `configurator` tag. Zigbee currently supports the definition of bitmaps, enums, integers, strings or structs. Before defining more types make sure to check all the existing atomic types defined in types.xml and all the non-atomic types defined in the other xml files. You may define them as follows: - Bitmap: - name: name of bitmap type. - type: Bitmap with a size between 8-64 bits can be defined, all of which should be multiples of 8. - Each bitmap can have multiple fields with a name and a mask associated with it. - eg: ```xml ``` ``` - Enum: - name: name of enum type. - type: Enum with a size between 8-64 bits can be defined, all of which should be multiples of 8. - Each enum can have multiple items with a name and a value associated with it. - eg: ```xml ``` - Integer: - Integer types are already defined under atomic types which exist in types.xml. Their size can range from 8-64 bits and can be signed or unsigned. - eg: ```xml ``` - String: - String types are already defined under atomic types which exist in types.xml. Current string types include octet string, char string, long octet string and long char string - eg: ```xml ``` - Struct: - name: name of struct type. - Each struct can have multiple items with a name and a type associated with it. The type can be any predefined types under data types. - eg: ```xml ``` - Custom Clusters can be defined within the `configurator` tag. - name: name of the cluster - domain: domain of the cluster. The cluster will show up in the ZAP UI under this domain. - description: Descirption of the cluster - code: cluster code - define: cluster define which is used by code generator to define the cluster in a certain way - manufacturerCode: Used to define a manufacturing specific cluster. This has to be between 0xfc00 - 0xffff. The manufacturer code for the cluster needs to be defined as follows: ```xml ``` - A manufacturing cluster automatically makes the attributes and commands under it of the same manufacturer code unless they explicitly list the manufacturer code. - introducedIn: Used to determine the spec version in which the cluster was introduced. This is used by code generator to add additional logic. - removedIn: Used to determine the spec version in which the cluster was removed. This is used by code generator to add additional logic. - singleton(boolean): Is used to determine a cluster as a singleton such that there is only one instance of that cluster shared across the endpoints. - attribute: - defines an attribute for the cluster - name: Name of attribute is mentioned between the attribute tag. ```xml attribute name ``` - side(client/server): The side of the cluster to which the attribute is associated too. - code: attribute code - manufacturer code: This can be used to define a manufacturer specific attribute outside the zigbee specification mentioned by the standard xml. - define: attribute define which is used by code generator to define an attribute in a certain way - type: the type of the attribute which can be any of the data types mentioned in the xml - default: default value for the attribute. - min: Minimum allowed value for an attribute - max: Maximum allowed value for an attribute - writable: Is attribute value writable or not. This can be used to prevent the attribute from being modified by write commands. - optional(boolean): Used to determine if an attribute is optional or not for the cluster. - min: Minimum allowed value for an attribute when it is an integer, enum or bitmap type. - max: Maximium allowed value for the attribute when it is an integer, enum or bitmap type - length: Used to specify the maximum length of the attribute when it is of type string. - minLength: Used to specify the minimum length of the attribute when it is of type string. - reportable(boolean): Tells if an attribute is reportable or not - isNullable(boolean): Allows null values for the attribute. - array(boolean): Used to declare an attribute of type array. - introducedIn: Used to determine the spec version in which the attribute was introduced. This is used by code generator to add additional logic. - removedIn: Used to determine the spec version in which the attribute was removed. This is used by code generator to add additional logic. - command: - define a command for a cluster - name: Name of command. ```xml ``` - code: command code - manufacturer code: This can be used to define a manufacturer specific command outside the zigbee specification mentioned by the standard xml. - description: description of the command - source(client/server): source of the command. - optional(boolean): Used to determine if a command is optional or not for the cluster. - introducedIn: Used to determine the spec version in which the command was introduced. This is used by code generator to add additional logic. - removedIn: Used to determine the spec version in which the command was removed. This is used by code generator to add additional logic. - command arguments: - Each command can have a set of command arguments - name: name of the command argument - type: type of the command argument which could be any of the types mentioned in the xml. - min: Minimum allowed value for an argument when it is an integer, enum or bitmap type. - max: Maximium allowed value for an argument when it is an integer, enum or bitmap type - length: Used to specify the maximum allowable length for a command argument when it is of type string. - minLength: Used to specify the minimum allowable length for a command argument when it is of type string. - array(boolean): To determine if the command argument is of type array. - presentIf(string): This can be a conditional string of logical operations based on other command arguments where you can expect the command argument if the conditional string evaluates to true. eg: ```xml ``` Note: Here `status` is another command argument name. - optional(boolean): Used to determine the command argument as optional. - countArg: Used when the command argument is of type array. This is used to mention the other command argument which denotes the size of array for this argument. ```xml ``` - introducedIn: Used to determine the spec version in which the command argument was introduced. This is used by code generator to add additional logic. - removedIn: Used to determine the spec version in which the command argument was removed. This is used by code generator to add additional logic. - Cluster Extension can be defined within the `configurator` tag. - Cluster extension is used to extend a standard cluster with manufacturing attributes and commands - eg ```xml Sample Mfg Specific Attribute: 0x0000 0x1002 Sample Mfg Specific Attribute: 0x0000 0x1049 Sample Mfg Specific Attribute: 0x0001 0x1002 Sample Mfg Specific Attribute: 0x0001 0x1040 Client command that turns the device off with a transition given by the transition time in the Ember Sample transition time attribute. Client command that turns the device on with a transition given by the transition time in the Ember Sample transition time attribute. Client command that toggles the device with a transition given by the transition time in the Ember Sample transition time attribute. Client command that turns the device on with a transition given by the transition time in the Ember Sample transition time attribute. Client command that toggles the device with a transition given by the transition time in the Ember Sample transition time attribute. ``` #### Multiple Device Types Per Endpoint This is a Matter-only feature where a user can select more than one device type per endpoint. The addition of multiple device types will add the cluster configurations within the device types to the endpoint configuration. ![Multiple Device Types Per Endpoint](/zap-users-guide/0.1/images/multiple-device-types-per-endpoint.png) The above image shows that endpoint 1 has more than one device types selected. The "Primary Device" denotes primary device type that the endpoint will be associated with. The primary device type is always present at index 0 of the list of device types selected so selecting a different primary device type will change the ordering of the device types selected. The device type selections also have constraints based on the Data Model Specification. ZAP protects the users from choosing invalid combinations of device types on an endpoint using these constraints. #### Matter Feature Page ZAP supports visualizing and toggling Matter features through two distinct feature pages: the **Device Type Feature Page** and the **Cluster Feature Page**. These pages allow users to view detailed feature information, update the featureMap attribute easily, and automatically apply the correct conformance to all elements related to the updated feature. ##### Device Type versus Cluster Feature Pages The following table introduces both feature pages and highlights their differences.
Device Type Feature Page Cluster Feature Page
Purpose View and toggle all device type features at the endpoint level (across all clusters under a selected endpoint). View and toggle features at the cluster level (for a specific selected cluster).
XML Source Features are loaded from the device type XML (matter-devices.xml) Features are loaded from a cluster XML (*-cluster.xml)
Spec Source Features are defined in the Matter Device Type Specification. Features are defined in the Matter Cluster Specification.
Navigation Steps
  1. Launch ZAP with latest Matter SDK.
  2. Create an endpoint with a Matter device type.
  3. Click the Device Type Features button at the top-middle of the endpoint view.
  1. Launch ZAP with latest Matter SDK.
  2. Create an endpoint with a Matter device type.
  3. Click the Configure button to go to the cluster view.
  4. Open the Features tab.
> **Note that:** > > 1. The **Device Type Feature** button and **Cluster Feature** tab are only visible when ZAP is launched in Matter mode and when conformance data exists in the Matter SDK. > 2. For the same feature under the same cluster and endpoint, any changes are automatically synchronized between the **Device Type** and **Cluster Feature** pages. ###### Visual Examples ![Device Type Feature Page](/zap-users-guide/0.1/images/device-type-feature-page.png) _Device Type Feature page for an endpoint with the Matter Extended Color Light device type._ ![Cluster Feature Page](/zap-users-guide/0.1/images/cluster-feature-page.png) _Cluster Feature page for the Color Control cluster. The value of featureMap is displayed on the top-right._ ##### Conformance Conformance defines optionality and dependency for attributes, commands, events, and data types. It determines whether an element is mandatory, optional, or unsupported under certain ZAP configurations. Device type's feature conformance takes precedence over cluster's feature conformance. For example, the Lighting feature has optional conformance in the On/Off cluster but is declared as mandatory in the On/Off Light device type that includes the On/Off cluster. Creating an endpoint with the On/Off Light device type will show the Lighting feature as mandatory on the feature page. ###### Conformance Expressions To help interpret conformance expressions: 1. Hover over any expression in the Conformance column to view its plain-language translation. 2. Refer to [Matter Conformance Overview](matter-conformance) for more details on conformance expression definitions. ##### Feature Toggling On a feature page, after clicking the toggle button to enable or disable a feature, ZAP will perform the following actions: 1. Display a confirmation dialog summarizing the changes to be applied, allowing users to confirm or cancel the operation. 2. If the user confirms: - Update associated elements (attributes, commands, events) to correct conformance. - Update the corresponding feature bit in the cluster's featureMap attribute. - Display warnings if the change results in invalid or inconsistent conformance. |![Enable Dialog](/zap-users-guide/0.1/images/enable-dialog.png)|![Disable Dialog](/zap-users-guide/0.1/images/disable-dialog.png)| |---|---| |_Enable Feature Dialogue_|_Disable Feature Dialogue_| > **Note:** When toggling a feature causes no element updates, the change is applied immediately without displaying a confirmation dialog. ###### Disabled Feature Toggling Feature toggling is disabled in the following cases: - The feature is deprecated or disallowed. - The feature’s conformance, or the conformance of elements related to the feature, contains unknown values or unsupported formats. - The feature is required by other features. Toggling it would cause the dependent features to fail conformance. See an example in the following image. In these situations, warnings appear in the notification pane with details and suggested resolution steps. ![Disabled Feature Toggle Warning](/zap-users-guide/0.1/images/disabled-toggle-warning.png) In this example, the AUTO feature toggle is disabled because the HEAD and COOL features conform to it. To enable AUTO, the user must first enable HEAD and COOL as instructed in the warning. ##### Element Compliance Warnings When toggling an element, ZAP may display both [device compliance warnings](spec-check) and feature compliance warnings. If the element's state does not match the expected conformance, ZAP will display a warning icon and log the warning in the notification pane. Example of both the device type and feature compliance warnings displayed for an element: ![Element Warnings](/zap-users-guide/0.1/images/element-warning.png) #### Matter Conformance Overview This document introduces the Matter conformance system, which defines the optionality and dependencies of various Matter elements, including features, attributes, commands, events, enumerations, and fields. Conformance may be expressed as a simple tag or a complex logical expression. In ZAP, conformance information appears on the Matter feature page and in conformance-related warnings on relevant elements. ##### 1. Basic Conformance Tags |Conformance|Name|Summary| |---|---|---| |`M`|Mandatory|Required for current revision; always present.| |`O`|Optional|Not required; no dependencies except M elements.| |`P`|Provisional|Provisional for now; future intended conformance is undetermined.| |`D`|Deprecated|No longer valid in current revision; it may occur in legacy versions.| |`X`|Disallowed|Not allowed for the cluster derivation.| |`desc`|Described|Complex conformance that cannot be represented with a logical expression.| ##### 2. Conformance Expressions Conformance expressions define conditional support for elements using Boolean logic. They consist of operands, which may be combined using logical operators to define complex conditions. ###### Operands Supported operands in a conformance expression are: - feature code （for example, `OO` for OnOff feature） - element name (for example, name of attribute, command, or event in the same cluster) If the referenced feature or element is supported or enabled, then the operand evaluates to `TRUE`; otherwise, it evaluates to `FALSE`. ###### Logical Operators |Conformance|Name|Summary| |---|---|---| |`AB & CD`|AND|`TRUE` if both `AB` and `CD` are true.| |`AB | CD`|OR|`TRUE` if either `AB` or `CD` is true.| |`!AB`|NOT|`TRUE` if `AB` is false.| |`(AB & CD)`|Grouping|Use parentheses to group expressions.| ###### Optional Conformance Brackets (`[]`) are used to indicate optional in conformance expressions. If no brackets surround an expression, it is mandatory. - `[AB]` → Optional if `AB` is true; otherwise, it is not supported. - `AB` → Mandatory if `AB` is true; otherwise, it is not supported. ##### 3. Otherwise Conformance Otherwise conformance defines a sequence of conformance expressions, separated by commas (`,`). They are evaluated from left to right, similar to an `if → else if → else` chain: ```pseudo if (first condition is true) apply first conformance else if (second condition is true) apply second conformance ... else not supported ``` ###### Examples - `AB, O` → Mandatory if `AB` is true; otherwise, it is optional. - `AB, [CD]` → Mandatory if `AB` is true; otherwise, it is optional if `CD` is true. If neither expression is true, it is not supported. - `!AB, [CD & EF], D` → Mandatory if `AB` is false; otherwise, it is optional if both `CD` and `EF` are true. If neither expression is true, it is deprecated. ##### 4. Provisional Conformance The tag `P` defines the element as provisional. `P` could be followed by the future intended conformance of the element. ###### Examples - `P` → Provisional now. Future conformance is undetermined. - `P, M`: Provisional now. In the future, the element is mandatory. - `P, [AA & BB]`: Provisional now. In the future, the element is optional if `AA & BB` are true; otherwise, it is not supported. - `[AA], P`: Optional if `AA` is true; otherwise, the element is provisional. Future conformance is undetermined. ##### 5. Additional Conformance Types For conformance types not covered in this document, refer to section `7.3 Conformance` in the Matter Core Specification. #### Notifications The following section defines how notifications are given to ZAP users in the UI. ##### Package Notifications Package notifications are the warnings or error messages associated for any specific package loaded into ZAP. For example, in the images below, clicking the warning icon under the status column will lead you to a dialog showing all notifications for that package. ![Package Notification Config Page](/zap-users-guide/0.1/images/config-page.png) ![Warning Dialog](/zap-users-guide/0.1/images/warning-dialog.png) ![Package Notice Notification page](/zap-users-guide/0.1/images/package-notification.png) ##### Session Notifications Session notifications are the warnings or error messages which are associated with a user session. These warnings/errors can be seen by clicking on the `Notifications` button in the toolbar on top of the ZAP UI. For example, the image below shows the session notifications page after an isc file was loaded into ZAP. ![Display Notification](/zap-users-guide/0.1/images/display-notification.png) #### Data Model and ZCL Specification Compliance This feature in ZAP helps users see compliance failures for Data Model or ZCL with their existing ZAP configurations. The warning messages for compliance failures will appear on the `Notifications` pane in the ZAP UI and will also be logged onto the console when running ZAP through the CLI. The compliance feature currently provides warnings for device type compliance and cluster compliance on an endpoint. ##### Compliance Warnings in the ZAP UI When a user opens a .zap file using the ZAP UI they will see warnings in the notifications pane of the ZAP UI for all the compliance failures. For example, the image below shows the session notifications page after a .zap file was opened with compliance issues. ![Display Compliance Notifications](/zap-users-guide/0.1/images/spec-compliance-warnings.png) The compliance messages will go away once the issues are resolved using the ZAP UI such that you can keep track of only the remaining compliance issues. New warnings will also show up for compliance if user disables mandatory elements(cluster/commands/attributes) of the configuration. Specification compliance notifications will always keep track of any failures that are introduced into the ZAP configuration but note that the warnings which show up during the opening of a .zap file are more elaborate on why it failed compliance when compared to the warnings which show up while interacting with the UI. This is by design and a full compliance check is performed during the opening of a .zap file. ##### Compliance Warnings on the Console When a user opens a .zap file using the ZAP standalone UI or the ZAP CLI they will see warnings logged into the console/terminal for all the compliance failures. For example, the image below shows the session notification warnings on the console/terminal after a .zap file was opened with compliance issues. ![Display Compliance Notifications on Console](/zap-users-guide/0.1/images/spec-compliance-warnings-console.png) #### Access Control Features ZAP supports access control on all ZCL entities. It's down to the implementation of the SDK to map these features to the required and supported access control SDK features. ZAP generally provides a data model and a mechanism to encode it in the meta-info files and propagate that data to the generation templates, without assigning specific meanings to the data points. ##### Base Terms ZAP access control defines three base terms, as follows: 1. **operation** : defined as something that can be done. Example: read, write, invoke. 2. **role**: defined as a privilege of an actor. Such as "View privilege", "Administrative role", and son on. 3. **modifiers**: defined as special access control conditions, such as _fabric sensitive_ data or _fabric scoped_ data. The base terms are defined in the metadata XML under a top tag ``. The following is an example of access control base term definitions: ```xml ``` This example defines three operations, _read_, _write_ and _invoke_, two modifiers and four roles. ##### Access Triplets Each individual access condition can be defined with an access triplet in the XML. Access triplet is a combination of an _operation_, _role_ and _modifier_. They are optional, so you can only have one of these. A missing part of triplet generally means permissivenes, which is implementation-specific for the given SDK. An entity that defines it's access can have one or more access triplets. The following is an example: ```xml at1 ``` This is a definition of an attribute that has an access triplet, declaring it allows _write_ operation by a _manage_ role, with _fabric-scoped_ modifier applied. ##### Default Permissions ZCL entities can define their own individual permissions. However, there is also a global definition of default permissions for given types. These are assumed for the given entity, unless it provides any specific permissions of its own. Default permissions are declared via a `` tag at the top level of the XML file. Example: ```xml ``` ##### Template Helpers The basic template helper to use is the `{{#access}} ... {{/access}}` iterator. This iterator iterates over all given access triplets. It supports the following two options: - `entity="attribute/command/event"` - if the entity can't be determined from context, this sets the entity type. - `includeDefault="true/false"` - determines if default values are included or not. The following is an example: ```xml {{#zcl_clusters}} Cluster: {{name}} [{{code}}] {{#zcl_attributes}} - attribute: {{name}} [{{code}}] {{#access entity="attribute"}} * Op: {{operation}} / Role: {{role}} / Modifier: {{accessModifier}} {{/access}} {{/zcl_attributes}} {{#zcl_commands}} - command: {{name}} [{{code}}] {{#access entity="command"}} * Op: {{operation}} / Role: {{role}} / Modifier: {{accessModifier}} {{/access}} {{/zcl_commands}} {{#zcl_events}} - event: {{name}} [{{code}}] {{#access entity="event"}} * Op: {{operation}} / Role: {{role}} / Modifier: {{accessModifier}} {{/access}} {{/zcl_events}} {{/zcl_clusters}} ``` #### Launching ZAP for Matter or Zigbee Applications The following sections describe launching ZAP in standalone mode with the Matter or Zigbee-specific metadata. The idea is to launch ZAP with the correct arguments related to XML metadata (the clusters and device types definitions as per the CSA specifications) and the generation templates, which are used to generate the appropriate code. ##### Launching ZAP with Matter The following script picks up the correct metadata from the Matter [SDK](https://github.com/project-chip/connectedhomeip) when launching ZAP. [https://github.com/project-chip/connectedhomeip/blob/master/scripts/tools/zap/run_zaptool.sh](https://github.com/project-chip/connectedhomeip/blob/master/scripts/tools/zap/run_zaptool.sh) Note: You can also take to the following Zigbee approach to launch ZAP in Matter. ##### Launching ZAP with Zigbee The following command launches ZAP with the ZCL specifications and generation templates from the [SDK](https://github.com/SiliconLabs/gecko_sdk). `[zap-path] -z [sdk-path]/gsdk/app/zcl/zcl-zap.json -g [sdk-path]/gsdk/protocol/zigbee/app/framework/gen-template/gen-templates.json` - zap-path: This is the path to the ZAP source or executable - sdk-path: This is the path to the SDK ##### Launching ZAP without Metadata Remember that when launching ZAP directly through an executable or from source using `npm run zap` you are launching ZAP with test metadata for Matter/Zigbee built in within ZAP and not the actual metadata coming from the Matter and Zigbee SDKs mentioned above. Therefore, remember to create your ZAP configurations by using the SDK metadata and not by opening ZAP directly with the built in test metadata. #### Generating Code for Matter, Zigbee or a Custom SDK The following sections describe how to generate code using ZAP. ##### Generate Code Using ZAP UI Launch the ZAP UI as per the instructions in Launching ZAP for Matter or Zigbee and click on the Generate button in the top menu bar. ##### Generate Code without the UI The following instructions provide different ways of generating code through CLI without launching the ZAP UI. ###### Generating Code from ZAP Source Run the following command to generate code using ZAP from [source](https://github.com/project-chip/zap): `node src-script/zap-generate.js --genResultFile --stateDirectory ~/.zap/gen -z ./zcl-builtin/silabs/zcl.json -g ./test/gen-template/zigbee/gen-templates.json -i ./test/resource/three-endpoint-device.zap -o ./tmp` ###### Generating Code from ZAP Executable Run the following command to generate code using ZAP [executable](https://github.com/project-chip/zap/releases): `[zap-path] generate --genResultFile --stateDirectory ~/.zap/gen -z ./zcl-builtin/silabs/zcl.json -g ./test/gen-template/zigbee/gen-templates.json -i ./test/resource/three-endpoint-device.zap -o ./tmp` ###### Generating Code from ZAP CLI Executable Run the following command to generate code using ZAP [CLI Executable](https://github.com/project-chip/zap/releases): `[zap-cli-path] generate --genResultFile --stateDirectory ~/.zap/gen -z ./zcl-builtin/silabs/zcl.json -g ./test/gen-template/zigbee/gen-templates.json -i ./test/resource/three-endpoint-device.zap -o ./tmp` #### Update ZAP ##### Update ZAP in Simplicity Studio This mechanism can be used when working with Matter extension or Zigbee from the Silicon Labs SDK releases. ZAP can be updated within Simplicity Studio without a Simplicity Studio release by downloading the latest [ZAP executable (recommended)](https://github.com/project-chip/zap/releases) or pulling the latest from [ZAP source](https://github.com/project-chip/zap) as shown in [ZAP Installation Guide](zap-getting-started-zap-installation). After you have the latest ZAP based on your currently used OS, you can update ZAP within Studio as an adapter pack. Follow the instructions below after downloading the latest ZAP: - Go to Simplicity Studio and select `Preferences > Simplicity Studio > Adapter Packs.` - Click `Add...` and browse to the expanded ZAP folder you downloaded and click `Select Folder`. - Click `Apply and Close` and then the newly-added ZAP will be used whenever a .zap file is opened. Note: Sometimes there might be older instances of ZAP already running even after updating to the latest ZAP. Make sure to end all existing ZAP instances such that the newly fetched ZAP is used instead of an old instance, which is still working in the background. ##### Update ZAP for Matter Development in Github When working with the [Matter](https://github.com/project-chip/zap) or [Matter-Silicon Labs](https://github.com/SiliconLabs/matter) repos on Github, set the environment variables with respect to ZAP to create/generate new ZAP configurations or re-generate existing sample ZAP configurations after applying changes to them. Set the `ZAP_DEVELOPMENT_PATH` to [ZAP from source](https://github.com/project-chip/zap) by pulling the latest or set `ZAP_INSTALLATION_PATH` to [ZAP executable](https://github.com/project-chip/zap/releases) you downloaded last in your local directory. Note that when both `ZAP_DEVELOPMENT_PATH` and `ZAP_INSTALLATION_PATH` are set, `ZAP_DEVELOPMENT_PATH` is used. The following are examples that show the above environment variables in use: - [Launching ZAP using Matter specification](https://github.com/project-chip/connectedhomeip/blob/master/scripts/tools/zap/run_zaptool.sh) - [Regenerating all the sample ZAP configurations for Matter applications](https://github.com/project-chip/connectedhomeip/blob/master/scripts/tools/zap_regen_all.py) **Note:** When using ZAP executables, ensure you are using an official release over a nightly release for more stability. See `Downloading the ZAP Executable` in [ZAP Installation Guide](zap-getting-started-zap-installation) #### Concurrent Multi-protocol between Zigbee and Matter ZAP can be used to configure ZCL (Zigbee) and Data-Model (Matter) configurations in a multi-protocol application for Zigbee and Matter. ZAP allows you to create endpoints for Zigbee and Matter explicitly in the same configuration file. If Zigbee and Matter endpoints are on the same endpoint Identifier (for example, LO Dimmable Light on endpoint Id 1 and Matter Dimmable Light on another instance of endpoint 1), ZAP takes care of syncing the common attributes across the Matter and Zigbee attributes. Make sure that the attributes being synced have the same data type. The common attributes between Zigbee and Matter are established through a file called `multi-protocol.json`. The user can link any two clusters across Zigbee and Matter along with their corresponding attributes using the cluster and attribute codes respectively. This file can be found in `[SDKPath]/app/zcl/multi-protocol.json`. This file has been updated with a certain set of clusters and attributes to begin with, but the user can update this file as required and ZAP will take care of the syncing the attribute configuration across Zigbee and Matter for common endpoint identifiers. You can also find a ZAP tutorial in any Zigbee and Matter multi-protocol application under the tutorials page. This tutorial will guide you through the multi-protocol application creation process. This tutorial is only available when you open an existing multi-protocol application and can be found as shown in the image below: ![CMP Tutorial](/zap-users-guide/0.1/images/cmp-tutorial.png) #### Integrate SLC CLI with ZAP Follow these steps to integrate the SLC CLI with ZAP: 1. Install SLC CLI by following the installation instructions in the [Simplicity Studio 5 User Guide](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-tools-slc-cli/02-installation). 2. Install ZAP by following the instructions in the [ZAP Installation Guide](../zap-getting-started/zap-installation). 3. To integrate SLC CLI with ZAP, add an environment variable `STUDIO_ADAPTER_PACK_PATH` that points to the ZAP application directory. 4. Remember to restart SLC CLI Daemon after step 3. 5. Any project that uses ZAP will now use the path defined in step 3 when generated from SLC CLI. Please refer to [SLC CLI Usage](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-tools-slc-cli/03-usage) for instructions on using SLC CLI for your projects.