Build a mobile app using the Home APIs on Android

Key Concepts

Google Home APIs, Android app development, Device and Structure APIs, Commissioning APIs, Automation APIs, OAuth 2.0, Google Cloud Console, Permissions API, Kotlin flows, Data model (structures, rooms, devices, device types, traits, attributes, commands, events), Matter devices, Google Home ecosystem, Google Home Developer Console.

Building a Mobile App Using Home APIs on Android

Introduction

The video introduces the Google Home APIs and how to use them to build a mobile app on Android. The APIs enable developers to create richer and more integrated smart home experiences. Cloud-to-cloud and Matter remain central to connecting devices, and these APIs build upon that foundation. The video focuses on using the Device and Structure APIs to obtain and control devices, and the Commissioning APIs to add Matter devices. Automation APIs will be covered in a future video.

Prerequisites

To get started, you need:

• Latest version of Android Studio
• Android phone with Google Play services and the Google Home app
• Compatible Google Home hub for Matter devices
• Compatible smart home device (light, outlet, etc.) or virtual devices (Google Home Playground for cloud devices, Matter Virtual Device for Matter devices). Instructions for setting up virtual devices are available on the Developer Center.

Project Setup

1. Obtain the Home APIs SDK: Follow the instructions on the Developer Center (QR code provided).
2. Clone the sample app source code from GitHub: Open the source code in Android Studio. The code contains "To Do" blocks indicating where to add code.
3. Connect a physical Android phone: A physical phone is recommended because the Home APIs rely on Google Play services. Enable USB Debugging in Developer Options if needed.

Authentication (OAuth 2.0)

The Home APIs use OAuth 2.0 for authentication.

1. Google Cloud Console: Create a new project or select an existing one.
2. APIs & Services: Go to the Credentials page.
3. Configure Consent Screen: Choose "Internal" or "External" based on your use case. Add test users.
4. Register the sample app for OAuth 2.0: Indicate the application type as an Android app. Detailed instructions are available on the Developer Center (QR code provided).

Permissions API

The Permissions API handles user permissions.

1. Define supported device types and traits: In the HomeApp.kt file, add the device types and traits your app will support in the To Do blocks 4.1.1 and 4.1.2. Unregistered types and traits will be unsupported. Refer to the Developer Center for supported device types and traits.
2. Initialize the Home client: The HomeClient object is the main interface for interacting with the APIs. The factory registry uses the supported types and traits. The HomeConfig is initialized using this registry. The getClient() call retrieves the HomeClient from the SDK.
3. Authenticate users: In the PermissionsManager.kt file, implement To Do block 4.3.1 to enable the code that requests permissions and records the results using the checkPermissions() and requestPermissions() functions.

Device and Structure APIs

The data model consists of:

• Structures: Represent a home and contain rooms.
• Rooms: Contain devices.
• Devices: Composed of device types.
• Device Types: Composed of traits.
• Traits: Composed of attributes (read/write), commands (controlling attributes), and events (reading/subscribing to past changes).
• Automations: Part of a structure, use metadata to automate tasks.

Working with Structures:

1. Subscribe to structure changes: In the HomeAppViewModel.kt file, implement To Do 5.1.1 to subscribe to structure changes by calling the collect() function on the structures() flow.
2. Traverse the structure set: Store the ViewModels. Select the first structure if none is selected.
3. Render the structure list: In the DevicesView.kt file, implement To Do 5.1.2 to render the structure list as a dropdown menu.
4. Handle devices without rooms: Structures can contain devices not assigned to a room.
5. Traverse Home objects: In the StructureViewModel.kt file, implement To Do blocks 5.2.1 and 5.2.2 to subscribe to a flow to get the latest room and device list.
6. Render the room list: In the DevicesView.kt file, implement To Do blocks 5.2.3 and 5.2.4 to render the room list as a menu.

Working with Devices:

1. Retrieve device types and traits: In the DeviceViewModel.kt file, implement To Do blocks 6.1.1 and 6.1.2 to retrieve device states. 6.1.1 determines the primary types for a device, and 6.1.2 gets a list of supported traits.
2. Render traits: In the DeviceView.kt file, implement To Do block 6.1.3 to render an on/off trait.
3. Issue commands: Use convenience functions on trait objects (e.g., Trait.On, Trait.MoveToLevel). Implement To Do 6.2.1 to add function controls. Use IDE autocomplete to discover available actions for each trait.

Commissioning APIs (Matter Devices)

The Commissioning API adds Matter devices to the Google Home ecosystem.

1. Prerequisites: Requires a Matter device and a compatible Google hub. If using Matter Virtual Device, a developer project on the Google Home Developer Console is needed.
2. Set up variables: Create an activityResultLauncher (for sending the commissioning intent and managing the result callback) and a commissioningResult (to store the commissioning result).
3. Build and launch the commissioning intent: Place the intent and launcher in a dedicated function tied to a UI element (e.g., an "Add Device" button).
4. Enable commissioning: In the CommissioningManager.kt file, implement To Do 7.1.1 to enable commissioning.

The commissioning flow includes:

• QR code scanner
• User agreement
• Device discovery and commissioning
• Naming the device

The commissioning result is passed back to the callback function.

Conclusion

The video provides a step-by-step guide to building an Android app using the Google Home APIs. It covers authentication, permissions, device and structure management, and commissioning Matter devices. The next video will cover advanced automations.