Need guide for using manufacturer-specific clusters (CON-235)

[jonsmirl]

esp-matter/components/esp_matter_rainmaker shows how to make a custom cluster.

But... that is only half the battle. To use this cluster from IOS/Android you are going to need to make an XML description of it and then use zap to generate the IOS/Java code needed to use it. It might be possible to write this by hand, but it is hundreds of lines of code.

So for the rainmaker case on Java, it would generate a Java class that extends BaseChipCluster and implements the wrappers for the various attributes, commands and events. Parallel activity needed for IOS.

This procedure is complex, there needs to be a guide written on how to do it.

[jonsmirl]

I tried coding this up in the CHIP source tree. It is not so hard to add the XML to define a custom cluster. But... once you do that you then have to rebuild the IOS and Android (and C?) client libraries which is a pain to do since they experience constant breakage. For example the code generated for Android is not just java code, there are hundreds of lines of C code generated too and this C code has to be in the Android CHIP libraries for the custom cluster to work.

The bigger problem here is reliably rebuilding the IOS and Android client libraries every time you make a tweak to your custom cluster.

I consider this poor design on the part of CHIP to require a rebuild of the IOS/Android client libraries to implement a custom cluster.

[jonsmirl]

Current status:
IOS supports accessing the clusters by numeric ID.
Android does not support this.

On IOS there is no issue building an app using custom CHIP clusters. That's because IOS supports accessing the cluster by number (instead of name).

Since the Android libs don't support access by ID number you have to edit the CHIP tree and add the names. To do this you need to supply the XML definition and then touch up three other files. Recompile to get the Android binaries. This is not a trivial thing to do and it requires you to have significant knowledge about how to build CHIP. There is also no easy way to automate the process since one of the steps requires using interactive ZAP to enable the custom cluster in the zap file.

It would be very helpful if the Android people were encouraged to support numerical access. I have filed bugs on them, but they will just ignore my bugs. Maybe you can push harder.

[jonsmirl]

IOS is easy, they provided an API
https://developer.apple.com/documentation/matter/mtrbasedevice
https://developer.apple.com/documentation/matter/mtrdevice

I have written up an example procedure for Android here. This procedure is complex and error prone. I am hoping Android will provide an API like Apple did.
https://github.com/Lowpan-com/connectedhomeip/pull/4

[jonsmirl]

A lot of useful info in this issue: #216

[dhrishi]

@jonsmirl Do you want to provide the latest update about the Android side implementation of the manufacturer-specific cluster and close this issue?

[jonsmirl]

Well, Espressif probably still needs to write up a guide and demo of how to do this. I can make it work myself but I don't suspect any of the other people using esp-matter can make it work without assistance.

The Rainmaker project works as a vehicle to do this. The guide needs to include:

1. The basic concept of a custom cluster. Maybe show app/src/zcl/data-model/chip/test-cluster.xml as examples of what can be done. Mention that they have to use vendor-ids in the cluster name.

2. How to add custom clusters on the esp-matter server side. Including how to deal with something more complex than a single INT. The easiest way to do this is to write the XML for it and than use zap to generate the C++ code that you insert into the esp-matter project. You can use any zap to do this, you are just going to clip out the bit about encode/decode of the TLV from the generated code. Or you can write it by hand.

3. A discussion of how to call the cluster using C++ from an esp-matter client controller.

4. Example of IOS calling this cluster using the APIs linked above.

5. Example of Android calling this cluster using the newly added code. Which I have not figured out how to use yet.
   Add JAVA/JNI IM Write API project-chip/connectedhomeip#25445
   Add JAVA/JNI Invoke command API project-chip/connectedhomeip#25476

6. How to return TLV from a command

7. How to implement read/write on a structured custom attribute.

[jonsmirl]

I am able to fully build manufacturer specific clusters but doing it is a complex process. I do which this was easier to do.