I “progetti” (o “blueprints”) di Home Assistant: cosa sono e come funzionano

A partire dalla prima versione stabile dell’HUB per domotica personale Home Assistant Core (la 1.0, meglio nota come 2020.12.x) sono state introdotte un po’ a sorpresa le “blueprints” (o meglio “Progetti“, almeno per come vengono tradotte sull’interfaccia dell’HUB in italiano). 

Detta in parole povere, le blueprints sono come le formine per biscotti: tramite ognuna di esse è possibile modellare una o più automazioni “gemelle”, differenziandole tramite le entità coinvolte nei vari trigger, condition e action. (se per chi legge stiamo parlando in ostrogoto forse è il caso, prima, di leggere la scheda formativa sulle automazioni).

Ipotizziamo per esempio di avere in casa tanti sensori di presenza (o di movimento) e tanti punti luce, e di voler scrivere automazioni che, a fronte dell’innesco del sensore, si accenda una luce corrispondente: una blueprint potrebbe essere d’aiuto per scrivere tante automazioni gemelle quanti sono gli abbinamenti sensore-punto luce.

Come funziona

Come sempre per spiegarci utilizzeremo gli esempi.
Rimanendo quindi nell’alveo dell’esempio di cui sopra, un’automazione “tipo” che accendaun punto luce ogni qual volta viene attivato un sensore di presenza sarebbe scritta all’incirca così:

automation:
- alias: "Accensione punto luce"
  trigger:
    platform: state
    entity_id: binary_sensor.rilevatore_presenza
    to: 'on'
  action:
    action: light.turn_on
    data:
      entity_id: light.punto_luce

Le entità coinvolte, come si capisce rapidamente, sono “binary_sensor.rilevatore_presenza” (il sensore di rilevazione presenza) e “light.punto_luce” (la luce da comandare).

Per creare un blueprint è necessario scrivere manualmente un file in formato YAML (come il file di configurazione dell’HUB, per capirci) nella cartella  blueprint/automation presente nella cartella di configurazione dell’HUB.

Tale file si compone di:

• un blocco principale (“blueprint:“) contenene:
  • alcune chiavi di configurazione (eg. “name:“)
  • un sottoblocco di definizione degli input (“input:“)
• un blocco trigger:
• un blocco action:

Nel nostro caso chiameremo il nostro file esempio.yaml.

BLOCCO PRINCIPALE

Cominciando la definizione del file (può essere utilizzato un qualsiasi editor) provvederemo a indicare alcune informazioni di base presso la sezione blueprint:.

Inseriremo quindi il nome della blueprint, il dominio (che per ora riguarda le sole automazioni) ed eventualmente una descrizione:

blueprint:
  name: Luce Presenza
  description: Accende la luce quando viene rilevata presenza da un sensore
  domain: automation

Fatto questo sarà necessario decidere cosa quali informazioni accettare in ingresso alla blueprint all’atto del suo uso per definire automazioni. Nel nostro caso dovranno essere passate due entità: quella relativa al sensore di movimento (il trigger) e quella relativa al punto luce (quella da comandare nel blocco action).

La definizione degli input viene effettuata presso il sottoblocco “input:“, come da esempio che segue:

blueprint:
  name: Luce Presenza
  description: Accende la luce quando viene rilevata presenza da un sensore
  domain: automation
  input:
    motion_sensor:
      name: Sensore di presenza
      description: Sensore che farà accendere la luce
    target_light:
      name: Luce
      descritption: Luce da pilotare

Nel blocco abbiamo indicato due input, motion_sensor e target_light. Non hanno bisogno di spiegazioni 🙂

BLOCCO TRIGGER

Terminata la definizione del blocco principale, concentriamoci sul blocco trigger, ovvero quello che gestirà gli inneschi delle automazioni dedfinite tramite la blueprint. A tale blocco è necessario indicare, tramite la particella !input, le variabili (indicate sopra tra gli input) da passargli:

trigger:
  platform: state
  entity_id: !input motion_sensor

BLOCCO ACTION

Analogamente al trigger, ora definiamo “cosa verrà eseguito” a fronte dell’innesco di un’automazione basata sulla blueprint che stiamo definendo.

action:
  action: light.turn_on
  data:
    entity_id: !input target_light

anche in questo caso gli passiamo una variabile, ovvero target_light, definita in testa tra gli input.

BLUEPRINT DEFINTIVA

A questo punto il file dovrebbe apparire come segue:

blueprint:
  name: Luce Presenza
  description: Accende la luce quando viene rilevata presenza da un sensore
  domain: automation
  input:
    motion_sensor:
      name: Sensore di presenza
      description: Sensore che farà accendere la luce
      selector:
        entity:
          domain: binary_sensor
          device_class: motion
    target_light:
      name: Luci
      description: Luce da pilotare
      selector:
        target:
          entity:
            domain: light

trigger:
  platform: state
  entity_id: !input motion_sensor

action:
  action: light.turn_on
  data:
    entity_id: !input target_light

una volta salvato nel percorso sopra illustrato, riavviare l’HUB: la blueprint apparirà presso l’elenco del menu dell’interfaccia web dell’HUB “Configurazione” > “Automazioni e scene” > “Progetti“.

Importare blueprint

Al di là della definizione manuale di blueprint, per aggiungerne di nuove è possibile anche scaricare da internet per aggiungerle al proprio elenco. Per farlo è sufficiente cliccare su “Importa progetto” e copia-incollare l’URL del file YAML dal quale importarlo, per esempio:

https://indomus.it/wp-content/docs/blueprint/esempio.yaml

Uso

Definita la blueprint è possibile finalmente cominciare a formare i biscotti, ovvero le automazione tramite essa definite.
Per farlo, recarsi alla voce di menu”Configurazione” > “Automazioni e scene” > “Progetti” e, in corrispondenza della riga relativa alla blueprint d’interesse, cliccare su “Crea automazione“.

Nel nostro caso d’esempio, l’interfaccia consentirà di selezionare gli input da utilizzare nel trigger e nell’action, proprio come da definizione YAML spiegata sopra:

Come al solito, il limite è la fantasia. Come già detto sopra, comunque, si consiglia di non utilizzare troppo le blueprint, ma piuttosto spendere tempo per capire come realizzare automazioni flessibili, potenti, e sopratutto non gemellari come accade utilizzando le blueprint.