Matter TV Casting Android App Example

Matter TV Casting Android App Example#

This is a Matter TV Casting Android app that can be used to cast content to a TV. This app discovers TVs on the local network that act as commissioners, lets the user select one, sends the TV a User Directed Commissioning request, enters commissioning mode, advertises itself as a Commissionable Node and gets commissioned. Then it allows the user to send Matter ContentLauncher commands to the TV.

Refer to the Matter Casting APIs documentation to build the Matter “Casting Client” into your consumer-facing mobile app.

Requirements for building#

Refer to this file to download the recommended version for the Android SDK and NDK for your machine. 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.

export ANDROID_HOME=~/Library/Android/sdk
export ANDROID_NDK_HOME=~/Library/Android/sdk/ndk/{NDK_VERSION_NUMBER}

ABIs and TARGET_CPU#

TARGET_CPU can have the following values, depending on your smartphone CPU architecture:

ABI

TARGET_CPU

armeabi-v7a

arm

arm64-v8a

arm64

x86

x86

x86_64

x64

Gradle & JDK Version#

We are using Gradle 7.1.1 for all android project which does not support Java 17 (https://docs.gradle.org/current/userguide/compatibility.html) while the default JDK version on MacOS for Apple Silicon is ‘openjdk 17.0.1’ or above.

If you attempt to build with an incompatible Java version, you may encounter the following error:

Unsupported class file major version XX

This error occurs when the Java version being used is not compatible with the Gradle version in your project.

See the Building Android guide for more info about the supported Gradle & JDK Version.

You can verify your current Java version by running:

java -version

Preparing for build#

Complete the following steps to prepare the Matter build:

  1. Check out the Matter repository.

  2. Run bootstrap (only required first time)

    source scripts/bootstrap.sh

  3. The build will produce libraries: AndroidPlatform.jar, CHIPAppServer.jar, CHIPInteractionModel.jar and TVCastingApp.jar in App/app/libs and libTvCastingApp.so and libc++_shared.so in App/app/libs/jniLibs/ consumed by any casting app to leverage the casting APIs, like the sample android tv-casting-app. If building for your own casting app, make sure your client’s specific values are set for CHIP_DEVICE_CONFIG_DEVICE_VENDOR_ID and CHIP_DEVICE_CONFIG_DEVICE_PRODUCT_ID in the CHIPProjectAppConfig.h file, before the build. Other values like the CHIP_DEVICE_CONFIG_DEVICE_NAME may be optionally updated as well.

Building & Installing the app#

This is the simplest option. In the command line, run the following command from the top Matter directory:

./scripts/build/build_examples.py --target android-arm64-tv-casting-app build

(To build this app with no debugging hooks, use the android-arm64-tv-casting-app-no-debug target)

See the table above for other values of TARGET_CPU.

The debug Android package app-debug.apk will be generated at out/android-$TARGET_CPU-tv-casting-app/outputs/apk/debug/, and can be installed with

adb install out/android-$TARGET_CPU-tv-casting-app/outputs/apk/debug/app-debug.apk

You can use Android Studio to edit the Android app itself and run it after build_examples.py, but you will not be able to edit Matter Android code from src/controller/java, or other Matter C++ code within Android Studio.

Common build environment issues#

  1. If you see an error like kotlinc: command not found, install the Kotlin in your build environment. Eg. on MacOS, this can be done with the command:

brew install kotlin

Running the app#

This example Matter TV Casting Android app can be tested with the example Matter tv-app running on a Raspberry Pi.

Running Unit Tests#

The Android TV Casting app includes unit tests for the SendUDC functionality and other features.

Running All Tests#

From the App directory, run all unit tests:

cd examples/tv-casting-app/android/App
./gradlew test

Running Specific Test Suites#

To run only the SendUDC tests:

cd examples/tv-casting-app/android/App
./gradlew app:testDebugUnitTest --tests "com.matter.casting.core.CastingPlayerSendUDCTest"

Viewing Test Results#

After running tests, you can view detailed HTML reports:

open app/build/reports/tests/testDebugUnitTest/index.html

Or navigate to app/build/reports/tests/testDebugUnitTest/ in your file browser.

Test Coverage#

The SendUDC test suite (CastingPlayerSendUDCTest.java) includes 10 test cases covering:

  1. Basic sendUDC invocation with minimal options

  2. NoPasscode flag handling for app detection

  3. CancelPasscode flag for ending UDC sessions

  4. InstanceName management for unique session identifiers

  5. TargetAppInfo handling with vendor/product IDs

  6. CommissionerDeclarationCallback registration

  7. Complete app detection workflow simulation

  8. Multiple target apps support

  9. Error handling and response validation

  10. Callback validation requirements

Troubleshooting Tests#

Issue: Tests don’t run or show as “up-to-date”

  • Solution: Clean and rebuild: ./gradlew clean test

Issue: Native method errors (UnsatisfiedLinkError)

  • Solution: Ensure all native objects are properly mocked in tests

Issue: Gradle version compatibility errors

  • Solution: Verify you’re using JDK 11 (not JDK 17) as per the build requirements above

For more details on the test implementation, see the test documentation.