Google Home Sample App for Matter

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

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 guide.
• Build a Matter device with On/Off capabilities. This sample app works with a virtual device and an ESP32.
  • Matter Virtual Device (MVD). 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 with the rootnode_dimmablelight_bCwGYSDpoe app. When you Create a Matter integration in the Google Home Developer Console, use 0xFFF1 as your Vendor ID and 0x8000 as your Product ID.
  • Build an Espressif Device with the all-clusters-app. When you Create a Matter integration in the Developer Console, 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.

Install

1. Go to the Releases section 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

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. 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?

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 Add Device button to start the commissioning process.

   

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.

   

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.

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 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.

   

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 settings icon. Here you have the options to update user preferences, get help, and learn more about the app.

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 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

If you're having issues with the Sample App for Matter, try completing the steps to verify your environment:

• Verify Matter Modules & Services

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

To get official guidance from Google on technical questions, use the Smart Home Developer Forum:

• 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