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 nel Google Home app (GHA) e tramite 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 Matter standard e smart home per un dispositivo, come indicato nelle API Home.
• Supporto per flussi di esecuzione sequenziali, paralleli e selezionati.

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 all'inizializzazione. Consulta la sezione Inizializzare 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, gli avviatori, le condizioni e le azioni associati a questi dispositivi smetteranno di funzionare.

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

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

Percorso dello sviluppatore

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

1. Lo sviluppatore pianifica l'automazione e la definisce utilizzando Automation DSL.
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, raccolte 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 ai tratti 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 dell'automazione. Per ulteriori dettagli, consulta la sezione Confrontare l'API Device e l'API Discovery.
4. L'app crea l'automazione effettiva a cui è associata la 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, magari un insieme di dispositivi diverso. Ogni volta che lo fa, l'app genera una nuova istanza dell'automazione.

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

Suggerimenti di automazione

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 AutomationSuggestion classe.

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() sono progettati per essere collegati ai controlli dell'interfaccia utente thumb_up e thumb_down che l'utente può toccare per fornire feedback.

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

Il feedback degli utenti influenza i suggerimenti futuri.

Questo esempio mostra come recuperare i suggerimenti di automazione disponibili per un Structure, estrarre un ID suggerimento e registrare il feedback dell'utente 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 di comando dinamici consentono agli sviluppatori di creare parametri di azione che vengono risolti dinamicamente in fase di esecuzione anziché basarsi rigorosamente su valori statici e costanti. Ciò consente due funzionalità principali:

• Riferimenti che passano il valore di una proprietà da un nodo di avviamento (ad esempio un payload di eventi) o di lettura dello stato oppure da variabili locali dichiarate all'interno del flusso di automazione.
• Espressioni che acquisiscono valori dinamici di runtime (ad esempio una proprietà evento o un valore di stato) e passano il valore dinamico 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

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

Regole di convalida

I parametri di comando dinamici seguono questi vincoli di convalida:

• Si presume che i parametri dinamici siano strutturalmente validi durante la rilevazione perché le API di rilevamento valutano solo i vincoli di valore concreti per gli argomenti statici.
• I nodi di riferimento o di espressione devono essere visualizzati a monte nel grafico di automazione prima di essere referenziati in un'azione di comando a valle.

Utilizzare i parametri di comando dinamici su Android

Passa le espressioni dinamiche direttamente ai parametri di 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 allineati alla definizione del tipo di schema Matter richiesto del parametro di comando ricevente (ad esempio UShort, UByte o UInt8).

Limiti delle risorse

Alle automazioni nelle API Home si applicano i seguenti limiti: