Skip to content

Commit 3a10766

Browse files
KhushbuShah25KhushbuShah25
committed
Added guide to add support of custom cluster in app.
1 parent b1a4783 commit 3a10766

5 files changed

+144
-0
lines changed

‎Matter_CustomCluster.md

+134
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
## Add Manufacturer Specific Cluster support in ESP RainMaker Android App
2+
3+
Assumption here is that you are already aware of the concept of clusters in matter terminology. For details you can refer to [here](
4+
https://blog.espressif.com/matter-clusters-attributes-commands-82b8ec1640a0).
5+
6+
You can add support for your own custom cluster(s) in addition to the existing supported clusters in your Android Application.
7+
A few additional steps are required to add this support.
8+
9+
Adding your cluster support will require to generate jniLibs from ["connectedhomeip"](https://github.com/project-chip/connectedhomeip) repo and use those libs while building this app.
10+
Here are the steps to compile.
11+
12+
### Setup Matter Repository
13+
14+
1. Check out the Matter repository. We have used SHA: 3c6bed3bb2 to generate matter libs.
15+
```
16+
$ git clone https://github.com/project-chip/connectedhomeip.git
17+
$ cd connectedhomeip
18+
$ git checkout 3c6bed3bb28f66cc2e1ebbe3561fa0838f6b7c51
19+
```
20+
21+
2. Run bootstrap (**only required first time**)
22+
```
23+
$ source scripts/bootstrap.sh
24+
```
25+
Install required dependencies.
26+
27+
### Add your cluster definition
28+
29+
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`](https://github.com/espressif/esp-matter/blob/main/components/esp_matter_rainmaker/rainmaker.xml).
30+
31+
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`.
32+
33+
[Here](https://github.com/project-chip/connectedhomeip/blob/24b1d03460da8033490570a959995982af94c04d/src/app/zap-templates/zcl/data-model/chip/sample-mei-cluster.xml) is a sample XML file available in Matter repo.
34+
35+
### References to your cluster from other files
36+
37+
Some modifications will be required to add your cluster support.
38+
39+
1. Add `<xi:include href="chip/sample-mei-cluster.xml" />` into src/app/zap-templates/zcl/data-model/all.xml file.
40+
41+
**`src/app/zap-templates/zcl/data-model/all.xml`**
42+
43+
![src/app/zap-templates/zcl/data-model/all.xml](cluster_doc_image1.png)
44+
45+
2. **`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.
46+
47+
**`src/app/zap-templates/zcl/zcl.json`**
48+
49+
![src/app/zap-templates/zcl/zcl.json](cluster_doc_image2.png)
50+
51+
### Add changes for zap code generation
52+
53+
Modify **`src/app/zap_cluster_list.json`** flags to the to include your server clusters and client clusters.
54+
Add `"SAMPLE_MEI_CLUSTER": ["sample-mei-server"],` line to `“ServerDirectories”` and `"SAMPLE_MEI_CLUSTER": [],` line to `“ClientDirectories”` .
55+
56+
**`src/app/zap_cluster_list.json`**
57+
58+
![src/app/zap_cluster_list.json](cluster_doc_image3.png)
59+
60+
### Add cluster to controller-clusters.zap
61+
62+
Note : DO NOT edit `src/controller/data_model/controller-clusters.zap` file manually.
63+
64+
- Run the below mentioned command to open the ZAP GUI.
65+
```
66+
$ ./scripts/tools/zap/run_zaptool.sh src/controller/data_model/controller-clusters.zap
67+
```
68+
- Find your cluster and turn on 'client/server'.
69+
- Use the tab to select the Attributes page.
70+
- Enable your attributes.
71+
- Go back to the main page.
72+
- Set the cluster to 'client'.
73+
- Save the file.
74+
75+
### Add JNI support
76+
77+
Modify **`src/controller/data_model/BUILD.gn`** to include Android JNI generation for your cluster.
78+
Add 2 lines as mentioned below in outputs array.
79+
```
80+
"jni/SampleMeiClient-ReadImpl.cpp",
81+
"jni/SampleMeiClient-InvokeSubscribeImpl.cpp",
82+
```
83+
84+
### Regenerate all code
85+
86+
Once all changes have been made, regenerate all code by running:
87+
```
88+
$ scripts/tools/zap_regen_all.py
89+
```
90+
91+
### Build matter libraries
92+
93+
Now its time to build matter libraries after zap code regeneration gets successful.
94+
95+
You need Android SDK 26 & NDK 23.2.8568313 downloaded to your machine.
96+
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`.
97+
98+
Set environment variables :
99+
```
100+
export ANDROID_HOME=~/Library/Android/sdk
101+
export ANDROID_NDK_HOME=~/Library/Android/sdk/ndk/23.2.8568313
102+
export JAVA_HOME=/Applications/Android\ Studio.app/Contents/jbr/Contents/Home/
103+
```
104+
105+
**ABIs and TARGET_CPU**
106+
`TARGET_CPU` can have the following values, depending on your smartphone CPU architecture:
107+
108+
| ABI | TARGET_CPU |
109+
|--|--|
110+
| armeabi-v7a | arm |
111+
| arm64-v8a | arm64 |
112+
| x86 | x86 |
113+
| x86_64 | x64 |
114+
115+
116+
Now run below command to build :
117+
118+
`./scripts/build/build_examples.py --target android-arm64-chip-tool build`
119+
120+
Copy examples/android/CHIPTool/app/lib into your android project - “arm64-v8a” folder of jniLibs.
121+
122+
Rebuild the android project and run.
123+
124+
### Reference links
125+
126+
[Google docs for Matter cluster](https://developers.home.google.com/matter/extensions/sample-cluster)
127+
128+
[Matter repo](https://github.com/project-chip/connectedhomeip)
129+
130+
[Android Matter build steps](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/android_building.md)
131+
132+
[Espressif Matter blogs](https://blog.espressif.com/matter-38ccf1d60bcd)
133+
134+
[ESP Matter device setuo](https://docs.espressif.com/projects/esp-matter/en/latest/esp32c3/developing.html#esp-matter-setup)

‎README.md

+10
Original file line numberDiff line numberDiff line change
@@ -226,6 +226,16 @@ To build app with Matter support do the following :
226226
- Add `isMatterSupported=true` in `local.properties` file.
227227
- Enable `matterBuild` variable to `true` in `app/build.gradle` to add matter libs in app.
228228

229+
### Add your cluster support in app for Matter device
230+
231+
Assumption here is that you are already aware of the concept of clusters in matter terminology. For details you can refer to [here](
232+
https://blog.espressif.com/matter-clusters-attributes-commands-82b8ec1640a0).
233+
234+
You can add support for your own custom cluster(s) in addition to the existing supported clusters in your Android Application.
235+
A few additional steps are required to add this support.
236+
237+
[Here](Matter_CustomCluster.md) is a guide to add support for custom cluster.
238+
229239
## Additional Settings:
230240

231241
Settings associated with provisioning a device can be modified in the `local.properties` file.

‎cluster_doc_image1.png

147 KB
Loading

‎cluster_doc_image2.png

93.4 KB
Loading

‎cluster_doc_image3.png

209 KB
Loading

0 commit comments

Comments
 (0)