Guida al DSL di Android per automazioni complesse

Il DSL di automazione può essere utilizzato per creare automazioni più complesse di quelle descritte in guida al DSL - automazioni di base su Android.

Sequenziale con più azioni

Un'automazione può eseguire più di un'azione. Ad esempio, al posto del singolo nodo action, puoi avere più nodi action, che vengono eseguiti in ordine sequenziale:

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

Sequenziale con più azioni parallele

Se inserisci più nodi action in un nodo parallel, le azioni vengono eseguite contemporaneamente.

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

Se nel nodo sequential sono presenti nodi action che seguono il nodo parallel, questi attendono l'esecuzione fino al completamento di tutti i nodi all'interno del nodo parallel.

Esecuzione condizionale

Per impostazione predefinita, un'automazione esegue i nodi in sequenza o in parallelo. Se hai bisogno di una logica di ramificazione condizionale, ovvero di eseguire azioni o percorsi diversi in base alle condizioni di runtime, utilizza le istruzioni if-then-else, che vengono create utilizzando i blocchi DSL di flusso di controllo condizionale: ifThen, elseIf, e orElse.

Mentre un nodo condition standard limita l'intera automazione (se la condizione restituisce false, l'esecuzione dell'automazione termina immediatamente), i blocchi ifThen consentono il flusso di controllo di ramificazione:

• Nodo condition: interrompe l'esecuzione dell'intera automazione (o del percorso di esecuzione corrente) se l'espressione è false.
• ifThen / elseIf / orElse: valuta le condizioni in ordine. Se una condizione è false, l'esecuzione passa al ramo elseIf successivo, al ramo di fallback orElse o continua ai nodi successivi nell'automazione se non viene soddisfatta alcuna condizione.

Eseguire un'azione in base a una condizione

Il blocco ifThen valuta un'espressione condizionale. Se l'espressione restituisce true, vengono eseguite le azioni o i nodi DSL nidificati all'interno del blocco. Se restituisce false, le azioni vengono ignorate e l'automazione continua con i nodi successivi nel flusso sequenziale.

Puoi utilizzare un blocco ifThen autonomo quando vuoi eseguire un'azione in modo condizionale senza bloccare o terminare i nodi successivi nell'automazione:

// When a door opens, turn on the light only if it is off,
// and always broadcast an announcement.
automation {
  sequential {
    val contactState = starter<_>(
      contactSensor,
      ContactSensorDevice,
      BooleanState,
    )
    val lightState = stateReader<_>(
      light,
      DimmableLightDevice,
      OnOff,
    )

    condition {
      // Door opened (contact sensor open)
      expression = contactState.stateValue equals false
    }

    // Conditionally turn on the light if it's off
    ifThen(lightState.onOff equals false) {
      action(light, DimmableLightDevice) { command(OnOff.on()) }
    }

    // Continue executing subsequent actions in the sequential flow
    action(structure) {
      command(AssistantBroadcast.broadcast("The door was opened."))
    }
  }
}

Eseguire azioni diverse in base a una condizione

Per eseguire un insieme di azioni quando una condizione è true e un insieme alternativo di azioni quando è false, concatenare il blocco .orElse { ... } facoltativo dopo ifThen(...) { ... }:

// When the door is unlocked, turn on the entryway light if it is off;
// otherwise, broadcast a welcome message.
automation {
  sequential {
    val doorLockEvent = starter<_>(
      doorLock,
      DoorLockDevice,
      LockOperationEvent,
    )
    val lightState = stateReader<_>(
      light,
      DimmableLightDevice,
      OnOff,
    )

    condition {
      expression =
        doorLockEvent.lockOperationType equals LockOperationTypeEnum.Unlock
    }

    ifThen(lightState.onOff equals false) {
      action(light, DimmableLightDevice) { command(OnOff.on()) }
    }.orElse {
      action(structure) {
        command(AssistantBroadcast.broadcast("Welcome home!"))
      }
    }
  }
}

Concatenare più condizioni in sequenza

Puoi concatenare uno o più blocchi .elseIf(...) { ... } facoltativi per valutare più condizioni in sequenza. Viene eseguito il primo ramo la cui condizione restituisce true e tutti i rami rimanenti vengono ignorati. Se nessuna delle condizioni restituisce true, viene eseguito un blocco .orElse { ... } facoltativo (se fornito):

// Adjust climate controls based on room temperature changes.
automation {
  sequential {
    val tempStarter = starter<_>(
      tempSensor,
      TemperatureSensorDevice,
      TemperatureMeasurement,
    )

    // If temperature is high (>= 28°C / 2800 mC), switch thermostat to Cool mode
    ifThen(tempStarter.measuredValue greaterThanOrEquals 2800) {
      action(thermostat, ThermostatDevice) {
        command(
          SimplifiedThermostat.setSystemMode(
            SimplifiedThermostatSystemModeEnum.Cool
          )
        )
      }
    }.elseIf(tempStarter.measuredValue lessThan 1800) {
      // If temperature is low (< 18°C / 1800 mC), switch to Heat mode
      action(thermostat, ThermostatDevice) {
        command(
          SimplifiedThermostat.setSystemMode(
            SimplifiedThermostatSystemModeEnum.Heat
          )
        )
      }
    }.orElse {
      // Otherwise, turn on the fan
      action(fan, FanDevice) {
        command(OnOff.on())
      }
    }
  }
}

Flussi condizionali nidificati

I blocchi condizionali possono essere nidificati all'interno di altri blocchi ifThen, elseIf o orElse, nonché combinati con i nodi parallel, delayFor e stateReader.

I blocchi ifThen, elseIf e orElse eseguono i contenuti come flussi sequenziali. Puoi inserire qualsiasi nodo sequenziale all'interno di ogni ramo, inclusi i blocchi action, stateReader, parallel, delayFor e ifThen nidificati.

Ritardi

Puoi introdurre pause nelle automazioni utilizzando la delayFor parola chiave, che accetta un java.time.Duration argomento che rappresenta la durata della pausa prima di continuare l'esecuzione. La durata della pausa può essere di soli cinque secondi o fino a 24 ore.

Ad esempio, per attivare/disattivare una luce quattro volte con una pausa di cinque secondi tra ogni attivazione/disattivazione:

sequential {
  action(light, OnOffLightDevice) { command(OnOff.toggle()) }
  delayFor(Duration.ofSeconds(5))
  action(light, OnOffLightDevice) { command(OnOff.toggle()) }
  delayFor(Duration.ofSeconds(5))
  action(light, OnOffLightDevice) { command(OnOff.toggle()) }
  delayFor(Duration.ofSeconds(5))
  action(light, OnOffLightDevice) { command(OnOff.toggle()) }
}

Soppressione dell'attivatore

La soppressione dell'attivatore è una funzionalità che consente all'automazione di ignorare un starter per un periodo di tempo specificato dopo l'evento di attivazione iniziale. Ad esempio, se l'automazione ha un starter attivato dal rilevamento del movimento e specifichi una durata di soppressione dell'attivatore di cinque minuti, quando l'attivatore starter viene attivato, non verrà attivato di nuovo per i cinque minuti successivi. In questo modo, l'automazione non viene attivata ripetutamente.

Per applicare la soppressione dell'attivatore all'automazione, utilizza la suppressFor parola chiave con un java.time.Duration argomento che rappresenta la durata dell'attesa prima di rispondere agli attivatori successivi. La durata della soppressione può essere di soli cinque secondi o fino a 24 ore.

automation {
  sequential {
    val starterNode = starter<_>(device, OccupancySensor, MotionDetection)
    suppressFor(Duration.ofMinutes(30))
    action(light, OnOffLightDevice) { command(OnOff.toggle()) }
}

Tieni presente che la soppressione dell'attivatore influisce su tutti gli starters in un'automazione che precedono suppressFor.

Limitare il numero di esecuzioni

Puoi limitare il numero di volte in cui è consentito eseguire un'automazione.

Ad esempio, potresti voler configurare un'automazione una tantum che esegue l'aspirapolvere mentre sei fuori casa per la giornata.

Per farlo, imposta il campo dei metadati maxExecutionCount dell'automazione. L'esempio seguente è un'automazione che può essere eseguita una sola volta:

automation {
  // The automation can only be executed once.
  maxExecutionCount = 1
  // When the door lock state changes
  sequential {
    val doorLockEvent = starter<_>(doorLock, DoorLockDevice, LockOperationEvent)
    // if the door is unlocked
    condition() {
      expression = (doorLockEvent.lockOperationType equals LockOperationTypeEnum.Unlock)
    }
    // turn the light on
    action(light, DimmableLightDevice) { command(OnOff.on()) }
  }
}

L'automazione viene eliminata immediatamente al termine dell'esecuzione per l'ultima volta e al raggiungimento di maxExecutionCount. La voce della cronologia dell'automazione rimane nella scheda Google Home app (GHA) Attività, incluso il automation_id.

Impostare gli attributi dei tratti in un'azione

Per impostare il valore di un attributo del tratto:

1. Crea un nodo update all'interno di un nodo action, includendo il tratto pertinente come argomento del nodo update nodo:

   action(deviceReference, deviceType) {
     update(trait) {
   
     }
   }

2. All'interno del nodo update, per ogni attributo da modificare, utilizza una funzione di mutazione e trasmetti il nuovo valore. Per formare il nome della funzione di mutazione:
   1. Metti in maiuscolo il nome dell'attributo
   2. Aggiungi il prefisso set.
   Ad esempio, per aggiornare un attributo denominato defaultMoveRate, utilizzeresti una funzione di mutazione denominata setDefaultMoveRate.

Tieni presente che un nodo update può avere più funzioni di mutazione. Ecco un esempio in cui vengono aggiornati due attributi:

action(device, Fan) {
  update(FanControl) {
    setPercentSetting(50u)
    setRockSetting(FanControlCluster.RockBitmap.rockUpDown)
  }
}