Browser Mod di Home Assistant: Panoramica generale e funzione Popup

Parto così … Browser Mod di Home Assistant è un componente STRA-OR-DI-NA-RIO!
Si davvero, mi piace molto e lo trovo utile in diversi contesti.

Browser Mod è un componente custom, si installa facilmente via HACS e si posiziona nella categoria Integrazioni.
E’ in grado di fare parecchie cose, ad esempio impostare un tema di Lovelace, navigare tra le viste di una plancia oppure visualizzare la finestra more-info di una qualsiasi entità. Tra tutte, per me, le caratteristiche più interessanti di questo componente sono due:

• Creazione di un popup personalizzato.
• Integrazione con Fully Kiosk Browser (versione PLUS a pagamento).

In questo articolo vediamo una panoramica generale del componente e come creare dei popup personalizzati, di Fully Kiosk ne parlerò in un prossimo articolo.

• Premessa
• Panoramica generale
  • Come funziona
  • Installazione
  • Configurazione
• Popup  personalizzato
  • Come creare un popup
  • Un popup per gestire illuminazione smart
• Conclusione

Premessa

In data 10 febbraio 2021, l’autore del componente, Thomas Lovén, ha rilasciato un importante aggiornamento con la versione 1.3.0 mandando in tilt molti appassionati del componente per via di una breaking change sulla generazione dei popup.

Pochi giorni dopo, come se non bastasse, la versione 2021.3 di Home Assistant Core ha cambiato un po’ le carte in tavola anche lato configurazione del componente.

Alla luce di questo per seguire l’articolo è necessario avere Browser Mod in versione 1.3.0 o superiore e Home Assistant Core in versione 2021.3.0 o superiore.

Panoramica generale

Browser Mod è un componente particolare, unico nel suo genere che io sappia, ma l’approccio iniziale non è facilissimo.
Qui vediamo come funziona in generale, come installarlo e infine come integrarlo su Home Assistant. Se già conosci e usi il componente, se vuoi, puoi saltare al prossimo capitolo.

Come funziona

Browser Mod gira intorno al concetto di device.
Il device è uno dei dispositivi client che usiamo per collegarci alla UI di Home Assistant: il desktop, lo smartphone, il tablet …

Quando un device si connette per la prima volta, Browser Mod lo intercetta e gli assegna un deviceID generato in maniera casuale, secondo questo formato ded3b4dc-abedd098.

Ogni nuovo device genera da tre a cinque entità:

• sensor.<deviceID>
  Il sensore restituisce, nello stato, il numero di tab del browser aperti sul device e negli attributi una serie di info utili.
• media_player.<deviceID>
  Entità per riprodurre media sul device.
• light.<deviceID>
  Entità light utile, a mio avviso, solo con Fully Kiosk dove puoi gestire lo schermo del device (on/off). In tutti gli altri casi lo schermo non viene spento, viene solo applicata una black screen sulla superficie del browser.
• camera.<deviceID> (da attivare)
  L’entità camera non viene generata di default, va abilitata.
• binary_sensor.<deviceID> (con Fully Kiosk Browser)
  Entità binary sensor di tipo Motion Detection usando la telecamera del device (molto utile in ambito plancia da tablet).
  Disponibile solo con integrazione Fully Kiosk Browser versione PLUS.

Di default le entità vengono denominate con il deviceID di riferimento, ad esempio light.ded3b4dc_abedd098.

Fino a poco tempo fa era possibile assegnare un nome più user friendly direttamente in fase di configurazione iniziale e anche disabilitare alcune entità. Purtroppo dalla versione 2021.3 di Home Assistant Core abbiamo perso queste funzionalità e la documentazione ufficiale non si è ancora aggiornata in tal senso.

Allo stato attuale possono essere rinominate da UI come una qualsiasi altra entità, ma mi auguro in un ripristino perché era oggettivamente più comodo gestire le entità da configurazione.

Installazione

L’installazione del componente è davvero molto semplice, lo facciamo con pochi click da HACS.

Nella Home di HACS clicca su Integrazioni.

Clicca su Explorer & Add Repositories in basso a destra.

Nella casella di ricerca digita Browser e clicca sul componente trovato.

Nella scheda del componente clicca su Installa questo repository in HACS  in basso a destra.

Infine conferma l’installazione cliccando su Installa in basso a destra.

Ora aggiungi nel file configuration.yaml questa riga. Per il momento facciamo una configurazione minimale con l’opzione prefix:, nel prossimo paragrafo vediamo cosa significa e altre opzioni utili.

browser_mod:
  prefix: "browser_"

Riavvia Home Assistant per rendere effettive le modifiche.

Configurazione

Dopo l’installazione ti dovresti trovare in questa situazione. Puoi verificarlo da Strumenti per sviluppatori -> Stati filtrando la lista entità con “Browser”.

Subito dopo il riavvio potresti non vedere nulla filtrando per “Browser”, in questo caso basta aggiornare la finestra del browser.

Quelle che vedi sono le tre entità di default create da Browser Mod per il dispositivo che stai usando ora.

Purtroppo, come accennato prima, ad oggi alcune opzioni di configurazione descritte nella documentazione ufficiale non funzionano correttamente, tra le più importanti il rename e il disable delle entità a monte. Vediamo quello che funziona e che ti consiglio di configurare.

Assegnare un alias ai devices è ancora possibile per fortuna con una configurazione di questo tipo:

browser_mod:
  prefix: "browser_"
  devices:
    a0baf760-07e40000:
      name: browser-imac
    bd89a088-7a05c758:
      name: browser-tablet
    c28c5299-bee79e5e:
      name: browser-cell-max

Per trovare il deviceID assegnato esistono diversi metodi, il più semplice è senz’altro usare il servizio browser_mod.debug da Strumenti per sviluppatori -> Servizi. Questo servizio non richiede parametri e una volta eseguito genera un popup su tutti i device connessi in quel momento con il deviceID assegnato.

Consiglio anche l’utilizzo dell’opzione prefix: per assegnare un prefisso al nome delle entità che saranno generate, in modo da poterle filtrare agevolmente nella scheda stati di strumenti per sviluppatori.

Quindi, ricapitolando, se vuoi seguire questi consigli di configurazione fai così:

• Collegati alla URL di Home Assistant dai dispositivi per i quali desideri creare un alias.
• Esegui il servizio browser_mod.debug da Strumenti per sviluppatori -> Servizi e prendi nota dei deviceID assegnati.
• Edita il file configuration.yaml adattando questo esempio con i tuoi dispositivi.

  browser_mod:
    prefix: "browser_"
    devices:
      a0baf760-07e40000:
        name: browser-imac
      bd89a088-7a05c758:
        name: browser-tablet
      c28c5299-bee79e5e:
        name: browser-cell-max

• Riavvia Home Assistant per applicare la nuova configurazione.

Dispositivi ed entità di Browser Mod possono essere gestiti da Impostazioni -> Integrazioni. Da qui puoi rinominare ed eliminare elementi.

Con il tempo ti potresti trovare parecchie entità obsolete (un client che ha cambiato deviceID), per fare pulizia è possibile usare il servizio browser_mod.clean_devices il quale rimuoverà solo i vecchi elementi.

L’alias impostato in configurazione ci torna molto utile per utilizzare i servizi messi a disposizione da Browser Mod. Esplorare tutti i servizi non è oggetto di questo articolo ma vediamo come impartire un comando ad un device specifico.

Per l’esempio usiamo il servizio browser_mod.toast.

service: browser_mod.toast
data:
  message: notifica di test
  duration: 3000

Con questi parametri viene generata una notifica su tutti i device per una durata di 3 secondi.
Per generare, invece, la notifica solo su un device specifico possiamo utilizzare il parametro deviceID con l’alias assegnato in configurazione.

service: browser_mod.toast
data:
  message: messaggio di prova
  duration: 3000
  deviceID: browser-tablet

Il parametro deviceID può essere assegnato a tutti i servizi esposti da Browser Mod, così da indirizzare il comando solo sul device desiderato, utile anche in caso di utilizzo via automazione.

Per generare un Popup da frontend solo sul device corrente invece le cose sono cambiate radicalmente con la versione 1.3.0.
La sintassi deviceID: this (ancora presente nella documentazione) non è più valida e lo vedremo nel prossimo capitolo.

Popup personalizzato

Come dicevo in apertura, una delle funzionalità più interessanti di Browser Mod è quella di poter creare Popup personalizzati con dentro qualsiasi cosa vogliamo.

Le possibilità di utilizzo sono davvero infinite. A me piace usarlo, ad esempio, per mostrare opzioni supplementari a partire da un comando principale della plancia.

Per un approfondimento completo di questa plancia da Tablet ti consiglio di partire da qui.

Vediamo nel dettaglio come scrivere il codice YAML per creare un popup base e poi un esempio per un popup più elaborato.

Come creare un popup

Con le novità introdotte dalla versione 1.3.0 di Browser Mod dobbiamo gestire i Popup con due sintassi differenti, in base alla situazione in cui ci troviamo.

• La prima per generare un Popup da UI (Lovelace) sul dispositivo in uso.
• La seconda per generare un Popup su un dispositivo specifico connesso in rete (un tablet, ad esempio).

Sul dispositivo in uso

Per generare un popup da frontend sul dispositivo in uso non è più richiesto l’utilizzo del parametro deviceID, dobbiamo usare la sintassi basata su fire-dom-event.

Iniziamo con un esempio molto semplice: una card di tipo button che apre un popup con dentro altre tre card button organizzate in una horizontal-stack.

type: button
name: APRI POPUP
tap_action:
  action: fire-dom-event
  browser_mod:
    command: popup
    title: POPUP
    card:
      type: horizontal-stack
      cards:
        - type: button
          name: BUTTON 1
        - type: button
          name: BUTTON 2
        - type: button
          name: BUTTON 3

Il popup si apre ma esteticamente si può fare di meglio. Con l’ausilio del sempre ottimo card-mod aggiungiamo un margine interno e arrotondiamo un po’ gli spigoli.

type: button
name: APRI POPUP
tap_action:
  action: fire-dom-event
  browser_mod:
    command: popup
    title: POPUP
    style:
      $: |
        .mdc-dialog 
        .mdc-dialog__container 
        .mdc-dialog__surface {
          border-radius: 15px;
        }
        .mdc-dialog 
        .mdc-dialog__content {
            padding: 40px 40px !important;
        }
    card:
      type: horizontal-stack
      cards:
        - type: button
          name: BUTTON 1
        - type: button
          name: BUTTON 2
        - type: button
          name: BUTTON 3

Su un dispositivo specifico

Con una sintassi diversa, e con l’utilizzo del parametro deviceID, possiamo generare un Popup su uno dei dispositivi connessi in rete e riconosciuti da Browser Mod. Questa modalità di solito non viene usata da Frontend, ha molto più senso un utilizzo via automazione secondo logiche diverse in base all’esigenza.

In questo caso usiamo il servizio browser_mod.popup nella sezione action di una automazione e nel parametro deviceID indichiamo un alias assegnato in precedenza oppure direttamente il valore alfanumerico generato da Browser Mod.

automation:
  - alias: TEST POPUP
    trigger: []
    condition: []
    action:
      - service: browser_mod.popup
        data:
          title: POPUP
          deviceID: browser-tablet
          card:
            type: horizontal-stack
            cards:
              - type: button
                name: BUTTON 1
              - type: button
                name: BUTTON 2
              - type: button
                name: BUTTON 3

Per entrambi le situazioni, a titolo di esempio, abbiamo usato una semplice horizontal-stack come card del popup, ma è possibile sviluppare qualsiasi tipo di card all’interno, anche componenti custom.

Ora vediamo un popup più creativo e articolato.

Un Popup per gestire illuminazione smart

Nella vista LUCI della mia plancia da tablet ho realizzato dei popup per gestire la luminosità e i valori RGB di una entità light.

Per la realizzazione di questi popup è richiesta l’installazione via HACS dei seguenti custom component:

• Light Popup Card
• Light Entity Card
• Card Mod
• Button Card

Ti lascio i due template di Button Card da usare in una card custom:button-card con una entità di tipo light.

Template per entità light NON RGB

popup_light:
  hold_action:
    action: fire-dom-event
    browser_mod:
      command: popup    
      title: '[[[ return entity.attributes.friendly_name ]]]'
      hide_header: true
      style:
        $: |
          .mdc-dialog .mdc-dialog__container {
            width: 100%;
          }
          .mdc-dialog .mdc-dialog__container .mdc-dialog__surface {
            width:100%;
            box-shadow:none;
          }
        .: |
          :host {
            --mdc-theme-surface: rgba(0,0,0,0);
            --secondary-background-color: rgba(0,0,0,0);
            --ha-card-background: rgba(0,0,0,0);
            --mdc-dialog-scrim-color: rgba(0,0,0,0.8);
            --mdc-dialog-min-height: 100%;
            --mdc-dialog-min-width: 100%;
            --mdc-dialog-max-width: 100%;
          }
          mwc-icon-button {
            color: #FFF;
          }        
      card:
        type: 'custom:light-popup-card'
        entity: '[[[ return entity.entity_id ]]]'
        icon: 'mdi:led-strip'
        actionSize: 60px
        actions:
          - service: light.turn_on
            service_data:
              entity_id: '[[[ return entity.entity_id ]]]'
              color_temp: 153
            color: '#d8d9e1'
          - service: light.turn_on
            service_data:
              entity_id: '[[[ return entity.entity_id ]]]'
              color_temp: 326
            color: '#d5b08d'
          - service: light.turn_on
            service_data:
              entity_id: '[[[ return entity.entity_id ]]]'
              color_temp: 500
            color: '#ce944b'

Template per entità light RGB

popup_light_rgb:
  hold_action:
    action: fire-dom-event
    browser_mod:
      command: popup   
      title: '[[[ return entity.attributes.friendly_name ]]]'
      hide_header: true
      style:
        $: |
          .mdc-dialog .mdc-dialog__container {
            width: 100%;
          }
          .mdc-dialog .mdc-dialog__container .mdc-dialog__surface {
            width:100%;
            box-shadow:none;
          }
        .: |
          :host {
            --mdc-theme-surface: rgba(0,0,0,0);
            --secondary-background-color: rgba(0,0,0,0);
            --ha-card-background: rgba(0,0,0,0);
            --mdc-dialog-scrim-color: rgba(0,0,0,0.8);
            --mdc-dialog-min-height: 100%;
            --mdc-dialog-min-width: 100%;
            --mdc-dialog-max-width: 100%;
          }
          mwc-icon-button {
            color: #FFF;
          }        
      card:
        type: 'custom:light-popup-card'
        entity: '[[[ return entity.entity_id ]]]'
        icon: 'mdi:led-strip'
        actionSize: 60px
        settings:
          openButton: RGB
          closeButton: CHIUDI
        settingsCard:
          type: 'custom:light-entity-card'
          cardOptions:
            entity: '[[[ return entity.entity_id ]]]'
            brightness: false
            full_width_sliders: true
            hide_header: true
            show_slider_percent: true
            smooth_color_wheel: true
            consolidate_entities: true
        actions:
          - service: light.turn_on
            service_data:
              entity_id: '[[[ return entity.entity_id ]]]'
              color_temp: 153
            color: '#d8d9e1'
          - service: light.turn_on
            service_data:
              entity_id: '[[[ return entity.entity_id ]]]'
              color_temp: 326
            color: '#d5b08d'
          - service: light.turn_on
            service_data:
              entity_id: '[[[ return entity.entity_id ]]]'
              color_temp: 500
            color: '#ce944b'

Se non ti è chiaro come usare i template di Button Card ne ho parlato qui.

Conclusione

Capita spesso che i custom component si adeguino alle evoluzioni di Home Assistant, a volte introducendo piccole novità ma a volte, purtroppo, anche delle breaking change importanti.

Spero di aver fatto un po’ di chiarezza sulle novità di Browser Mod e di aver descritto bene le caratteristiche di questo utilissimo componente.

Ciao e a presto.
Max