- Client: This is your user-facing phone app for Android or iOS. By making your phone app a Matter client, the user can discover casting targets such as a Fire TV. They can also cast content, and control casting sessions.
- Content app: This is your user-facing app on a Fire TV. By making your TV app a Matter content app, clients are able to control it. For example, they can start playback of specific content.
Step 1: Integrate the Matter Casting SDK into your client app
Here are the steps required to integrate and initialize the Matter SDK into your mobile Android or iOS app.Build and setup
To consume any of the APIs described in this document, your client must include the Matter Casting library in your Android or an iOS project.Caching
Clients maintain an on-device cache with the information about the players it previously connected to. This cached information allows the client to connect with these players faster, and using fewer resources, by potentially skipping the longer commissioning process, and simply re-establishing the CASE session. This cache can be cleared by calling theClearCache method on the client. Clearing the cache can be useful when the user signs out of the client, for instance.
Integration on Android
Download the Android SDK from the CSA Github repository and add it to your project. After it has been added to your project, initialize the library with the following steps (full listing).1. Define the rotating device identifier
This is a unique per-device identifier, consisting of a randomly-generated 128-bit or longer octet string. Review the Matter specifications for details on how to generate the Rotating Device Identifier. Instantiate a DataProvider object as described below to provide this identifier.2. Initialize commissioning data
TheCommissionableDataProvider object contains the passcode and other artifacts, which identify the client and are provided to the player during the commissioning process. Refer to Matter specification’s Onboarding Payload section for details on commissioning data.
3. Add Device Attestation Credentials
The Device Attestation Credentials (DAC) object provides the certificates required to sign messages as part of the Device Attestation process during commissioning. The Matter specification provides background information on how this works. For development purposes, you can use the DAC provided in the sample code. DefinedacProvider to provide the client’s Device Attestation Credentials, by implementing com.matter.casting.support.DACProvider.
4. Initialize the client
After the objects are created, initialize the client as listed below. The client might be initialized only one time before a Matter Casting session is started.Integration on iOS
A. Build the Matter framework The open source Github repository provides a framework for handling low-level communication between your iOS client and the video casting player and content app. Build the framework using the following steps.- Git clone the Github repository to your development machine using git clone https://github.com/project-chip/connectedhomeip/tree/master
- In a terminal, change the folder to the location of your repository and run source scripts/bootstrap.sh. This builds the libraries and associations required.
- Open the example iOS app to build the framework locally.
- Include the framework in your iOS app.
1. Define the rotating device identifier
This is a unique per-device identifier that consists of a randomly-generated 128-bit or longer octet string. Review the Matter specifications for details on how to generate the Rotating Device Identifier. Instantiate aDataProvider object as described below to provide this identifier.
2. Initialize commissioning data
This object contains the passcode and discriminator. which identifies the app and provides theCastingPlayer object during the commissioning process. A passcode must be included as a 27-bit unsigned integer. This serves as proof of possession during commissioning. A Discriminator must be included as a 12-bit unsigned integer, which must match the value that a device advertises during commissioning. See Chapter 5 Commissioning in the Matter Core specification for more details on the Matter specification’s Onboarding Payload section.
Add func CommissionableDataProvider to the MCAppParametersDataSource class previously defined, that provides the required values to MCCastingApp. If using the CastingPlayer / Commissioner-Generated Passcode UDC feature, the casting client must update the CommissionableDataProvider during the VerifyOrEstablishConnection() API call (described later). In the following example, the update function updates the CommissionableData with a CastingPlayer generated passcode entered by the user on the casting client UX.
3. Add device attestation credentials
This object contains theDeviceAttestationCertificate and ProductAttestationIntermediateCertificate, that implements a way to sign messages when called by the Matter TV Casting library as part of the Matter Device Attestation process during commissioning.
Add functions castingAppDidReceiveRequestForDeviceAttestationCredentials and didReceiveRequestToSignCertificateRequest to the MCAppParametersDataSource class previously defined, which returns MCDeviceAttestationCredentials and sign messages for the Casting client.
4. Initialize SDK
After you have created the previousDataProvider objects, you are ready to initialize the casting app as described below.
Call MCCastingApp.initialize with an object of MCAppParametersDataSource.
MCCastingApp shared instance when the app sends UIApplication.didBecomeActiveNotification and UIApplication.willResignActiveNotification.
Step 2. Integrate Matter with your Fire TV app
After Integrate the Matter Casting SDK into your client app, your client is ready to discover players and content apps on the same Matter network. Before you can listen, send, and receive Matter commands from the content app on Fire TV you must integrate it with the Fire TV Matter Casting service. This step shows you how to use the Android TV example app to bootstrap a content app for Android TV that’s already Matter Casting-enabled.1. Update your Android manifest
Enabling Matter Casting requires extending the information provided in your Android manifest. The player and the Matter agent client use information provided in the Android manifest to understand which clients to allow casting to your content app and which Matter clusters the content app supports.1. Product and vendor information
Update your app’s tag to include your product ID and vendor ID. See App Attestation for more information. For development, you have the option to use the Product ID of65521, Vendor ID of 32769, and Vendor Name provided in the following example.
2. Update permissions
To bind with the player’s Matter agent service, your content app must provide the following permissions in its manifest file.3. Supported clusters
Next, to add the Clusters your content app supports, add the following to the Android manifest.2. Integrate with Matter AIDL files
Matter Casting uses the Android Interface Definition Language (AIDL) to define the programming interface to communicate between the player and your content app. Copy the following three AIDL files from the example app to your app’s repository: IMatterapplicationAgent.aidl, SetSupportedClustersRequest.aidl, and SupportedCluster.aidl. This helps you integrate with the following required methodssetSupportedClusters and reportAttributeChange. These methods are necessary for the following:
-
setSupportedClusters- This method reports clusters dynamically to the Matter agent.
- This is not incremental and on each call, report the full set of clusters. Any clusters that are omitted in the latest method call that were added previously are removed.
- The previous behavior does not impact static clusters declared in app resources and they are not removed.
- Dynamic cluster can be used to override and hide a static cluster based on the cluster name.
-
reportAttributeChange- This method reports changes to attributes by the content app.
- It also takes in the cluster ID and attribute ID for the reported attribute change.
3. Create a Matter agent client
Create a Matter agent client as found in the example. The agent is used to connect to the Matter service and to use the methods provided in the previous AIDL step. Here’s an example of establishing a binder connection.4. Register the Matter command receiver
The content app registers itself as a receiver to handle incoming Matter commands. To receive commands sent from the client, the content app registers a receiver instance that listens for MATTER_COMMAND intents with permission.com.matter.tv.app.api.permission.SEND_DATA for the receiver as previously seen. After you receive the intent, you can read the Matter command in your content app.
5. Execute commands
After the content app is started, it binds to the Matter agent service to receive commands and registers all its dynamic endpoints and supported clusters through thereportClusters call.
reportAttributeChange on the Matter agent to notify the SDK.
When receiving a command from the Matter SDK, an intent of type ACTION_MATTER_COMMAND is received using BroadcastReceiver implemented by the content app. The intent includes the command ID, cluster ID, and corresponding payload data. After the command handler is called, a response for these commands must be sent. An example receiver is found in MatterCommandReceiver.java. All the internal fields within the intents are found under MatterIntentConstants provided through the common-api module.
6. Install your Fire TV app on-demand
The following assumes that the customer has your content app installed and they are casting to it. However, this might not be the case. If the content app is not installed, Fire TV can prompt them to install the app if its package name is provided in theApplicationID information of the launch app cluster payload.
Step 3. Interact with players
In this step you learn how to discover, select, and connect to a player, issue commands, read attributes like playback state, and subscribe to playback events.Interaction on Android
1. Discover casting players
The client discovers players such as Fire TV using Matter Commissioner Discovery overDNS-SD by listening for player events as they are discovered, updated, or lost from the network.
First implement CastingPlayerDiscovery.CastingPlayerChangeListener.
castingPlayerChangeListener as a listener to MatterCastingPlayerDiscovery to listen to changes in the discovered players and call startDiscovery.
2. Connect with a discovered player
Each player object created during Discovery contains information such asdeviceName, vendorId, and productId, which helps the user pick the right player. A client can attempt to connect to selectedCastingPlayer using Matter User Directed Commissioning (UDC). The Matter TV Casting library locally caches information required to reconnect to a player object after the client has been commissioned by it. After that, the Casting client is able to skip the full UDC process by establishing CASE with the player directly. After connected, the Player object contains the list of available endpoints on that player. The following arguments might also be passed in as options. commissioningWindowTimeoutSec indicates how long to keep the commissioning window open, if commissioning is required. DesiredEndpointFilter specifies the attributes, such as vendor ID and product ID, of the endpoint the client wants to interact with after connecting. This forces the Matter TV Casting library to go through the full UDC process in search of the desired endpoint, in cases where it’s not available in the client’s cache.
The client might call verifyOrEstablishConnection on the CastingPlayer object it wants to connect to.
3. Select an endpoint on the player
On a successful connection with a player object, a casting client might select one of the endpoints to interact with based on its attributes, such as the vendor ID, product ID, or list of supported clusters. In the context of Matter Casting, endpoints refer to your content app.4. Interacting with a casting endpoint
After the Casting client has selected an endpoint, it is ready to issue commands to it, read the current playback state, and subscribe to playback events. The list of supported clusters, commands, and attributes on Android can be found in the example code. Issuing commands Given the endpoint from the previous step, you can send aLaunchURL command (part of the Content Launcher cluster) by calling the launchURL method on a ChipClusters.ContentLauncherCluster object.
subscribeCurrentStateAttribute on a ChipClusters.MediaPlaybackCluster object.
Interaction on iOS
1. Discover casting players
Now that you have integrated the Matter library into your client and in the content app, you can discover and communicate with video casting players and content apps on the same Matter fabric. Implement func addDiscoveredCastingPlayers, funcremoveDiscoveredCastingPlayers and func updateDiscoveredCastingPlayers, which listens to notifications as casting players are added, removed, or updated.
addObserver in NotificationCenter with the appropriate selector, and then call start on the sharedInstance object of MCCastingPlayerDiscovery.
2. Connect to a casting player
EachCastingPlayer object created during discovery contains information such as deviceName, vendorId, and productId, which helps the user pick the right CastingPlayer. A Casting client can attempt to connect to selectedCastingPlayer using Matter User Directed Commissioning (UDC). The Matter TV Casting library locally caches information required to reconnect to a CastingPlayer object after the Casting client has been commissioned by it. After that, the Casting client can skip the full UDC process by establishing CASE with the CastingPlayer object directly. After connected, the CastingPlayer object contains the list of available endpoints on that CastingPlayer object. commissioningWindowTimeoutSec indicates how long to keep the commissioning window open, if it’s required. DesiredEndpointFilter specifies the attributes, such as the vendor ID and product ID of the endpoint the Casting client wants to interact with after connecting. This forces the Matter TV Casting library to go through the full UDC process in search of the desired endpoint, in cases where it’s not available in the casting client’s cache.
The Casting client might call verifyOrEstablishConnection on the MCCastingPlayer object it wants to connect to and handle any errors through NSErrors that might happen in the process.
3. Select a casting player endpoint
After successfully connected with aCastingPlayer object, a casting client might select one of the endpoints to interact with based on its attributes (such as vendor ID, product ID, or list of supported clusters). Select MCEndpoint as shown below.
4. Interacting with a casting endpoint
After the casting client has selected an endpoint, it is ready to issue commands to it, read current playback state, and subscribe to playback events. Refer to the following operating system-specific files to find the list of clusters, commands, and attributes with their request and response types available for use with the Matter TV casting library. Refer to the following files:- For a list of supported clusters, commands, and attributes: MCClusterObjects.h.
- For the IDs and request and response types to use with the commands: MCCommandObjects.h and MCCommandPayloads.h.
- For attribute read operations: Read Operations and subscriptions: MCAttributeObjects.h.
5. Issuing commands
Given an endpoint (MCEndpoint), it can send a LaunchURL command, which is part of the Content Launcher cluster, by calling the invoke method on MCContentLauncherClusterLaunchURLCommand.
6. Read operations
CastingClient might read an attribute from the endpoint on the CastingPlayer object. It should make sure that the desired cluster and attribute are available for reading on the endpoint before trying to read it.
Within MCEndpoint, the VendorID can be read similarly, by calling the read method on MCApplicationBasicClusterVendorIDAttribute.

