Google Home Sample App for Matter

Stay organized with collections Save and categorize content based on your preferences.

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 Google fabric, allowing you to control devices from Google Home
  • 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

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. However, if you want to use GHA to control devices that you've commissioned with the Sample App for Matter, you'll need a hub.

Install

  1. Go to the Releases section in the Sample App for Matter GitHub repository. Locate the most recent APK named GHSAFM-[version], for example GHSAFM-1.0.1-default-debug.apk. Do not select the targetcommissioner:

    Download the APK

  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-1.0.1-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 Google fabric, along with a development fabric that's local to the sample app only.

What are Matter fabrics?

Google Home Sample App for 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

  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

  3. On Connect this device to your Google Account, click I Agree. Play services will connect your device to Wi-Fi, Ethernet, or Thread, depending on your network platform.

  4. When commissioning completes, enter a Device Name, then tap Done.

Your device is now connected to the Google fabric. This means that you can control your device through the Google Home app, Android power controls, voice, and Nest touch screen devices.

All of the commissioning work and associated screens are handled by Play services when commissioning devices to the Google fabric. This provides a consistent user experience and removes the need to handle sensitive permissions, for example Wi-Fi and Thread credentials.

Control devices

After your device was commissioned to the Google fabric, Mobile SDK also requested commissioning to a development fabric. This development fabric creates the credentials to control Matter devices right from the sample app, without having to switch to Google Home.

From the Home screen, you can toggle your device On or Off. Tap the device to access device details.

Device Added

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. Locate the most recent APK named GHSAFM-[version]-targetcommissioner, for example GHSAFM-1.0.1-targetcommissioner-debug.apk:

    Download the Target Commissioner

  2. Install the target commissioner.

    $ adb unroot && adb install GHSAFM-1.0.1-targetcommissioner-debug.apk
    
  3. From the Home screen, tap the device to display the device information. Tap Share.

    Share device

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

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:

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 Stack Overflow: