Обзор API автоматизации на Android

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

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

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

Автоматизация выполняется с использованием Automation DSL, предметно-ориентированного языка, предназначенного для создания автоматизированных процессов на Kotlin.

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

Рекомендации в случае отзыва пользователем полных прав доступа

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

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

При отзыве доступа к структуре в вашу облачную среду отправляется событие StructureAccessRevokedEvent . Подробную информацию о полном процессе отзыва доступа к облачным сервисам и мобильным приложениям партнеров см. в разделе «Предоставление доступа к структуре» .

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

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

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

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

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

Предложения по автоматизации

API-интерфейсы Home могут предлагать варианты автоматизации для конкретной 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 во время выполнения.

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

В языке автоматизации 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 ).

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

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