Add documentation for TV App common-api and content-app (#27423)

Co-authored-by: Restyled.io <commits@restyled.io>
Co-authored-by: Justin Wood <woody@apple.com>

.github/.wordlist.txt

@@ -44,6 +44,7 @@ AdvSendAdvert
 AE
 aef
 AES
+AIDL
 AlarmCode
 algs
 alloc
@@ -164,6 +165,7 @@ bredr
 BridgedDeviceBasicInformation
 bridgedLightEndpoint
 bringup
+BroadcastReceiver
 BromateConcentrationMeasurement
 BromodichloromethaneConcentrationMeasurement
 BromoformConcentrationMeasurement
@@ -1361,9 +1363,9 @@ tmp
 tngvndl
 TODO
 toJson
+tokenization
 tokenized
 tokenizer
-tokenization
 toolchain
 toolchains
 topologies

examples/tv-app/android/App/common-api/README.md

@@ -0,0 +1,55 @@
+# Matter tv app common-api
+
+The tv-app common-api module defines the interface to interact with the Matter
+agent service for the content apps. This module defines the AIDL interfaces,
+clusters and command abstractions accessible. It also defines various constants
+and intent field definitions that would be used by the content app while
+interacting with the Matter SDK. The interface provided by this module helps
+content app to register dynamic endpoints as well as report any attribute
+changes to the SDK.
+
+## Permissions needed
+
+To utilize the Matter agent interface the partner apps need to
+
+-   Query and bind themselves to a service that handles
+    `com.matter.tv.app.api.action.MatterAppAgent` action
+-   The host process should hold the
+    `com.matter.tv.app.api.permission.SEND_DATA` permission
+-   To bind with the Matter app agent service, the client should hold the
+    `com.matter.tv.app.api.permission.BIND_SERVICE_PERMISSION` permission
+
+## Matter app agent APIs
+
+The Matter app agent service exposes the following interface
+
+-   `setSupportedClusters`
+    -   This API allows partners to report clusters dynamically to the Matter
+        agent
+    -   This API is not incremental and on each API call we should report the
+        full set of clusters - any clusters that are omitted in the latest API
+        call that were added previously will be removed
+    -   The above behavior does not impact static clusters declared in app
+        resources and they will not be removed
+    -   Dynamic cluster can be used to override and hide a static cluster based
+        on cluster name
+-   `reportAttributeChange`
+    -   This API allows reporting changes to attributes by the content app
+    -   It takes in the cluster ID and attribute ID for which the attribute
+        change is reported
+
+## Cluster and Attribute IDs
+
+The common API package defines commonly used cluster IDs as well as
+corresponding Attribute ID's through `com.matter.tv.app.api.Clusters`. The
+common-api provides a quick way to refer to different clusters defined by the
+Matter spec relevant for media casting, as well as attributes and commands
+associated with each one.
+
+## Intents
+
+The supported intents are defined under the
+`com.matter.tv.app.api.MatterIntentConstants`. This helper class defines the
+relevant intents used while interacting with the Matter app agent service. This
+includes the android permission strings to as well as command and attribute
+intent fields to be used.

examples/tv-app/android/App/content-app/README.md

@@ -0,0 +1,77 @@
+# Content App
+
+This module provides an example of a TV Content App that supports Matter
+casting. The content app can register its supported clusters with the Matter SDK
+as well as receive any incoming commands and provide responses.
+
+### Specifying the permissions
+
+The content app needs to bind with the Matter agent service to start receiving
+commands as well as register its supported clusters. To bind with the service,
+the content app need to add the following permissions to their manifest file
+
+```xml
+<uses-permission android:name="com.matter.tv.app.api.permission.BIND_SERVICE_PERMISSION"/>
+<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES" tools:ignore="QueryAllPackagesPermission"/>
+```
+
+The permission string is defined within the `common-api` module as
+`PERMISSION_MATTER_AGENT_BIND`
+
+`AndroidManifest.xml` can be used as a good reference point
+
+### Registering a command receiver
+
+The content app should register itself as a receiver in order to get any
+incoming matter commands that needs to be handled. To receive commands from
+matter stack, the app will need to register a receiver instance that listens for
+`MATTER_COMMAND` intents and have permission to send data via Matter API. Here
+is a sample snippet
+
+```xml
+<!-- Intent action for receiving an Matter directive-->
+<receiver
+        android:name=".receiver.MatterCommandReceiver"
+        android:permission="com.matter.tv.app.api.permission.SEND_DATA"
+        android:enabled="true"
+        android:exported="true">
+    <intent-filter>
+        <action android:name="com.matter.tv.app.api.action.MATTER_COMMAND" />
+    </intent-filter>
+</receiver>
+```
+
+In order to send data and respond to commands we need to include the permission
+`com.matter.tv.app.api.permission.SEND_DATA` for the receiver as above.
+
+### Structuring the application
+
+The first step is to register for appropriate permissions as well as an intent
+receiver as described in the steps above. Once the application is started, it
+can bind to the Matter agent service. Refer to `MatterAgentClient.java` as an
+example.
+
+Once the content app binds to the Matter agent, it can register all its dynamic
+endpoints and supported clusters through the `reportClusters` API call.
+
+```cpp
+executorService.execute(() -> matterAgentClient.reportClusters(supportedClustersRequest));
+```
+
+Whenever the content app wants to report an attribute change, it can leverage
+the `reportAttributeChange` on the matter agent to notify the SDK.
+
+Upon receiving a command from the Matter SDK - an intent of type
+`ACTION_MATTER_COMMAND` will be received by the BroadcastReceiver implemented by
+the content app. The intent would have the command id, cluster id as well as
+corresponding payload data. Once the command handler is called, a response for
+the command needs to be sent. An example for a receiver can be found within
+`MatterCommandReceiver.java`. All the internal fields within the intents can be
+found under `MatterIntentConstants` provided through the `common-api`.
+
+### Example files
+
+-   `MainActivity` - a sample content app
+-   `MatterCommandReceiver` - a receiver for incoming commands
+-   `MatterAgentClient` - a client that binds and manages connection to matter
+    app agent service