The Home APIs present all devices in the Google Home ecosystem in a unified data model. This data model covers all types of devices (from Google Nest or 3rd party manufacturers), regardless of the underlying smart home technology (such as Matter or Cloud-to-cloud), and provides a common API surface to build user experiences for both smart home and mobile app developers.
Device types
The device types presented in the Home APIs are a unification of Matter and Cloud-to-cloud data models. Some are derived directly from Matter, some are an extension of Matter device types, and some are derived from Cloud-to-cloud.
Device types contain traits that are used to control and manage devices. Like device types, traits are derived from Matter clusters and Cloud-to-cloud traits and presented in a common format that is similar to that of Matter clusters. In the Home APIs, Matter-derived traits are called traits, not clusters.
As such, device types and traits in the Home APIs are intended to be Matter-first. A Matter device type or trait takes precedence over a Cloud-to-cloud analog.
See Supported device types for a list of device types and their traits.
Traits
Kotlin versions of traits are generated for use in the Home APIs, and contain additional features specific to the Home APIs (not found in Matter or Cloud-to-cloud). For example, each trait has methods to check whether a trait supports a specific attribute or command. This is useful when determining whether reading of state or certain actions can be carried out on a user's device, since not all devices in a device type are expected to have all the same features.
Each trait is contained in its own namespace and must be imported individually for use.
For example, to use the Matter On/Off trait and On/Off Plug-in Unit device type, import the following packages into your application:
import com.google.home.matter.standard.OnOff
import com.google.home.matter.standard.OnOffPluginUnitDevice
For a Garage device type (from the Google smart home), include a mix of Matter and Google traits:
import com.google.home.google.LockUnlock
import com.google.home.matter.standard.DoorLock
import com.google.home.matter.standard.GoogleGarageDevice
Android Studio has auto-complete functionality and will often
handle the full package names for you when adding import lines to source files
in your project. However, package names are not consistent across all device
types and traits. See the reference to verify the correct package name for each
DeviceType or
Trait.
Traits are also supported for use with Automations, but may be limited, and some traits are only available for Automations. For a list, see Automation API trait support.
Device type composition
The Home APIs support most Matter 1.3 application clusters as traits in the data model. Traits that don't correspond to device control or states and don't offer any utility for end users, such as Binding and Groups, are not exposed through the Home APIs.
Traits derived from Cloud-to-cloud smart home traits typically have
the same name between Cloud-to-cloud and the Home APIs, such as in
the example of OpenClose. Others are represented as extensions of
Matter traits, created using Matter
manufacturer-specific extensions. These traits bridge the gap for a
smart home trait where functionality is split between the
Matter SDK and the Google Home ecosystem. A specific
example of this are the Google* device types which come from
Cloud-to-cloud but don't have Matter analogs yet.
Device types are composed of traits from one or both sources, Matter or Cloud-to-cloud.
For example, the Fan device type is composed of both and features two FanControl traits:
- The FanControl Matter trait provides all the functionality from the Matter FanControl trait
- The ExtendedFanControl Google trait provides all the functionality from the Google smart home FanSpeed trait that is not covered by the FanControl Matter trait
This type of trait composition provides a flexible model for complete device type functionality, abstracting the underlying smart home data models.