09. Script e scene

Script e scene sono i due strumenti che HA offre per raggruppare azioni riusabili. Sono spesso confusi, ma servono a cose diverse. In questo capitolo vediamo la differenza pratica fra i due, quando usarne uno o l’altro, come si chiamano fra loro, e perché a volte l’errore è usarli quando in realtà bastava un’automazione più chiara.

Le due domande semplici da farsi

Prima delle definizioni tecniche, la scelta si riduce a due domande:

• “Voglio riportare le cose in un certo stato” → scena.
  Esempio: alle 22:00 tutte le luci del salotto al 20% color caldo, tende al 30%, TV spenta. Non ti interessa come ci si arriva, ti interessa lo stato finale.

• “Voglio eseguire una sequenza di azioni” → script.
  Esempio: quando dico “buonanotte”, spegni tutte le luci, verifica che le porte siano chiuse, arma l’allarme in modalità “casa”, invia una notifica al mio telefono con il riepilogo.

Se la risposta è “entrambe”, di solito lo script è la scelta giusta, perché uno script può anche chiamare una scena.

Le scene

Una scena è una fotografia dello stato di un gruppo di entità in un dato momento. Salva il valore di ogni entità inclusa (on/off, brightness, temperatura, posizione tenda, ecc.). Quando la attivi, ogni entità torna al valore memorizzato.

Creare una scena

Il modo più veloce è “cattura dallo stato attuale”:

1. Metti manualmente il salotto come lo vuoi (luci a certo brightness, tenda in certa posizione, ecc.).
2. Impostazioni → Scene → Aggiungi scena → Cattura entità.
3. Selezioni le entità che devono far parte della scena, HA legge il loro stato attuale e lo salva.
4. Dai un nome (“Salotto, serata rilassante”) e salvi.

Da quel momento hai una scene.salotto_serata_rilassante. Per attivarla: scene.turn_on con target la scena.

Cosa può salvare una scena

Molte cose ma non tutte. Salva stato base + attributi visibili delle entità:

• Luci: on/off + brightness + color + color temp
• Interruttori: on/off
• Tende: posizione
• Termostati: setpoint + hvac mode
• Media player: source, volume (parzialmente)

Non può salvare cose come “avvia scansione robot aspirapolvere” o “manda notifica”: quelle sono azioni, non stati. Per quelle serve uno script.

Scena vs “azione che attiva luci”

La tentazione, arrivando dall’editor automazioni, è di fare la scena “manualmente” nelle azioni: light.turn_on con brightness 50, light.turn_on sull’altra con brightness 30, ecc. Funziona, ma per stati complessi è tanti click e diventa illeggibile. La scena centralizza tutto in un oggetto solo, e se un domani vuoi cambiare “un po’ più luminose”, cambi la scena e tutte le automazioni che la chiamano ne beneficiano.

Gli script

Uno script è una sequenza di azioni che puoi eseguire come se fosse un servizio. La sintassi delle azioni è identica a quella delle automazioni (call_service, delay, wait_template, choose, repeat, ecc.).

Creare uno script

Impostazioni → Script → Aggiungi script. L’editor è praticamente lo stesso delle automazioni, solo che non ha la sezione trigger/condition: uno script viene chiamato da qualcun altro (un’automazione, un pulsante Lovelace, un altro script, un comando vocale), quindi non “scatta da solo”.

Esempio pratico: “Buonanotte”.

sequence:
  - service: light.turn_off
    target:
      area_id:
        - salotto
        - cucina
        - ingresso
  - service: cover.close_cover
    target:
      entity_id: cover.tenda_salotto
  - service: alarm_control_panel.alarm_arm_home
    target:
      entity_id: alarm_control_panel.casa
  - service: notify.mobile_app_iphone
    data:
      message: "Casa messa a dormire. Ci si vede domani."

Una volta salvato hai script.buonanotte. Puoi chiamarlo da:

• un’automazione (action → script.turn_on o direttamente service: script.buonanotte)
• un pulsante Lovelace (card Button → tap action → call service script.buonanotte)
• un comando vocale Assist (“buonanotte”)
• l’app mobile (dalla schermata degli script)

Perché non fare tutto in un’automazione

La domanda giusta è: quel blocco di azioni serve solo a un’automazione, o è riusabile?

Se serve solo lì (es. “quando arriva una notifica, aggiorna un contatore”), scrivilo direttamente dentro l’automazione. Estrarlo in uno script aggiunge un livello di indirezione senza guadagno.

Se lo stesso blocco serve a più automazioni o a un pulsante Lovelace o a un comando vocale, allora estrai in uno script: cambi la logica in un posto solo.

Parametri (script con “campi”)

Gli script possono accettare parametri come una funzione. Definizione nell’editor sotto “Fields”:

• light (entity, richiesto)
• brightness (number 0-100, default 50)
• transition (number, default 2)

Nel body dello script usi {{ light }}, {{ brightness }}, ecc. Chi lo chiama passa i valori. Utile per script tipo “accendi la luce X al brightness Y” chiamato da più automazioni diverse.

Come i tre pezzi si combinano nella pratica

Un tipico “flusso serale”:

• Automazione: trigger sun (30 min dopo il tramonto) + condition (è un giorno feriale) → chiama script serata.
• Script serata: → attiva scene.salotto_serata + accende le luci corridoio al 30% + invia notifica.
• Scena salotto_serata: memorizza lo stato desiderato del salotto (luci, tende, TV).

L’automazione decide quando. Lo script decide cosa. La scena decide come stanno le cose.

Se domani cambi orario (“30 min prima del tramonto invece che dopo”) tocchi solo l’automazione. Se cambi routine (“aggiungi profumatore ambiente”) tocchi solo lo script. Se cambi “un po’ più caldo il salotto” tocchi solo la scena.

Quando NON usarli

Script per fare una cosa sola. Se lo script contiene una singola action, meglio non estrarlo. script.accendi_salotto che dentro fa solo light.turn_on: light.salotto è ridondante: chiama direttamente il servizio.

Scene per stati che cambiano nel tempo. Se la scena “serata” richiede brightness “80% se qualcuno è in casa, altrimenti 20%”, la scena non ce la fa (è statica). Serve uno script con choose che a runtime decide.

Script come workaround per non capire le mode. Se stai spezzando un’automazione in tre script perché “così parte solo il primo se il secondo non è finito”, quasi sempre la soluzione era mettere l’automazione in mode: single e basta.

Ricapitolando

• Scena: fotografia di stati, la richiami e le cose tornano lì.
• Script: sequenza di azioni riusabile, con parametri se serve.
• Automazioni decidono quando, script cosa, scene come stanno le cose.
• Estrai in script solo se la logica è riusabile da più chiamanti.
• Le scene sono statiche: per logica condizionale serve uno script.