Guida all'DSL Android

Utilizza la seguente guida per capire come utilizzare i vari nodi DSL di automazione per creare un'automazione.

Tutto il DSL di automazione è inserito in un unico nodo automation. Il nodo automation costituisce il confine tra il contesto esterno del linguaggio Kotlin e il contesto DSL incorporato.

Flusso sequenziale

Il flusso sequenziale è il tipo predefinito di flusso di automazione.

Ecco un modello di DSL di automazione molto semplice che utilizza un flusso sequenziale composto da un comando iniziale, una condizione e un'azione:

import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.condition
import com.google.home.automation.sequential
import com.google.home.automation.starter

...

automation {
  sequential {
    starter<_>(...)
    condition {...}
    action {...}
  }
}

Questo può essere perfezionato aggiungendo altri nodi.

Starter

I nodi di attivazione definiscono le circostanze iniziali che attivano un'automazione. Ad esempio, una modifica dello stato o del valore. Un'automazione deve avere almeno un comando iniziale, altrimenti la convalida non andrà a buon fine. Per aggiungere più di un comando iniziale a un'automazione, devi utilizzare un nodo select.

Comando iniziale basato sull'attributo della caratteristica

Quando dichiari un nodo iniziale basato su un attributo di un tratto, specifica:

• il dispositivo
• il tipo di dispositivo a cui appartiene il tratto
• il tratto

starter<_>(thermostat, TemperatureSensorDevice, TemperatureMeasurement)

Il parametro del tipo di dispositivo è obbligatorio perché ti consente di specificare il tipo di dispositivo all'interno di un dispositivo a cui è indirizzata l'automazione. Ad esempio, un dispositivo potrebbe essere composto da un FanDevice e un HeatingCoolingUnitDevice, entrambi contenenti il tratto OnOff. Specificando il tipo di dispositivo, non ci sono ambiguità su quale parte del dispositivo attiva l'automazione.

Comando iniziale basato su un evento

Quando dichiari un nodo iniziale basato su un evento, specifica:

• il dispositivo
• il tipo di dispositivo a cui appartiene il tratto
• l'evento

starter<_>(doorBell, GoogleDoorbellDevice, DoorbellPressed)

Comando iniziale basato su una struttura e un evento, con parametri

Alcuni eventi possono avere parametri, che devono essere inclusi anche nello starter.

Ad esempio, questo comando iniziale utilizza l'attributo ScheduledTimeEvent del tratto Time per attivare l'automazione alle 07:00:

val earlyMorning = starter<_>(structure, Time.ScheduledTimeEvent) {
  parameter(Time.ScheduledTimeEvent.clockTime(
    LocalTime.of(7, 0, 0, 0)))
}

Comando iniziale basato sul meteo

Puoi specificare le condizioni meteo attuali o previste in un comando iniziale utilizzando la caratteristica Meteo:

val weatherState = starter<_>(structure, trait = Weather)

Consulta l'esempio Chiudi le persiane se è probabile che piova nella pagina Esempi di automazioni.

Comando iniziale manuale

Un comando iniziale manuale è un tipo speciale di comando iniziale che consente all'utente di eseguire manualmente l'automazione.

Quando dichiari un comando iniziale manuale:

• Non specificare un tratto o un tipo di dispositivo.
• Fornisci un elemento UI che chiami Automation.execute().

Quando inserisci un comando iniziale manuale in un flusso select insieme a un altro comando iniziale, il comando iniziale manuale sostituisce l'altro:

select {
  manualStarter()
  starter<_>(thermostat, TemperatureSensorDevice, TemperatureMeasurement)
}

Tieni presente che tutti i nodi condition che seguono un comando iniziale manuale verranno valutati e potrebbero bloccare l'esecuzione dell'automazione, a seconda dell'espressione condition.

Un modo per strutturare l'automazione in modo che i nodi condition non blocchino un'automazione attivata con un comando iniziale manuale è inserire l'altro comando iniziale in un flusso sequenziale separato insieme al relativo condition:

automation_graph {
  sequential {
    select {
      sequential {
        starter<_>(...)
        condition {...}
      }
      sequential {
        manualStarter()
      }
    }
    action {...}
  }
}

Fai riferimento al valore di un attributo

Per utilizzare il valore di un attributo in un'espressione, utilizza la seguente sintassi.

Con un stateReader:

val time = stateReader<_>(structure, Structure, Time)
val currTime = time.currentTime

Con un starter:

val starterNode = starter<_>(device1, LaundryWasherDevice, OnOff)
condition() {
  expression = starterNode.onOff equals true
}

Nodi ed espressioni di condizione

Un nodo di condizione rappresenta un punto di decisione che determina se l'automazione continua o meno. Un'automazione può avere più nodi condition. Se l'espressione di un nodo condition restituisce false, l'esecuzione dell'intera automazione termina.

All'interno di un nodo condition, puoi combinare più criteri di condizione utilizzando vari operatori, purché l'espressione restituisca un singolo valore booleano. Se il valore risultante è true, la condizione è soddisfatta e l'automazione continua l'esecuzione del nodo successivo. Se è false, l'automazione interrompe l'esecuzione in quel punto.

Le espressioni vengono create in modo simile alle espressioni in Kotlin e possono contenere valori primitivi come numeri, caratteri, stringhe e valori booleani, nonché valori Enum. Il raggruppamento delle sottoespressioni tra parentesi ti consente di controllare l'ordine in cui vengono valutate.

Ecco un esempio di condition che combina più sottoespressioni in un'unica espressione:

condition() {
  val expr1 = starterNode.lockState equals DlLockState.Unlocked
  val expr2 = stateReaderNode.lockState equals true

  val expr3 = occupancySensingDevice.occupied notEquals 0
  val expr4 = timeStateReaderNode
    .currentTime
    .between(
      timeStateReaderNode.sunsetTime,
      timeStateReaderNode.sunriseTime)
  expression = (expr1 and expr2) or (expr3 and expr4)
}

Puoi fare riferimento al valore di un tratto a cui accedi tramite un comando iniziale:

val starterNode = starter<_>(device, OnOff)
condition() { expression = starterNode.onOff equals true }

stateReader

L'altro modo per fare riferimento ai valori degli attributi dei trait in un nodo condition è utilizzare un nodo stateReader.

Per farlo, acquisisci innanzitutto il valore dell'attributo del tratto in un nodo stateReader. Un stateReader accetta structure e la caratteristica come argomenti:

import com.google.home.automation.stateReader
...
val filterMonitoringState = stateReader<_>(structure, ActivatedCarbonFilterMonitoring)

Quindi, fai riferimento a stateReader nel nodo condition:

condition() {
  expression =
    filterMonitoringState.changeIndication
      .equals(ChangeIndicationEnum.Warning)
}

Utilizzando operatori di confronto e logici, è possibile utilizzare più stateReaders in un nodo condition:

val armState = stateReader<_>(doorLock, DoorLockDevice, ArmDisarm )
val doorLockState = stateReader<_>(doorLock, DoorLockDevice, DoorLock)
condition() {
  expression =
    (armState.armState equals true)
    and
    (doorLockState.lockState equals true)
}

Durata della condizione

Oltre a un'espressione booleana in una condizione, puoi specificare un periodo di tempo durante il quale l'espressione deve essere vera per eseguire l'automazione. Ad esempio, puoi definire una condizione che si attiva solo se una luce è accesa da dieci minuti.

  condition {
    expression(lightStateReader.onOff == true)
    forDuration(Duration.ofMinutes(10))
  }

La durata può variare da 5 secondi a 24 ore.

Nodi di azione

Il nodo di azione è il punto in cui viene eseguito il lavoro dell'automazione. In questo esempio, l'azione richiama il comando broadcast() del tratto AssistantBroadcast:

action(device, SpeakerDevice) {
  command(AssistantBroadcast.broadcast("Intruder detected!"))
}

Istruzioni di importazione

Quando sviluppi automazioni, non è sempre ovvio come importare vari elementi delle API Home nel tuo codice.

Gli attributi dei tratti vengono importati dall'oggetto Companion del tratto:

import com.google.home.matter.standard.OnOff.Companion.onOff

Le strutture di dati definite da un trait vengono importate dalla classe trait il cui nome termina con "-Trait":

import com.google.home.matter.standard.MediaPlaybackTrait.PlaybackStateEnum

I comandi dei tratti vengono importati dall'oggetto Companion del tratto:

import com.google.home.matter.standard.Thermostat.Companion.setTemperatureSetpointHold