The Google Home APIs for Android provide a unified API surface to enable developers to interact with the state of entities in a user's home. These entities can describe devices and non-device information associated with a user's structure and rooms.
The Home APIs define the following entities that a user can interact with:
- Structures represent a home that contains rooms and devices.
- Rooms are part of a structure and contain devices.
- Devices implement traits containing attributes, conform to types, emit events, and respond to commands.
- Automations are part of a structure and use home metadata and devices to automate tasks in the home.
Figure 1 illustrates this architecture:
Home API device types may be backed by Matter, an open standard for the smart home, or be a Cloud-to-cloud device in the Google Home ecosystem. Some device types may incorporate functionality from both. See Supported device types for more information.
In Matter, device functionality is grouped by clusters, which are represented in the Home APIs as Matter standard traits. The Home APIs support the standard set of Matter clusters as defined in the current Matter specification.
In the Google Home ecosystem, device functionality is grouped by smart home traits, which are represented in the Home APIs as Google smart home traits. The Home APIs support the set of smart home traits as defined in the Cloud-to-cloud program.
Other traits, such as Manufacturer-specific clusters and Platform traits, are also available. To learn more, see Data model.
Language
The Home APIs are written in Kotlin and provide an idiomatic Kotlin interface that uses Flow to manage state and subscription. This provides a number of advantages over a standard subscription API.
We recommend getting familiar with the Kotlin documentation on coroutines, flow, and Jetpack Compose, if you are not already:
- Develop Android apps with Kotlin
- Learn Kotlin for Androids
- Kotlin coroutines on Android. These specific codelabs may be useful:
- Kotlin flows on Android and more specifically, StateFlow.
- State and Jetpack Compose, specifically the
collectAsStateWithLifecycle()function. This function automatically manages subscribing and unsubscribing from the flows based on whether the UI showing that state is actually in the foreground or not. - If you're working with the Automation API, reading about Kotlin type-safe builders is useful in understanding how the Automation DSL works.
Entity identifiers
Each entity in the Home APIs has an ID which represents its primary identifier. This ID is a unique and stable identifier that will never change for the lifetime of the entity. This ID can be used to cache objects or check for equality as the metadata of an entity can change.
See the HasId interface to learn
what entities have an ID.
Terminology mapping
Entities in the Home APIs map to Matter and Cloud-to-cloud concepts as follows:
| Home APIs | Matter | Cloud-to-cloud |
|---|---|---|
| Trait | Cluster | Trait |
| Attribute | Attribute | Attribute, State |
| Command | Command | Command |
| Event | Event | Follow up response, Notification |