Gli “script” di Home Assistant, cosa sono e come si usano

Un’importante freccia all’arco degli utilizzatori di Home Assistant – specialmente in affiancamento alle automazioni – sono gli “script“. In realtà, per amore di chiarezza, sarebbe forse stato meglio chiamarli “sequenze” (ma tant’è), perché di questo si tratta.

In pratica le entità di tipo “Script”, quando evocate, eseguono una serie di azioni sequenziali, le quali possono anche essere condizionate da condizioni (condition), ritardi di esecuzione (delay) e attese (wait).

• Definire uno script
• Variabili
• Condition
• Delay
• Wait
• Innesco

Come definire uno script

La definizione di una o più entità di tipo “Script” è piuttosto semplice, specialmente per chi abbia dimestichezza con le automazioni di Home Assistant.

Ci sono due modi per definire/amministrare/modificare uno script:

• tramite interfaccia utente Home Assistant;
• a mano.

Interfaccia utente

È il metodo più semplice: permette, tramite interfaccia web/app, di definire uno script il quale, una volta salvato, verrà aggiunto al file scripts.yaml.

Cliccando su “Impostazioni” / “Script” / “+” presso il frontend, infatti, apparirà una web form tale da permetterci da configurare il nome dello script e indicare la sequenza di azioni da attuare:

Al termine della configurazione, sarà sufficiente salvare e rendere così operativa l’automazione.

MANUALMENTE

Per aggiungere uno script è sufficiente aggiungere in configurazione (tipicamente nel file scripts.yaml) un blocco analogo al seguente:

script:
  ritorno_a_casa:
    sequence:
      - service: light.turn_on
        data:
          entity_id: group.ingresso
          brightness: 100
      - delay:
          minutes: 1
      - service: switch.turn_on
        entity_id: switch.acqua

La configurazione di cui sopra definisce un’entità chiamata “script.ritorno_a_casa” la quale, se evocata tramite il servizio “script.turn_on” provvede all’accensione di un gruppo di luci (“group.ingresso“), attende un minuto dopodiché apre l’acqua in casa attivando lo switch.acqua (immaginandolo come un attuatore collegato a un’elettrovalvola integrato a Home Assistant).

Come i più attenti avranno notato, la definizione della sequenzialità è in tutto e per tutto analoga a quella definibile all’interno di un comune blocco “action” di un’automazione.

Ovviamente all’interno del blocco “script:” è possibile definire quanti script si vuole, per esempio:

script:
  uscita_di_casa:
    sequence:
      - service: light.turn_off
        entity_id: group.ingresso
      - service: switch.turn_off
        entity_id: switch.acqua
  ritorno_a_casa:
    sequence:
      - service: light.turn_on
        data:
          entity_id: group.ingresso
          brightness: 100
      - delay:
          minutes: 1
      - service: switch.turn_on
        entity_id: switch.acqua

Variabili

L’adozione degli script consente, all’atto della loro esecuzione, il passaggio di variabili. Si tratta di un concetto banale quanto versatile: questo consente di definire degli script che varino il loro comportamento in base alle variabili previste che gli vengono passati.

Poniamo per esempio di aver definito uno script che provveda alla regolazione del volume di tutti dispositivi Alexa integrati come “Media Player” presenti in casa:

script:
  volume_alexa:
    sequence:
      - service: media_player.volume_set
        data_template:
          entity_id: media_player.alexa_sala, media_player.alexa_camera
          volume_level: '{{ volumelevel }}'

Tale script (“script.volume_alexa“) provvede ad evocare il servizio “media_player.volume_set” imponendo alle due entità indicate di regolare il proprio volume tramite il parametro “volume_level“, al quale viene passata la variabile “volumelevel“.

Evocare tale script via automazione è  piuttosto semplice:

automation:
  alias: "Regolazione volume"
  trigger: [] # qualcosa che inneschi l'automazione
  condition: []
  action:
    - service: script.turn_on
      entity_id: script.volume_alexa
      data:
        variables:
          volumelevel: 0.5

Condition (condizione)

Gli script vengono eseguiti in modo sequenziale, dall’alto verso il basso. Nella sequenza è possibile introdurre una o più condizioni (anche annidate) al fine di consentire allo script di proseguire o meno nell’esecuzione in base al verificarsi o meno della condizione definita.

Poniamo il seguente esempio:

script:
  accensione_luce_condizionata:
    sequence:
      - condition: numeric_state
        entity_id: sensor.broadlink_sensor_light
        below: 2
      - service: light.turn_on
        entity_id: light.sala

In questo esempio “script.accensione_luce_condizionata“, quando eseguito, prima di accendere la luce “light.sala” verifica le condizioni di luce a partire dal sensore “sensor.broadlink_sensor_light” derivante dall’integrazione di un sensore Broadlink A1 e-Air. Se il sensore rileva un grado di luminosità maggiore o uguale a 2, la sequenza si interrompe e la luce non viene accesa.

Delay (ritardo)

La particella “delay” consente di interrompere temporaneamente – per un tempo definito – l’esecuzione di uno script.
Le possibilità di configurazione sono svariate. Alcuni esempi:

# Attende un'ora
- delay: '01:00'

# Attende un minuto e 30 secondi
- delay: '00:01:30'

# Attende un minuto
- delay:
    # Supporta millisecondi, secondi, minuti, ore, giorni
    minutes: 1

# Attende un numero di secondi preimpostato tramite l'entità input_number.second_delay
- delay:
    # Supporta millisecondi, secondi, minuti, ore, giorni
    seconds: "{{ states('input_number.second_delay') }}"

# Attende un numero di secondi preimpostato tramite l'entità input_number.minut_delay
# Formati validi includono HH:MM e HH:MM:SS
- delay: "{{ states('input_number.minute_delay') | multiply(60) | timestamp_custom('%H:%M:%S',False) }}"

Wait (attesa)

A differenza di “delay”, la particella “wait_template” sospende l’esecuzione in attesa del verificarsi di una data condizione, tipicamente un cambio (specifico) di stato di una entità. Ovviamente è possibile configurare il “wait” in modo da sbloccare la situazione a fronte del passaggio di uno specifico lasso di tempo, oltre che dirli cosa fare, successivamente, in tal caso.

Vediamo un esempio:

# Attende che il sensore binary_sensor.ingresso rilevi l'apertura di un varco
- wait_template: "{{ is_state('binary_sensor.entrance', 'on') }}"
  timeout: '00:01:00'
  continue_on_timeout: 'false'

La sequenza non procede oltre questo blocco finché lo stato del sensore non diventi “on” (entro un minuto).  Se lo stato del sensore non diventa “on” entro un minuto, la sequenza si interrompe.

Innesco

L’avvio di uno script può essere eseguito in vari modi; il servizio comunque da utilizzare è sempre il medesimo, ovvero script.turn_on. Tipicamente utilizzati nelle automazioni di Home Assistant, può essere anche utile innescare manualmente gli script utilizzando degli switch virtuali.

Ulteriori informazioni sulla sintassi degli script sono disponibili sulla pagina dedicata presso il sito di Home Assistant.

Definire switch virtuali per comandare sequenze (script) Home Assistant

ATTENZIONE: ricorda che sul nostro community FORUM c'è una sezione ad hoc dedica a Home Assistant, per qualsiasi dubbio, domanda, informazione nel merito specifico di queste componenti.