La Libreria dispositivi
La Libreria dispositivi è un catalogo di template pronti all'uso per apparecchiature già mappate: contatori di energia, inverter solari, batterie domestiche, stazioni di ricarica per veicoli elettrici, relè intelligenti, lettori multimediali e altoparlanti Sonos. È sufficiente selezionare il modello e compilare pochi campi — generalmente l'indirizzo del dispositivo — e la libreria genera i widget con tutti i relativi oggetti di comunicazione già associati: registri, topic, percorsi, tipi di dati, fattori di scala e unità di misura inclusi. Un'operazione che richiederebbe ore di consultazione manuale dei registri si completa in un minuto.
È accessibile da Dispositivi → Aggiungi da libreria.
Requisiti: il dispositivo deve essere presente sulla rete con un indirizzo statico (prenotazione DHCP), con l'eventuale protocollo abilitato nella propria configurazione (il Modbus TCP è disattivato per impostazione predefinita sulla maggior parte degli inverter) e il protocollo attivo in Servizi (consultare la sezione «Servizi e protocolli»).
Esplorazione del catalogo
Ogni template è rappresentato da una scheda che riporta marchio, modello, badge del protocollo e una breve descrizione. È possibile filtrare l'elenco tramite:
- il campo di ricerca: per marchio, modello, nome del dispositivo o descrizione; il contatore a destra mostra corrispondenze / totale;
- i selettori di categoria: uno per ogni categoria presente nel catalogo (Attualmente Illuminazione, Schermature solari, Energia e Audio / Video);
- i menu a discesa Marchio e Protocollo.

Dispositivi supportati. Il catalogo è integrato nel server e viene arricchito a ogni aggiornamento. Attualmente include 83 template di 49 marchi:
| Famiglia di dispositivi | Marchi supportati |
|---|---|
| Inverter solari e inverter ibridi | SMA · Huawei (SUN2000) · SolarEdge · Sungrow · GoodWe · Growatt · FoxESS · Solax · Deye · SAJ · SofarSolar · Solplanet · Solinteg · SolarMax · M-TEC · Senergy · IBC Solar · Anker (SOLIX X1) · EcoFlow (PowerOcean) |
| Batterie domestiche e accumulo | Marstek (Venus) · Alpha ESS · SAX Power · Siemens (Junelight) · INTILION · Ads-tec · Anker (Solarbank) · SolarMax (MAX STORAGE) |
| Energy manager e datalogger | Huawei (EMMA, SmartLogger) · SMA (Data Manager, WebBox) · Sungrow (iHomeManager) · Ferroamp · OpenEMS / FENECON · Atmoce · Plexlog · Powerdog |
| Contatori di energia | HomeWizard (P1) · Siemens (SENTRON 7KT PAC) · Kostal (Smart Energy Meter) · Acrel · my-PV · Shelly (Plus Plug S) |
| Stazioni di ricarica per veicoli (EV) | KEBA · Mennekes · Schneider (EVlink Pro) · Phoenix Contact (CHARX, EM-CP-PP-ETH, EV-SER) · Heidelberg · go-e · Bender · Peblar · EM2GO · OBO Bettermann · openWB · Stark in Strom |
| Relè per illuminazione e tapparelle | Shelly (1 / 1PM, Plus 1 / 1PM, RGBW2, Plus RGBW PM, 2.5 roller) |
| Audio / video | Sonos (qualsiasi zona) · AUDAC (XMP44) |
La maggior parte dei dispositivi per l'energia comunica via Modbus TCP. Le unità Shelly sono disponibili sia in versione HTTP che MQTT con due schede distinte; selezionare quella corrispondente alla configurazione attiva sul dispositivo. HomeWizard utilizza HTTP, AUDAC TCP/UDP e Sonos il proprio protocollo proprietario (consultare la sezione «Integrazione Sonos»).
📘 Nota: Un template copre un'intera famiglia di prodotti, non un singolo codice articolo: il template Sonos gestisce qualsiasi zona, mentre il template Shelly Plus 1 gestisce sia l'1 che l'1PM. Quando un produttore ha modificato la mappa dei registri tra diverse generazioni hardware, sono presenti schede separate (Shelly Gen1 e Shelly Plus).
Creazione di un dispositivo da un template
- Fare clic sulla scheda del template. Si apre la pagina di configurazione con la descrizione e, se presenti, il pannello dei Requisiti di configurazione. Verificare preventivamente questi requisiti: account installatore, attivazione del Modbus sul dispositivo, o impostazione di un intervallo di polling più lungo per gli inverter con tempi di risposta elevati.
- Inserire il Nome del dispositivo. Questo testo fungerà da prefisso per ogni widget generato dal template: ad esempio, "Garage" genererà "Garage — Rete", "Garage — Solare", ecc.
- Compilare i parametri del template richiesti dai widget: l'ID unità Modbus, la variante di modello dal menu a discesa, o la zona Sonos. Il modulo non richiede l'indirizzo IP: quest'ultimo è definito nella connessione e va inserito al passaggio 4.
- Aprire la sezione Connessione. L'elenco mostra unicamente le connessioni compatibili con il protocollo del template. Selezionare la connessione esistente del dispositivo oppure, per un dispositivo con indirizzo IP dedicato (inverter, wallbox, altoparlante), scegliere Crea una nuova connessione…: si apre la finestra di dialogo Aggiungi una connessione con protocollo e nome precompilati. Inserire l'indirizzo IP del dispositivo e fare clic su Crea connessione; la nuova connessione viene subito selezionata, senza dover passare preventivamente dalla pagina Connessioni. Se esiste già una connessione verso quell'indirizzo, la libreria lo segnala e la riutilizza per evitare duplicazioni. I template basati su infrastruttura condivisa (come un broker MQTT) selezionano automaticamente la connessione esistente.
- Selezionare l'Ambiente e la Categoria di destinazione per i widget (entrambi obbligatori).
- Il pannello Widget da creare mostra l'anteprima in tempo reale.

L'anteprima e le opzioni di modifica
Ciascun widget nell'anteprima visualizza il proprio nome, la tipologia di widget e il contatore N / M oggetti associati. Il template definisce quali widget risultano selezionati per impostazione predefinita, includendo generalmente le funzioni comuni a ogni impianto. Le altre rimangono deselezionate poiché richiedono componenti hardware aggiuntivi: ad esempio, il template Huawei seleziona il contatore solare e lascia deselezionati i contatori di rete e batteria, che andranno abilitati solo se è presente lo Smart Power Sensor. Verificare i requisiti di configurazione e selezionare esclusivamente i componenti effettivamente installati. Prima della creazione è possibile:
- selezionare o deselezionare ciascun widget (in un impianto solo fotovoltaico non occorre creare la batteria);
- rinominare un widget direttamente nel campo;
- espandere il contatore degli oggetti per verificare ciascun oggetto: numero progressivo, nome, indirizzo assegnato e tipo di dati. Gli oggetti lasciati intenzionalmente vuoti dal template riportano la dicitura nessun indirizzo.
In caso di parametri mancanti o non validi, al posto dell'elenco dei widget compare un messaggio di errore in rosso che indica il parametro da correggere; il pulsante di creazione rimane disabilitato fino alla risoluzione dell'errore.
Fare clic su Crea N widget. La pagina di riepilogo elenca i dispositivi creati con il relativo numero di oggetti, le eventuali operazioni non riuscite con la rispettiva causa, e offre il comando Aggiungi un altro dispositivo per utilizzare nuovamente la libreria. Questa è la procedura standard per configurare un sistema multi-zona o un'abitazione con più dispositivi Sonos, applicando il template per ciascuna zona.
📘 Nota: I widget vengono salvati ma non sono ancora operativi. Fare clic su Applica modifiche nella barra laterale, quindi confermare in Applica modifiche alla configurazione (consultare la sezione «Panoramica del pannello di amministrazione») per riavviare i protocolli e distribuire la configurazione a tutti i client.

Operazioni successive alla creazione
Una volta creati, i widget funzionano come normali dispositivi: possono essere rinominati, personalizzati nelle icone, spostati tra gli ambienti, associati alla registrazione dati (logging) e inseriti in viste, scenari e automazioni. Anche le associazioni create sono standard: è possibile aprire qualsiasi oggetto e modificarne la configurazione (consultare «Integrazione Modbus TCP» e «Integrazione MQTT»).
I contatori generati da un template per l'energia vengono creati con il relativo ruolo già impostato (rete, solare, batteria, ricarica, consumo), consentendo alla sezione Energia e al bilancio energetico di operare senza ulteriori configurazioni (consultare «Dispositivi per l'energia» e «Panoramica energia»).
Importazione ed esportazione dei template
La libreria supporta l'uso di template personalizzati: file in formato .yaml o .yml con dimensione massima di 256 KB, strutturati con lo stesso schema dei template integrati. Il pannello di amministrazione non include un editor integrato: i template personalizzati vengono redatti o modificati con un editor di testo esterno.
- Importa template (in alto a destra) consente di caricare un file. Il sistema esegue una validazione preliminare: se il file presenta errori, l'importazione viene bloccata segnalando il numero e il dettaglio delle anomalie. I template caricati mostrano il badge importato sulla scheda.
- Se un template importato utilizza lo stesso identificatore di uno integrato, quest'ultimo viene sostituito e sulla scheda appare la dicitura sostituisce integrato. Eliminando il file personalizzato viene ripristinata la versione originale inclusa nel sistema.
- I template importati possono essere esportati (Esporta come YAML) ed eliminati (Elimina template) tramite le icone visibili al passaggio del cursore sulla scheda. Il comando Elimina template rimuove il template immediatamente senza richiesta di conferma.
- I template integrati non possono essere né esportati né eliminati (non presentano le relative icone). Fanno parte del sistema base e vengono ripristinati a ogni aggiornamento. Per creare un nuovo template, è possibile esportare un template importato esistente o compilare un nuovo file da zero.
⚠️ Attenzione: L'eliminazione di un template non influisce sui dispositivi già creati con esso. I dispositivi continuano a funzionare regolarmente: viene rimosso unicamente il modello di creazione.
Associazione Sonos
Gli oggetti Sonos vengono associati a una zona, non a un indirizzo IP inserito manualmente. Impostando il protocollo del dispositivo su Sonos — operazione eseguita automaticamente dalla libreria — l'editor di ciascun oggetto mette a disposizione i seguenti campi:
| Campo | Descrizione |
|---|---|
| Zona Sonos | La zona controllata dal widget, selezionata dall'elenco delle zone attive rilevate nell'impianto. L'identificatore salvato rimane valido anche in caso di ridenominazione della stanza nell'app Sonos o di variazione dell'indirizzo IP. |
| Agisci sull'intero gruppo | Disponibile sui due oggetti di comando, Setpoint volume e Muto On/Off: se la zona appartiene a un gruppo, il comando agisce sull'intero gruppo anziché sul singolo altoparlante. L'opzione è configurabile separatamente per ciascun oggetto (ad esempio per regolare il volume di gruppo mantenendo la funzione muto individuale). L'opzione compare anche su Stato volume e Stato muto, dove non produce effetti: il feedback riporta sempre lo stato specifico della singola zona. |
Tutti gli oggetti del widget fanno riferimento alla stessa zona; il numero dell'oggetto ne determina la funzione: volume, muto, play/pause, sorgente, traccia precedente/successiva, titolo brano, artista, copertina. La funzione Zona On/Off non è applicabile a un altoparlante Sonos e non va associata; per questo motivo il template della libreria adotta il sottotipo audio senza zone.
Fare clic su Salva oggetto, quindi selezionare Applica modifiche nella barra laterale e confermare (consultare la sezione «Panoramica del pannello di amministrazione»).
📘 Nota: La creazione e lo scioglimento dei gruppi avvengono esclusivamente all'interno dell'app Sonos; HyperVisu non gestisce la composizione dei gruppi. Nelle applicazioni le zone restano visualizzate come dispositivi audio indipendenti, ciascuno con il proprio cursore del volume e pulsante muto; il cursore continua a indicare il livello effettivo della singola zona anche quando i comandi agiscono sul gruppo. Per verificare i gruppi attivi, consultare l'app Sonos o la sezione Zone in questa abitazione all'interno della connessione Sonos (consultare «Integrazione Sonos»). I comandi di riproduzione, pausa, traccia successiva e precedente vengono sempre indirizzati al dispositivo coordinatore del gruppo.

Le sorgenti corrispondono ai preferiti Sonos. Sopra l'elenco degli oggetti del widget è presente il pannello Sorgenti Sonos. Premendo Sincronizza preferiti Sonos, il server interroga il sistema: rileva prima gli ingressi fisici dell'altoparlante (TV per le soundbar, Line-In sui modelli provvisti), poi i preferiti salvati nell'app Sonos. I nomi e il numero delle sorgenti vengono memorizzati nel widget e le applicazioni mostrano un pulsante per ciascuna sorgente.
L'elenco è gestito direttamente dal sistema Sonos e non è modificabile manualmente da questa schermata. È necessario ripetere la sincronizzazione dopo ogni aggiunta, rimozione o ridenominazione dei preferiti nell'app Sonos per aggiornare i pulsanti nell'interfaccia.

💡 Suggerimento: Se le sorgenti configurate superano il numero di sei, le applicazioni sostituiscono i singoli pulsanti con un menu a discesa per mantenere l'interfaccia compatta e fruibile.