Eccolo qui, il primo post del blog.

Oh .. non è mica sempre facile essere il primo, in qualsiasi cosa, per cui sono io stesso che ti faccio un bel in bocca al lupo 🙂

Poi bisogna rompere il ghiaccio, scegliere un tema da argomentare, trovare le parole e tentare di far partire qualcosa.
Un sacco di cose.
E allora rompo il ghiaccio con un tema che mi sta a cuore e che mi ha sempre divertito: le interfacce grafiche, quelle che comunemente chiamiamo UI (User Interface).

Vi racconto la mia Dashboard Lovelace ottimizzata per il tablet, utilizzabile comunque anche come Dashboard da PC con qualche accorgimento (lo vedremo più avanti).

Non sarà proprio una guida step by step, credo sia più sensato raccontare nei dettagli la logica che c’è dietro, così da fornire un metodo (spero) valido per la costruzione di una dashboard Lovelace in autonomia.

Gli aspetti di cui parlare sono parecchi, meglio dividere l’argomento in due parti.

In questa prima parte vediamo come costruire una struttura di base per gestire le dashboards su Home Assistant con Lovelace, nella seconda parte invece vedremo come sviluppare la dashboard con le card.

Modalità Lovelace: Storage vs YAML

Voglio prima spendere due parole sulla modalità YAML di Lovelace perché sta alla base di tutto il progetto.

Sappiamo che oggi esistono due modalità di gestione di Lovelace:

  • Modalità STORAGE
  • Modalità YAML

La modalità STORAGE ci viene proposta di default ed quella che un po’ tutti siamo abituati a vedere, gestiamo i pannelli direttamente dall’interfaccia.
Con la modalità YAML, invece, la gestione si trasferisce completamente ad uno o più file yaml, e la gestione da interfaccia viene disabilitata.

Certo che detta così sembra proprio dire: Come disabilitata? Ma allora chi te lo fa fare?

Io pure la pensavo così, poi ho iniziato a sviluppare la Dashboard da tablet ed in poco tempo sono arrivato ad avere un file raw totalmente ingestibile.
Il file raw, per chi non lo sapesse, è la configurazione che il modulo di Frontend genera a fronte delle tue modifiche da UI.

In modalità STORAGE, nel file raw, non puoi inserire commenti e soprattutto non puoi usare gli include, per cui arrivi facilmente a superare 5000 righe di codice in un unico file, da impazzire.
E’ vero, hai la UI per trovare le card da gestire, ma se inizi ad annidare diverse card stack tra loro, anche via UI non è proprio immediato trovare una card per modificarla o qualsiasi altro.

Ebbene, sono stato molto felice nello scoprire che i problemi sono brillantemente risolti dalla modalità YAML, puoi scrivere tutti i commenti che ti pare e puoi dividere la tua configurazione in più files grazie agli include.

Questo non significa che bisogna abbandonare definitivamente Lovelace da interfaccia grafica. E’ possibile lasciare la dashboard di default in modalità STORAGE e creare quante dashboards si vogliono in modalità YAML, ad esempio una per il tablet, una per smartphone, una dedicata alla configurazione di HA … Qui la creatività non ha limiti.

In corso d’opera mi sono fermato un secondo e ho migrato la dashboard in modalità YAML.

Al momento la mia configurazione è questa:

lovelace:
  mode: storage
  dashboards:
    lovelace-tablet:
      mode: yaml
      title: Tablet
      icon: mdi:tablet
      show_in_sidebar: true
      filename: lovelace-tablet.yaml
  • mode: storage
    Lasciamo la plancia di default in modalità interfaccia grafica
  • dashboards:
    Elenco delle plance in modalità YAML
  • filename: lovelace-tablet.yaml
    Nome del file yaml “master” della configurazione, da creare nella directory /config di Home Assistant.

Un altro notevole vantaggio della modalità YAML è quello di poter condividere “pezzi” di configurazione tra una dashboard e l’altra. In modalità STORAGE, purtroppo, sei obbligato a creare duplicati di una configurazione, perchè ogni dashboard ha il suo file raw esclusivo.
Chi usa i template del custom component Button Card sa benissimo di cosa parlo (ne parlerò in dettaglio più avanti).

La Struttura della Dashboard

Con l’occasione della migrazione in modalità YAML, ho provato ad ottenere una struttura chiara, leggibile, aggiornabile senza troppi sforzi e che soprattutto si prestasse ad essere riutilizzata come punto di partenza per lo sviluppo di altre dashboards. E da qui nasce anche l’idea di parlarne un pochino e di condividere il materiale.

Per descriverla nel migliore dei modi ho pensato di costruire insieme, a titolo puramente esemplificativo, una dashboard chiamata Demo con due viste, Home e Luci.

A fine post avremo una dashboard vuota, senza card, ma con tutta la configurazione di base per iniziare a svilupparla in base alle proprie esigenze. Nei prossimi articoli della serie, invece, vi racconto nel dettaglio come ho realizzato le mia.

Puoi seguire i passaggi uno ad uno, in ogni caso in fondo all’articolo ti lascerò un pacchetto da scaricare con la struttura funzionante e pronta da installare.

Iniziamo.

Custom Components

Per realizzare questa dashboard dimostrativa abbiamo bisogno di due custom components:

Sono due custom molto noti, probabilmente li stai già usando, se così non fosse entrambi possono essere installati via HACS.

Organizziamo la configurazione

Lovelace è basato sostanzialmente su tre macro elementi:

  • Dashboard
    Una dashboard è un insieme di una o più views, associabile ad un utente e, se specificato in configurazione, genera una icona nella sidebar. Da ora la chiameremo PLANCIA.
  • View
    Una view è una “sezione” della dashboard e funziona da raccoglitore di una o più card. Da ora la chiameremo VISTA.
  • Card
    Sono gli oggetti che manipoliamo per mostrare informazioni ed eseguire azioni all’interno di una vista.

Creiamo su disco, a partire dalla configurazione principale di Home Assistant (/config), una gerarchia di directory che rifletta esattamente gli elementi base appena descritti.

  • lovelace
    • demo
      • home
      • luci
lovelace
Directory di configurazione per tutte le plance in modalità YAML. Da creare dentro /config.
demo
Directory di configurazione della plancia DEMO
home & luci
Sotto Directories di configurazione, ognuna dedicata per la relativa vista

In questo modo abbiamo già ottenuto una struttura di primo livello che ci consente di dividere e organizzare la configurazione delle nostre plance.

Il Layout delle Viste

Ora ci dobbiamo occupare della configurazione delle viste (Home e Luci), e lo facciamo creando un classico layout web formato da Header, Body e Footer.
Il Body lo dividiamo in diverse colonne, in base alle esigenze della specifica vista.

Layout della vista HOME a 3 colonne
Layout della vista LUCI a 2 colonne

Un layout di questo tipo, con l’ausilio degli strumenti vertical-stack e horizontal-stack di Lovelace, ci offre una grande flessibilità in termini di organizzazione delle card e di personalizzazione dell’aspetto grafico.

La modalità Pannello

Le viste di Lovelace possono essere create in due modi: nella modalità di default, chiamiamola a colonne, oppure in modalità Pannello.
La modalità Pannello è l’ideale per una plancia da tablet perché ci consente di sfruttare tutto lo schermo e avere totale controllo sulla disposizione delle card.

Si attiva con panel: true

Nella modalità Pannello possiamo creare una sola card, e questa card occuperà tutta la larghezza dello schermo, per cui abbiamo bisogno di una card “strutturale” in cui poi sviluppare il nostro layout.

A questo scopo utilizziamo una vertical-stack, si tratta di una card Lovelace particolare, molto utile, che consente di raggruppare diverse card nella stessa colonna.
Per raggruppare, invece, diverse card nella stessa riga, abbiamo a disposizione la card sorella horizontal-stack.

I Template di Button Card

Tutto il progetto fa grande uso dei Template del custom component Button Card.

Button Card, per chi non lo conoscesse, è un custom component molto potente e versatile.
Il nome fa pensare ad una semplice card per creare pulsanti, ma in realtà offre molte opzioni e diversi strumenti per realizzare praticamente ogni cosa. L’ho usato ovviamente per i pulsanti della plancia, in diverse forme, ma anche per alcune card di tipo “sensore” con lo scopo di mostrare solo informazioni, quindi nessuna azione al tap.
Un altro caso d’uso molto, ma molto utile, è quello di creare card “vuote” e invisibili, da usare come separatore tra card, oppure per regolare automaticamente la dimensione delle card in una horizontal-stack.

Vedremo tutto nel dettaglio, ma ora, per comprendere appieno il codice YAML della plancia, devi sapere cosa sono e come usare i suoi Template.

I Template di Button Card ricordano un po’ il concetto di un foglio di stile CSS.
Possiamo definire un modello centralizzato e poi usarlo nelle card type: 'custom:button-card', evitando così molte ripetizioni della stessa configurazione. Di conseguenza otteniamo anche un codice più pulito e ordinato.
Inoltre, c’è la grande comodità di applicare una modifica a tutte le card dello stesso template contemporaneamente.

In modalità STORAGE la configurazione dei template va inserita direttamente nel file raw, ad esempio:

button_card_templates:
  no_background:
    styles:
      card:
        - background-color: 'rgba(0, 0, 0, 0.0)'
        - box-shadow: none
  empty_card:
    template: no_background
    color_type: blank-card

In modalità YAML possiamo configurare i templates in un file dedicato e inserire un include nella configurazione della plancia, così da rendere autonoma la configurazione dei templates e lasciare compatto il file principale della plancia:

button_card_templates.yaml
no_background:
  styles:
    card:
      - background-color: 'rgba(0, 0, 0, 0.0)'
      - box-shadow: none
empty_card:
  template: no_background
  color_type: blank-card
Configurazione nella plancia
button_card_templates: !include button_card_templates.yaml

Hai notato che dentro al secondo template viene richiamato il primo?
Esatto, un template può ereditare la configurazione di un altro, questo apre alla possibilità di avere un codice modulare e ben organizzato.

Per concludere, vediamo che con due semplici righe possiamo creare una card vuota e senza sfondo da usare nei casi più disparati:

type: 'custom-button-card'
template: empty_card

Il codice YAML

Dopo questa lunga ma doverosa premessa, passiamo finalmente a vedere come strutturare il codice YAML per ottenere il layout sopra descritto.

All’inizio abbiamo creato una gerarchia per avere la configurazione di ogni vista in una directory specifica.
Ora, all’interno di queste directories, andiamo a creare diversi file YAML, ognuno per la relativa sezione del layout della vista (Header, Body, etc).

Per il momento ci occupiamo della sola vista HOME, con un layout che prevede un Body a tre colonne.

Nella directory lovelace creiamo il file principale della plancia, lovelace-demo.yaml, che poi attiveremo nel configuration.yaml di Home Assistant.

button_card_templates: !include button_card_templates.yaml

views:
  - title: HOME
    path: home
    panel: true
    cards:
      - type: vertical-stack
        cards:
          - !include demo/home/header.yaml
          - type: 'custom:button-card'
            template: row_space_10
          - type: horizontal-stack
            cards:
              - !include demo/home/body_col_1.yaml
              - !include demo/home/body_col_2.yaml
              - !include demo/home/body_col_3.yaml
          - type: 'custom:button-card'
            template: empty_card
            styles:
              card:
                - height: 10px
          - !include demo/home/footer.yaml

Come puoi notare è un codice compatto e facilmente leggibile, grazie alla separazione della struttura dai contenuti veri e propri.
Le righe evidenziate si riferiscono ai diversi file YAML inclusi dalla directory della vista, in questo caso home della plancia demo.

E’ facile intuire che in questi files andremo a creare solo le card della relativa sezione del layout, ottenendo così, ancora una volta, un’ulteriore separazione dei ruoli e dei files YAML non troppo voluminosi da gestire in futuro.

  • lovelace
    • demo
      • home
        • header.yaml
        • body_col_1.yaml
        • body_col_2.yaml
        • body_col_3.yaml
        • footer.yaml

Analizziamo il codice strutturale della vista punto per punto.

1

Card principale

Contenitore principale (vertical-stack) della vista in modalità Pannello.
All'interno del contenitore le card saranno posizionate una sotto l'altra, tutte a larghezza intera.
2

Header

Include del file YAML dedicato alla sezione HEADER del layout
3

Separatore

Card vuota per creare una separazione visiva tra HEADER e BODY
4

Body

Una card Horizontal Stack con 3 colonne, ognuna con il suo file dedicato, per creare la sezione BODY del layout
5

Separatore

Card vuota che crea una separazione visiva tra BODY e FOOTER
6

Footer

Include del file YAML dedicato alla sezione FOOTER del layout

Ora vediamo la vista LUCI, stavolta realizziamo un layout con un Body a due colonne.

Secondo i miei gusti, in questo caso, è preferibile armonizzare l’aspetto grafico restringendo un pochino il layout. Usiamo Card Mod, un famoso strumento custom per applicare stili CSS alle card Lovelace.

- title: LUCI
  path: luci
  panel: true
  cards:
    - type: 'custom:mod-card'
      style:
        hui-vertical-stack-card$: |
          #root {
            max-width: 90%;
          }
      card:
        type: vertical-stack
        cards:          
          - !include demo/luci/header.yaml
          - type: 'custom:button-card'
            template: row_space_10
          - type: horizontal-stack
            cards:
              - !include demo/luci/body_col_1.yaml
              - !include demo/luci/body_col_2.yaml
          - type: 'custom:button-card'
            template: empty_card
            styles:
              card:
                - height: 10px
          - !include demo/luci/footer.yaml

Nelle righe evidenziate vediamo che il blocco di Card Mod applica una larghezza massima pari al 90% di quella disponibile.

Questo passaggio non è obbligatorio ovviamente, se preferisci usare tutto lo schermo anche con un layout a due colonne, ti basta usare lo stesso codice della vista HOME.

Infine, una piccola ottimizzazione all’aspetto grafico complessivo. Applichiamo un margine al layout in modo che non venga schiacciato ai bordi dello schermo.

- title: HOME
  path: home
  panel: true
  cards:
    - type: 'custom:mod-card'
      style:
        hui-vertical-stack-card$:|
          #root {
            margin: 15px !important;
          }
      card:
        type: vertical-stack
        cards:
          - !include demo/home/header.yaml
          - type: 'custom:button-card'
            template: row_space_10
          - type: horizontal-stack
            cards:
              - !include demo/home/body_col_1.yaml
              - !include demo/home/body_col_2.yaml             
              - !include demo/home/body_col_3.yaml
          - type: 'custom:button-card'
            template: empty_card
            styles:
              card:
                - height: 10px
          - !include demo/home/footer.yaml

Inseriamo il blocco di codice evidenziato per applicare un margine di 15px alla Vertical Stack principale.
Vediamo la differenza con il layout originale.

Ora dobbiamo creare delle card vuote in tutti i files YAML della plancia, altrimenti il modulo di Frontend non riuscirà a caricarla correttamente.

type: 'custom:button-card'
template: empty_card

Abbiamo finito!

Ora abbiamo a disposizione uno scheletro vuoto, ma ben organizzato e pronto per essere sviluppato secondo gusti ed esigenze personali.

Installazione

Non ci resta che scaricare ed installare il materiale nella nostra configurazione e attivare la plancia.

download demo
  • Scarica l’archivio e scompattalo nella directory /config della tua installazione di Home Assistant.
  • Attiva la plancia nella configurazione di Home Assistant editando il file configuration.yaml:

    lovelace:
      mode: storage
      dashboards:
        lovelace-demo:
          mode: yaml
          title: Demo
          icon: mdi:help
          show_in_sidebar: true
          filename: lovelace/lovelace-demo.yaml
  • Riavvia Home Assistant.

Questa configurazione lascia la plancia di default in modalità STORAGE (gestita da interfaccia grafica) e crea una nuova plancia chiamata DEMO in modalità YAML.
Ovviamente prima di attivarla puoi personalizzare nome ed icona.

Conclusione

In questa prima parte abbiamo visto come organizzare la configurazione, come dividere la struttura dai contenuti e come ottenere un layout pronto per essere sviluppato.

Nella seconda parte vi parlo dello sviluppo della plancia e di come ho gestito le card all’interno di ogni sezione.

Ciao e a presto!
Max.

Se apprezzi i miei contenuti puoi stimolare nuove idee sostenendo il progetto con una buona birra!

Partecipa alla discussione 45 Commenti

  • Fabrizio Defend ha detto:

    Complimenti e grazie della guida

  • carlo ha detto:

    Ci tengo a lasciare i miei complimenti per questa ottima guida chiara e semplice in ogni suo punto!!
    Salverò il link nei miei preferiti in modo da poterla controllare di tanto in tanto per vederne sempre le novità con le ultime guide!!

    Spero presto in un nuovo articolo.

    Complimentoni

    Carlo

  • Luciano Veronese ha detto:

    Complimenti, sei stato chiarissimo nella esposizione e mi piace molto lo stile “tutorial”
    Grazie per la condivisione

  • Simone ha detto:

    Guida molto interessante, salverò anche io il link e spero continuerai il progetto che trovo molto utile
    Complimenti

  • Giuseppe ha detto:

    Finalmente: c’è luce in fondo al tunnel!
    Un’ottima guida da cui prenderò sicuramente spunto. Non volevo credere che tutto ciò non fosse possibile.
    Grazie mille e COMPLIMENTI MAX!

    • Max ha detto:

      Grazie Giuseppe! Infatti ho notato che non è molto battuto come argomento, ottime dashboard su github si trovano, ma nessuno ha provato a spiegarle e allora sto provando a dare un contributo

  • Luigi Doria ha detto:

    Cosa posso aggiungere che già non ho detto nel gruppo FB.
    Mi sono avvicinato da poco al mondo HA e sei stato un aiuto importantissimo e preziosissimo.
    La tua plancia mi ha affascinato da quando l’hai postata su FB ed è diventata un riferimento per le mie sperimentazioni.
    Questo ulteriore blog, fatto benissimo, sarà per me una bibbia per capire meglio e aiutarmi a migliorare.
    Grazie grazie e ancora grazie !!!

  • Giovanni ha detto:

    Complimenti per la tua guida, davvero ben fatta, chiara ed esaustiva. Purtroppo ho sempre pensato che il sito ufficiale di home assistant sia fatto male e non si capisca bene come muoversi, soprattutto se si è alle prime armi. Con la tua guida, invece, sono riuscito a configurare la plancia come si deve.

  • Simone ha detto:

    A quando la prossima puntata?

    • Max ha detto:

      Eh il più presto possibile spero, ci sto lavorando ma tra lavoro e famiglia mi posso dedicare solo la notte praticamente 😉

  • Renzo Severino ha detto:

    Guida molto interessante, salverò anche io il link se puoi vorrei cercare di capire come utilizzare un database esterno (tipo mariadb) e grafana per memorizzare alcuni dati nel tempo, come le temperature, ecc.
    Complimenti

  • Lucio ha detto:

    Con la struttura ad albero proposta nel tutorial, non riesco a capire come richiamare i percorsi delle risorse hacs.

    resources:
    – url: /hacsfiles/button-card/button-card.js
    type: module

    Ho provato più varianti ma niente da fare… un suggerimento?

    • Max ha detto:

      Ciao Lucio, la configurazione proposta nell’articolo lascia la plancia di default in modalità UI, in questo modo le risorse continuano ad essere gestite da HACS senza la necessità di inserire manualmente le stringhe.

      • Lucio ha detto:

        Forse è quello il mio problema, non ho mai usato la modalità UI e sto passando da un mio file ui-lovelace.yaml nella root alla struttura dell’articolo. Quindi di default non ci sono risorse caricate ed ovviamente mi va tuto in errore.

        • Max ha detto:

          Allora in questo caso ti basta accodare alla tua configurazione yaml la nuova plancia (adattando i path degli include), lasciando inalterato tutto il resto.

          • Andrew ha detto:

            mi accodo anche io Max al riavvio (nonostante tutte le risorse gestite da HACS) mi trovo la plancia nuova ma con all’interno tutte card auto-create e nessuna vista. Controllato persino i permessi sulle directory e i file ma niente da fare. (Ho finora utilizzato la modalità UI e mai in modalità YAML nonostante scrivevo tutte le viste e le card in modalità “manuale” da tempo)

          • Max ha detto:

            Ciao Andrew, non mi è chiarissimo quale sia il problema, se mi contatti su messenger ne parliamo, così mi puoi allegare anche qualche screen per capire meglio.

          • Max Taino ha detto:

            @Andrew, ho avuto anch’io lo stesso problema: nel mio caso era dovuto al path non corretto del file di definizione della plancia (tablet.yaml): l’avevo messo nella directory di lovelace, mentre nell’include del config.yaml non avevo specificato il path completo. In questo caso, invece di dare errore nella verifica della configurazione, HA si comporta in questa maniera bizzarra, e include una plancia in cui include tutti gli oggetti presenti nella configurazione RAW (?!?). Risolto (pare) aggiustando i path.

  • Franco ha detto:

    Riproponendo il commento di Giuseppe del 21/2 …una luce in fondo al tunnel!!! ti ringrazio per il tempo che stai dedicando per noi neofiti… si comincia a capire qualcosa…
    Ti seguirò passo passo per migliorare le mie poche conoscenze in tema HA e sono sicuro che con i tuoi articoli la cosa sarà meno faticosa…
    grazie per il tempo che dedichi e che vorrai dedicarci.

  • Ale ha detto:

    Ciao, sto seguendo la tua guida per creare la mia plancia con la struttura da te creata. Ho il problema che però modifico i file yaml ma anche se riavvio HA o cancello la cronologia del browser, non mi aggiorna la plancia… dimentico qualche passaggio?

    • Max ha detto:

      Ciao Ale, dopo aver modificato i files YAML per aggiornare la plancia devi cliccare sui 3 puntini in alto a destra e poi su Aggiorna 😉
      Non è necessario il riavvio di HA

  • Matteo ha detto:

    Se la guida ufficiale di HA fosse scritta come la tua, sarebbe il programma di domotica più utilizzato al mondo. COMPLIMENTI!

  • Vittorio ha detto:

    Ottima guida… molto comprensibile. Gran lavoro! Di sicuro è il più chiaro esempio che ho visto ad ora. Complimenti!!!

  • Luca ha detto:

    Ciao Max, stavo iniziando a seguire la tua ottima guida, ti volevo segnalare che il pulsante Download Demo porta ad una pagina con errore 404, lo posso trovare da un altra parte il file? Grazie e complimenti!

    • Max ha detto:

      Ciao Luca, sei passato proprio quando stavo aggiornando il pacchetto per via delle recenti modifiche che ci sono state a Layout Card, riprova ora!

      • Luca ha detto:

        Wà, tempismo perfetto :°D
        Andata! Grazie!

        • Max ha detto:

          Saranno stati si e no 30 secondi con il link non funzionante! 😉

          • Antonio ha detto:

            Ciao, innanzitutto complimenti per l’ottima guida e grazie per averla condivisa. Le sto seguendo tutte passo passo (si tutte, compresa quella di Spotify 😉 ).
            Però mi sfugge una cosa talmente stupida che ho quasi paura a chiedere:
            c’è la possibilità di modificare la larghezza delle colonne dei body? Esempio nel LAYOUT DELLA VISTA LUCI A 2 COLONNE ho la necessità di avere il body_col_1 più stretto (circa la metà) e lasciare il restante spazio al body_col_2
            Magari è un semplice parametro dell’Horizontal Stack o una istruzione CSS del Card Mod, ma ci ho provato in tutti i modi senza riuscirci.
            Grazie

          • Max ha detto:

            Ciao Antonio, grazie mille! Con horizontal stack non puoi fare quello che chiedi, si può con layout card. Appena ho un secondo ti dico come fare

        • Max ha detto:

          In ogni caso ti consiglio di leggere anche la seconda parte e scaricare il pacchetto che trovi li, è più completo.

          • Luca ha detto:

            Si, sto seguendo quella al momento, ti volevo segnalare che nel file header.yaml linea 42
            style: |
            ho dovuto mettere uno spazio tra : e | altrimenti dal tablet mi dava errore su quella riga

          • Antonio ha detto:

            Grazie

  • Paolo ha detto:

    Ciao Max, ottima guida.
    ho provato ad utilizzare i file allegati ma non riesco a far prendere il colore di background.
    Ho provato anche con il template della seconda parte della guida ma niente. Hai qualche idea di dove sto sbagliando.

Lascia un Commento