A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from https://docs.espressif.com/projects/esp-matter/en/latest/esp32/developing.html below:

Website Navigation


2. Developing with the SDK - ESP32

2. Developing with the SDK

Please refer the Release Notes to know more about the releases

2.1 ESP-IDF Setup

This section talks about setting up ESP-IDF.

2.1.1 Host Setup

You should install drivers and support packages for your development host. Linux and Mac OS-X are the supported development hosts in Matter, the recommended host versions:

Additionally, we also support developing on Windows Host using WSL.

2.1.1.1 Windows 10

Development on Windows is supported using Windows Subsystem for Linux (WSL). Please follow the below instructions to set up host.

For using CHIP tool on WSL, please check Using CHIP-tool in WSL.

For using VSCode for development, please check Developing in WSL.

2.1.2 Getting the Repository

The Prerequisites for ESP-IDF:

Note

git clone command accepts the optional argument --jobs N, which can significantly speed up the process by parallelizing submodule cloning. Consider using this option when cloning repositories.

Cloning esp-idf:

git clone --recursive https://github.com/espressif/esp-idf.git
cd esp-idf; git checkout v5.4.1; git submodule update --init --recursive;
./install.sh
cd ..
2.1.3 Configuring the Environment

This should be done each time a new terminal is opened

cd esp-idf; source ./export.sh; cd ..
2.2 ESP Matter Setup

There are two options to setup esp-matter, you can select one according to demand:

2.2.1 ESP-Matter Repository 2.2.1.1 Getting the Repository

The Prerequisites for Matter:

Cloning the esp-matter repository takes a while due to a lot of submodules in the upstream connectedhomeip, so if you want to do a shallow clone use the following command:

Note

The modules for platform linux or darwin are required for the host tools building.

Note

If you don’t want to install host tools (chip-tool, chip-cert etc.) you can use ./install.sh --no-host-tool.

To clone the esp-matter repository with all the submodules, use the following command:

cd esp-idf
source ./export.sh
cd ..

git clone --recursive https://github.com/espressif/esp-matter.git
cd esp-matter
./install.sh
cd ..

Note

If it runs into some errors like:

dial tcp 108.160.167.174:443: connect: connection refused

ConnectionResetError: [Errno 104] Connection reset by peer

It’s probably caused by some network connectivity issue, a VPN is required for most of the cases.

2.2.1.2 Configuring the Environment

This should be done each time a new terminal is opened

cd esp-idf; source ./export.sh; cd ..
cd esp-matter; source ./export.sh; cd ..

Enable Ccache for faster IDF builds.

Ccache is a compiler cache. Matter builds are very slow and takes a lot of time. Ccache caches the previous compilations and speeds up recompilation in subsequent builds.

export IDF_CCACHE_ENABLE=1

Above can also be added to your shell’s profile file (.profile, .bashrc, .zprofile, etc.) to enable ccache every time you open a new terminal.

2.2.2 ESP Matter Component (experimental)

You can check the component in Espressif Component Registry.

To add the esp_matter component to your project, run:

idf.py add-dependency "espressif/esp_matter^1.4.0"

An example with esp_matter component is offered:

Note

To use this component, the version of IDF component management should be 1.4.* or >= 2.0. Use compote version to show the version. Use pip install 'idf-component-manager~=1.4.0' or pip install 'idf-component-manager~=2.0.0' to install.

2.2.3 Building Applications 2.2.4 Flashing the Firmware

Choose IDF target.

(When flashing the SDK for the first time, it is recommended to do idf.py erase_flash to wipe out entire flash and start out fresh.)

Note

If you are getting build errors like:

ERROR: This script was called from a virtual environment, can not create a virtual environment again

It can be fixed by running below command:

pip install -r $IDF_PATH/requirements.txt
2.3 Commissioning and Control

There are a few implementations of Matter commissioners present in the connectedhomeip repository.

CHIP Tool is an example implementation of Matter commissioner and used for development purposes. An in-depth guide on how to use chip-tool can be found in the CHIP Tool User Guide.

Espressif’s ESP RainMaker iOS and Android applications support commissioning and control of Matter devices.

2.3.1 Test Setup (CHIP Tool)

A host-based chip-tool can be used as a commissioner to commission and control a Matter device. During the previous install.sh step, the chip-tool is generated under the folder:

${ESP_MATTER_PATH}/connectedhomeip/connectedhomeip/out/host

Note

macOS Users: To use chip-tool with BLE commissioning on macOS, you must install the Bluetooth Central Matter Client Developer Mode Profile. It enables Matter commissioning, and may require periodic re-installation.

Instructions to download the profile can be found in the profile installation section

2.3.1.1 Commissioning

Use chip-tool in interactive mode to commission the device:

chip-tool interactive start

pairing ble-wifi 0x7283 <ssid> <passphrase> 20202021 3840

In the above commands:

Above method commissions the device using setup passcode and discriminator. Device can also be commissioned using manual pairing code or QR code.

To Commission the device using manual pairing code 34970112332

pairing code-wifi 0x7283 <ssid> <passphrase> 34970112332

Above default manual pairing code contains following values:

Version:             0
Custom flow:         0      (STANDARD)
Discriminator:       3840
Passcode:            20202021

To commission the device using QR code MT:Y.K9042C00KA0648G00

pairing code-wifi 0x7283 <ssid> <passphrase> MT:Y.K9042C00KA0648G00

Above QR Code contains the below default values:

Version:             0
Vendor ID:           65521    (0xFFF1)
ProductID:           32768    (0x8000)
Custom flow:         0        (STANDARD)
Discovery Bitmask:   0x02     (BLE)
Long discriminator:  3840     (0xf00)
Passcode:            20202021

Alternatively, you can scan the below QR code image using Matter commissioners.

If QR code is not visible, paste the below link into the browser and scan the QR code.

https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT:Y.K9042C00KA0648G00

If you want to use different values for commissioning the device, please use the esp-matter-mfg-tool to generate the factory partition which has to be flashed on the device. It also generates the new pairing code and QR code image using which you can commission the device.

2.3.1.2 Post Commissioning Setup

The device would need additional configuration depending on the example, for it to work. Check the “Post Commissioning Setup” section in examples for more information.

2.3.1.3 Cluster Control

Use the cluster commands to control the attributes.

levelcontrol move-to-level 10 0 0 0 0x7283 0x1

levelcontrol move-to-level 100 0 0 0 0x7283 0x1

colorcontrol move-to-color-temperature 0 10 0 0 0x7283 0x1

chip-tool when used in interactive mode uses CASE resumption as against establishing CASE for cluster control commands. This results into shorter execution times, thereby improving the overall experience.

For more details about the commands, please check chip-tool usage guide

2.4 Device console

The console on the device can be used to run commands for testing. It is configurable through menuconfig and enabled by default in the firmware. Here are some useful commands:

Additional Matter specific commands:

2.5 Developing your Product

Understanding the structure before actually modifying and customising the device is helpful.

2.5.1 Building a Color Temperature Lightbulb

A device is represented in Matter in terms of its data model. As a first step of building your product, you will have to define the data model for your device. Matter has a standard set of device types already defined that you can use. Please refer to the Espressif Matter Blog for clarity on the terms like endpoints, clusters, etc. that are used in this section.

2.5.1.1 Data Model 2.5.1.2 Attribute Callback 2.5.1.3 Device Drivers 2.5.2 Defining your own data model

This section demonstrates creating standard endpoints, clusters, attributes, and commands that are defined in the Matter specification

2.5.2.1 Endpoints

The device can be customized by editing the endpoint/device_type creating in the app_main.cpp of the example. Examples:

2.5.2.2 Clusters

Additional clusters can also be added to an endpoint. Examples:

2.5.2.3 Attributes and Commands

Additional attributes and commands can also be added to a cluster. Examples:

2.5.2.4 Features

Mandatory features for a device type or endpoint can be configured at endpoint level.

Few of some mandatory feature for a cluster (i.e. cluster having O.a/O.a+ feature conformance) can be configured at cluster level. For example: Thermostat cluster has O.a+ conformance for Heating and Cooling features, that means at least one of them should be present on the thermostat cluster while creating it.

Optional features which are applicable to a cluster can also be added.

2.5.3 Adding custom data model fields

This section demonstrates creating custom endpoints, clusters, attributes, and commands that are not defined in the Matter specification and can be specific to the vendor.

2.5.3.1 Endpoints

Non-Standard endpoint can be created, without any clusters.

2.5.3.2 Clusters

Non-Standard/Custom clusters can also be created:

2.5.3.3 Attributes and Commands

Non-Standard/Custom attributes can also be created on any cluster:

2.5.4 Advanced Setup

This section explains adding external platforms for Matter. This step is optional for most devices. Espressif’s SDK for Matter provides support for overriding the default platform layer, so the BLE and Wi-Fi implementations can be customized. Here are the required steps for adding an external platform layer.

2.5.4.1 Creating the external platform directory

Create a directory platform/${NEW_PLATFORM_NAME} in your codebase. You can typically copy ${ESP_MATTER_PATH}/connectedhomeip/connectedhomeip/src/platform/ESP32 as a start. Note that the new platform name should be something other than ESP32. In this article we’ll use ESP32_custom as an example. The directory must be under platform folder to meet the Matter include path conventions.

2.5.4.2 Modifying the BUILD.gn target

There is an example BUILD.gn file for the ESP32_custom example platform. It simply compiles the ESP32 platform in Matter without any modifications.

2.5.4.3 Editing Kconfigs 2.5.4.4 Example Usage

As an example, you can build light example on ESP32_custom platform with following steps:

mkdir $ESP_MATTER_PATH/../platform
cp -r $ESP_MATTER_PATH/connectedhomeip/connectedhomeip/src/platform/ESP32 $ESP_MATTER_PATH/../platform/ESP32_custom
cp $ESP_MATTER_PATH/examples/common/external_platform/BUILD.gn $ESP_MATTER_PATH/../platform/ESP32_custom
cd $ESP_MATTER_PATH/examples/light
cp sdkconfig.defaults.ext_plat sdkconfig.defaults
idf.py build
2.6 Factory Data Providers 2.6.1 Providers Introduction

There are four factory data providers, each with its own implementation, that need to be configured. These providers supply the device with necessary factory data, which is then read by the device according to their respective implementations.

2.6.2 Configuration Options

Different implementations of the four providers can be chosen in meuconfig:

2.6.3 Custom Providers

In order to use custom providers, you need to define implementations of the four base classes of the providers and override the functions within them. And the custom providers should be set before esp_matter::start() is called.

2.7 Using esp_secure_cert partition 2.7.1 Configuration Options

Build the firmware with below configuration options

# Disable the DS Peripheral support
CONFIG_ESP_SECURE_CERT_DS_PERIPHERAL=n

# Use DAC Provider implementation which reads attestation data from secure cert partition
CONFIG_SEC_CERT_DAC_PROVIDER=y

# Enable some options which reads CD and other basic info from the factory partition
CONFIG_ENABLE_ESP32_FACTORY_DATA_PROVIDER=y
CONFIG_ENABLE_ESP32_DEVICE_INSTANCE_INFO_PROVIDER=y
CONFIG_FACTORY_COMMISSIONABLE_DATA_PROVIDER=y
CONFIG_FACTORY_DEVICE_INSTANCE_INFO_PROVIDER=y
2.7.2 Certification Declaration

If you do not have an certification declaration file then you can generate the test CD with the help of below mentioned steps. We need to generate the new CD because it SHALL match the VID, PID in DAC and the ones reported by basic cluster.

cd connectedhomeip/connectedhomeip
gn gen out/host
ninja -C build

Generate the Test CD, please make sure to change the -V (vendor_id) and -p (product-id) options based on the ones that are being used. For more info about the arguments, please check chip-cert’s gen-cd command in the connectedhomeip repository.

out/host/chip-cert gen-cd -f 1 -V 0xFFF1 -p 0x8001 -d 0x0016 \
                          -c "CSA00000SWC00000-01" -l 0 -i 0 -n 1 -t 0 \
                          -K credentials/test/certification-declaration/Chip-Test-CD-Signing-Key.pem \
                          -C credentials/test/certification-declaration/Chip-Test-CD-Signing-Cert.pem \
                          -O TEST_CD_FFF1_8001.der
2.7.3 Factory Partition

Factory partition contains basic information like VID, PID, etc.

By default, the CD(Certification Declaration) is stored in the factory partition and we need to add the -cd option when generating the factory partition.

Alternatively, if you’d like to embed the CD in the firmware, you can enable the CONFIG_ENABLE_SET_CERT_DECLARATION_API option and use the SetCertificationDeclaration() API to set the CD. You can refer to the reference implementation in :project_file: light example.

Export the dependent tools path

cd esp-matter
export PATH=$PATH:$PWD/connectedhomeip/connectedhomeip/out/host

Generate the factory partition, please use the APPROPRIATE values for -v (Vendor Id), -p (Product Id), and -cd (Certification Declaration).

esp-matter-mfg-tool --passcode 89674523 \
              --discriminator 2245 \
              -cd TEST_CD_FFF1_8001.der \
              -v 0xFFF1 --vendor-name Espressif \
              -p 0x8001 --product-name Bulb \
              --hw-ver 1 --hw-ver-str DevKit

Few important output lines are mentioned below. Please take a note of onboarding codes, these can be used for commissioning the device.

[2022-12-02 11:18:12,059] [   INFO] - Generated QR code: MT:-24J06PF150QJ850Y10
[2022-12-02 11:18:12,059] [   INFO] - Generated manual code: 20489154736

Factory partition binary will be generated at the below path. Please check for <uuid>.bin file in this directory.

[2022-12-02 11:18:12,381] [   INFO] - Generated output files at: out/fff1_8001/e17c95e1-521e-4979-b90b-04da648e21bb
2.7.4 Flashing firmware, secure cert and factory partition

Flashing secure cert partition. Please check partition table for esp_secure_cert partition address.

Note

Flash only if not flashed on manufacturing line.

esptool.py -p (PORT) write_flash 0xd000 secure_cert_partition.bin

Flashing factory partition, Please check the CONFIG_CHIP_FACTORY_NAMESPACE_PARTITION_LABEL for factory partition label. Then check the partition table for address and flash at that address.

esptool.py -p (PORT) write_flash 0x10000 path/to/partition/generated/using/mfg_tool/uuid.bin

Flash application

2.7.5 Test commissioning using chip-tool

If using the DACs signed by custom PAA that is not present in connectedhomeip repository, then download the PAA certificate, please make sure it is in DER format.

Run the following command from host to commission the device.

./chip-tool pairing ble-wifi 1234 my_SSID my_PASSPHRASE my_PASSCODE my_DISCRIMINATOR --paa-trust-store-path /path/to/PAA-Certificates/
2.8 Matter OTA

Please follow the OTA guide in the connectedhomeip repository for generating a Matter OTA image and performing OTA.

2.8.1 Encrypted Matter OTA

The esp-matter SDK supports using a pre-encrypted application image for OTA upgrades. Please follow the steps below to enable and use encrypted application images for OTA upgrades.

#include <esp_matter_ota.h>

{
    const char *rsa_private_key;    // Please set this to the buffer containing RSA 3072 private key in PEM format
    uint16_t rsa_private_key_len;   // Please set this to the length of RSA 3072 private key

    esp_err_t err = esp_matter_ota_requestor_encrypted_init(rsa_private_key, rsa_private_key_len);
}

Note

There are several ways to store the private key, such as hardcoding it in the firmware, embedding it as a text file, or reading it from the NVS. We have demonstrated the use of the private key by embedding it as a text file in the light example.

2.9 Mode Select

This cluster provides an interface for controlling a characteristic of a device that can be set to one of several predefined values. For example, the light pattern of a disco ball, the mode of a massage chair, or the wash cycle of a laundry machine.

2.9.1 Attribute Supported Modes

This attribute is the list of supported modes that may be selected for the CurrentMode attribute. Each item in this list represents a unique mode as indicated by the Mode field of the ModeOptionStruct. Each entry in this list SHALL have a unique value for the Mode field. ESP_MATTER uses factory partition to set the values of Supported Modes attribute.

2.9.2 Generate Factory Partition Using esp-matter-mfg-tool

Use esp-matter-mfg-tool to generate factory partition of the supported modes attribute.

2.9.2.1 Usage 
esp-matter-mfg-tool -cn "My bulb" -v 0xFFF2 -p 0x8001 --pai \
-k path/to/esp-matter/connectedhomeip/connectedhomeip/credentials/test/attestation/Chip-Test-PAI-FFF2-8001-Key.pem \
-c path/to/esp-matter/connectedhomeip/connectedhomeip/credentials/test/attestation/Chip-Test-PAI-FFF2-8001-Cert.pem \
-cd path/to/esp-matter/connectedhomeip/connectedhomeip/credentials/test/certification-declaration/Chip-Test-CD-FFF2-8001.der \
--supported-modes mode1/label1/endpointId/"value\mfgCode, value\mfgCode"  mode2/label2/endpointId/"value\mfgCode, value\mfgCode"

--supported-modes mode1/label1/endpointId  mode2/label2/endpointId
2.9.3 Build example

For example we want to use mode_select cluster in light example.

Append "${MATTER_SDK_PATH}/examples/platform/esp32/mode-support" to SRC_DIRS and PRIV_INCLUDE_DIRS

#include <static-supported-modes-manager.h>

ModeSelect::StaticSupportedModesManager sStaticSupportedModesManager;
{
    cluster::mode_select::config_t ms_config;
    cluster_t *ms_cluster = cluster::mode_select::create(endpoint, &ms_config, CLUSTER_FLAG_SERVER, ESP_MATTER_NONE_FEATURE_ID);

    sStaticSupportedModesManager.InitEndpointArray(get_count(node));
    ModeSelect::setSupportedModesManager(&sStaticSupportedModesManager);
}
2.10 Matter Controller

This section introduces the Matter controller example. Now this example supports the following features of the standard Matter controller:

2.10.1 Device console

Once you have flashed the controller example onto the device, you can use the device console to commission the device and send commands to the end-device. All of the controller commands begin with the prefix matter esp controller.

2.10.2 Pairing commands

The pairing commands are used for commissioning end-devices and are available when the Enable matter commissioner option is enabled. Here are three standard pairing methods:

For the code pairing method, commissioner tries to discover the end-device only on the IP network. However, when using code-wifi, code-thread, or code-wifi-thread, and id CONFIG_ENABLE_ESP32_BLE_CONTROLLER is enabled, controller tries to discover the end-device on both the IP and BLE networks.

Below are supported commands:

matter esp controller pairing code <node_id> <setup_payload>

matter esp controller pairing code-wifi <node_id> <ssid> <passphrase> <setup_payload>

matter esp controller pairing code-thread <node_id> <operationalDataset> <setup_payload>

matter esp controller pairing code-wifi-thread <node_id> <ssid> <passphrase> <operationalDataset> <setup_payload>
2.10.3 Cluster commands

The invoke-cmd command is used for sending cluster commands to the end-devices. It utilizes a cluster_command class to establish the sessions and send the command packets. The class constructor function could accept two callback inputs:

Note

Here are some examples of the command-data format.

2.10.4 Read commands

The read_command class is used for sending read commands to other end-devices. Its constructor function could accept two callback inputs:

2.10.4.1 Read attribute commands

The read-attr commands are used for sending the commands of reading attributes on end-devices.

Note

2.10.4.2 Read event commands

The read-event commands are used for sending the commands of reading events on end-devices.

2.10.5 Write attribute commands

The write-attr command is used for sending the commands of writing attributes on the end-device.

Note

Here are some examples of the attribute_value format.

For StartUpOnOff attribute of OnOff Cluster, you should use the following JSON structures as the attribute_value to represent the StartUpOnOff 2 and null:

matter esp controller write-attr <node_id> <endpoint_id> 6 0x4003 "{\"0:U8\": 2}"
matter esp controller write-attr <node_id> <endpoint_id> 6 0x4003 "{\"0:NULL\": null}"

For Binding attribute of Binding cluster, you should use the following JSON structure as the attribute_value to represent the binding list [{"node":1, "endpoint":1, "cluster":6}]:

matter esp controller write-attr <node_id> <endpoint_id> 30 0 "{\"0:ARR-OBJ\":[{\"1:U64\":1, \"3:U16\":1, \"4:U32\": 6}]}"

For ACL attribute of AccessControl cluster, you should use the following JSON structure as the attribute_value to represent the AccessControlList [{"privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"privilege": 4, "authMode": 3, "subjects": [1], "targets": null}]:

matter esp controller write-attr <node_id> <endpoint_id> 31 0 "{\"0:ARR-OBJ\":[{\"1:U8\": 5, \"2:U8\": 2, \"3:ARR-U64\": [112233], \"4:NULL\": null}, {\"1:U8\": 4, \"2:U8\": 3, \"3:ARR-U64\": [1], \"4:NULL\": null}]}"

To write multiple attributes in one commands, the attribute_value should be a JSON array. For example, to write the ACL attribute and Binding attribute above, you should use the following JSON structure as the attribute_value:

matter esp controller write-attr <node_id> <endpoint_id1>,<endpoint_id2> 31,30 0,0 "[{\"0:ARR-OBJ\":[{\"1:U8\": 5, \"2:U8\": 2, \"3:ARR-U64\": [112233], \"4:NULL\": null}, {\"1:U8\": 4, \"2:U8\": 3, \"3:ARR-U64\": [1], \"4:NULL\": null}]}, {\"0:ARR-OBJ\":[{\"1:U64\":1, \"3:U16\":1, \"4:U32\": 6}]}]"

For attributes of type uint64_t or int64_t, if the absolute value is greater than (2^53), you should use string to represent number in JSON structure for precision

matter esp controller write-attr <node_id> <endpoint_id> 42 0 "{\"0:ARR-OBJ\":[{\"1:U64\": \"9007199254740993\", \"2:U8\": 0}]}"
2.10.6 Subscribe commands

The subscribe_command class is used for sending subscribe commands to other end-devices. Its constructor function could accept four callback inputs:

2.10.6.1 Subscribe attribute commands

The subs-attr commands are used for sending the commands of subscribing attributes on end-devices.

2.10.6.2 Subscribe event commands

The subs-event commands are used for sending the commands of subscribing events on end-devices.

2.10.7 Group settings commands

The group-settings commands are used to set group information of the controller. They are available when the Enable matter commissioner option is enabled in menuconfig. If the controller wants to send multicast commands to end-devices, it should be in the same group as the end-devices.

2.10.8 Attestation Trust Storage

The controller example offers two options for the Attestation Trust Storage which is used to store and utilize the PAA certificates for the Device Attestation verification. This feature is available when the Enable matter commissioner option is enabled in menuconfig. You can modify this setting in menuconfig Components -> ESP Matter Controller -> Attestation Trust Store

2.11 Custom Cluster

Matter enables users to implement custom clusters for unique features. This section introduces how to add a custom cluster.

2.11.1 Cluster XML Template

Before adding a custom cluster, you should design the attributes, commands, and events it will include, and create the cluster XML template file based on your design.

Example:

<?xml version="1.0"?>
<configurator>
  <domain name="CHIP"/>
  <cluster>
    <domain>General</domain>
    <name>Sample ESP</name>
    <!-- The MSB 16 bits of <code> are the VendorID. Replace this with your
         VendorID. 0x131B is the VendorId of Espressif.
         The LSB 16 bits of <code> are a self-assigned ClusterID -->
    <code>0x131BFC20</code>
    <define>SAMPLE_ESP_CLUSTER</define>
    <description>The Sample ESP cluster showcases a manufacturer custom cluster</description>

    <!-- Attributes -->
    <!-- A simple test boolean attribute -->
    <attribute side="server" code="0x0000" define="SAMPLE_BOOLEAN" type="boolean" writable="true" default="false" optional="false">SampleBoolean</attribute>
    <attribute side="server" code="0x0001" define="SAMPLE_CHAR_STR" type="char_string" writable="false" optional="false">SampleCharStr</attribute>

    <!-- Commands -->
    <command source="client" code="0x00" name="CommandwithoutArgs" optional="false">
      <description>
        Simple command without any parameters and without a response.
      </description>
    </command>

    <command source="client" code="0x01" name="CommandWithArgs" response="CommandWithArgsResponse" optional="false">
      <description>
        Command that takes two uint8 arguments.
      </description>
      <arg name="Arg1" type="int8u"/>
      <arg name="Arg2" type="int8u"/>
    </command>

    <!-- Command Responses -->
    <command source="server" code="0x02" name="CommandWithArgsResponse" optional="false" disableDefaultResponse="true">
      <description>
        Response for CommandwithArgs.
      </description>
      <arg name="ResponseArg" type="int8u"/>
    </command>

    <!-- Events -->
    <event side="server" code="0x0000" name="TestEvent" priority="info" isFabricSensitive="true" optional="false">
      <description>
        Example event with a event data
      </description>
      <field id="1" name="EventData" type="int32u"/>
    </event>
  </cluster>
</configurator>

The example XML file above illustrates a cluster with two attributes, two accepted commands, one generated command(command response), and one event.

After creating the custom cluster XML template file, add the root directory of your template file to the xmlRoot array and the template file name to the xmlFile array in both the zcl configuration file and the zcl test configuration file.

Run zap_regen_all.py in Matter virtual environment to generate common code and client code for the custom cluster.

cd esp_matter/connectedhomeip/connectedhomeip
source ./scripts/activate.sh
./scripts/tools/zap_regen_all.py

The code generation script will create client code for the custom cluster, supporting Android, Darwin, and Python controllers, as well as the chip-tool. It will also generate app-common code for the new custom cluster. The chip-tool can be used to test the custom cluster after recompiling.

2.11.2 Cluster Implementation

The custom cluster should be implemented after the app-common code has been generated.

2.11.2.1 Custom Cluster Attributes

The attributes in a cluster can be managed with the two following methods. A cluster can utilize both the methods to manage its attributes.

2.11.2.2 Custom Cluster Commands

The commands in a cluster can be handled with one of the two following methods. A cluster can only choose one method to handle its commands.

2.11.2.3 Custom Cluster Events

All the events are managed by the EventLogging. If an event is triggered, chip::app::LogEvent() can be called to record it. The event will then be reported to the subscriber that has subscribed to it.

2.11.2.4 Custom Cluster Functions

A custom cluster might requires special funtions to handle initialization, attribute changes, shutdown, and pre-attribute changes. For instance, the AAI and CHI need to be registered so that they can be accessed by the Matter data model. Therefore, the cluster requires an initialization function to register them. To enable these functions, the cluster should be added to the appropriate entry in the zap configuration data file.

2.11.3 Example Usage

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4