Come installare e configurare Mushroom Cards in Home Assistant

Mushroom Cards è una raccolta software di card custom per dashboard Lovelace. Non è un dispositivo e non aggiunge entità: visualizza e controlla quelle già presenti in Home Assistant. È distribuita tramite HACS dal repository piitaya/lovelace-mushroom; la grafica e la sintassi possono cambiare con gli aggiornamenti, quindi conserva un backup della dashboard.

Prerequisiti & Hardware Necessario

• Home Assistant aggiornato con HACS già installato e configurato.
• Una dashboard Lovelace e almeno un’entità reale, per esempio light.soggiorno.
• Accesso amministrativo per installare una risorsa frontend e modificare card.
• Browser desktop per l’installazione e tablet/smartphone per il test responsive.
• Nessun prodotto d’acquisto necessario: Mushroom Cards è software frontend.

Procedura passo-passo

1. Fai un backup. Crea un backup Home Assistant prima di installare una risorsa custom. Salva anche la configurazione YAML della dashboard se la usi.
2. Apri HACS. In Home Assistant apri HACS → Frontend, cerca Mushroom e verifica che il repository sia piitaya/lovelace-mushroom. Non installare fork con nomi simili senza controllare autore e documentazione.
3. Installa la risorsa. Seleziona Mushroom, scegli l’ultima release compatibile e premi Download. HACS installa la risorsa frontend nella configurazione; non serve un’integrazione dispositivo e non devi aggiungere Mushroom a configuration.yaml come integrazione YAML.
4. Ricarica il frontend. Esegui un hard refresh del browser e riapri l’app Companion. Se il card picker non mostra Mushroom, svuota la cache del browser dopo aver verificato che HACS abbia completato il download.
5. Crea una card Mushroom. Modifica una dashboard, scegli Aggiungi card e cerca le card Mushroom. In modalità YAML una card luce minima è:

   type: custom:mushroom-light-card
   entity: light.soggiorno
   name: Soggiorno
   icon: mdi:ceiling-light
   show_brightness_control: true
   use_light_color: true

   Sostituisci l’entity ID con uno esistente nel tuo sistema.
6. Aggiungi una card entità.

   type: custom:mushroom-entity-card
   entity: sensor.temperatura_soggiorno
   name: Temperatura
   icon: mdi:thermometer
   primary_info: name
   secondary_info: state

   Le opzioni disponibili dipendono dal tipo di card e dalla release installata: segui il README della release corrente.
7. Configura una card template con cautela.

   type: custom:mushroom-template-card
   primary: Porta ingresso
   secondary: "{{ states('binary_sensor.porta_ingresso') }}"
   icon: mdi:door
   entity: binary_sensor.porta_ingresso
   tap_action:
     action: more-info

   Il template deve restituire testo valido e riferirsi a un’entità esistente; una stringa Jinja errata può lasciare la card vuota.
8. Imposta azioni touch. Usa tap_action per more-info, toggle o navigate; usa hold_action per azioni meno frequenti. Evita di mettere comandi distruttivi su un singolo tap senza conferma o senza una condizione.
9. Componi la dashboard. Raggruppa le card con le card native grid, horizontal-stack o Sections. Mushroom non sostituisce il layout Lovelace: ogni card deve stare in una view e in una sezione valide.
10. Usa temi senza confonderli con le card. Mushroom applica il proprio stile alle card, ma temi e card-mod sono risorse separate. Installa una sola risorsa alla volta e verifica l’interfaccia prima di aggiungerne altre.
11. Testa gli aggiornamenti. Dopo un aggiornamento HACS ricarica frontend, dashboard e app. Controlla card, azioni e log browser; se una release rompe la UI, ripristina la versione compatibile dal backup o dalla funzione di rollback disponibile.
12. Limita le entità esposte. Una Mushroom Card non crea autorizzazioni aggiuntive. Gli utenti vedono ciò che il loro account Home Assistant può vedere; non inserire token o password nei template.

Verifica del funzionamento

1. Controlla in HACS che Mushroom risulti installato senza errori.
2. Ricarica il frontend e verifica che una card luce, una card entità e una card template vengano renderizzate.
3. Aziona la luce dal card e controlla che lo stato torni in Home Assistant.
4. Apri la dashboard su browser, smartphone e tablet per verificare testo, dimensioni e tap.
5. Riavvia Home Assistant e verifica che le card custom restino disponibili senza reinstallazione.

Problemi comuni

FAQ essenziali

Mushroom Cards funziona senza HACS?

Sì, è possibile installarla manualmente come risorsa frontend, ma HACS semplifica download e aggiornamenti. Per una gestione ripetibile usa il repository ufficiale del progetto.

Mushroom sostituisce le card native di Home Assistant?

No. È un set di card custom che usa le entità e il sistema Lovelace di Home Assistant. Se la risorsa non carica, le card native restano il fallback più stabile.