Panoramica dell'API Automation su Android

Le automazioni sono un modo per automatizzare le attività e le impostazioni dei dispositivi in una casa. Le automazioni sono disponibili nell'ecosistema Google Home come routine nell'Google Home app (GHA) e tramite l'automation script editor su Google Home for web.

Ora, le automazioni nell'ecosistema Google Home sono disponibili tramite le API Home per Android. Utilizzano gli stessi concetti di base delle routine GHA e dello script editor, ma con funzionalità e capacità avanzate possibili solo tramite le API Home, tra cui:

• Accesso a tutti i tratti standard Matter e smart home di un dispositivo, come presentati nelle API Home.
• Supporto per flussi di esecuzione sequenziali, paralleli e di selezione.

Le automazioni vengono scritte utilizzando Automation DSL, un linguaggio specifico del dominio progettato per la creazione di automazioni in Kotlin.

Tutti i tratti e i tipi che intendi utilizzare nella tua app con le API Device & Structure o Automation devono essere registrati durante l'inizializzazione. Consulta Inizializza la casa su Android.

Indicazioni se l'utente revoca le autorizzazioni complete

Se l'utente revoca le autorizzazioni complete, tutte le automazioni esistenti smetteranno di funzionare. Inoltre, se l'utente revoca l'accesso a dispositivi specifici, i comandi iniziali, le condizioni e le azioni associati a questi dispositivi smetteranno di funzionare.

Ogni volta che l'app viene avviata, assicurati di controllare che le autorizzazioni siano ancora attive. Se sono state revocate, assicurati che tutti i dati precedenti vengano rimossi, inclusi quelli memorizzati nella cache dell'applicazione.

Quando l'accesso alla struttura viene revocato, viene inviato un evento StructureAccessRevokedEvent al tuo backend cloud. Consulta la sezione Concessioni della struttura per il flusso di lavoro di revoca end-to-end del cloud e dell'app mobile del partner.

Percorso per gli sviluppatori

L'API Automation è una parte di un percorso di sviluppo più ampio. Viene dopo l'integrazione delle API Structure e Device per garantire che, quando un utente vuole utilizzare un'automazione, possa farlo.

1. Lo sviluppatore pianifica l'automazione e la definisce utilizzando il DSL di automazione.
2. Lo sviluppatore incorpora la definizione dell'automazione in un'app per Android Kotlin.
3. L'app presenta le automazioni a un utente in base alle informazioni sui suoi dispositivi, inclusi tratti, attributi, comandi ed eventi, raccolti utilizzando l'API Discovery o l'API Device.
   1. Con l'API Discovery, l'app può generare una bozza di automazione personalizzata in base ai tipi di dispositivi e alle caratteristiche presenti nella struttura dell'utente, con o senza l'input dell'utente.
   2. L'API Device può fornire la maggior parte delle stesse informazioni dell'API Discovery, ma non è ottimizzata per i casi d'uso di automazione. Per maggiori dettagli, consulta Confronta l'API Device e l'API Discovery.
4. L'app crea l'automazione effettiva associata alla struttura selezionata.
5. L'automazione è ora disponibile nella struttura dell'utente e può essere eseguita o eliminata utilizzando i metodi dell'API Structure.

L'utente può creare nuove istanze dell'automazione in qualsiasi momento, selezionando una struttura diversa o, a seconda della logica dell'app, un insieme diverso di dispositivi. Ogni volta che lo fanno, l'app genera una nuova istanza dell'automazione.

Nello scenario più semplice, potresti suggerire ai tuoi utenti un'automazione predefinita che esegue un'attività relativamente semplice. In alternativa, puoi presentare uno scheletro di un'automazione che l'utente personalizza in base alle sue esigenze. In alternativa, puoi scrivere un editor di automazioni aperto che consenta all'utente di creare automazioni complesse utilizzando tutti i componenti di base disponibili nell'API Automation.

Crea e gestisci le automazioni

Per creare e gestire le automazioni su Android:

1. Registra tutti i tipi di dispositivi e i tratti a cui fanno riferimento le tue automazioni in FactoryRegistry passato a HomeConfig durante l'inizializzazione dell'SDK. Per i dettagli sulla registrazione, consulta Inizializza la casa su Android.
2. Crea il tuo DraftAutomation (BaseAutomation) utilizzando il DSL automation() e chiama i metodi HasAutomations standard sull'oggetto Structure:
   • Chiama createAutomation() per creare un'automazione nella struttura.
   • Chiama automations() per elencare o recuperare le automazioni create dalla tua app nella struttura.
   • Chiama update() su un'istanza Automation per aggiornare i relativi metadati o sostituire il relativo automationGraph.
   • Chiama deleteAutomation() per rimuovere un'automazione in base all'ID.

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)

Per la sintassi DSL completa e gli esempi di codice CRUD, consulta Crea un'automazione su Android.

Suggerimenti di automazione

   Implementato nell'app di esempio per Android   

Le API Home possono suggerire automazioni per un Structure in base a fattori come i tipi di dispositivi presenti nello spazio.

I suggerimenti di automazione sono rappresentati dalla classe AutomationSuggestion.

L'interfaccia Structure comprende l'interfaccia HasSuggestions, che fornisce la funzione suggestions(), che restituisce una raccolta di suggerimenti di automazione.

I metodi likeSuggestion() e dislikeSuggestion() devono essere collegati ai controlli UI thumb_up e thumb_down che l'utente può toccare per fornire feedback.

Un terzo metodo, clearSuggestionFeedback(), consente all'utente di rimuovere il proprio feedback per un'automazione suggerita.

Il feedback degli utenti influisce sui suggerimenti futuri.

Questo esempio mostra come recuperare i suggerimenti di automazione disponibili per un Structure, estrarre un ID suggerimento e registrare il feedback degli utenti utilizzando likeSuggestion(), clearSuggestionFeedback() e 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)
    }
  }
}

Parametri di comando dinamici

I parametri dei comandi dinamici consentono agli sviluppatori di creare parametri di azione che vengono risolti dinamicamente in fase di runtime, anziché fare affidamento esclusivamente su valori statici e costanti. Ciò consente due funzionalità principali:

• Riferimenti che trasmettono il valore di una proprietà da un nodo di attivatore (ad esempio un payload di evento) o di lettura dello stato oppure da variabili locali dichiarate all'interno del flusso di automazione.
• Espressioni che acquisiscono valori dinamici di runtime (come una proprietà evento o un valore di stato) e li passano direttamente a un parametro di comando.

Caso d'uso

Associa un interruttore rotativo fisico che invia un evento di pressione multipla a una luce dimmerabile. Il conteggio dei clic è il valore dinamico passato a un comando di passaggio LevelControl in fase di esecuzione.

Come funzionano i parametri dinamici

Nel DSL di automazione su Android, i parametri dei comandi accettano istanze Expression o Reference direttamente al posto dei valori costanti statici. Il DSL li incapsula nelle definizioni Parameter durante la creazione dell'automazione.

Regole di convalida

I parametri dei comandi dinamici seguono questi vincoli di convalida:

• I parametri dinamici sono considerati strutturalmente validi durante il rilevamento perché le API di rilevamento valutano solo i vincoli dei valori concreti per gli argomenti statici.
• I nodi di riferimento o di espressione devono apparire a monte nel grafico dell'automazione prima di essere richiamati in un'azione di comando a valle.

Utilizza i parametri dei comandi dinamici su Android

Passa espressioni dinamiche direttamente ai parametri del comando:

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

In alternativa, assegna un'espressione a una dichiarazione di variabile locale e fai riferimento alla variabile in un secondo momento nel flusso:

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

Vincoli di tipo

Assicurati che i tipi di variabili ed espressioni siano in linea con la definizione del tipo di schema Matter richiesto dal parametro del comando di ricezione (ad esempio UShort, UByte o UInt8).

Limiti delle risorse

Alle automazioni nelle API Home si applicano i seguenti limiti: