Building Android#

There are following Apps on Android

  • CHIPTool - Android CHIPTool is an application for Android for commissioning and controlling Matter accessory devices. It offers the following features:

    • Scan a Matter QR code and display payload information to the user

    • Read the NFC tag containing Matter onboarding information

    • Commission a Matter device

    • Send echo requests to the Matter echo server

    • Send on/off cluster requests to a Matter device

  • CHIPTest

    • Android CHIPTest is an application for Android for running Matter’s unit tests

Source files#

You can find source files of the Android applications in the examples/android/ directory.

Requirements for building#

You need Android SDK 26 & NDK 23.2.8568313 downloaded to 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.

  1. Install Android Studio

  2. Install NDK:

    1. Tools -> SDK Manager -> SDK Tools Tab

    2. Click [x] Show Package Details

    3. Select NDK (Side by Side) -> 23.2.8568313

    4. Apply

  3. Install Command Line Tools:

    1. Tools -> SDK Manager -> SDK Tools Tab -> Android SDK Command Line Tools 10.0

    2. Apply

  4. Install SDK 30:

    1. Tools -> SDK Manager -> SDK Platforms Tab -> Android 11.0 (R) SDK Level 30

    2. Apply

  5. Install Emulator:

    1. Tools -> Device Manager -> Create device -> Pixel 5 -> Android S API 31 -> Download

Linux#

export ANDROID_HOME=~/Android/Sdk
export ANDROID_NDK_HOME=~/Android/Sdk/ndk/23.2.8568313

MacOS#

export ANDROID_HOME=~/Library/Android/sdk
export ANDROID_NDK_HOME=~/Library/Android/sdk/ndk/23.2.8568313

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#

All Android projects utilize Gradle version 7.3.3 and JDK version 11.0.

For developer using java 11 in MacOS, the JAVA can be configured as follows via sdkman:

sdk install java 11.0.26-tem

For developer using openjdk-11-jdk in Linux, the JAVA_HOME environment variable can be configured as follows:

sudo apt-get install openjdk-11-jdk
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64

Kotlin Version#

The build requires kotlinc to be in your $PATH.

For Linux:

cd /usr/lib
wget -q https://github.com/JetBrains/kotlin/releases/download/v2.1.10/kotlin-compiler-2.1.10.zip
unzip kotlin-compiler-*.zip
rm kotlin-compiler-*.zip
rm -f kotlinc/bin/*.bat
export PATH=$PATH:/usr/lib/kotlinc/bin

For MacOS:

sdk install kotlin 2.1.10

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. Choose how you want to build the Android CHIPTool. There are two ways: from script, or from source within Android Studio.

Building Android CHIPTool from scripts#

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

./scripts/build/build_examples.py --target android-arm64-chip-tool build

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-chip-tool/outputs/apk/debug/, and can be installed with

adb install out/android-$TARGET_CPU-chip-tool/outputs/apk/debug/app-debug.apk

You can use Android Studio to edit the Android CHIPTool 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.

Building Android CHIPTool from Android Studio#

This option allows Android Studio to build the core Matter code from source, which allows us to directly edit core Matter code in-IDE.

  1. In the command line, run the following command from the top Matter directory:

    TARGET_CPU=arm64 ./scripts/examples/android_app_ide.sh

    See the table above for other values of TARGET_CPU.

  2. Modify the matterSdkSourceBuild variable to true, matterBuildSrcDir point to the appropriate output directory (e.g. ../../../../out/android_arm64), and matterSourceBuildAbiFilters to the desired ABIs in examples/android/CHIPTool/gradle.properties

  1. Open the project in Android Studio and run File -> Sync Project with Gradle Files.

  2. Use one of the following options to build an Android package:

    • Click Make Project in Android Studio.

    • Run the following command in the command line:

      cd examples/android/CHIPTool
./gradlew build

The debug Android package app-debug.apk will be generated at examples/android/CHIPTool/app/build/outputs/apk/debug/, and can be installed with

adb install examples/android/CHIPTool/app/build/outputs/apk/debug/app-debug.apk

or

(cd examples/android/CHIPTool && ./gradlew installDebug)

Building Android CHIPTest from scripts#

Currently, the CHIPTest can only be built from scripts. The steps are similar to building CHIPTool from scripts.

./scripts/build/build_examples.py --target android-arm64-chip-test build

You can modify the matterUTestLib variable to the test lib in examples/android/CHIPTest/gradle.properties to change target to test.