Automation API unter Android – Übersicht

Mit automatisierten Abläufen kannst du Aufgaben und Geräteeinstellungen in einem Zuhause automatisieren. Automatisierungen sind im Google Home-System als Abläufe in der Google Home app (GHA) und über den automation script editor auf Google Home for web verfügbar.

Automatisierungen im Google Home-Ökosystem sind jetzt über die Home APIs für Android verfügbar. Sie verwenden dieselben grundlegenden Konzepte wie GHA-Abläufe und die script editor, bieten aber erweiterte Funktionen, die nur über die Home APIs möglich sind, darunter:

• Zugriff auf alle Standardmerkmale von Matter und smart home für ein Gerät, wie in den Home APIs dargestellt.
• Unterstützung für sequenzielle, parallele und ausgewählte Ausführungsabläufe.

Automatisierte Abläufe werden mit der Automation DSL geschrieben, einer domänenspezifischen Sprache, die für die Erstellung automatisierter Abläufe in Kotlin entwickelt wurde.

Alle Eigenschaften und Typen, die du in deiner App mit der Device & Structure API oder der Automation API verwenden möchtest, müssen bei der Initialisierung registriert werden. Weitere Informationen findest du unter Zuhause auf Android-Geräten initialisieren.

Anleitung für den Fall, dass der Nutzer die vollständigen Berechtigungen widerruft

Wenn der Nutzer die vollständigen Berechtigungen widerruft, funktionieren alle vorhandenen automatisierten Abläufe nicht mehr. Wenn der Nutzer den Zugriff auf bestimmte Geräte widerruft, funktionieren die mit diesen Geräten verknüpften Auslöser, Bedingungen und Aktionen nicht mehr.

Prüfen Sie bei jedem Start der App, ob die Berechtigungen noch gültig sind. Wenn sie widerrufen wurden, müssen alle vorherigen Daten entfernt werden, einschließlich aller in der Anwendung im Cache gespeicherten Daten.

Wenn der Zugriff auf das Gebäude widerrufen wird, wird ein StructureAccessRevokedEvent an dein Cloud-Backend gesendet. Informationen zum End-to-End-Workflow für den Widerruf von Partner-Cloud- und mobilen Apps findest du unter Struktur-Berechtigungen.

Entwickler-Journey

Die Automation API ist nur ein Teil eines größeren Entwicklungsprozesses. Sie erfolgt nach der Integration der Structure API und der Device API, damit Nutzer Automatisierungen verwenden können.

1. Der Entwickler plant seine Automatisierung und definiert sie mit der Automation DSL.
2. Der Entwickler bettet die Automatisierungsdefinition in eine Kotlin-Android-App ein.
3. Die App präsentiert einem Nutzer Automatisierungen basierend auf Informationen zu seinen Geräten, einschließlich Eigenschaften, Attributen, Befehlen und Ereignissen, die über die Discovery API oder die Device API erfasst wurden.
   1. Mit der Discovery API kann die App einen Automatisierungsentwurf erstellen, der auf die Gerätetypen und ‑eigenschaften in der Struktur des Nutzers zugeschnitten ist, mit oder ohne Eingabe des Nutzers.
   2. Die Device API kann die meisten Informationen der Discovery API bereitstellen, ist aber nicht für Automatisierungsanwendungsfälle optimiert. Weitere Informationen findest du unter Device API und Discovery API vergleichen.
4. Die App erstellt die eigentliche Automatisierung, die auf das ausgewählte Gebäude abgestimmt ist.
5. Die Automatisierung ist jetzt im Gebäude des Nutzers verfügbar und kann mit Structure API-Methoden ausgeführt oder gelöscht werden.

Der Nutzer kann jederzeit neue Instanzen der Automatisierung erstellen und dabei ein anderes Gebäude oder, je nach App-Logik, eine andere Gruppe von Geräten auswählen. Jedes Mal, wenn sie dies tun, generiert die App eine neue Instanz der Automatisierung.

Im einfachsten Fall schlägst du deinen Nutzern eine vordefinierte Automatisierung vor, die eine relativ einfache Aufgabe ausführt. Alternativ kannst du ein Grundgerüst einer Automatisierung präsentieren, das der Nutzer an seine Bedürfnisse anpassen kann. Oder du könntest einen offenen Automatisierungseditor schreiben, mit dem der Nutzer komplexe Automatisierungen mit allen in der Automation API verfügbaren Bausteinen erstellen kann.

Automatisierte Abläufe erstellen und verwalten

So erstellst und verwaltest du Automatisierungen auf Android-Geräten:

1. Registriere alle Gerätetypen und Eigenschaften, auf die deine automatisierten Abläufe verweisen, in der FactoryRegistry, die während der SDK-Initialisierung an HomeConfig übergeben wird. Weitere Informationen zur Registrierung findest du unter Zuhause auf Android-Geräten initialisieren.
2. Erstellen Sie Ihr DraftAutomation (BaseAutomation) mit der automation()-DSL und rufen Sie Standard-HasAutomations-Methoden für das Structure-Objekt auf:
   • Rufen Sie createAutomation() auf, um eine Automatisierung im Gebäude zu erstellen.
   • Rufe automations() auf, um die von deiner App im Gebäude erstellten automatisierten Abläufe aufzulisten oder abzurufen.
   • Rufen Sie update() für eine Automation-Instanz auf, um ihre Metadaten zu aktualisieren oder ihre automationGraph zu ersetzen.
   • Rufen Sie deleteAutomation() auf, um eine Automatisierung anhand der ID zu entfernen.

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)

Die vollständige DSL-Syntax und CRUD-Codebeispiele findest du unter Automatisierung für Android erstellen.

Vorschläge für automatisierte Abläufe

   In der Beispiel-App für Android implementiert   

Die Home APIs können automatisierte Abläufe für einen Structure vorschlagen, basierend auf Faktoren wie den im Raum vorhandenen Gerätetypen.

Vorschläge für automatisierte Abläufe werden durch die Klasse AutomationSuggestion dargestellt.

Die Schnittstelle Structure umfasst die Schnittstelle HasSuggestions, die die Funktion suggestions() bereitstellt, die eine Sammlung von Automatisierungsvorschlägen zurückgibt.

Die Methoden likeSuggestion() und dislikeSuggestion() sind für die Verknüpfung mit den UI-Steuerelementen thumb_up und thumb_down vorgesehen, auf die der Nutzer tippen kann, um Feedback zu geben.

Mit einer dritten Methode, clearSuggestionFeedback(), kann der Nutzer sein Feedback zu einer vorgeschlagenen Automatisierung entfernen.

Das Feedback der Nutzer beeinflusst zukünftige Vorschläge.

In diesem Beispiel wird gezeigt, wie Sie die verfügbaren Automatisierungsvorschläge für ein Structure abrufen, eine Vorschlags-ID extrahieren und Nutzerfeedback mit likeSuggestion(), clearSuggestionFeedback() und dislikeSuggestion() aufzeichnen.

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

Dynamische Befehlsparameter

Mit dynamischen Befehlsparametern können Entwickler Aktionsparameter erstellen, die zur Laufzeit dynamisch aufgelöst werden, anstatt sich ausschließlich auf statische, konstante Werte zu verlassen. Dies ermöglicht zwei Hauptfunktionen:

• Verweise, die den Wert einer Property von einem Starter (z. B. einer Ereignisnutzlast) oder einem Statusleseknoten oder von lokalen Variablen, die im Automatisierungsablauf deklariert wurden, übergeben.
• Ausdrücke, die dynamische Werte zur Laufzeit erfassen (z. B. einen Ereignisattribut- oder Statuswert) und den dynamischen Wert direkt an einen Befehlsparameter übergeben.

Anwendungsfall

Einen physischen Drehschalter, der ein Ereignis für mehrmaliges Drücken sendet, an eine dimmbare Lampe binden. Die Anzahl der Klicks ist der dynamische Wert, der zur Laufzeit an einen LevelControl-Schrittbefehl übergeben wird.

Funktionsweise von dynamischen Parametern

In der Automatisierungs-DSL für Android akzeptieren Befehlsparameter Expression- oder Reference-Instanzen direkt anstelle von statischen konstanten Werten. Die DSL kapselt diese beim Erstellen der Automatisierung in Parameter-Definitionen.

Validierungsregeln

Für dynamische Befehlsparameter gelten die folgenden Validierungseinschränkungen:

• Dynamische Parameter werden während der Erkennung als strukturell gültig angenommen, da Erkennungs-APIs nur konkrete Werteinschränkungen für statische Argumente auswerten.
• Referenz- oder Ausdrucksknoten müssen im Automatisierungsdiagramm vor den Befehlsaktionen angezeigt werden, in denen sie referenziert werden.

Dynamische Befehlsparameter unter Android verwenden

Übergeben Sie dynamische Ausdrücke direkt an Befehlsparameter:

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

Alternativ können Sie einer lokalen Variablendeklaration einen Ausdruck zuweisen und später im Ablauf auf die Variable verweisen:

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

Typeinschränkungen

Achten Sie darauf, dass die Typen von Variablen und Ausdrücken mit der erforderlichen Matter-Schematypdefinition des empfangenden Befehlsparameters übereinstimmen (z. B. UShort, UByte oder UInt8).

Ressourcenlimits

Für automatisierte Abläufe in den Home APIs gelten die folgenden Limits: