Quando si iniziano a superare i primi scogli nella configurazione di Home Assistant, e magari si scrive qualche automazione o se ne ricicla sapientemente una di altri, ci si imbatte abbastanza rapidamente nei template. La documentazione ufficiale li definisce come uno strumento “avanzato” di Home Assistant, ed indubbiamente sono uno degli aspetti meno intuitivi e immediati da comprendere.

Vale la pena imparare ad usare i template?

In breve, sì. L’utilizzo dei template (o modelli, in italiano) rende possibile un livello di controllo molto più elevato. Comprendendone i principi di base si riesce spesso a snellire la logica delle automazioni più complesse e si capisce anche un po’ meglio come funziona Home Assistant, che è cosa buona e giusta.

Introduzione

Giusto per dare una definizione di massima, iniziamo a dire che i modelli possono essere utilizzati principalmente per:

1. Formattare le informazioni in ingresso, solitamente da sensori di dati “grezzi” come MQTT, REST, o i sensori linea di comando;
2. Aiutare nella scrittura di automazioni complesse, sotto forma di Template Trigger o Template Condition, ed introdurre il concetto di variabili nelle automazioni stesse;
3. Creare interruttori, luci o sensori che mostrano dati di nostro interesse, e sui quali vogliamo un controllo totale.

La sintassi

Iniziamo ad occuparci della sintassi, per poi passare a qualche esempio di utilizzo pratico. I modelli sono stringhe in linguaggio Jinjia2 che vengono interpretate da HA fornendoci un risultato. Per prima cosa dobbiamo familiarizzare con la scheda “Modelli” che troviamo sotto il solito “Strumenti per Sviluppatori”.

Si tratta di un editor ed interprete di template integrato nell’interfaccia di Home Assistant: scrivendo nella parte sinistra delle stringhe valide in Jinjia2, queste vengono istantanemente interpretate mostrando il risultato a destra. Arrivando qui si troveranno già alcuni esempi, sia quelli con condizioni (if) o azioni (set) che altri in cui si provvede semplicemente a trasformare variabili (o proprietà) in testo semplice da concatenare in una stringa. Più precisamente, il primo blocco di codice definisce il contenuto di una variabile (per altro in formato json), il secondo la utilizza in una espressione del tipo “La temperatura è tot gradi”, mentre nel terzo si verifica lo stato di due diversi dispositivi e si decide di conseguenza cosa “mostare” all’utente.

Da questi primi esempi possiamo notare che l’output di stringhe in Jinjia2 si ottiene racchiudendo il codice tra {{ e }}, mentre le condizioni e le azioni sono comprese all’interno di {% e %}. Le parentesi graffe su macOS si ottengono facilmente con le combinazioni ⌥⇧è e ⌥⇧+

Home Assistant fornisce numerose estensioni che permettono ai modelli di avere accesso agli stati ed agli attributi delle entities del sistema. Citeremo qualche esempio in seguito. In linea generale possiamo dividere le possibilità di scrittura in due macrocategorie di modelli distinti, a seconda del risultato che forniscono, una volta interpretati:

1. Vero/Falso
Sono utilizzabili ad esempio nelle Template Conditions, ma anche nei Template Binary Sensors.

{{ is_state('light.cucina', 'off') }}

Questo codice restituirà True (Vero) se lo stato della entity light.cucina è off (cioè se la luce è spenta) o False (Falso) in tutti gli altri casi (ovvero se è accesa, visto che qui ci sono solo due stati)). Seguendo il principio base delle automazioni, secondo cui le conditions sono dei test che interrompono l’esecuzione se non verificati, inserendo questa espressione come Template Condition si arriverebbe alla action solo se questa fosse verificata all’innesco del trigger (ovvero se la luce in cucina fosse spenta).

Se qualcosa di quanto appena scritto non vi è chiara, consigliamo di rileggere l’articolo con i concetti di base delle automazioni.

2. Valore effettivo
I templates di questo tipo sono utilizzabili nei Template Sensors ma, grazie agli operatori di comparazione che vedremo in seguito, sono facilmente trasformabili in modelli Vero/Falso.

{{ states.sun.sun.attributes.elevation }}

L’esempio qui sopra restituirà il valore in gradi (numerico, in questo caso) dell’attuale elevazione del sole, nel momento e nel luogo dove lo interpretiamo, grazie alle caratteristiche intrinseche del componente sun.sun.

Operazioni con le espressioni

Jinjia è già nativamente capace di gestire operazioni logiche, matematiche e di comparazione, e queste caratteristiche ci sono estremamente utili per la scrittura dei nostri templates in HA. Riporto in tabelle un breve riassunto delle operazioni che è possibile eseguire.

Operazioni logiche
Sono utilizzabili i principali connettivi logici and, or e not:

Operazioni matematiche
Non sono molto sfruttate nei modelli, ma è possibile utilizzare i principali operatori:

Operazioni di comparazione
Quelle di confronto sono sicuramente le espressioni più utilizzate:

Resta inteso che si possono utilizzare le parentesi tonde per concatenare logicamente più operazioni o confronti, nonché l’esistenza di costrutti come i filtri e le condizioni if, che spiegheremo quando li incontreremo negli esempi.

L’utilizzo in Home Assistant

Passando al funzionamento sul campo, ci viene sicuramente comodo rivedere i dettagli mostrati nella pagina Stati degli Strumenti per Sviluppatori relativamente ad una entity di tipo light (esatto, una luce).

Come ormai avrete imparato, la colonne rappresentano (da sinistra a destra) l’entità, il suo stato e i vari attributi. Tenendo presenti proprio questi ultimi, scriviamo alcuni template (non si sa mai se parlare in inglese o italiano…) che trasformano quelle proprietà in valori:

Diverse espressioni si possono connettere logicamente con le operazioni viste prima. Ad esempio si potrebbe voler verificare che sia la luce della cucina del garage siano spente, aggiungendo tra di essere la parolina magica “and”.

{{ is_state('light.cucina', 'off') and is_state('light.garage', 'off') }}

O ancora andare a mischiare il semplice stato di una delle luci (acceso/spento) con una verifica sulla luminosità di un’altra. Data la presenza di “and” l’espressione restituirà True (Vero) solo se entrambe le verifiche tra parentesi saranno True.

{{ (states.light.cucina.attributes.brightness < 200) and is_state('light.garage', 'off') }}

Più ci si addentra nell’uso di Home Assistant e più ci si accorge dell’importanza della pagina Stati negli Strumenti per Sviluppatori (<>). Qui si possono imparare molte cose sulle entità e sulle loro proprietà, capendo come queste cambiano e sfruttando la cosa nelle automazioni. Se ad esempio volessimo creare una condition che faccia eseguire delle azioni solo se non siamo presenti a casa, la cosa più semplice da fare sembrerebbe essere quella di utilizzare una state condition di questo tipo:

condition:
  condition: state
  entity_id: device_tracker.alberto
  state: 'not_home'

Una condizione come questa funziona perfettamente, se però non abbiamo settato altre zone al di fuori di quella “home” di default.

Lo stato di device_tracker.alberto, infatti, rispecchia la zona in cui il device si trova: se siamo a casa lo state sarà ‘home’, se siamo per strada sarà ‘not_home’, ma se siamo nella zona che abbiamo indicato come lavoro sarà ‘lavoro’, come indicato nel seguente diagramma:

Quindi, se ci troviamo al lavoro la condition scritta sopra darà il risultato False e non permetterà l’esecuzione dell’automazione, nonostante in realtà noi ci troviamo fuori casa. Conoscendo questo fenomeno (l’evoluzione degli stati della entity device_tracker.alberto) possiamo risolvere rapidamente il problema con una Template Condition:

conditions:
  condition: template
  value_template: '{{ not is_state("device_tracker.alberto", "home") }}'

Nel codice qui sopra notate principalmente una cosa: per far capire ad HA che il valore indicato è un template bisogna utilizzare “value_template” e non il semplice “value”. Con questa prima applicazione pratica concludiamo la parte uno del nostro approfondimento sui modelli. Nella successiva vedremo qualche esempio applicato a casi reali, così da capire come questo strumento di Home Assistant possa aiutarci nella scrittura di automazioni e nel mostrare le informazioni di nostro interesse.

Autore:
Alberto Zamboni (@albyzambo)

Revisore:
Davide (@daxda)
Maurizio Natali (@simplemal)