Matter_CustomCluster.md

November 4, 2025 · View on GitHub

Add Manufacturer Specific Cluster support in ESP RainMaker Android App

Assumption here is that you are already aware of the concept of clusters in matter terminology. For details you can refer to here.

You can add support for your own custom cluster(s) in addition to the existing supported clusters in your Android Application. A few additional steps are required to add this support.

Adding your cluster support will require to generate jniLibs from "connectedhomeip" repo and use those libs while building this app. Here are the steps to compile.

Add your cluster definition

The first step to adding a custom feature is to define your data model in an XML file. In our sample, we've created the file rainmaker.xml.

In case you want to define your own new cluster, define your sample-mei-cluster.xml and place your data model file into this folder: src/app/zap-templates/zcl/data-model/chip.

Here is a sample XML file available in Matter repo.

References to your cluster from other files

Some modifications will be required to add your cluster support.

Add load "src/app/zap-templates/zcl/data-model/chip/sample-mei-cluster.xml"; into .matterlint file.

.matterlint
src/app/zap-templates/zcl/zcl.json is also used by the ZAP GUI. It alternatively draws from this list the set of available clusters when a device is being created. Make sure you also define your cluster here.

src/app/zap-templates/zcl/zcl.json

Install ZAP for code generation

You will need the ZAP tool to edit the ZAP file to enable your new cluster in Android clients.

Run below command to download the latest version of ZAP tool.

$ ./scripts/tools/zap/zap_download.py

Export the your ZAP installation path.

$ export ZAP_INSTALL_PATH=connectedhomeip/.zap/zap-v2025.01.10-nightly

Add changes for zap code generation

Modify src/app/zap_cluster_list.json flags to the to include your server clusters and client clusters. Add "SAMPLE_MEI_CLUSTER": ["sample-mei-server"], line to “ServerDirectories” and "SAMPLE_MEI_CLUSTER": [], line to “ClientDirectories” .

src/app/zap_cluster_list.json

src/app/zap_cluster_list.json

Add cluster to controller-clusters.zap

Note : DO NOT edit src/controller/data_model/controller-clusters.zap file manually.

Run the below mentioned command to open the ZAP GUI.

$ ./scripts/tools/zap/run_zaptool.sh src/controller/data_model/controller-clusters.zap

In the gui, select Endpoint-1 from the left pane.
Find your cluster and turn on 'client/server'.
Use the tab to select the Attributes page.
Enable your attributes.
Go back to the main page.
Set the cluster to 'client'.
Save the file.
Close the GUI.

Regenerate all code

Once all changes have been made, regenerate all code by running:

$ scripts/tools/zap_regen_all.py

Build matter libraries

Now its time to build matter libraries after zap code regeneration gets successful.

You need Android SDK 26 & NDK 23.2.8568313 downloaded to your machine. Set the $ANDROID_HOME environment variable to where the SDK is downloaded and the $ANDROID_NDK_HOME environment variable to point to where the NDK package is downloaded. The build also requires kotlinc to be in your $PATH.

Set environment variables :

export ANDROID_HOME=~/Library/Android/sdk
export ANDROID_NDK_HOME=~/Library/Android/sdk/ndk/23.2.8568313
export JAVA_HOME=/Applications/Android\ Studio.app/Contents/jbr/Contents/Home/

ABIs and TARGET_CPU TARGET_CPU can have the following values, depending on your smartphone CPU architecture:

ABI	TARGET_CPU
armeabi-v7a	arm
arm64-v8a	arm64
x86	x86
x86_64	x64

Now run below command to build :

./scripts/build/build_examples.py --target android-arm64-chip-tool build

Copy examples/android/CHIPTool/app/lib into your android project - “arm64-v8a” folder of jniLibs.

Rebuild the android project and run.

Reference links

Google docs for Matter cluster

Matter repo

Android Matter build steps

Matter - Adding new clusters

Espressif Matter blogs

ESP Matter device setup