Home Assistant
Come installare e configurare Bubble Card in Home Assistant: Guida Completa
Guida tecnica avanzata per installare Bubble Card in Home Assistant tramite HACS, configurare le risorse frontend, strutturare le card YAML e risolvere i problemi.
La presente guida descrive l'installazione, la configurazione e la risoluzione dei problemi relativi a Bubble Card, una delle interfacce grafiche più apprezzate per Home Assistant. Questo componente permette di trasformare la dashboard predefinita in un ambiente moderno, fluido e altamente personalizzabile, ideale per gestire dispositivi domotici complessi come quelli coordinati da un hardware affidabile come l'Home Assistant Green o l'Home Assistant Yellow. Prima di procedere, assicurati di disporre di una versione recente di Home Assistant Core e di HACS installato e correttamente configurato. Considera che le interfacce basate su custom card dipendono strettamente dal supporto frontend del browser e potrebbero richiedere la pulizia della cache dopo ogni aggiornamento. Non sono inclusi in questa guida trucchi di ottimizzazione non ufficiali o modifiche al codice sorgente core.
Prerequisiti e Architettura di Bubble Card
Per iniziare, è fondamentale comprendere la natura di Bubble Card. Si tratta di una custom card per Lovelace, il sistema di visualizzazione di Home Assistant. A differenza delle schede standard, Bubble Card sfrutta layout avanzati a comparsa (pop-up) e pulsanti multifunzione che riducono drasticamente l'ingombro visivo delle schermate su smartphone e tablet. L'utilizzo di questo strumento richiede la presenza di HACS (Home Assistant Community Store), lo strumento non ufficiale ma di fatto standard per la gestione dei componenti aggiuntivi della community. Assicurati che il tuo sistema sia aggiornato e che tu abbia i privilegi di amministratore. Se utilizzi periferiche di controllo locale come la chiavetta Sonoff ZBDongle-E per la gestione Zigbee dei tuoi sensori, avrai la certezza di avere stati istantanei e affidabili da richiamare all'interno delle tue nuove card personalizzate.
Procedura passo dopo passo
- Accedi al pannello di controllo del tuo Home Assistant con un account dotato di privilegi di amministratore.
- Apri lo store della community HACS dal menu laterale sinistro della tua interfaccia utente.
- Clicca sulla sezione Frontend all'interno della schermata principale di HACS per visualizzare le schede e i temi aggiuntivi.
- Utilizza la barra di ricerca in alto a destra e digita il termine Bubble Card per individuare il repository ufficiale.
- Seleziona il pacchetto corrispondente e clicca sul pulsante di download situato in basso a destra nella finestra di dialogo.
- Conferma la versione desiderata (generalmente l'ultima stabile proposta) e avvia il processo di scaricamento dei file sul server.
- Attendi il completamento dell'operazione e verifica che Home Assistant ti chieda di ricaricare le risorse frontend.
- Conferma il ricaricamento delle risorse oppure pulisci la cache del tuo browser web per evitare conflitti visivi.
- Crea una nuova dashboard Lovelace in modalità vuota o modifica una dashboard esistente sbloccando l'editor.
- Aggiungi una nuova scheda cercando manualmente Bubble Card tra le opzioni disponibili e inizia a configurare i primi parametri YAML.
Configurazione Avanzata e Struttura YAML
Una volta completata l'installazione, la vera potenza di Bubble Card emerge attraverso la scrittura e la personalizzazione del codice YAML. Ogni card può essere configurata sia tramite l'interfaccia grafica editor integrata sia scrivendo direttamente il codice. Di seguito viene mostrato un esempio strutturato per la creazione di un pulsante avanzato che gestisce lo stato di un'entità e apre un pop-up dedicato.
type: custom:bubble-card
card_type: button
button_type: state
name: Illuminazione Salotto
icon: mdi:ceiling-light
entity: light.salotto
sub_button:
- entity: switch.presa_salotto
icon: mdi:power
styles: |
.bubble-button {
background-color: var(--card-background-color);
}Questo blocco di codice definisce una scheda di tipo pulsante con un'icona personalizzata, un nome descrittore e un sotto-pulsante utile per controllare un carico secondario. È possibile replicare questa struttura per qualsiasi entità supportata, assicurandosi sempre di verificare la correttezza dei nomi delle entità nel menu Strumenti di sviluppo di Home Assistant.
Verifica del Risultato e Controlli di Stabilità
Dopo aver salvato la configurazione della dashboard, è necessario verificare che il rendering grafico avvenga correttamente su tutti i dispositivi utilizzati quotidianamente, inclusi smartphone, tablet e PC desktop. Apri la dashboard e clicca sul pulsante appena creato per testare la risposta immediata del comando. Se utilizzi componenti fisici per la misurazione energetica, come una presa intelligente Shelly Plus Plug IT, potrai verificare in tempo reale se i dati di potenza compaiono correttamente all'interno dei sottotitoli o delle informazioni estese della card. Controlla anche la console degli sviluppatori del browser (usando F12) per assicurarti che non vi siano errori di tipo Uncaught ReferenceError o problemi legati al caricamento dei file JavaScript di Bubble Card.
Problemi Comuni e Risoluzione dei Guasti
Quando si gestiscono dashboard avanzate, è possibile riscontrare anomalie di visualizzazione o errori di caricamento. La tabella seguente elenca i problemi più frequenti riscontrati dagli utenti e le relative soluzioni tecniche verificate.
| Problema Riscontrato | Causa Probabile | Soluzione Consigliata |
|---|---|---|
| La card mostra l'errore Custom element doesn't exist | La risorsa frontend non è stata registrata correttamente in HACS o il browser sta usando una versione obsoleta in cache. | Verifica in HACS che Bubble Card sia presente, quindi ricarica le risorse frontend ed esegui una pulizia forzata della cache del browser (Ctrl+F5). |
| Il pop-up non si apre al clic | Sintassi YAML errata nella definizione del target o ID del pop-up non corrispondente tra trigger e contenitore. | Modifica la card in modalità YAML, controlla che l'ID del pop-up corrisponda esattamente e rimuovi eventuali spazi superflui nel codice. |
| L'icona non riflette lo stato reale dell'entità | Modifica del dominio dell'entità o entità non disponibile temporaneamente nel database interno di Home Assistant. | Controlla lo stato attuale dell'entità nella sezione Stati degli Strumenti di Sviluppo e aggiorna il nome dell'entità nel codice della Bubble Card. |
Domande Frequenti (FAQ)
Bubble Card è compatibile con tutte le versioni di Home Assistant?
Bubble Card richiede versioni recenti di Home Assistant Core e HACS. Si consiglia sempre di mantenere aggiornato sia il sistema di domotica che la card stessa per evitare deprecazioni di codice frontend.
Posso usare Bubble Card senza HACS?
Sì, è teoricamente possibile installare la card scaricando manualmente i file dal repository GitHub e inserendoli nella cartella www del proprio Home Assistant, ma HACS rimane il metodo consigliato per gestire gli aggiornamenti automatici in sicurezza.
Cosa devo fare se una dashboard non carica più dopo un aggiornamento?
Se una dashboard restituisce una schermata bianca o un errore critico, accedi alla modalità di emergenza di Lovelace, rimuovi temporaneamente la stringa della card difettosa dal file di configurazione grezzo e verifica i log di sistema per identificare eventuali conflitti di script.
Come posso personalizzare i colori di Bubble Card?
La personalizzazione dei colori avviene principalmente tramite l'inserimento di proprietà CSS personalizzate all'interno del parametro styles della configurazione YAML o sfruttando i temi globali supportati da Home Assistant.
Prodotti consigliati
Hardware pertinente alla guida
I collegamenti portano alle pagine dei prodotti indicati. Il prezzo Amazon, quando disponibile, proviene dall’API ufficiale ed è aggiornato con data e ora; prezzo e disponibilità finali sono quelli della pagina Amazon.