Omówienie interfejsu Automation API na Androidzie

Automatyzacje to sposób na automatyzację zadań i ustawień urządzeń w domu. Automatyzacje są dostępne w ekosystemie Google Home jako rutyny w Google Home app (GHA) i w automation script editor na Google Home for web.

Teraz automatyzacje w ekosystemie Google Home są dostępne za pomocą interfejsów Home API na Androida. Wykorzystują one te same podstawowe koncepcje co rutyny GHA i script editor, ale mają ulepszone funkcje i możliwości, które są dostępne tylko dzięki interfejsom Home API, takie jak:

• Dostęp do wszystkich cech standardowych (Matter) i smart home urządzenia, zgodnie z interfejsami Home API.
• Obsługa sekwencyjnych, równoległych i wybranych przepływów wykonywania.

Automatyzacje są pisane przy użyciu Automation DSL, języka dziedzinowego przeznaczonego do tworzenia automatyzacji w Kotlinie.

Wszystkie cechy i typy, których zamierzasz używać w aplikacji z interfejsami API Device & Structure lub Automation, muszą zostać zarejestrowane podczas inicjowania. Zobacz Inicjowanie domu na Androidzie.

Wskazówki dotyczące sytuacji, gdy użytkownik cofnie pełne uprawnienia

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

Przy każdym uruchomieniu aplikacji sprawdź, czy uprawnienia są nadal aktywne. Jeśli zostały unieważnione, upewnij się, że wszystkie poprzednie dane zostały usunięte, w tym dane zapisane w pamięci podręcznej aplikacji.

Gdy dostęp do domu zostanie cofnięty, do backendu w chmurze zostanie dostarczone zdarzenie StructureAccessRevokedEvent. Informacje o całym procesie wycofywania uprawnień do domu w aplikacji partnera w chmurze i na urządzeniach mobilnych znajdziesz w artykule Uprawnienia do domu.

Ścieżka dewelopera

Interfejs Automation API to tylko jeden z elementów procesu programowania. Następuje po zintegrowaniu interfejsów Structure API i Device API, aby użytkownik mógł korzystać z automatyzacji, gdy tego potrzebuje.

1. Deweloper planuje automatyzację i definiuje ją za pomocą języka DSL automatyzacji.
2. Deweloper umieszcza definicję automatyzacji w aplikacji na Androida napisanej w języku Kotlin.
3. Aplikacja prezentuje użytkownikowi automatyzacje na podstawie informacji o jego urządzeniach, w tym cech, atrybutów, poleceń i zdarzeń, zebranych za pomocą interfejsu Discovery API lub Device API.
   1. Dzięki interfejsowi Discovery API aplikacja może wygenerować wersję roboczą automatyzacji dostosowaną do typów urządzeń i cech obecnych w strukturze użytkownika, z udziałem użytkownika lub bez niego.
   2. Device API może dostarczać większość tych samych informacji co Discovery API, ale nie jest zoptymalizowany pod kątem 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ą wykonać lub usunąć za pomocą metod interfejsu Structure API.

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

W najprostszym scenariuszu możesz zaproponować użytkownikom wstępnie zdefiniowaną 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ć edytor automatyzacji, który pozwoli użytkownikowi tworzyć złożone automatyzacje przy użyciu wszystkich elementów dostępnych w interfejsie Automation API.

Tworzenie automatyzacji i zarządzanie nimi

Aby tworzyć automatyzacje i nimi zarządzać na Androidzie:

1. Zarejestruj wszystkie typy urządzeń i cechy, do których odwołują się Twoje automatyzacje, w FactoryRegistry przekazywanym do HomeConfig podczas inicjowania pakietu SDK. Szczegółowe informacje o rejestracji znajdziesz w artykule Inicjowanie domu na Androidzie.
2. Utwórz DraftAutomation (BaseAutomation) za pomocą DSL automation() i wywołaj standardowe metody HasAutomations w obiekcie Structure:
   • Wywołaj createAutomation(), aby utworzyć automatyzację w domu.
   • Wywołaj automations(), aby wyświetlić listę automatyzacji utworzonych przez Twoją aplikację w domu lub je pobrać.
   • Wywołaj update() w instancji Automation, aby zaktualizować jej metadane lub zastąpić automationGraph.
   • Wywołaj deleteAutomation(), aby usunąć automatyzację według identyfikatora.

val draft = automation {
  name = "Turn on light"
  description = "Turn on light2 when light1 turns on."
  sequential {
    val starterNode = starter<_>(light1, OnOffLightDevice, OnOff)
    condition { expression = starterNode.onOff equals true }
    action(light2, OnOffLightDevice) { command(OnOff.on()) }
  }
}

val createdAutomation = structure.createAutomation(draft)

Pełną składnię DSL i przykłady kodu CRUD znajdziesz w artykule Tworzenie automatyzacji na Androidzie.

Sugestie automatyzacji

   Wdrożone w przykładowej aplikacji na Androida   

Interfejsy Home API mogą sugerować automatyzacje dla Structure na podstawie takich czynników jak typy urządzeń obecnych w przestrzeni.

Sugestie automatyzacji są reprezentowane przez klasę AutomationSuggestion.

Interfejs Structure obejmuje interfejs HasSuggestions, który udostępnia funkcję suggestions() zwracającą kolekcję sugestii automatyzacji.

Metody likeSuggestion() i dislikeSuggestion() są przeznaczone do połączenia z elementami sterującymi interfejsu thumb_up i thumb_down, które użytkownik może kliknąć, aby przesłać 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)
    }
  }
}

Dynamiczne parametry poleceń

Dynamiczne parametry poleceń umożliwiają deweloperom tworzenie parametrów działań, które są rozwiązywane dynamicznie w czasie działania, zamiast polegać wyłącznie na statycznych, stałych wartościach. Umożliwia to 2 główne funkcje:

• odwołania, które przekazują wartość właściwości z węzła inicjującego (np. ładunek zdarzenia) lub węzła odczytu stanu albo ze zmiennych lokalnych zadeklarowanych w procesie automatyzacji.
• Wyrażenia, które rejestrują wartości dynamiczne w czasie działania (np. właściwość zdarzenia lub wartość stanu) i przekazują je bezpośrednio do parametru polecenia.

Przypadek użycia

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

Jak działają parametry dynamiczne

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

Reguły weryfikacji

Parametry poleceń dynamicznych podlegają tym ograniczeniom dotyczącym weryfikacji:

• Podczas wykrywania parametry dynamiczne są uznawane za prawidłowe pod względem strukturalnym, ponieważ interfejsy API wykrywania oceniają tylko ograniczenia wartości konkretnych argumentów statycznych.
• Węzły odniesienia lub wyrażenia muszą pojawiać się w grafie automatyzacji przed węzłami, w których są przywoływane w działaniu polecenia.

Używanie dynamicznych parametrów poleceń na Androidzie

Przekazywanie wyrażeń dynamicznych bezpośrednio do parametrów polecenia:

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 Matter parametru polecenia odbierającego (np. UShort, UByte lub UInt8).

Limity zasobów

W przypadku automatyzacji w interfejsach Home API obowiązują te limity: