![Google Home Sample App for Matter](https://developers.home.google.com/static/images/sample-home-app-logo.png) The Google Home Sample App for Matter uses the [Google Home Mobile SDK](https://developers.home.google.com/matter/apis/home.md.txt) to create an Android app that's similar to [Google Home app (GHA)](https://play.google.com/store/apps/details?id=com.google.android.apps.chromecast.app). This sample app provides the following features: - Commission physical and virtual Matter devices to the Local Android fabric - Commission physical and virtual devices to a development fabric - Control devices on your development fabric, for example turning on a light - Multi-admin features allow you to share devices on the development fabric with other apps, and conversely be able to include in the development fabric devices shared from other apps - Developer Utilities > [!NOTE] > **Note:** The sample app currently only supports devices that have the On/Off server attribute, for example lights, smart plugs, and fans. This guide describes how to install the Sample App for Matter APK and use it to commission, control, and share Matter devices. To download the source code, learn how to integrate the Mobile SDK, and customize screens in Android Studio, try our Sample App for Matter codelab. [Go to the Sample App for Matter codelab](https://developers.home.google.com/codelabs/matter-sample-app) ## Prerequisites - An Android O (8.1, API level 27) or newer device available for testing. To make sure that your device has the latest Matter support, review the [Verify Matter Modules \& Services](https://developers.home.google.com/matter/verify-services.md.txt) guide. - Build a Matter device with On/Off capabilities. This sample app works with a virtual device and an ESP32. - [Matter Virtual Device (MVD)](https://developers.home.google.com/matter/tools/virtual-device.md.txt). To minimize environment issues, we strongly suggest that you use MVD to start with. If you ever run into issues, it will be much easier to investigate if the sample app is used against MVD. - [Build a Matter Virtual Device](https://developers.home.google.com/codelabs/matter-device-virtual) with the `rootnode_dimmablelight_bCwGYSDpoe` app. When you [Create a Matter integration](https://developers.home.google.com/matter/integration/create.md.txt) in the [Google Home Developer Console](https://console.home.google.com/projects), use `0xFFF1` as your Vendor ID and `0x8000` as your Product ID. - [Build an Espressif Device](https://developers.home.google.com/matter/vendors/espressif) with the `all-clusters-app`. When you [Create a Matter integration](https://developers.home.google.com/matter/integration/create.md.txt) in the [Developer Console](https://console.home.google.com/projects), use `0xFFF1` as your Vendor ID and `0x8001` as your Product ID. You don't need a hub, for example a Google Nest Hub (2nd gen), to commission and control devices with the Sample App for Matter. > [!IMPORTANT] > **Important:** The Sample App for Matter only supports devices that have the On/Off server attribute, for example lights, smart plugs, and fans. ## Install 1. Go to the [Releases section](https://github.com/google-home/sample-apps-for-matter-android/releases) in the Sample App for Matter GitHub repository. For the most recent release, locate in the Assets section the APK named `GHSAFM-version-default-debug.apk`. Don't select the `targetcommissioner`. 2. Install Android Debug Bridge (adb): [Install adb](https://developer.android.com/studio/command-line/adb) 3. Connect your Android device with USB and enable **File Transfer**, then install the APK: $ adb unroot && adb install GHSAFM-version-default-debug.apk ## Commission devices When you launch the sample app for the first time, you'll get a dialog with a link to the [Sample App for Matter codelab](https://developers.home.google.com/codelabs/matter-sample-app). If you select **Don't show this message again**, you can bring the dialog back at any time by updating your preferences in the app's Admin section. In the next steps, you'll add a Matter device to the Local Android fabric, along with a development fabric that's local to the sample app only. ### What are Matter fabrics? ![Google Home Sample App for Matter](https://developers.home.google.com/static/images/matter-fabric.png) A Matter fabric is a shared domain of trust among devices in a home network that enables them to communicate with each other. Devices may have one or more fabrics that correspond to a platform, app, or group of devices interacting together. Fabrics have a unique id, and devices share the same set of credentials and **certificate authority** (**CA** ). These credentials are assigned during Matter commissioning. To commission a Matter device, complete the following steps: 1. Tap the Add Device button to start the commissioning process. ![Add device](https://developers.home.google.com/static/images/sample-app-add.png) 2. Next, control is transferred to Google Play services, which is launched from a call to the Mobile SDK. To establish proof of possession, **Scan QR code** or tap **Use pairing code**. ![Scan QR Code](https://developers.home.google.com/static/images/sample-app-qrcode.png) 3. When commissioning completes, enter a **Device Name** , then tap **Done**. Your device is now connected to both the Local Android fabric and the development fabric. All of the commissioning work and associated screens are handled by Play services when commissioning devices. This provides a consistent user experience and removes the need to handle sensitive permissions, for example, Wi-Fi and Thread credentials. ## Control devices The development fabric creates the credentials to control Matter devices right from the sample app. From the Home screen, you can toggle your device **On** or **Off**. Tap the device to access device details. ![Device Added](https://developers.home.google.com/static/images/sample-app-added.png) ## Share devices Sharing a device is referred to as *multi-admin flow* in the Matter specification. Once a device is commissioned to the sample app, you can easily share it with other ecosystems. To share your Matter device with other ecosystems, you'll need to have another platform installed on your Android device. This external platform becomes the **target commissioner**. We've created another instance of the sample app that you can use as the target commissioner. 1. Go to the [Releases section](https://github.com/google-home/sample-apps-for-matter-android/releases) in the Sample App for Matter GitHub repository. For the most recent release, locate in the Assets section the APK named `GHSAFM-version-targetcommissioner-debug.apk`. Don't select the `default`. 2. Install the target commissioner. $ adb unroot && adb install GHSAFM-version-targetcommissioner-debug.apk 3. From the Home screen, tap the device to display the device information. Tap **Share**. ![Share device](https://developers.home.google.com/static/images/sample-app-share.png) The sample app calls the Mobile SDK Share API and once again, control is transferred to Play services. A share sheet displays, allowing you to choose the app or platform that you want to pair the device to. This screen provides two ways for you to share the device: 1. Manually through a setup code to be shared with the target commissioner app 2. With a local android app that has registered as a Matter commissioner The target commissioner app is labeled **GHSAFM-TC**. Tap this instance of the sample app to share your device. Next, the external app (target commissioner) completes the commissioning of the device into its own fabric. ## Settings From the Home screen, click the settings icon. Here you have the options to update user preferences, get help, and learn more about the app. ![Settings](https://developers.home.google.com/static/images/sample-app-settings.png) ### Halfsheet notification From the Settings screen, you can choose to disable proactive commissionable discovery notifications for Matter devices. If your application provides its own Matter discovery or commissioning flow, you may wish to suppress these notifications to prevent interruptions. See [Suppress commissionable discovery notifications](https://developers.home.google.com/matter/apis/home/commissioning#suppress_commissionable_discovery_notifications) for more information. ### Developer utilities From the Settings screen, you can also access **Developer utilities**. To review the contents of the Device and User Preferences DataStore repositories in **Logcat**, complete the following steps: 1. Click **Log repositories content**. 2. Click **OK** to the dialog, then check **Logcat**. ## Feedback and help To submit your thoughts or feedback on how we can improve the development experience with Sample App for Matter, complete our Feedback Form. [Send us your feedback](https://docs.google.com/forms/d/e/1FAIpQLSfWGEzJ4LzseLSW-DcAvVPHMpymkafCq00CY1q9VwT3FkAsyQ/viewform?usp=sf_link) If you're having issues with the Sample App for Matter, try completing the steps to verify your environment: - [Verify Matter Modules \& Services](https://developers.home.google.com/matter/verify-services.md.txt) If you have questions about using the sample app or discover a code bug, you can submit issues to the Issue Tracker in the GitHub repository: - [sample-apps-for-matter-android/issues](https://github.com/google-home/sample-apps-for-matter-android/issues) To get official guidance from Google on technical questions, use the Smart Home Developer Forum: - [Smart Home Developer Forum](https://www.googlenestcommunity.com/t5/Smart-Home-Developer-Forum/bd-p/Smart-Home-Developer-Forum) To get technical support from the community, use the `google-smart-home` tag on Stack Overflow: - [Stack Overflow: google-smart-home](https://stackoverflow.com/questions/tagged/google-smart-home)