Create advanced automations using the Home APIs on Android

Key Concepts

Automations, Starters, Conditions, Actions, Nodes (Sequential, Parallel), Domain-Specific Language (DSL), Resource Limits, Automation Editor, Device API, Trait, Command, Value, Draft Automation, Validation, Manual Execution, Starter Event, Discovery API, Command Candidate, Event Candidate, Trait Attributes Candidate, Structure-Based Traits, Time-Based Starters, Assistant Broadcast, DelayFor, SuppressFor, Area-Presence State.

Automations Overview

Automations are defined as "if-this-then-that" statements used to automate device state control based on specified factors. They comprise three core components:

• Starters: Initiate the automation, triggered by a change to a trait value. Essential for every automation.
• Conditions: Additional constraints evaluated after the starter is triggered. The condition's expression must evaluate to "true" for actions to execute.
• Actions: Commands or state updates performed when all conditions are met.

These components, or nodes, are evaluated by the automation engine sequentially or in parallel. Sequential flows execute nodes in order (starter -> condition -> action), while parallel flows can execute multiple actions simultaneously. The DSL (Domain-Specific Language) is used to provide these nodes to the automation engine. Resource limits exist, such as a maximum number of nodes per automation, detailed in the Google Home Developer Center.

Example: Dimming lights when a switch is toggled and the TV is on involves:

• Starter: Switch is toggled.
• Condition: TV is on.
• Action: Lights are dimmed.

Building an Automation Editor

The video provides steps on how to create an editor to allow users to configure automations, defining devices, commands, and parameters themselves.

Setting up Starters

1. Starter ViewModel (Kotlin): Requires a device, trait, operation, and value. Devices and traits are from the Device API. Commands and parameters are handled separately.
2. The app defines a preset list of operations and then for each supported trait, a list of supported operations.
3. Values assignable to traits and their API-defined mappings are tracked.
4. Starter View File:
   • TODO 4.1.1: Render all starter devices in a dropdown menu.
   • TODO 4.1.2: Render all traits of the starter devices.
   • TODO 4.1.3 & 4.1.4: Render operations and values of the selected trait, respectively.
   • TODO 4.1.5: Store starter ViewModel variables into the draft.

Implementing Actions

1. Automation action nodes require a device, trait, command, and value. Device and trait can be selected using the Device API. The app comes with a predefined list of commands and for each trait a list of supported operations.
2. Commands can take parameters (e.g., brightness percentage for "moveToLevel").
3. Action View (Kotlin):
   • TODO 4.2.1: Render all action devices in a dropdown menu to set action device VM.
   • TODO 4.2.2: Render all traits of action device VM in a dropdown menu to set the action trait.
   • TODO 4.2.3: Render all available actions of the action trait to set action action then render the available values of trait action.
   • TODO 4.2.4: Store the value into action value level.
   • TODO 4.2.5: Store all action view models variables in the draft automations action view model.

Automation Draft and Execution

Draft automation preparation occurs in the draft view model class, specifically the getDraftAutomation function.

1. TODO 4.4.1: Set starter expressions according to trait type (e.g., creating expressions for the on-off trait).
2. TODO 4.4.2: Implement parallel expressions for actions (e.g., level control and moveToLevel).
3. TODO 4.4.3: Create the automation by calling the Home APIs and handling exceptions.

Validation: Automations are validated upon creation. isValid = false indicates an invalid automation, with details in the validation_issues field.

Execution: Automations can be executed via a starter event (if conditions match) or a manual execution API call. The sample app provides a "Manual Execute" button. A manual starter function must be defined for this option.

Example: Toggling outlet one (starter) to "on" sets light two's level control (action) to 100%.

Discovery API

The Discovery API is used to query devices for supported attributes and commands.

1. The candidates function retrieves a list of candidates (command, event, trait attributes).
2. TODO 5.1.1 (Home App ViewModel Kotlin): Retrieve the candidate list and filter for the candidate type.
3. TODO 5.1.2: Set the supported commands in the command map defined.

To integrate the Discovery API into the editor, display the list of discovered actions to the user, allowing pre-population of action nodes based on the user's selection.

TODO 5.2.1 (Candidate's View File): Enable the candidate list items clickable function, which sets the selected draft VM to the selected candidate.

Advanced Automation Examples

The video highlights more advanced automation capabilities beyond the sample app:

• Structure-Based Traits (Time): Automations with time-based starters.

  // Example: Scheduled time event as starter, then perform an action.
  

• Assistant Broadcast: Using assistant broadcast as an action.

  // Example: Announce "Time is up" via assistant broadcast.
  

• DelayFor and SuppressFor: DelayFor delays commands; SuppressFor prevents re-triggering within a time span.

  // Example: Suppress starter for 1 minute after triggering; delay broadcast by 3 seconds.
  

• Area-Presence State: Detecting if anyone is home.

  // Example: Lock doors if someone is at home after 10:00 PM.
  

Conclusion

The video details how to create automations using the Google Home APIs on Android. It covers the core components of automations (starters, conditions, actions), building an automation editor, using the Discovery API to find supported commands, and more advanced automation scenarios. It emphasizes the use of the Domain-Specific Language (DSL) for defining automation logic and provides actionable insights for integrating automations into custom Android apps. The automation API provides several building blocks with different functions which can then be combined to create complex automations.