The Google Home Sample App for Matter uses the Google Home Mobile SDK to create an Android app that's similar to Google Home app (GHA). 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
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
- 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 guide.
- Build a Matter device with On/Off capabilities. This
sample app works with a virtual device and an ESP32.
- Build a Matter Virtual Device
rootnode_dimmablelight_bCwGYSDpoeapp. When you Create a Matter integration in the Google Home Developer Console, use
0xFFF1as your Vendor ID and
0x8000as your Product ID.
- Build an Espressif Device
all-clusters-app. When you Create a Matter integration in the Developer Console, use
0xFFF1as your Vendor ID and
0x8001as your Product ID.
- Build a Matter Virtual Device with the
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.
Go to the Releases section in the Sample App for Matter GitHub repository. Locate the APK named
GHSAFM-1.4.1-default-debug.apk. Do not select the
Install Android Debug Bridge (adb):
Connect your Android device with USB and enable File Transfer, then install the APK:
$ adb unroot && adb install GHSAFM-1.4.1-default-debug.apk
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. 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?
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:
Tap theAdd Device button to start the commissioning process.
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.
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.
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.
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.
Go to the Releases section in the Sample App for Matter GitHub repository. Locate the most recent APK named
GHSAFM-[version]-targetcommissioner, for example
Install the target commissioner.
$ adb unroot && adb install GHSAFM-1.4.1-targetcommissioner-debug.apk
From the Home screen, tap the device to display the device information. Tap Share.
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:
- Manually through a setup code to be shared with the target commissioner app
- 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.
From the Home screen, click the settingsicon. Here you have the options to update user preferences, get help, and learn more about the app.
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 for more information.
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:
Click Log repositories content.
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.
If you're having issues with the Sample App for Matter, try completing the steps to verify your environment:
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:
To get official guidance from Google on technical questions, use the Smart Home Developer Forum:
To get technical support from the community, use the
google-smart-home tag on