Esercizi di domotica su Home Assistant: “1 – Creare dei sensori template”

Altre esercitazioni:

• Esercizi di domotica su Home Assistant: “2 – Definire diversi trigger per innescare automazioni”
• Esercizi di domotica su Home Assistant: “3 – Automazioni, come definire le action da eseguire”
• Esercizi di domotica su Home Assistant: “4 – Script, come realizzarli ed eseguirli”

Gli esercizi di questa puntata

In questa prima esercitazione vi insegneremo a prendere dimestichezza con l’HUB per quanto riguarda i sensori. 

Capiremo in primis cosa siano i sensori, come si generino in modo automatico su Home Assistant e poi, successivamente, capiremo – provando con mano – come definirne alcuni in modo manuale, sfruttando l’integrazione “Template“, la quale si appoggia al motore template Jinja. Gli esempi sono esplicativi: sta all’utente identificare, sulla base di quanto a propria disposizione, gli elementi da utilizzare per testare le tecniche qui spigate.
Si consiglia di non saltare alcuna parte del corso espresso in questa puntata.

In primis: cosa sono i sensori?

Figli del componente “Sensor”, i sensori sono quelle entità riconoscibili dal prefisso “sensor.” le quali, tipicamente, vengono utilizzate dall’utente per censire metriche di diversa natura. Esistono poi i sensori figli di un dio minore (ma egualmente importanti) prodotti dal componente “Binary Sensor“, i quali possono assumere solo stati binari (“on“/”off“) e che si riconoscono dal prefisso “binary_sensor.”

Naturalmente si tratta delle tipologie di entità tra le più importanti: rappresentano gli organi di senso della nostra domotica, utili in consultazione ma, sopratutto, nell’uso con automazioni e script.

L’elenco completo di tutte le entità presenti in dato momento sull’HUB è disponibile, presso la sua interfaccia è disponibile alla voce “Strumenti per gli sviluppatori” > “Stati“. Scendendo in basso, si troveranno – se ne sono stati creati – una o più entità dal prefisso “sensor.” (o “binary_sensor.” nel caso dei sensori binari).

I sensori (normali o binari) vengono generati automaticamente all’atto della configurazione di una piattaforma di integrazione che preveda l’uso dei componenti “Sensor” e/o “Binary Sensor”. Per esempio, la piattaforma per l’integrazione “Netatmo” serve per integrare componenti domotici della linea Netatmo: tale integrazione sfrutta svariati componenti Home Assistant tra i quali, appunto, “Sensor”, dando così vita a svariati sensori (e molte altre entità) in base ai componenti Netatmo integrato tramite essa.

I sensori possono essere generati da una quantità enorme di diverse piattaforme di integrazione, tra le quali la sopracitata “Template“. Tale piattaforma consente di definire, manualmente, dei sensori “derivati“, ovvero dei sensori che – a partire da un generico algoritmo – possano esporre degli stati arbitrari.

Esercizi

• Esercizio 1.1: creare un generico sensore template
• Esercizio 1.2: creare un sensore casuale
• Esercizio 1.3: creare un sensore condizionale
• Esercizio 1.4: creare un sensore binario

Esercizio 1.1

Mettiamo di disporre di un’entità di tipo “Climate” (termostato) derivata dall’integrazione “Tado” per gli omonimi componenti. e mettiamo (come in effetti capita) che tale entità collezioni, nei suoi attributi, contenga la rilevazione della temperatura dell’ambiente in cui è installato il termostato:

L’esempio di cui sopra riporta, per l’entità climate.home (colonna a sinistra) derivata dall’integrazione, il suo stato (“auto“, ovvero modalità di riscaldamento automatica, colonna centrale) e una serie di interessanti attributi, i quali riportano svariati parametri operativi (colonna di destra). Tra di essi, interessante l’attribuito “temperature“, il quale riporta, come detto, la temperatura dell’ambiente in cui il termostato è installato.

Diventa quindi utile definire, per comodità, un sensore personalizzato che riporti nel proprio stato il valore di quell’attribuito.

Innanzitutto, come si estrae quel valore?

Si utilizza la sintassi states.NOME_ENTITA.attributes.NOME_ATTRIBUITO. Calandolo sul nostro esempio, la sintassi di estrazione del valore quindi è:

states.climate.home.attributes.temperature

oppure, con una sintassi più pulita, tramite la funzione state_attr():

state_attr(“climate.home”,”temperature”) 

per verificare che l’estrazione avvenga a buon fine, si usa il trucco di accedere al pannello “Strumenti per gli sviluppatori” > “Modelli” e nell’editor modelli si inserisce la sintassi completa prevista da Home Assistant:

‘{{ states.climate.home.attributes.temperature }}’

oppure:

‘{{ state_attr(“climate.home”,”temperature”) }}’

il quale, come risultato, riporta una stringa contenente il valore atteso.

Per fare ancora di meglio, è bene esplicitare la natura del dato e il suo “default”, ovvero quale valore Home Assistant debba assumere in assenza di dato all’origine. Variando la configurazione come segue:

‘{{ states.climate.home.attributes.temperature|float(default=0) }}’

oppure:

‘{{ state_attr(‘climate.home’,’temperature’)|float(default=0) }}’

si esplicita che il valore sia di tipo decimale e che il default, in caso di assenza di dato all’origine, sia 0. L’assenza di espliciti default può portare a errori sull’HUB, quindi è sempre meglio esplicitarli d’abitudine.

Come creare il sensore

In questo caso è necessario aggiungere un blocco alla propria configurazione YAML.
Se non si sa di cosa si stia parlando, è certamente necessario leggere l’approfondimento sulla configurazione YAML dell’HUB.

Il blocco va aggiunto sotto la chiave “sensor:“, sia che sia presente sul file principale di configurazione configuration.yaml sia i contenuti della chiave siano dislocati, per scelta, su file sidecar. Se la chiave è assente, va creata (appena installato l’HUB, tale chiave non esiste sul file di configurazione).

Il blocco YAML d’esempio è il seguente:

template:
  - sensor:
      temperatura_sala:
        friendly_name: "Temperatura della sala"
        value_template: '{{ states.climate.home.attributes.temperature }}'
        unit_of_measurement: "°C"
        icon_template: mdi:thermometer

sotto la chiave “sensors:” andiamo a definire un sensore di tipo template (“platform: template“) chiamato “temperatura_sala“, contenente i seguenti parametri:

• friendly_name, ovvero il nome “amichevole” che verrà visualizzato sull’interfaccia;
• value_template, ovvero “dove andrà a prendere il valore del suo stato” (definito in precedenza);
• unit_of_measurement, ovvero l’unità di misura dello stato, in questo caso gradi centrigradi;
• icon_template, ovvero l’icona di materialdesign che verrà visualizzata in interfaccia, in questo caso un termometro.

Uscire e salvare.  Questo punto verificare che la propria configurazione sia corretta: recarsi alla voce di menu “Strumenti per sviluppatori” > “YAML“, cliccare su “Verifica configurazione“: se tutto ok, cliccare su “RIAVVIA” per riavviare Home Assistant – altrimenti correggere gli eventuali errori.

Al riavvio dell’HUB, una nuova entità sarà “nata”, chiamata “sensor.temperatura_sala” con le caratteristiche di cui sopra.

Alcuni sensori template possono tra l’altro essere aggiornati sulla base non di un template quando di un trigger vero e proprio, così come spiegato in questa guida dedicata all’estrazione di informazioni orarie da un’entità Weather.

Esercizio 1.2

Proviamo ora a creare un sensore casuale, ovvero un sensore che riporti un valore a caso.

Ipotizziamo di voler scrivere un’automazione che, una volta all’ora, cambi in modo casuale lo schema colorato delle nostre lampade Nanoleaf integrate su Home Assistant. Ci serve un sensore che, quando gli si richieda l’aggiornamento forzoso, riporti un nuovo valore casuale, da passare poi alle entità di tipo “Light“.

Ipotizziamo quindi una configurazione simile alla seguente:

template:
  - sensor:
      nanoleaf_random_effect:
        friendly_name: "Effetto luminoso casuale Naoleaf"
        value_template: >-
            {{ ["Berries Cocktail",
            "Berries n Cream",
            "Big Sur Dark",
            "Calm Forest",
            "Cocoa Beach",
            "cyberpunk",
            "Emerald Sun",
            "Falling Whites"] | random }}

questa configurazione, grazie all’ausilio della funzione random, genera un’entità chiamata sensor.nanoleaf_random_effect la quale, quando evocata tramite l’action homeassistant.update_entity, fornirà uno stato diverso contenente uno degli effetti sopra elencati (“Berries n Cocktail“, “Big Sur Dark” eccetera).

Immaginando quindi di avere un’entità light.nanoleaf data dall’integrazione delle nostre Nanoleaf sull’HUB, potrei quindi completare l’action della mia automazione come segue:

#parte finale dell'automazione
    action:
      - action: homeassistant.update_entity
        entity_id: sensor.nanoleaf_random_effect
      - action: light.turn_on
        entity_id: light.nanoleaf
        data:
          effect: "{{ states('sensor.nanoleaf_random_effect') }}" 

la funzione states(‘sensor.nanoleaf_random_effect’), infatti, riporta lo stato di sensor.nanoleaf_random_effect forzosamente aggiornato in modo casuale subito prima da homeassistant.update_entity.

action: homeassistant.update_entity
data:
  entity_id: sensor.NOMEDELSENSORE

Esercizio 1.3

Vediamo ora di creare un sensore condizionale, ovvero che assuma uno stato piuttosto che un altro in base a delle condizioni prefissate.

Ipotizziamo di aver integrato la stazione Meteo della Netatmo: tale integrazione fornisce, di suo, un sensore che riporta il valore di CO2 presente nella stanza in cui è posizionato il sensore/i.

Ma se volessi un sensore che riportasse genericamente la qualità dell’aria espressa sotto forma di stringhe intelleggibili?
Potrei realizzarlo come segue. Ipotizziamo che il sensore Netatmo si chiami sensor.netatmo_casa_co2, la configurazione potrebbe essere

template:
  - sensor:
      air_quality:
        friendly_name: "Qualità dell'aria di casa"
        icon_template: mdi:jquery
        value_template: >-
          {% if states('sensor.netatmo_casa_co2')|int <= 500 %}
            Eccellente
          {% elif (states('sensor.netatmo_casa_co2')|int > 500 and states('sensor.netatmo_casa_co2')|int <= 1000) %}
            Buona 
          {% elif (states('sensor.netatmo_casa_co2')|int > 1000 and states('sensor.netatmo_casa_co2')|int <= 1500) %}
            Normale
          {% elif (states('sensor.netatmo_casa_co2')|int > 1500 and states('sensor.netatmo_casa_co2')|int <= 2000) %}
            Viziata
          {% elif states('sensor.netatmo_casa_co2')|int > 2000 %}
            Molto viziata
          {% else %}
            -unknown-
          {% endif %}

Questa configurazione genera un sensore chiamato sensor.air_quality il quale assume un valore in base agli intervalli sopra espressi, ovvero:

• sotto le 500 parti per milione di CO, assume valore “eccellente“;
• da 500 a 1000, assume valore “buona“;
• da 1000 a 1500, assume valore “normale“;
• da 1500 a 2000, assume valore “viziata“;
• sopra a 2000, assume valore “molto viziata“;
• in caso di assenza di valore, assume valore “-unknown-“.

Questo sensore potrà poi venire utilizzato per esempio in automazione:

automation:
  - alias: "NOTIFICA - CO2"
    id: "notifica_co2"
    initial_state: true
    trigger:
      - platform: state
        entity_id: sensor.air_quality
        to: 'Viziata'
        for:
          minutes: 20
    condition:
      - condition: state
        entity_id: group.awesome_people
        state: 'home'
    action:
      - action: notify.alexa_media
        data:
          target: media_player.alexa
          data:
            type: announce
            method: speak
          message: "In casa c'è aria viziata." 

In questa automazione di esempio, Alexa (integrata come media player) ci avvisa con un messaggio vocale dell’insalubrità dell’aria di casa e lo fa quando il sensore sensor.air_quality assume valore “Viziata” per più di 20 minuti, ma solo se siamo a casa (usando lo stato dell’entità gruppo group.awesome_people come condition per l’esecuzione).

Esercizio 1.4

Fin qui abbiamo visto sensori figli del componente “Sensor” ma non del componente “Binary Sensor“, ovvero – come spiegato all’inizio – sensori che possono assumere solo stati binari (“on“/”off“). 

I sensori binari template si definiscono come per i sensori “normali”: l’unica differenza sta nel fatto che il blocco o i blocchi di configurazione vanno aggiunti alla chiave “binary_sensor:” e non a “sensor:“.

Ipotizziamo di avere integrato in domotica un sensore che rilevi la potenza di assorbimento di un elettrodomestico tradizionale (diciamo una lavatrice) chiamato washing_machine_power. Possiamo assumere che, se tale sensore rilevi per più di 15 secondi un assorbimento maggiore di 5 Watt, la lavatrice stia operando, mentre sotto tale valore non sia operativa.

Possiamo definire un sensore binario così fatto:

binary_sensor:
  - platform: template
    sensors:
      washing_machine_status:
        friendly_name: "Stato operativo lavatrice"
        value_template: "{{ states('sensor.washing_machine_power')| int(default=0) > 5 }}"
        device_class: power
        delay_on:
          seconds: 15
        delay_off:
          seconds: 15

La configurazione di cui sopra è semplice da capire. Se la condizione:

“{{ states(‘sensor.washing_machine_power’)|int(default=0) > 5 }}”

è rispettata, lo stato del sensore binario è “on“, mentre se non la è, allora lo stato è “off“.
Inoltre, i parametri opzionali delay_on/delay_off meglio ci permettono di gestire il comportamento del sensore, indicando in 15 i secondi per i quali la condizione deve rimanere stabile affinché condizioni lo stato del sensore binario.

Conclusioni

Il tema dei sensori è vastissimo. La possibilità di definirne alcuni custom fornisce all’utente Home Assistant un’incredibile versatilità di configurazione. 

Ovviamente in questa scheda di esercitazione non abbiamo toccato tutte le possibilità a disposizione (come potremmo!), ma abbiamo cercato di dare all’utente novello qualche elemento cardine su come si effettuano queste configurazioni.

Per tutte le possibilità legate al componente “Template”, si faccia dunque riferimento alla documentazione ufficiale.

Altre esercitazioni:

• Esercizi di domotica su Home Assistant: “2 – Definire diversi trigger per innescare automazioni”
• Esercizi di domotica su Home Assistant: “3 – Automazioni, come definire le action da eseguire”
• Esercizi di domotica su Home Assistant: “4 – Script, come realizzarli ed eseguirli”