Google's Home Developer program allows device manufacturers to connect their smart home devices with the Google Home ecosystem. We are expanding the Smart Home Actions local fulfillment path with the ability to add Matter-enabled devices for setup using the Google Home app (GHA) and control them using Google Assistant, GHA, or smart displays like the Google Nest Hub (2nd gen).
This documentation describes how to get started with building and integrating a Matter-supported platform in the Google Home ecosystem.
Disclaimers
Regarding the procedures described in the Matter documentation, be aware of the following:
- We recommend that the account used for development only have a single Matter-enabled hub connected for testing. Multiple Matter-enabled hubs connected at the same time or connected to the same structure during testing could result in unpredictable behavior.
- All procedures assume the use of a Linux machine running Ubuntu 20.04 for building and flashing Matter samples, which have been tested by Google. While macOS machines are supported, Linux is recommended. Mac-specific instructions are called out in the procedures as needed.
How to build
To build a Matter-enabled device that integrates with the Google Home ecosystem, you'll work with a Matter-compatible development board and the Matter SDK.
The easiest way to get started is by going through our codelabs. We recommend doing at least one of the following codelabs:
Enable local fulfillment for Cloud-to-cloud integrations
49 minutes
Updated November 27, 2024
Learn to enable local fulfillment with the Local Home SDK to enhance smart home integrations with the Assistant.
Debugging the Local Home
50 minutes
Updated November 20, 2024
Learn how to use GCP Metrics and Logging to identify and resolve production issues. Learn how to use the Test Suite to identify functional and API issues. Learn how to use Chrome Dev Tools while developing your Local Home app.
Enhance and secure your Cloud-to-cloud integrations
50 minutes
Updated November 20, 2024
Learn to enhance and secure your Cloud-to-cloud integration through customizable device traits and secure them with two-factor authentication.
Implement CameraStream with WebRTC
23 minutes
Updated November 20, 2024
Learn how to stream from a webcam to a Google Nest display device with the CameraStream trait and WebRTC.
Connect smart home devices to the Google Assistant
35 minutes
Updated November 20, 2024
Build and deploy a Cloud-to-cloud integration to integrate a virtual smart washer to the Assistant.
Monitoring Outages for Smart Home
31 minutes
Updated November 20, 2024
In this codelab, learn how to detect outages by setting up automated alerts on your Smart Home integration.
Debugging the Smart Home
25 minutes
Updated November 20, 2024
Learn how to use GCP Metrics and Logging to identify and resolve production issues. Learn how to use the Test Suite to identify functional and API issues.
Log-based Metrics for Smart Home
16 minutes
Updated November 20, 2024
Learn how to use Log-based Metrics on Google Cloud to track patterns and analyze your Smart Home integration error logs.
Build a Custom Web Receiver
1 hour 37 minutes
Updated September 18, 2024
In this codelab, you will build a Custom Web Receiver app to play content on Cast-enabled devices.
Cast-enable an iOS app
2 hours 28 minutes
Updated September 18, 2024
In this codelab, you will modify an existing iOS video app to cast content on a Google Cast-enabled device.
Cast-enable an Android app
2 hours 48 minutes
Updated September 18, 2024
In this codelab, you will modify an existing Android video app to cast content on a Google Cast-enabled device.
Cast-enable an Android TV app
1 hour 8 minutes
Updated September 18, 2024
In this codelab, you will modify an existing Android TV app to support casting and communication from your existing Cast sender apps.
Add live support to a Cast Receiver
30 minutes
Updated September 18, 2024
In this codelab, you will build a Custom Web Receiver application that uses the Cast Live API.
Add Ad Breaks API Support to a Web Receiver
56 minutes
Updated September 18, 2024
In this codelab, you will build a Custom Web Receiver application that uses the Cast Ad Breaks API.
Cast-enable a web app
1 hour 18 minutes
Updated September 18, 2024
In this codelab, you will modify an existing web video app to cast content on a Google Cast-enabled device.
Debugging Cast Receiver Apps
59 minutes
Updated September 18, 2024
In this codelab, you will add the Cast Debug Logger to your existing Custom Web Receiver app.
Build an Android App for Matter
1 hour 17 minutes
Updated August 29, 2024
Customize the Google Home Sample App for Matter to commission and manage devices.
Building a Device Access Web Application
1 hour
Updated August 7, 2024
In this Codelab, you’ll learn how Device Access works and build a web application that handles authentication and Smart Device Management API calls for a Nest Thermostat.
Build a Matter virtual device
1 hour 12 minutes
Updated August 1, 2024
In this codelab, you’ll build, commission, and use a virtual Matter device.
Debugging Matter Integrations
36 minutes
Updated December 26, 2023
Learn how to troubleshoot Matter integrations using analytics tools and find out more about the developer support resources.
Build a Matter device
1 hour 17 minutes
Updated October 2, 2023
In this codelab, you’ll build, commission, and use a Matter device.
After that, check our list of supported devices to ensure that what you plan to integrate is supported in the Google Home ecosystem. Then read through the Developer Checklist to understand the entire development flow from project creation to launch.
Supported Devices Developer Checklist
Definitions
The following terms are used throughout this documentation:
- Border router
- A hub that implements a general-purpose Thread Border Router for Thread-enabled devices.
- Hub
- A supported Google Nest device, such as the Google Nest Hub (2nd gen). A hub is required to control Matter-enabled devices through other surfaces such as Assistant, the GHA, and smart displays.
- Matter-enabled device
- A device or development board that has been flashed with a Matter-enabled build or sample app.
- Mobile device
- The test phone used to assist with pairing. Currently this is an Android phone.
Prerequisites
In order to fully integrate a Matter-enabled device with the Google Home ecosystem, a developer must have:
- A Google hub with Thread support to serve as both a Border Router for Thread-enabled devices and as a local fulfillment path for routing Smart Home intents.
- A mobile device (test phone) that meets the minimum requirements:
- Android O (8.1, API level 27 or newer)
- iOS (v16.5 or newer)
- BLE capability
- A Vendor ID (VID) and Product ID (PID) for the Matter-enabled device.
- A Matter-enabled device. This device should be one of
the Matter device types supported in the
Google Home ecosystem, and could be:
- Your own product with Matter-enabled firmware.
- One of the following Matter devices to use for end-to-end verification:
Vendor | Platform | Thread Support | Guide |
---|---|---|---|
Bouffalo Lab | BL602 | ||
BL702 | |||
Espressif | ESP32 | OTA Testing | |
Nordic Semiconductor | nRF52840 DK | OTA Testing | |
NXP | IOTZTB-DK006 development kit | ||
Realtek | Ameba D Series | ||
Silicon Labs | EFR32MG24 Dev Kit | ||
EFR32MG Zigbee and Thread Starter Kit | |||
Telink | TLSR9518 | ||
Texas Instruments | CC2652R7 LaunchPad development kit |
Vendor ID
By default, you can use one of the VIDs allocated by the CSA for testing
purposes. Select one of the following:
0xFFF1
, 0xFFF2
, 0xFFF3
, 0xFFF4
.
To use a Production VID so that your integration can be certified and launched, you must first have it verified by Google to ensure that it has been issued to you by the CSA.
This VID should be implemented in your device's firmware.
A Matter device can only be paired in the Google Home ecosystem in certain Vendor ID and device type scenarios.
- A test VID cannot be used in a consumer device.
- Your production VID must issued by the Connectivity Standards Alliance (Alliance). Google will validate you're the owner of that VID before you can use it in the Google Home Developer Console. Once that happens you'll be able to create integrations for that VID.
- For development and Field Trial purposes, a project and integration with the corresponding VID and PID combination must be created in the Developer Console. The user commissioning the device must either be a member of the project or be included in the list of Field Trial users.
- Consumer users can only use your product once it has been certified by the Alliance.
VID and PID can only be used once for one integration. If you want to use the same VID or PID in your integration, you need to either:
- Edit the integration using the VID or PID to a different VID or PID.
- Delete the integration using the VID or PID.
Which types of users can commission the device into the Google Home ecosystem? | |||
---|---|---|---|
VID type | VID certification and console integration status | Production
(Consumer users) |
Development
(Developers, Field Trial users) |
Test | No integration in the Developer Console (cannot be certified) | ||
Test | Integration exists in the Developer Console (cannot be certified) | ||
Production | Not certified, integration does not exist in the Developer Console | ||
Production | Not certified, integration exists in the Developer Console | ||
Production | Certified in the Alliance DCL, integration does not exist in the Developer Console | ||
Production | Certified in the Alliance DCL and integration exists in the Developer Console |
Product ID
Information about the device is read from the Matter Basic Information Cluster. The Product ID encoded in your device's firmware must match the Product ID of the Matter integration in the Developer Console.
Unsupported features
Some Matter clusters are not yet exposed to users, though they may be used by the system. In most cases, this means that attributes exposed through these clusters aren't visible to end users:
Cluster Type | Clusters |
---|---|
Core |
|
Application |
|
¹ See On/Off Light Switches for how this impacts On/Off Light Switches.