Omówienie interfejsu Automation API na Androidzie

Automatyzacje umożliwiają automatyzowanie zadań i ustawień urządzeń w domu. Automatyzacje są dostępne w ekosystemie Google Home jako rutyny w Google Home app (GHA) oraz za pomocą automation script editor na Google Home for web.

Automatyzacje w ekosystemie Google Home są teraz dostępne za pomocą interfejsów Home API na Androida. Korzystają one z tych samych podstawowych koncepcji co GHA rutyny w aplikacji Google Home i script editor, ale mają ulepszone funkcje i możliwości, które są dostępne tylko dzięki interfejsom Home API, w tym:

• dostęp do wszystkich Matter standardowych i smart home cech urządzenia, które są prezentowane w interfejsach Home API;
• obsługę sekwencyjnych, równoległych i wybranych przepływów wykonywania.

Automatyzacje są pisane w języku Automation DSL, czyli języku specyficznym dla domeny, który został zaprojektowany do tworzenia automatyzacji w Kotlinie.

Wszystkie cechy i typy, których chcesz używać w aplikacji z interfejsami Device &Structure API lub Automation API, muszą zostać zarejestrowane podczas inicjowania. Więcej informacji znajdziesz w artykule Inicjowanie domu na Androidzie.

Wskazówki, jeśli użytkownik cofnie pełne uprawnienia

Jeśli użytkownik cofnie pełne uprawnienia, wszystkie dotychczasowe automatyzacje przestaną działać. Jeśli użytkownik cofnie dostęp do określonych urządzeń, przestaną działać też elementy początkowe, warunki i działania powiązane z tymi urządzeniami.

Za każdym razem, gdy uruchamiasz aplikację, sprawdzaj, czy uprawnienia nadal obowiązują. Jeśli zostały cofnięte, usuń wszystkie poprzednie dane, w tym dane zapisane w pamięci podręcznej aplikacji.

Gdy dostęp do domu zostanie cofnięty, do Twojego backendu w chmurze zostanie dostarczone zdarzenie StructureAccessRevokedEvent. Zapoznaj się z artykułem Przyznawanie dostępu do domu, aby dowiedzieć się więcej o całym procesie cofania dostępu w chmurze partnera i aplikacji mobilnej.

Ścieżka dewelopera

Interfejs Automation API jest częścią większego procesu tworzenia aplikacji. Następuje po zintegrowaniu interfejsów Structure i Device API, aby zapewnić użytkownikowi możliwość korzystania z automatyzacji.

1. Deweloper planuje automatyzację i definiuje ją za pomocą języka Automation DSL.
2. Deweloper osadza definicję automatyzacji w aplikacji na Androida w Kotlinie.
3. Aplikacja prezentuje użytkownikowi automatyzacje na podstawie informacji o jego urządzeniach, w tym o cechach, atrybutach, poleceniach i zdarzeniach, które zostały zebrane za pomocą interfejsu Discovery API lub Device API.
   1. Za pomocą interfejsu Discovery API aplikacja może wygenerować wersję roboczą automatyzacji dostosowaną do typów urządzeń i cech występujących w domu użytkownika, z jego udziałem lub bez niego.
   2. Interfejs Device API może dostarczyć większość tych samych informacji co interfejs Discovery API, ale nie jest zoptymalizowany pod kątem przypadków użycia automatyzacji. Więcej informacji znajdziesz w artykule Porównanie interfejsów Device API i Discovery API.
4. Aplikacja tworzy rzeczywistą automatyzację, która jest powiązana z wybranym domem.
5. Automatyzacja jest teraz dostępna w domu użytkownika i można ją uruchomić lub usunąć za pomocą metod interfejsu Structure API.

Użytkownik może w każdej chwili utworzyć nowe instancje automatyzacji, wybierając inny dom lub, w zależności od logiki aplikacji, być może inny zestaw urządzeń. Za każdym razem, gdy to zrobi, aplikacja wygeneruje nową instancję automatyzacji.

W najbardziej podstawowym scenariuszu możesz zaproponować użytkownikom predefiniowaną automatyzację, która wykonuje stosunkowo proste zadanie. Możesz też przedstawić szkielet automatyzacji, który użytkownik dostosuje do swoich potrzeb. Możesz też napisać otwarty edytor automatyzacji, który pozwoli użytkownikowi tworzyć złożone automatyzacje za pomocą wszystkich elementów dostępnych w interfejsie Automation API.

Sugestie automatyzacji

Interfejsy Home API mogą sugerować automatyzacje dla Structure na podstawie takich czynników jak typy urządzeń znajdujące się w danym miejscu.

Sugestie automatyzacji są reprezentowane przez klasę AutomationSuggestion.

Interfejs Structure obejmuje interfejs HasSuggestions, który udostępnia funkcję suggestions(), która zwraca zbiór sugestii automatyzacji.

Metody likeSuggestion() i dislikeSuggestion() mają być połączone z elementami interfejsu użytkownika thumb_up i thumb_down, które użytkownik może kliknąć aby przekazać opinię.

Trzecia metoda, clearSuggestionFeedback(), umożliwia użytkownikowi usunięcie opinii o sugerowanej automatyzacji.

Opinie użytkowników wpływają na przyszłe sugestie.

Ten przykład pokazuje, jak pobrać dostępne sugestie automatyzacji dla Structure, wyodrębnić identyfikator sugestii i zarejestrować opinię użytkownika za pomocą likeSuggestion(), clearSuggestionFeedback(), i 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)
    }
  }
}

Parametry poleceń dynamicznych

Parametry poleceń dynamicznych umożliwiają deweloperom tworzenie parametrów działań, które są rozwiązywane dynamicznie w czasie działania, a nie tylko na podstawie statycznych, stałych wartości. Umożliwia to 2 główne funkcje:

• Odwołania, które przekazują wartość właściwości z elementu początkowego (np. ładunku zdarzenia) lub węzła czytnika stanu albo ze zmiennych lokalnych zadeklarowanych w przepływie automatyzacji.
• Wyrażenia, które przechwytują dynamiczne wartości w czasie działania (np. właściwość zdarzenia lub wartość stanu) i przekazują dynamiczną wartość bezpośrednio do parametru polecenia.

Przypadek użycia

Powiąż fizyczny przełącznik obrotowy, który wysyła zdarzenie wielokrotnego naciśnięcia, ze ściemnianym światłem. Liczba kliknięć to wartość dynamiczna przekazywana do polecenia kroku LevelControl w czasie działania.

Jak działają parametry dynamiczne

W języku Automation DSL na Androidzie parametry poleceń akceptują Expression lub Reference instancje bezpośrednio zamiast statycznych wartości stałych. Podczas tworzenia automatyzacji język DSL hermetyzuje je w Parameter definicjach.

Reguły weryfikacji

Parametry poleceń dynamicznych podlegają tym ograniczeniom weryfikacji:

• Podczas wykrywania przyjmuje się, że parametry dynamiczne są strukturalnie prawidłowe, ponieważ interfejsy Discovery API sprawdzają tylko ograniczenia wartości konkretnych argumentów statycznych.
• Węzły odwołań lub wyrażeń muszą występować w górę w grafie automatyzacji, zanim zostaną do nich odwołane w działaniu polecenia w dół.

Używanie parametrów poleceń dynamicznych na Androidzie

Przekazuj wyrażenia dynamiczne bezpośrednio do parametrów poleceń:

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,
        )
      )
    }
  }
}

Możesz też przypisać wyrażenie do deklaracji zmiennej lokalnej i odwołać się do niej później w przepływie:

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,
        )
      )
    }
  }
}

Ograniczenia typu

Upewnij się, że typy zmiennych i wyrażeń są zgodne z wymaganą definicją typu schematu parametru polecenia odbierającegoMatter (np. UShort, UByte lub UInt8).

Limity zasobów

Automatyzacje w interfejsach Home API podlegają tym ograniczeniom: