Data model on iOS

The Home APIs for iOS 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 on iOS for a list of device types and their traits.

Traits

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

To import traits and device types, import the GoogleHomeTypes module into your application:

import GoogleHomeTypes

Also, you can use typealias for trait and device type names to shorten code and avoid namespace repetition:

import GoogleHomeTypes

typealias OpenCloseTrait = Google.OpenCloseTrait
typealias OnOffTrait = Matter.OnOffTrait
typealias FanDevice = Matter.FanDeviceType

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

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 OpenCloseTrait. 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 FanDeviceType is composed of both and features three traits:

  • The IdentifyTrait Matter trait provides all the functionality from the Matter IdentifyTrait.
  • The FanControlTrait Matter trait provides all the functionality from the Matter FanControlTrait.
  • The ExtendedFanControlTrait Google trait provides all the functionality from the Google smart home FanSpeedTrait that is not covered by the FanControlTrait Matter trait.

This type of trait composition provides a flexible model for complete device type functionality, abstracting the underlying smart home data models.