Trident IoT Zigbee SDK
 
Loading...
Searching...
No Matches
ZAP User Guide

Table of Contents

Back to Trident IoT SDK

Overview

The ZCL Advanced Platform (ZAP) tool is an open source ZCL configuration interface that provides users with an easy way to create, modify, and generate ZCL configurations for a device.

Setup

In the current iteration of the Trident development tools, ZAP must be installed from the project chip open source repository and added to the elcap configuration. ZAP version 2025.01.15 has been tested against and is what the Trident tools expect to be installed. Once ZAP has been installed and added to the elcap configuration, it an be invoked using the command line from within a Trident Zigbee project.

Installation Instructions

Note
This assumes that elcap has already been installed. See elcap documentation page for installation instructions.
  1. Download ZAP v2025.01.15 from: https://github.com/project-chip/zap/releases/tag/v2025.01.15
  2. Install ZAP for your OS
    • for Linux use the .deb or .rpm installer to install it on your machine
    • for MacOS uncompress the downloaded .zip file and move zap.app to the location of your choice such as /Applications
    • for Windows unzip the downloaded .zip file where you would like ZAP to live
  3. Add ZAP to the elcap configuration using command: elcap config set tools.zap_path path/to/zap/directory
    • Linux example: elcap config set tools.zap_path /usr/bin
    • Mac example: elcap config set tools.zap_path /Applications/zap-mac-arm64/zap.app/Contents/MacOS
    • Windows example: elcap config set tools.zap_path C:\Users\archb\Programs\zap-win-x64
  4. Verify ZAP has been setup correctly using elcap doctor
    • running elcap doctor from inside a Zigbee project directory will allow it to check the ZAP installation.
    • do this by creating a new Zigbee project using elcap new, then navigate to the newly created project directory and run elcap doctor inside of it.

Troubleshooting

  1. To confirm that ZAP is installed correctly on your machine, run zap.exe --version from the installation location on a Windows machine or zap --version from a Linux or MacOS machine. If this command fails then ZAP is not installed correctly.
  2. The elcap doctor command can be used to check the ZAP configuration within elcap as long as you are inside a Zigbee project directory when you execute the command. A Zigbee project can be created using the elcap new command, then change into the project directory you created and run elcap doctor to check the zap installation. If all looks good, it will look something like this:
    Successful ZAP Check
  3. To dump your current elcap configuration, run command elcap config. Use this to confirm that your ZAP path aligns with what you were expecting.

Invoking ZAP

Invoking ZAP to configure the ZCL portion of a Zigbee project can happen in 2 ways.

Method 1: Terminal Window

ZAP can be invoked using elcap from the command line in a terminal window directly.

  1. Navigate to your zigbee project directory in the terminal of your choosing.
  2. Run command elcap project zap.
  3. Observe ZAP window open.

Method 2: VS Code Run Task

Opening a Trident Zigbee project inside of VS Code enables custom VS Code Tasks to be used for doing things like building a project, flashing it to a device, and opening the ZAP configuration tool.

  1. Open your Trident Zigbee project in VS Code.
  2. Open the command palette using Ctrl+Shift+P on Linux and Windows, or Cmd+Shift+P on MacOS.
  3. Type "Tasks: Run Task" into the command palette and select the "Tasks: Run Task" option.
  4. Observe the [Trident-IoT] tasks appear in the task list.
  5. Select [Trident-IoT] ZAP and press enter.
  6. Observe ZAP window open.

Using ZAP

Once ZAP is open, you can use it to configure everything ZCL for your Zigbee project. This includes adding/removing/configuring:

  • Endpoints
  • ZCL clusters/attributes
  • Supported commands
  • Attribute reporting
  • MFG ID
  • Default response policy
  • Etc.

Adding an Endpoint

To add an endpoint in ZAP, click the "+ Add Endpoint" button on the left of the screen, select the Device Type from the "Device" drop down menu, and click "Create".

Add Endpoint Menu

Adding Clusters

Adding a cluster can be done by selecting the endpoint you wish to modify and check the "Client" or "Server" box next to the cluster.

Adding a Cluster
Note
The OTA Bootloading Cluster MUST not exist on multiple endpoints!

Adding Attributes

Adding/modifying attribute configurations can be done by selecting the gear icon next to an enabled cluster. Once inside the cluster menu, enable attributes by activating the "Enabled" option next to the attribute of choice. The default value for the attribute can be entered on the right hand side of the screen. Attribute storage can be selected as RAM, NVM, or external. To handle external attributes please see tr_zcl_external_attribute_read_cb.

Adding an Attribute

Attribute Reporting Configurations

Default attribute reporting configurations can be modified from the "Attribute Reporting" tab within the cluster configuration page. Reporting options are configurable for any enabled attributes.

Default Attribute Reporting Configurations

Adding Commands

Incoming and outgoing commands can be enabled by navigating to the "Commands" tab within the cluster configuration page and checking the box next to which command(s) you would like to support.

Adding Commands
Note
The supported commands must be the same for each cluster that is shared across multiple endpoints

Global Options

Global options can be conifgured to set things like the product manufacturer ID and the default response policy. This is done by clicking the "Options" menu at the top of the screen and making the desired selections.

Global Options

Generating Project Outputs

The current implementation of ZAP in the Trident ecosystem requires a manual generation step where you must naviage to the directory in which the generated ZAP files should live. This will be solved in future releases and will only need to be dealt with during the Beta release phase.
Once ZCL configuration changes have been made, generate the resulting files into your project by:

  1. Saving your new ZAP configuration using "Ctrl+S".
  2. Click the generate button at the top of the ZAP UI.
    ZAP Generate Button
  3. Navigate to the "generated" directory inside your project
    Setting path to generated directory for a bulb project
  4. Click generate.

Once the files have been generated into your Zigbee project, you can rebuild the project and the changes will have taken place.

Note
Adding a ZCL cluster will add the cluster to the descriptor for the device but does not automatically add functionality. To add ZCL functionality for a cluster please reference the Plugin Configuration Guide.