From 11756232ba89309eeb624e45f6c3e74216db7ab1 Mon Sep 17 00:00:00 2001 From: sreejitu <137451852+sreejitu@users.noreply.github.com> Date: Tue, 27 Jun 2023 09:08:19 -0700 Subject: [PATCH] Add documentation for TV App common-api and content-app (#27423) Co-authored-by: Restyled.io Co-authored-by: Justin Wood --- .github/.wordlist.txt | 4 +- .../tv-app/android/App/common-api/README.md | 55 +++++++++++++ .../tv-app/android/App/content-app/README.md | 77 +++++++++++++++++++ 3 files changed, 135 insertions(+), 1 deletion(-) create mode 100644 examples/tv-app/android/App/common-api/README.md create mode 100644 examples/tv-app/android/App/content-app/README.md diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index 750009aabbeb45..33d3b335cfc2d6 100644 --- a/.github/.wordlist.txt +++ b/.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 diff --git a/examples/tv-app/android/App/common-api/README.md b/examples/tv-app/android/App/common-api/README.md new file mode 100644 index 00000000000000..0eb7c4ac7daac3 --- /dev/null +++ b/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. diff --git a/examples/tv-app/android/App/content-app/README.md b/examples/tv-app/android/App/content-app/README.md new file mode 100644 index 00000000000000..c0c5c5f5b534d1 --- /dev/null +++ b/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 + + +``` + +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 + + + + + + +``` + +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