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

5 minuti di lettura

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.Home Assistant Official Logo

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).

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:

Home Assistant - Nuovo script

 

 

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.

Chooser

Capita spesso che si abbiano più script che controllino le medesime entità. Da questa nuova versione è possibile definire singoli script dotati di selettore, ovvero che eseguano porzioni di codice in base alle condizioni configurate.

Si prenda ad esempio questo blocco:

script:
    sequence:
      - choose:
        - conditions:
            - condition: state
              entity_id: binary_sensor.button1
              state: "on"
          sequence:
            - service: light.turn_on
              entity_id: light.bulb
        - conditions:
            - condition: state
              entity_id: binary_sensor.button2
              state: "on"
          sequence:
            - service: light.turn_off
              entity_id: light.bulb
        default:
          - service: notify.marco
            data:
              message: "E' stato premuto il pulsante 3"

In pratica l’automazione si innesca con la pressione di uno dei tre pulsanti indicati:

  • binary_sensor.button1
  • binary_sensor.button2
  • binary_sensor.button3

dopodiché nel blocco action avviene la magia: con la nuova sintassi, se viene premuto il pulsante 1, la luce viene accesa; col 2, viene spenta mentre nel caso del tre, dato che non è esplicitamente gestito, viene eseguito il sottoblocco default, ovvero quello che invia il messaggio.

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.

Repeat

Altra possibilità è quella di ripetere porzioni di script in tre diverse modalità:

Counted repeat Ripetizione a numero chiuso
While loop Ripetizione con proseguimento subordinato a una condizione specifica
Repeat until Ripetizione con uscita subordinata a una condizione specifica

Facciamo un esempio. Potremmo scrivere uno script che spammi un medesimo messaggio di notifica per dieci volte al proprio smartphone:

script:
- alias: Invia notifica spam al telefono
  repeat:
    count: 10
    sequence:
      - service: notify.marco
        data:
          message: Ding dong! C'è qualcuno alla porta!

e così via.

Innesco di uno script

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.

Modalità di esecuzione

Le automazioni prevedono, dalla versione 0.113 dell’HUB, anche la possibilità di variarne le modalità di esecuzione, ovvero il comportamento da tenere a fronte del presentarsi dei trigger di esecuzione durante un’esecuzione già in corso della medesima automazione. Sono stati inoltre introdotti anche dei costrutti utili a creare delle condizioni di scelta per l’esecuzione all’interno del blocco action.

A tal proposito abbiamo dedicato una scheda formativa ad hoc.


Home Assistant Official Logo 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.


Telegram News Channel