Dashboard custom su Home Assistant: i principi

Il problema

Realizzare una dashboard custom per Home Assistant non è semplice, soprattutto per chi non ha competenze tecniche legate alla programmazione. Ci si trova quindi spesso ad accontentarsi delle plance realizzabili via interfaccia che però hanno molti limiti e soprattutto spesso non sono come le vorremmo.

Proverò a dare qualche dritta a chi vuole provare a realizzarne una propria, partendo magari dal codice di uno “scheletro” che metterò a disposizione.

Le attuali soluzioni

Al momento c’è una bellissima dashboard messa a disposizione da Max Albani in questo articolo e nella sua seconda parte. Ho notato però che la sua guida, richiede conoscenze un pochino più avanzate di quelle che spero di richiedere qui. Più volte infatti qualcuno mi ha contattato per essere aiutato a realizzarla.

I requisiti

Per poter realizzare le personalizzazioni dal codice yaml avremo bisogno delle seguenti estensioni installabili da HACS:

• Card Mod
• Button Card

Per aggiungerle rimando alle documentazioni ufficiali o alle varie guide in giro per il web. Tranquilli farlo è un’operazione veramente banale. Basta cercare nella sezione “Frontend” di HACS le parole “card-mod” per il primo e “button-card” per il secondo, scaricarli e riavviare.

Suggerisco inoltre, ma non è obbligatorio, l’uso di un editor di testo un po’ più avanzato come Studio Code Server (praticamente Visual Studio Code per chi lo conoscesse), installabile dai componenti aggiuntivi.

La soluzione – parte 1

Vorrei provare a salire insieme un gradino alla volta, trattando le cose piano piano, in modo da suddividere i concetti nella maniera più semplice possibile. Cominciamo quindi dalla realizzazione di una dashboard custom per Home Assistant vuota ma realizzata completamente via codice e suddivisa per file e cartelle ordinati secondo una logica. Apriamo quindi il file “configuration.yaml” ed aggiungiamo la seguente voce:

# PLANCE CUSTOM
lovelace: !include plance.yaml

Questo codice dice ad Home Assistant che vogliamo gestire alcune dashboard dal file “plance.yaml”. Andiamo quindi a creare un file con questo nome.

Al suo interno andremo a scrivere quanto segue:

mode: storage
dashboards:
  sax-desk:
    mode: yaml
    title: Desk
    icon: mdi:desktop-tower-monitor
    show_in_sidebar: true
    filename: lovelace/sax-desk.yaml

La chiave “mode: storage” indica che vogliamo usare sia dashboard realizzate via codice che in maniera visuale. Permettendo di fatto di non escludere nessun tipo di lavoro fatto fino ad oggi.

Inizia poi la dichiarazione delle proprie plance sotto la chiave “dashboard”. Nel file ne ho dichiarata una chiamata “sax-desk” per indicare che si tratta di quella che uso per i dispositivi desktop. Potete però aggiungerne quante ne volete, rispettando ovviamente i rientri degli spazi.

Dopo aver specificato che sax-desk è una dashboard realizzata in modalità codice (mode: yaml) ho impostato alcune configurazioni ed infine indicato la posizione del file da cui partire per la costruzione della plancia vera e propria: “lovelace/sax-desk.yaml”.

Come potete vedere il file si chiama “sax-desk.yaml” e si trova sotto la cartella “lovelace”. Andiamo quindi a creare questa cartella e il relativo file al suo interno, che conterrà il seguente codice:

button_card_templates: !include stile.yaml
views:
  - title: HOME
    path: home
    icon: "mdi:home"
    panel: true
    cards:
      - type: markdown
        content: Ciao mondo

La prima riga indica il file per i template di button card. Ho scelto di chiamarlo “stile.yaml”. Creiamolo nella stessa cartella lovelace anche se per ora lo lasceremo vuoto.

A seguire ho indicato la nostra prima vista dal titolo “Home”, che come path usa “home” (il path viene usato nell’indirizzo del browser per puntare direttamente a questa vista…in buona sostanza basta metterne uno diverso per ognuna di esse) e che è di tipo “panel”. Di quel tipo cioè, il cui contenuto è un solo elemento che viene esteso su tutto lo spazio disponibile. Nelle dashboard create da interfaccia grafica, è possibile impostarlo scegliendo “Pannello” come tipo di visualizzazione.

Infine troviamo la sezione “cards:” che conterrà tutti gli elementi di questa vista. Per ora ho inserito soltanto un testo. Salviamo tutti i file e riavviamo Home Assistant.

Se tutto è stato fatto correttamente, al riavvio vi troverete nel menu laterale una dashboard in più chiamata “Desk”. Potete spostarla in alto dallo smartphone trascinandola, oppure dal computer tenendo prima premuto per qualche secondo sulla scritta in alto a sinistra “Home Assistant”.

Complimenti, avete appena creato la vostra prima dashboard custom su Home Assistant e superato il primo livello! Passiamo adesso alla realizzazione di uno scheletro, che ci permetta di capire bene gli spazi a disposizione e come occuparli.

La soluzione – parte 2

Home Assistant mette a disposizione due elementi estremamente utili: “horizontal-stack” e “vertical-stack“. Da interfaccia vengono chiamate “Pila verticale” e “Pila orizzontale“.

Si tratta di elementi che permettono di inserire al proprio interno degli altri componenti, mostrandoli rispettivamente in verticale e orizzontale. Li sfrutteremo per crearci una griglia che ci permetta di suddividere gli spazi a nostro piacimento.

Modifichiamo quindi il nostro file “sax-desk.yaml” sostituendo il codice che avevamo inserito nella prima parte con questo:

button_card_templates: !include stile.yaml
views:
  - title: HOME
    path: home
    icon: "mdi:home"
    panel: true
    cards:
      - type: "custom:mod-card"
        card:
          type: vertical-stack
          cards:
            - type: markdown
              content: TESTATA (HEADER)
            - type: horizontal-stack
              cards:
                - type: markdown
                  content: COLONNA 1
                - type: markdown
                  content: COLONNA 2
                - type: markdown
                  content: COLONNA 3
            - type: markdown
              content: PIE' DI PAGINA (FOOTER)

La parte fino a “cards:” non è cambiata. L’elemento che però viene usato come contenitore principale della dashboard, è adesso di tipo “custom:mod-card” che è una delle estensioni che troviamo tra i requisiti. Senza soffermarci troppo, notiamo subito che permette di inserire al suo interno un altro componente usando la chiave “card” (attenzione alla “s” che questa volta non c’è).

Dentro troviamo un “vertical-stack”, con a sua volta la voce “cards” che elenca, disponendoli quindi in verticale, tre elementi:

• un testo in cima con la scritta “TESTATA (HEADER)”
• un testo in fondo con la scritta “PIE’ DI PAGINA (FOOTER)”
• un elemento al centro di tipo “horizontal-stack” che contiene a sua volta altri tre testi disposti questa volta in colonna

A primo impatto quello che ho scritto può sembrare complicato ma se letto con calma dovrebbe permettervi di capire cosa è stato realizzato. Aiutatevi con il supporto di questa immagine visibile in maniera estesa anche al seguente link:

Una volta ottenuto il risultato vi invito a fermarvi a fare qualche esperimento. Provate ad esempio ad inserire una colonna in più nella parte centrale, oppure una seconda riga orizzontale con soltanto due colonne prima del footer. Insomma questo è uno dei punti più importanti di questo articolo. Fateci pratica perché se capite bene questo meccanismo, avete fatto un grosso passo avanti.

Una piccola ma utile nota: quando fate modifiche al codice della dashboard, per vederne gli effetti aprite quest’ultima cliccando su “Desk” nel menu laterale (o fate come me che la lascio aperta in un’altra scheda del browser), cliccate poi sui tre puntini in alto a destra e poi su “Aggiorna”. Eviterete di dover riavviare tutto per vedere la modifica.

Benissimo! Anche il secondo livello è stato superato. Passiamo adesso a giocare con i colori e le rifiniture “artistiche”.

La soluzione – parte 3

In cima al file “sax-desk.yaml”, abbiamo indicato come file di template per button card “stile.yaml”, ma poi vio ho detto di crearlo, lasciarlo vuoto e passare oltre. E’ adesso arrivato il momento di capire di cosa si tratta.

In questo file è possibile realizzare dei template. Si tratta di “personalizzazioni” sugli elementi da riutilizzare in base alle esigenze. Faccio subito un esempio chiarificatore. Supponiamo di volere che il bordo della testata (header) diventi rosso. Modifichiamo quindi il file “sax-desk.yaml” con questo codice:

button_card_templates: !include stile.yaml
views:
  - title: HOME
    path: home
    icon: "mdi:home"
    panel: true
    cards:
      - type: "custom:mod-card"
        card:
          type: vertical-stack
          cards:
            - type: "custom:button-card"
              name: HEADER CON BORDO ROSSO
              template: bordo_rosso
            - type: horizontal-stack
              cards:
                - type: markdown
                  content: COLONNA 1
                - type: markdown
                  content: COLONNA 2
                - type: markdown
                  content: COLONNA 3
            - type: markdown
              content: PIE' DI PAGINA (FOOTER)

In pratica abbiamo sostituito il markdown dell’header con la parte evidenziata, cioè un “custom:button-card“, e gli abbiamo assegnato il template “bordo_rosso”.

Apriamo poi il file “stile.yaml” per definire il template:

bordo_rosso:
  styles:
    card:
      - border-color: red

La prima voce definisce il nome del template. In esso sono andato ad indicare che voglio personalizzare lo stile (styles) dell’elemento “card” (in pratica il contenitore di qualsiasi elemento venga posizionato in Home Assistant). Infine come personalizzazione ho detto di volere che il colore del bordo (“border-color”) fosse “red”. Ecco il risultato:

Chi conosce i fogli di stile CSS per lo sviluppo web saprà bene di cosa parlo. Si tratta di regole che è facile imparare o comunque trovare con qualche piccola ricerca sul web e che se non si pretende la luna, ci consentono di applicare tutte le modifiche grafiche che vogliamo.

Oltre ai colori è infatti possibile cambiare spazi, allineamenti, testi e molto altro ancora. Non è scopo di questo articolo spiegare come fare tutto questo. Al momento preferisco evidenziare come integrare queste personalizzazioni con le entità di Home Assistant.

Realizziamo quindi un pulsante per una luce, la cui icona diventi verde quando è accesa e bianca quando è spenta. Ecco il nuovo codice di “sax-desk.yaml”:

button_card_templates: !include stile.yaml
views:
  - title: HOME
    path: home
    icon: "mdi:home"
    panel: true
    cards:
      - type: "custom:mod-card"
        card:
          type: vertical-stack
          cards:
            - type: "custom:button-card"
              name: HEADER CON BORDO ROSSO
              template: bordo_rosso
            - type: horizontal-stack
              cards:
                - type: markdown
                  content: COLONNA 1
                - type: "custom:button-card"
                  entity: light.[TUO_LUCE]
                  template: luce_colorata
                - type: markdown
                  content: COLONNA 3
            - type: markdown
              content: PIE' DI PAGINA (FOOTER)

E quello per il file “stile.yaml”:

bordo_rosso:
  styles:
    card:
      - border-color: red

luce_colorata:
  state:
    - value: "on"
      styles:
        icon:
          - color: green
    - value: "off"
      styles:
        icon:
          - color: white

Ho evidenziato le parti nuove/sostituite. Come vedete nel file della dashboard ho inserito un “custom:button-card” specificando una entità “light.[TUA_LUCE]” che ti invito a sostituire con una delle entità delle tue luci di casa aggiornandone il nome. La magia viene invece fatta dal template “luce_colorata” dove ho introdotto il concetto di state (stato).

Come è facile capire, ho indicato che quando il value è “on” (la luce è accesa) voglio applicare uno stile all’icona e darle il colore verde. Stesso discorso per il valore “off” con il colore bianco. Il risultato lo potete vedere in queste due immagini che mostrano il medesimo pulsante nei due stati:

Conclusioni

E’ quasi fatta! Ora non resta che fare prove ed esperimenti di ogni tipo e realizzare una propria prima dashboard custom per Home Assistant.

Supporto reciproco

La realizzazione di questo articolo ha richiesto tempo, studio ed impegno.

Vi chiedo quindi mettere una mano sul cuore e l’altra sul portafogli per ricompensare il mio sforzo con un contributo libero:

Grazie.

Il download ed un piccolo extra

Per aiutarvi vi lascio un file contenente il codice per alcuni scheletri base con impaginazione a 1, 2 e 3 colonne.

Soprattutto coloro invece che si prenderanno la briga di supportare questo mio lavoro con una donazione sono invitati a contattarmi tramite telegram e sarò lieto di provare ad aiutarli come posso.

Download “Scheletri di dashboard custom per Home Assistant” scheletri_dashboard_1_0.zip – Scaricato 547 volte – 1,63 KB