Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Automatisierung auf Android-Geräten erstellen

Auf die Automatisierungs-APIs kann über die Home-APIs für Android zugegriffen werden. Da der Einstiegspunkt jedoch über ein Gebäude erfolgt, muss zuerst die Berechtigung für das Gebäude erteilt werden, bevor sie verwendet werden können.

Sobald die Berechtigungen für eine Struktur erteilt wurden, importieren Sie diese Pakete in Ihre App:


import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.Id
import com.google.home.Structure

Eine Struktur enthält eine HasAutomations-Schnittstelle mit den folgenden automatisierungsspezifischen Methoden:

API	Beschreibung
`automations()`	Alle Automatisierungen auflisten, die zum Zuhause gehören Es werden nur Automatisierungen zurückgegeben, die Sie über die Home APIs erstellt haben.
`createAutomation(automation)`	Automatisierungsinstanz für ein Zuhause erstellen
`deleteAutomation(automationId)`	Eine Automatisierungsinstanz anhand ihrer ID löschen

Automatisierung erstellen

Nachdem Sie eine Instanz von „Zuhause“ erstellt und Berechtigungen vom Nutzer erhalten haben, rufen Sie die Struktur und die Geräte ab:

val structure = homeManager.structures().list().single()
val device = homeManager.devices().get(Id("myDevice"))!!

Definieren Sie dann die Logik Ihrer Automatisierung mit Automation DSL. In den Home APIs wird eine Automatisierung durch die Automation-Schnittstelle dargestellt. Diese Schnittstelle enthält eine Reihe von Eigenschaften:

Metadaten wie Name und Beschreibung.
Flags, die beispielsweise angeben, ob die Automatisierung ausgeführt werden kann.
Eine Liste von Knoten, die die Logik der Automatisierung enthalten, auch als Automatisierungsdiagramm bezeichnet und durch das Attribut automationGraph dargestellt.

automationGraph hat standardmäßig den Typ SequentialFlow. Das ist eine Klasse, die eine Liste von Knoten enthält, die in sequenzieller Reihenfolge ausgeführt werden. Jeder Knoten stellt ein Element der Automatisierung dar, z. B. einen Auslöser, eine Bedingung oder eine Aktion.

Weisen Sie der Automatisierung ein name und ein description zu.

Beim Erstellen einer Automatisierung wird das Flag isActive standardmäßig auf true gesetzt. Es ist daher nicht erforderlich, dieses Flag explizit festzulegen, es sei denn, die Automatisierung soll anfangs deaktiviert sein. In diesem Fall setzen Sie das Flag beim Erstellen auf false.

Die DraftAutomation-Schnittstelle wird zum Erstellen und Erstellen von Automatisierungen verwendet, die Automation-Schnittstelle zum Abrufen. Hier ist beispielsweise die Automation DSL für eine Automatisierung, die ein Gerät einschaltet, wenn ein anderes Gerät eingeschaltet wird:

import com.google.home.automation.Action
import com.google.home.automation.Automation
import com.google.home.automation.Condition
import com.google.home.automation.DraftAutomation
import com.google.home.automation.Equals
import com.google.home.automation.Node
import com.google.home.automation.SequentialFlow
import com.google.home.automation.Starter
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.HomeManager
import com.google.home.Id
import com.google.home.matter.standard.OnOff
import com.google.home.Structure

...

val automation: DraftAutomation = automation {
  name = "MyFirstAutomation"
  description = "Turn on a device when another device is turned on."
  sequential {
    val starterNode = starter<_>(device1, OnOffLightDevice, trait=OnOff)
    condition() { expression = stateReaderNode.onOff equals true }
    action(device2, OnOffLightDevice) { command(OnOff.on()) }
  }
}

Sobald die Automatisierungs-DSL definiert ist, übergeben Sie sie an die Methode createAutomation(), um die DraftAutomation-Instanz zu erstellen:

val createdAutomation = structure.createAutomation(automation)

Von hier aus können Sie alle anderen Automatisierungsmethoden für die Automatisierung verwenden, z. B. execute(), stop() und update().

Validierungsfehler

Wenn die Automatisierungserstellung die Validierung nicht besteht, wird eine Warnung oder Fehlermeldung mit Informationen zum Problem angezeigt. Weitere Informationen finden Sie in der Referenz zu ValidationIssueType.

Auch wenn createAutomation() ohne Ausnahme abgeschlossen wird, ist die erstellte Automatisierung möglicherweise ungültig oder kann nicht ausgeführt werden. Im Backend können ungültige Automatisierungsentwürfe gespeichert werden, z. B. wenn ein Nutzer die erforderlichen Einwilligungen wie die Gesichtswiedererkennung nicht erteilt hat oder Gerätefunktionen fehlen.

Sie sollten immer isValid prüfen und validationIssues für die zurückgegebene Automation-Instanz prüfen:

val createdAutomation = structure.createAutomation(automation)

if (!createdAutomation.isValid) {
  // Iterate through validation issues to identify errors and warnings
  for (issue in createdAutomation.validationIssues) {
    when (issue.severity) {
      ValidationIssueSeverity.ERROR -> {
        Log.e(
          "Automation",
          "Validation error on node ${issue.node}: ${issue.issueType}"
        )
        // Handle error (for example, prompt the user to enable missing
        // consents or device features)
      }
      ValidationIssueSeverity.WARNING -> {
        Log.w(
          "Automation",
          "Validation warning on node ${issue.node}: ${issue.issueType}"
        )
      }
      else -> {}
    }
  }
}

Codebeispiele

Hier finden Sie Beispielcode, mit dem sich Teile der hypothetischen Automatisierungen implementieren lassen, die auf der Seite Automatisierung für Android entwerfen beschrieben werden.

Einfache Automatisierung

Eine Automatisierung, die die Jalousien um 8:00 Uhr hochfährt, könnte so implementiert werden:

// get all the automation node candidates in the structure
val allCandidates = structure.allCandidates().first()
// determine whether a scheduled automation can be constructed
val isSchedulingSupported =
  allCandidates.any {
    it is EventCandidate &&
      it.eventFactory == Time.ScheduledTimeEvent &&
      it.unsupportedReasons.isEmpty()
  }
// get the blinds present in the structure
val blinds =
  allCandidates
    .filter {
      it is CommandCandidate &&
        it.commandDescriptor == WindowCoveringTrait.UpOrOpenCommand &&
        it.unsupportedReasons.isEmpty()
    }
    .map { it.entity }
    .filterIsInstance<HomeDevice>()
    .filter { it.has(WindowCoveringDevice) }
 if (isSchedulingSupported && blinds.isNotEmpty()) {
  // Proceed to create automation
  val automation: DraftAutomation = automation {
    name = "Day time open blinds"
    description = "Open all blinds at 8AM everyday"
    isActive = true
    sequential {
      // At 8:00am local time....
      val unused =
        starter(structure, Time.ScheduledTimeEvent) {
          parameter(Time.ScheduledTimeEvent.clockTime(LocalTime.of(8, 0, 0, 0)))
        }
        // ...open all the blinds
       parallel {
        for (blind in blinds) {
          action(blind, WindowCoveringDevice) { command(WindowCovering.upOrOpen()) }
        }
      }
    }
  }
   val createdAutomation = structure.createAutomation(automation)
} else if (!isSchedulingSupported) {
  // Cannot create automation.
  // Set up your address on the structure, then try again.
} else {
  // You don't have any WindowCoveringDevices.
  // Try again after adding some blinds to your structure.
}

Komplexe Automatisierung

Eine Automatisierung, die blinkende Lichter auslöst, wenn eine Bewegung erkannt wird, könnte so implementiert werden:

import com.google.home.Home
import com.google.home.HomeClient
import com.google.home.HomeDevice
import com.google.home.HomeManager
import com.google.home.Id
import com.google.home.Structure
import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.equals
import com.google.home.automation.parallel
import com.google.home.automation.starter
import com.google.home.google.AssistantBroadcast
import com.google.home.matter.standard.OnOff
import com.google.home.matter.standard.OnOff.Companion.toggle
import com.google.home.matter.standard.OnOffLightDevice
import java.time.Duration

// get all the automation node candidates in the structure
val allCandidates = structure.allCandidates().first()

// get the lights present in the structure
val availableLights = allCandidates.filter {
   it is CommandCandidate &&
   it.commandDescriptor == OnOffTrait.OnCommand
}.map { it.entity }
.filterIsInstance<HomeDevice>()
.filter {it.has(OnOffLightDevice) ||
         it.has(ColorTemperatureLightDevice) ||
         it.has(DimmableLightDevice) ||
         it.has(ExtendedColorLightDevice)}

val selectedLights = ... // user selects one or more lights from availableLights

automation {
isActive = true

sequential {
   // If the presence state changes...
   val starterNode = starter<_>(structure, AreaPresenceState)
   // ...and if the area is occupied...
   condition() {
      expression = starterNode.presenceState equals PresenceState.PresenceStateOccupied
   }
   // "blink" the light(s)
   parallel {
            for(light in selectedLights) {
            action(light, OnOffLightDevice) { command(OnOff.toggle()) }
            delayFor(Duration.ofSeconds(1))
            action(light, OnOffLightDevice) { command(OnOff.toggle()) }
            delayFor(Duration.ofSeconds(1))
            action(light, OnOffLightDevice) { command(OnOff.toggle()) }
            delayFor(Duration.ofSeconds(1))
            action(light, OnOffLightDevice) { command(OnOff.toggle())}
         }
      }
   }
}

Geräte mit Gerätefiltern dynamisch auswählen

Beim Erstellen einer Automatisierung müssen Sie nicht unbedingt bestimmte Geräte angeben. Mit der Funktion Entitätsfilter können Geräte in Ihrer Automatisierung zur Laufzeit anhand verschiedener Kriterien ausgewählt werden.

Mit Entitätsfiltern können Sie beispielsweise das Targeting Ihrer Automatisierung auf Folgendes ausrichten:

alle Geräte eines bestimmten Gerätetyps
alle Geräte in einem bestimmten Raum
alle Geräte eines bestimmten Gerätetyps in einem bestimmten Raum
alle eingeschalteten Geräte
alle Geräte, die in einem bestimmten Raum eingeschaltet sind

So verwenden Sie Entitätsfilter:

Rufen Sie atExecutionTime() entweder in Structure oder in Room auf. Dadurch wird ein TypedExpression<TypedEntity<StructureType>> zurückgegeben.
Rufen Sie für dieses Objekt getDevicesOfType() auf und übergeben Sie ein DeviceType-Objekt.

Entitätsfilter können in Auslösern, Statuslesern und Aktionen verwendet werden.

Wenn beispielsweise eine beliebige Ein/Aus-Lampe eine Automatisierung über einen Auslöser starten soll:

// If any light is turned on or off
val starter =
  starter(
    entityExpression = structure.atExecutionTime().getDevicesOfType(OnOffLightDevice),
    trait = OnOff,
  )

So erfassen Sie den Status OnOff aller Lampen in einem Gebäude (insbesondere Ein-/Aus-Lampen) in einem Statusleser:

// Build a Map<Entity, OnOff>
val onOffStateOfAllLights =
  stateReader(
    entityExpression = structure.atExecutionTime().getDevicesOfType(OnOffLightDevice),
    trait = OnOff,
  )

So rufen Sie die Beleuchtung in einem bestimmten Raum ab und verwenden sie in einer Bedingung:

val livingRoomLights =
  stateReader(
    entityExpression = livingRoom.atExecutionTime().getDevicesOfType(OnOffLightDevice),
    trait = OnOff,
  )
// Are any of the lights in the living room on?
condition { expression = livingRoomLights.values.any { it.onOff equals true } }

Zur Laufzeit:

Szenario	Ergebnis
Keine Geräte erfüllen die Kriterien in einem Starter.	Die Automatisierung wird nicht ausgelöst.
Keine Geräte erfüllen die Kriterien in einem Statusleser.	Die Automatisierung wird gestartet, aber basierend auf dem Bedingungsknoten fortgesetzt.
Keine Geräte erfüllen die Kriterien in einer Aktion.	Die Automatisierung wird gestartet, aber die Aktion hat keine Auswirkungen.

Im folgenden Beispiel wird eine Automatisierung gezeigt, die alle Lichter außer der Flurbeleuchtung ausschaltet, wenn ein einzelnes Licht ausgeschaltet wird:

val unused = automation {
  sequential {
    // If any light is turned on or off
    val starter =
      starter(
        entityExpression = structure.atExecutionTime().getDevicesOfType(OnOffLightDevice),
        trait = OnOff,
      )
    condition {
      // Check to see if the triggering light was turned off
      expression = starter.onOff equals false
    }
    // Turn off all lights except the hall light
    action(
      entityExpression =
        structure.atExecutionTime().getDevicesOfType(OnOffLightDevice).filter {
          it notEquals entity(hallwayLight, OnOffLightDevice)
        }
    ) {
      command(OnOff.on())
    }
  }
}

Automatisierung ausführen

Führen Sie eine erstellte Automatisierung mit der Methode execute() aus:

createdAutomation.execute()

Wenn die Automatisierung einen manuellen Auslöser hat, startet execute() die Automatisierung ab diesem Punkt und ignoriert alle Knoten, die dem manuellen Auslöser vorangestellt sind. Wenn die Automatisierung keinen manuellen Auslöser hat, beginnt die Ausführung mit dem Knoten, der auf den ersten Auslöserknoten folgt.

Wenn der Vorgang execute() fehlschlägt, wird möglicherweise eine HomeException ausgelöst. Weitere Informationen finden Sie unter Fehlerbehandlung.

Automatisierung beenden

So beenden Sie eine laufende Automatisierung mit der Methode stop():


createdAutomation.stop()

Wenn der Vorgang stop() fehlschlägt, wird möglicherweise eine HomeException ausgelöst. Weitere Informationen finden Sie unter Fehlerbehandlung.

Liste der Automatisierungen für ein Gebäude abrufen

Automatisierungen werden auf Gebäudeebene definiert. Sammeln Sie automations() für die Struktur, um auf Flow Automatisierungen zuzugreifen:


import com.google.home.automation.Automation
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.HomeManager
import com.google.home.Id
import com.google.home.Structure

...

val structure = homeManager.structures().list().single()
structure.automations().collect {
  println("Available automations:")
  for (automation in it) {
    println(String.format("%S %S", "$automation.id", "$automation.name"))
  }
}

Alternativ können Sie sie einer lokalen Collection zuweisen:

import com.google.home.automation.Automation
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.HomeManager
import com.google.home.Id
import com.google.home.Structure

...

var myAutomations: Collection<Automation> = emptyList()
myAutomations = structure.automations()

Automatisierung nach ID abrufen

Wenn Sie eine Automatisierung anhand der Automatisierungs-ID abrufen möchten, rufen Sie die Methode automations() für das Gebäude auf und gleichen Sie die ID ab:

import com.google.home.automation.Automation
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.HomeManager
import com.google.home.Id
import com.google.home.Structure

...

val structure = homeManager.structures().list().single()
val automation: DraftAutomation = structure.automations().mapNotNull {
  it.firstOrNull
    { automation -> automation.id == Id("automation-id") }
  }.firstOrNull()

Antwort:

// Here's how the automation looks like in the get response.
// Here, it's represented as if calling a println(automation.toString())

Automation(
  name = "automation-name",
  description = "automation-description",
  isActive = true,
  id = Id("automation@automation-id"),
  automationGraph = SequentialFlow(
    nodes = [
      Starter(
        entity="device@test-device",
        type="home.matter.0000.types.0101",
        trait="OnOff@6789..."),
      Action(
        entity="device@test-device",
        type="home.matter.0000.types.0101",
        trait="OnOff@8765...",
        command="on")
    ]))

Automatisierung anhand des Namens abrufen

Mit der Methode filter() in Kotlin können API-Aufrufe weiter optimiert werden. Wenn Sie eine Automatisierung anhand des Namens abrufen möchten, rufen Sie die Automatisierungen des Zuhauses ab und filtern Sie nach dem Namen der Automatisierung:

import com.google.home.automation.Automation
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.HomeManager
import com.google.home.Id
import com.google.home.Structure

...

val structure = homeManager.structures().list().single()
val automation: DraftAutomation = structure.automations().filter {
  it.name.equals("Sunset Blinds") }

Alle Automatisierungen für ein Gerät abrufen

Wenn Sie alle automatisierten Abläufe abrufen möchten, die auf ein bestimmtes Gerät verweisen, verwenden Sie die geschachtelte Filterung, um die automationGraph jedes automatisierten Ablaufs zu scannen:

import android.util.Log
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.HomeManager
import com.google.home.Id
import com.google.home.Structure
import com.google.home.automation.Action
import com.google.home.automation.Automation
import com.google.home.automation.Automation.automationGraph
import com.google.home.automation.Node
import com.google.home.automation.ParallelFlow
import com.google.home.automation.SelectFlow
import com.google.home.automation.SequentialFlow
import com.google.home.automation.Starter
import com.google.home.automation.StateReader

...

fun collectDescendants(node: Node): List<Node> {
  val d: MutableList<Node> = mutableListOf(node)

  val children: List<Node> =
    when (node) {
      is SequentialFlow -> node.nodes
      is ParallelFlow -> node.nodes
      is SelectFlow -> node.nodes
      else -> emptyList()
    }
  for (c in children) {
    d += collectDescendants(c)
  }
  return d
}

val myDeviceId = "device@452f78ce8-0143-84a-7e32-1d99ab54c83a"
val structure = homeManager.structures().list().single()
val automations =
  structure.automations().first().filter {
    automation: Automation ->
    collectDescendants(automation.automationGraph!!).any { node: Node ->
      when (node) {
        is Starter -> node.entity.id.id == myDeviceId
        is StateReader -> node.entity.id.id == myDeviceId
        is Action -> node.entity.id.id == myDeviceId
        else -> false
      }
    }
  }

Automatisierung aktualisieren

Rufen Sie die Methode update() auf, um die Metadaten einer Automatisierung zu aktualisieren. Übergeben Sie dazu einen Lambda-Ausdruck, der die Metadaten festlegt:

import com.google.home.automation.Automation
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.HomeManager
import com.google.home.Id
import com.google.home.Structure

...

val structure = homeManager.structures().list().single()
val automation: DraftAutomation = structure.automations().mapNotNull {
  it.firstOrNull
    { automation -> automation.id == Id("automation-id") }
  }.firstOrNull()
automation.update { this.name = "Flashing lights 2" }

Die Methode update() unterstützt das vollständige Ersetzen eines Automatisierungsdiagramms, aber nicht die Bearbeitung des Diagramms auf Knotenebene. Die Bearbeitung einzelner Knoten ist aufgrund von Knotenabhängigkeiten fehleranfällig. Wenn Sie die Logik einer Automatisierung ändern möchten, erstellen Sie ein neues Diagramm und ersetzen Sie das vorhandene vollständig.

import com.google.home.automation.Automation
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.HomeManager
import com.google.home.Id
import com.google.home.Structure

...

val structure = homeManager.structures().list().single()
val automation: Automation = structure.automations().mapNotNull {
  it.firstOrNull
    { automation -> automation.id == Id("automation-id") }
  }.firstOrNull()
automation.update {
  this.automationGraph = sequential {
    val laundryWasherCompletionEvent =
      starter<_>(laundryWasher, LaundryWasherDevice, OperationCompletionEvent)
    condition {
      expression =
        laundryWasherCompletionEvent.completionErrorCode equals
          // UByte 0x00u means NoError
          0x00u
    }
    action(speaker, SpeakerDevice) { command(AssistantBroadcast.broadcast("laundry is done")) }
    }
  }
}

Automatisierung löschen

Verwende zum Löschen einer Automatisierung die Methode deleteAutomation() des Gebäudes. Eine Automatisierung muss anhand ihrer ID gelöscht werden.

import com.google.home.automation.Automation
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.HomeManager
import com.google.home.Id
import com.google.home.Structure

...

val structure = homeManager.structures().list().single()
val automation: DraftAutomation = structure.automations().first()
structure.deleteAutomation(automation.id)

Wenn das Löschen fehlschlägt, wird möglicherweise eine HomeException ausgelöst. Weitere Informationen finden Sie unter Fehlerbehandlung.

Auswirkungen des Löschens von Geräten auf Automatisierungen

Wenn ein Nutzer ein Gerät löscht, das in einer Automatisierung verwendet wird, kann das gelöschte Gerät keine Starter auslösen und die Automatisierung kann keine Attribute daraus lesen oder Befehle an das Gerät senden. Wenn ein Nutzer beispielsweise ein OccupancySensorDevice aus seinem Zuhause löscht und ein automatisierter Ablauf einen Auslöser hat, der vom OccupancySensorDevice abhängt, kann dieser Auslöser den automatisierten Ablauf nicht mehr aktivieren.

Zurück

Automatisierung entwerfen

Weiter

Geräteerkennung nutzen