Обзор Automation API для Android

Автоматизации позволяют автоматизировать задачи и настройки устройств в доме. Автоматизации доступны в экосистеме Google Home в виде программ в Google Home app (GHA) и через automation script editor на Google Home for web.

Теперь автоматизации в экосистеме Google Home доступны через Home API для Android. В них используются те же базовые концепции, что и в программах GHA и script editor, но с расширенными функциями и возможностями, доступными только через Home API, в том числе:

• Доступ ко всем стандартным (Matter) и smart home свойствам устройства, представленным в Home API.
• Поддержка последовательных, параллельных и выборочных потоков выполнения.

Автоматизации пишутся на Automation DSL – предметно-ориентированном языке, предназначенном для создания автоматизаций в Kotlin.

Все характеристики и типы, которые вы планируете использовать в приложении с Device & Structure API или Automation API, должны быть зарегистрированы при инициализации. Подробнее о том, как инициализировать дом на Android…

Что делать, если пользователь отзывает полные разрешения

Если пользователь отзовет полные разрешения, все существующие автоматизации перестанут работать. Если пользователь отзовет доступ к определенным устройствам, то связанные с ними условия, действия и триггеры перестанут работать.

При каждом запуске приложения проверяйте, действуют ли разрешения. Если разрешения были отозваны, убедитесь, что все предыдущие данные удалены, включая данные, кэшированные в приложении.

Когда доступ к дому отзывается, в облачный бэкенд отправляется запрос StructureAccessRevokedEvent. Полный рабочий процесс отзыва разрешений для облака и мобильного приложения партнера описан в разделе Разрешения для структуры.

Путь разработчика

Automation API – это лишь часть более крупного процесса разработки. Она выполняется после интеграции Structure API и Device API, чтобы пользователи могли запускать автоматизации.

1. Разработчик планирует автоматизацию и определяет ее с помощью DSL автоматизации.
2. Разработчик встраивает определение автоматизации в приложение Android на Kotlin.
3. Приложение предлагает пользователю автоматизации на основе информации о его устройствах, включая характеристики, атрибуты, команды и события, собранные с помощью Discovery API или Device API.
   1. С помощью Discovery API приложение может создать черновик автоматизации, настроенный для типов устройств и функций, присутствующих в структуре пользователя, с вводом данных пользователем или без него.
   2. Device API может предоставлять большую часть той же информации, что и Discovery API, но он не оптимизирован для автоматизации. Подробнее о сравнении Device API и Discovery API…
4. Приложение создает автоматизацию, привязанную к выбранной структуре.
5. Теперь автоматизация доступна в структуре пользователя и может быть выполнена или удалена с помощью методов Structure API.

Пользователь может в любой момент создать новые экземпляры автоматизации, выбрав другой дом или, в зависимости от логики приложения, другой набор устройств. Каждый раз, когда они это делают, приложение генерирует новый экземпляр автоматизации.

В самом простом сценарии вы можете предложить пользователям предопределенную автоматизацию, которая выполняет относительно простую задачу. Или вы можете предложить пользователю шаблон автоматизации, который он сможет настроить под свои нужды. Или вы можете написать редактор автоматизации открытого типа, который позволит пользователю создавать сложные автоматизации, используя все стандартные блоки, доступные в Automation API.

Предложения программ

   Реализовано в примере приложения для Android   

Home API может предлагать автоматизации для Structure на основе таких факторов, как типы устройств, присутствующих в пространстве.

Предложения программ представлены классом AutomationSuggestion.

Интерфейс Structure включает интерфейс HasSuggestions, который предоставляет функцию suggestions(), возвращающую коллекцию предложений по автоматизации.

Методы likeSuggestion() и dislikeSuggestion() предназначены для подключения к элементам управления пользовательского интерфейса thumb_up и thumb_down, на которые пользователь может нажать, чтобы оставить отзыв.

Третий метод, clearSuggestionFeedback(), позволяет пользователю удалить свой отзыв о предложенной автоматизации.

Отзывы пользователей влияют на будущие предложения.

В этом примере показано, как получить доступные предложения по автоматизации для Structure, извлечь идентификатор предложения и записать отзыв пользователя с помощью likeSuggestion(), clearSuggestionFeedback() и dislikeSuggestion().

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.google.home.Structure
import kotlinx.coroutines.launch

class AutomationSuggestionsViewModel(private val structure: Structure) : ViewModel() {

  fun loadAndGiveFeedback() {
    viewModelScope.launch {
      // 1. Fetch suggestions from structure
      val suggestions = structure.suggestions()
      val firstSuggestion = suggestions.firstOrNull() ?: return@launch

      // Extract string suggestion ID
      val suggestionId: String = firstSuggestion.id.id

      // 2. Like the suggestion (thumbs up)
      val liked = structure.likeSuggestion(suggestionId)

      // 3. Clear previous feedback if the user toggled it off
      if (liked) {
        structure.clearSuggestionFeedback(suggestionId)
      }

      // 4. Dislike the suggestion (thumbs down)
      structure.dislikeSuggestion(suggestionId)
    }
  }
}

Динамические параметры команд

Динамические параметры команд позволяют разработчикам создавать параметры действий, которые разрешаются динамически во время выполнения, а не полагаются строго на статические постоянные значения. Это дает две основные возможности:

• Ссылки, которые передают значение свойства от узла запуска (например, полезной нагрузки события) или узла считывания состояния, или от локальных переменных, объявленных в рамках автоматизации.
• Выражения, которые фиксируют динамические значения времени выполнения (например, свойство события или значение состояния) и передают их непосредственно в параметр команды.

Пример использования

Привяжите физический поворотный переключатель, который отправляет событие многократного нажатия, к светильнику с регулируемой яркостью. Количество кликов – это динамическое значение, которое передается в команду шага LevelControl во время выполнения.

Как работают динамические параметры

В Automation DSL на Android параметры команд принимают экземпляры Expression или Reference непосредственно вместо статических постоянных значений. При создании автоматизации DSL инкапсулирует их в определения Parameter.

Правила проверки данных

Параметры динамических команд должны соответствовать следующим ограничениям:

• Динамические параметры считаются структурно допустимыми во время обнаружения, поскольку API обнаружения оценивают только ограничения конкретных значений для статических аргументов.
• Узлы ссылок или выражений должны появляться в графе автоматизации выше, чем они упоминаются в действии команды.

Как использовать динамические параметры команд на Android

Передавайте динамические выражения напрямую в параметры команд:

import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.fieldSelect
import com.google.home.automation.sequential
import com.google.home.automation.starter
import com.google.home.matter.standard.DimmableLightDevice
import com.google.home.matter.standard.DimmerSwitchDevice
import com.google.home.matter.standard.LevelControl
import com.google.home.matter.standard.LevelControlTrait.StepModeEnum
import com.google.home.matter.standard.Switch

val keypressAutomation = automation {
  name = "Dynamic command parameters example"
  description = "Pass starter event field directly to command"
  sequential {
    val dimmerStarter = starter(
      dimmerSwitch,
      DimmerSwitchDevice,
      Switch.MultiPressOngoingEvent,
    )

    val clickCountExpr = fieldSelect<Switch.MultiPressOngoingEvent, UInt>(
      dimmerStarter,
      Switch.MultiPressOngoingEvent.EventFields.currentNumberOfPressesCounted,
    )

    action(dimmableLight, DimmableLightDevice) {
      command(
        LevelControl.step(
          stepMode = StepModeEnum.Up,
          stepSize = clickCountExpr,
        )
      )
    }
  }
}

Вы также можете присвоить выражение объявлению локальной переменной и ссылаться на нее в дальнейшем:

import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.fieldSelect
import com.google.home.automation.sequential
import com.google.home.automation.starter
import com.google.home.automation.variable
import com.google.home.matter.standard.DimmableLightDevice
import com.google.home.matter.standard.DimmerSwitchDevice
import com.google.home.matter.standard.LevelControl
import com.google.home.matter.standard.LevelControlTrait.StepModeEnum
import com.google.home.matter.standard.Switch

val myAutomationWithVariable = automation {
  name = "Dynamic command parameters with variables"
  description = "Declare a variable, assign value, and pass reference"
  sequential {
    val dimmerStarter = starter(
      dimmerSwitch,
      DimmerSwitchDevice,
      Switch.MultiPressOngoingEvent,
    )

    val clickCountExpr = fieldSelect<Switch.MultiPressOngoingEvent, UInt>(
      dimmerStarter,
      Switch.MultiPressOngoingEvent.EventFields.currentNumberOfPressesCounted,
    )

    val clickCountVar = variable<UInt>()
    clickCountVar.assign(clickCountExpr)

    action(dimmableLight, DimmableLightDevice) {
      command(
        LevelControl.step(
          stepMode = StepModeEnum.Up,
          stepSize = clickCountVar,
        )
      )
    }
  }
}

Ограничения по типу

Убедитесь, что типы переменных и выражений соответствуют типу схемы Matter, который требуется для параметра команды-получателя (например, UShort, UByte или UInt8).

Ограничения ресурсов

Для автоматизаций в Home API действуют следующие ограничения: