Dispositivi virtuali
Un dispositivo virtuale non ha alcun collegamento fisico — è il server stesso a conservarne lo stato. I dispositivi virtuali collegano le funzioni delle installazioni avanzate. Utilizzi tipici:
- Punti controllati da flussi Node-RED (vedere sotto).
- Gruppi di dispositivi — un gruppo è un widget virtuale che controlla i propri membri (vedere «Gruppi di dispositivi»).
- Uscite logiche materializzate — l’uscita di una funzione trasformata in un vero widget (vedere «Configurazione delle funzioni e uscite»).
- Indicatori e setpoint per le automazioni («Modalità vacanza», «Scostamento della temperatura desiderata»).
Createli nell’area di lavoro Dispositivi come qualsiasi altro widget, impostando Protocol su VIRTUAL. Per ogni oggetto si configurano:
| Impostazione | Significato |
|---|---|
| Range - Min / Range - Max | I valori accettati dall’oggetto. Un valore scritto dall’esterno (da un flusso o dal webhook) fuori dall’intervallo viene rifiutato; un nuovo oggetto parte da 0 a 100. |
| Persist State | Indica se il valore attuale viene conservato dopo un riavvio del server. Attivare per indicatori e setpoint; lasciare disattivato per segnali momentanei. |
Un oggetto virtuale non ha un’impostazione del valore predefinito. Attivare Persist State se l’ultimo valore deve essere ripristinato dopo un riavvio. L’Object ID sotto il titolo della finestra dell’oggetto è l’identificativo usato da un flusso o dal webhook per indirizzare l’oggetto.

Node-RED
Node-RED è un servizio opzionale del server (attivabile in «Servizi e protocolli») per creare flussi personalizzati — ponti MQTT, API cloud particolari, logica su misura che non rientra nel motore logico o un driver per un dispositivo non supportato da HyperVisu.
- Attivazione: in Services, attivare Node-RED. La riga mostra Changes need a restart; fare clic su Restart Server nel banner Pending Changes e attendere che il server torni disponibile.
- Apertura: quando il servizio è in esecuzione, Node-Red compare nel gruppo APPS della barra laterale di amministrazione. Fare clic per aprire l’editor dei flussi in una nuova scheda.
- Connessione: accedere con il proprio account HyperVisu.
- Controllo dei dispositivi: i nodi Hypervisu della palette leggono e scrivono direttamente sui dispositivi HyperVisu (vedere «I nodi HyperVisu» sotto). I dispositivi virtuali sono il punto d’incontro naturale: il flusso calcola, il dispositivo virtuale mostra il risultato e partecipa a scenari, automazioni e viste come qualsiasi altro dispositivo.
- API webhook: i flussi e i sistemi di terze parti possono usare anche l’API webhook dei dispositivi, protetta tramite verifica del numero di serie (vedere «Webhook e API di terze parti»). L’interruttore Webhooks della pagina Services deve essere attivo (vedere «Servizi e protocolli»). Mantenere segreto il numero di serie: chiunque lo conosca può scrivere tramite il webhook.
💡 Suggerimento: preferire il motore logico (vedere «Motore logico — Concetti e area di lavoro») per la logica standard degli edifici — è monitorata, validata e visibile ai residenti. Usare Node-RED per ciò che richiede codice.
I nodi HyperVisu
Il Node-RED del server include una categoria Hypervisu nella palette: un nodo per tipo di dispositivo, un nodo Input Target, due nodi di comandi globali e un nodo Scenario. Un nodo di dispositivo rappresenta un dispositivo HyperVisu. Inviandogli un messaggio si comanda il dispositivo; quando il dispositivo cambia, il nodo invia il nuovo valore da una delle proprie uscite.

| Nodo | Tipo di dispositivo (vedere «Panoramica dei tipi di widget») | Ingressi → uscite |
|---|---|---|
| Pushbutton | Pulsante | Qualsiasi messaggio → 1 uscita |
| Light Switch, Switch | Interruttore luce, interruttore | 2 destinazioni → 2 uscite |
| Analog Output | Uscita analogica | Un numero → 1 uscita |
| Shutter / Blind | Tapparella / veneziana | 8 destinazioni → 8 uscite |
| Temperature Controller | Temperatura / termostato | 5 destinazioni → 5 uscite |
| Dimmer | Dimmer | 4 destinazioni → 4 uscite |
| RGB Dimmer | Dimmer RGB | 4 destinazioni → 4 uscite |
| Tunable White Dimmer | Dimmer per bianco regolabile | 6 destinazioni → 6 uscite |
| Analog Input | Ingresso analogico | Un numero → 1 uscita |
| Digital Input | Ingresso digitale | true / false → 1 uscita |
| Text Input | Ingresso testo | Un testo → 1 uscita |
| Alarm | Allarme | 7 destinazioni → 7 uscite |
| Audio | Audio | 13 destinazioni → 13 uscite |
| Ventilation | Ventilazione | 10 destinazioni → 10 uscite |
| Air Conditioning | Climatizzazione | 11 destinazioni → 11 uscite |
| Door Lock | Serratura | 2 destinazioni → 2 uscite |
| Meter | Contatore | 4 destinazioni → 4 uscite |
| Charger | Caricatore per veicoli elettrici | 8 destinazioni → 8 uscite |
| Global Lights, Global Shutters | Tutte le luci o tapparelle di una stanza o categoria | Accensione / spegnimento, salita / discesa — nessuna uscita |
| Scenario | Uno scenario | Qualsiasi messaggio lo esegue — nessuna uscita |
| Input Target | — | Aggiunge il nome della destinazione a un messaggio (vedere «Il nodo Input Target») |
Come i nodi raggiungono il server. Il Node-RED del server include un sottoflusso Hypervisu già inserito in una scheda di flusso, accanto ai nodi che instradano i messaggi da e verso i nodi di dispositivo (un nodo di collegamento, un nodo Widget out e un nodo di inoltro). Il sottoflusso accede al server con un account di servizio dedicato, carica stanze, categorie, dispositivi e scenari e mantiene aperta la connessione in tempo reale. Lasciare questi nodi al loro posto: senza di essi, i nodi di dispositivo hanno elenchi vuoti e non emettono messaggi. La palette include anche un nodo Msg Forwarder: fa parte di questo instradamento ed è già posizionato — non aggiungerne un altro ai propri flussi.

⚠️ Avvertenza: i flussi operano con tutti i diritti e un nodo Global Lights o Global Shutters agisce su tutti i dispositivi corrispondenti della stanza o categoria, inclusi quelli fisici.
Aggiungere un nodo di dispositivo
Requisiti: servizio Node-RED attivo (vedere «Node-RED» sopra), server attivato e dispositivo creato nell’area di lavoro Dispositivi.
- Nell’editor Node-RED, trascinare il nodo del tipo di dispositivo dalla categoria Hypervisu della palette nel flusso.
- Fare doppio clic sul nodo. La finestra elenca stanze, categorie e dispositivi dell’installazione.
- Scegliere Room, poi Category, quindi Widget (il dispositivo). Ogni elenco filtra il successivo. Il dispositivo deve corrispondere al tipo del nodo: un nodo Dimmer elenca solo dimmer.
- Controllare Description e l’elenco degli oggetti sottostante: mostrano gli oggetti del dispositivo con i relativi Object IDs, per verificare di aver scelto il dispositivo giusto.
- Name to display viene compilato automaticamente come «Room - Device». Modificarlo se si desidera un’altra etichetta nell’area di lavoro.
- Fare clic su Done.
- Collegare un nodo inject (o qualsiasi nodo che produca un valore) all’ingresso e un nodo debug a ogni uscita da osservare.
- Fare clic su Deploy.

Se un dispositivo appena creato non compare negli elenchi, riavviare i flussi (menu Deploy → Restart Flows), ricaricare la pagina dell’editor e riaprire la finestra.
Messaggi in ingresso e in uscita
Un messaggio a un nodo di dispositivo contiene due proprietà:
| Proprietà | Contenuto |
|---|---|
msg.inputTarget | L’oggetto del dispositivo a cui è destinato il valore, identificato per nome — ad esempio Switch On/OFF o Dimming setpoint. I nomi per ciascun nodo sono riportati in «Riferimento dei nodi» sotto. Usare un nodo Input Target per impostarlo (vedere «Il nodo Input Target»). |
msg.payload | Il valore: true / false, un numero, un testo o un oggetto RGB {"red": 255, "green": 120, "blue": 0}. |
Un messaggio emesso da un’uscita contiene il valore in msg.payload e l’Object ID dell’oggetto in msg.topic. L’uscita n corrisponde alla destinazione n dell’elenco del nodo, nello stesso ordine.
Le destinazioni di un nodo sono di due tipi:
- Comandi (Switch On/OFF, Dimming setpoint, Up/Down output…) — l’invio comanda il dispositivo, esattamente come un tocco nell’app.
- Riscontri (Feedback, Status feedback, Actual setpoint, Temperature…) — lo stato comunicato dal dispositivo. Una scrittura da un flusso aggiorna il valore mostrato da HyperVisu; non viene inviato nulla al dispositivo.
Quando si attivano le uscite:
| Uscita di una… | Si attiva quando |
|---|---|
| Destinazione di comando | il flusso invia quella destinazione (il valore esce subito); l’app, uno scenario, un’automazione o un altro flusso comanda il dispositivo — solo quando il valore cambia. |
| Destinazione di riscontro | il dispositivo comunica un valore — ogni volta, anche quando si ripete. |
ℹ️ Nota: i nomi distinguono maiuscole e minuscole. Un messaggio con nome sconosciuto, o senza
msg.inputTargetsu un nodo che lo richiede, viene ignorato senza errore — ad esempioSwitch ON/OFFanzichéSwitch On/OFF.
Node-RED come driver di dispositivo
Node-RED può gestire un dispositivo per il quale HyperVisu non dispone di un protocollo:
- Creare un dispositivo virtuale del tipo corretto (vedere «Dispositivi virtuali» sopra).
- Aggiungerne il nodo a un flusso. Collegare le uscite di comando ai nodi che comunicano con il dispositivo reale (HTTP, MQTT, seriale…).
- Riportare le risposte del dispositivo reale nel nodo, tramite un nodo Input Target impostato sulla destinazione di riscontro corrispondente.
I residenti usano il dispositivo nelle app come di consueto; il flusso trasmette i comandi e restituisce lo stato.

Il nodo Input Target
Il nodo Input Target imposta msg.inputTarget da un elenco, evitando di dover digitare i nomi.
- Trascinare un nodo Input Target tra la sorgente del valore e il nodo di dispositivo.
- Fare doppio clic su di esso.
- In Widget, scegliere il tipo di dispositivo (Dimmer, Shutter/Blind, Audio…).
- In Input, scegliere la destinazione. L’elenco mostra le destinazioni di quel tipo nell’ordine delle uscite del nodo di dispositivo.
- Compilare facoltativamente Name. Senza nome, il nodo mostra il nome della destinazione nell’area di lavoro.
- Fare clic su Done, quindi su Deploy.

Il nodo inoltra ogni messaggio aggiungendo msg.inputTarget e mostra sotto di sé l’ultimo valore: un punto verde con Value: …, oppure un anello rosso con No input target selected quando Input è vuoto. Un nodo di dispositivo è normalmente preceduto da più nodi Input Target, uno per ogni destinazione utilizzata.
💡 Suggerimento: in un nodo function, impostare direttamente la stessa proprietà —
msg.inputTarget = "Dimming setpoint"; msg.payload = 40; return msg;. Una funzione può quindi inviare più destinazioni in sequenza connode.send().
Riferimento dei nodi
Ogni voce elenca le destinazioni nell’ordine delle uscite. C = comando, F = riscontro. Gli esempi provengono da un flusso di prova su dispositivi virtuali: nodi inject a sinistra, nodi Input Target al centro, il nodo di dispositivo e un nodo debug per uscita a destra.
Importare un esempio
Ogni esempio seguente è disponibile come file da importare nel proprio Node-RED. I nodi di dispositivo di questi file non sono associati ad alcun dispositivo: nel nome mostrano «(set device)».
- Scaricare il file di esempio.
- Nell’editor Node-RED, aprire il menu principale (☰) e scegliere Import.
- Fare clic su select a file to import e scegliere il file, oppure incollarne il contenuto nella finestra.
- Scegliere current flow o new flow, fare clic su Import, quindi sull’area di lavoro per posizionare il gruppo.
- Fare doppio clic sul nodo di dispositivo e scegliere Room, Category e Widget della propria installazione (vedere «Aggiungere un nodo di dispositivo»). Per Global Lights e Global Shutters, scegliere una stanza o categoria; per Scenario, uno scenario. Fare clic su Done.
- Fare clic su Deploy.
⚠️ Avvertenza: i nodi inject di un esempio comandano il dispositivo non appena vengono cliccati. Associare prima gli esempi a un dispositivo di prova o virtuale e impostare il dispositivo prima del rilascio — un nodo senza dispositivo si limita a registrare errori.
Pulsante
| Ingresso | Uscita |
|---|---|
Qualsiasi messaggio — msg.inputTarget e msg.payload non sono necessari | 1 · il valore inviato, ogni volta che viene usato il pulsante (app, scenario o flusso), una volta ricevuto dal server |
Il sottotipo del dispositivo determina il valore: ON invia true, OFF invia false, Toggle invia l’opposto dell’ultimo valore.

Interruttore luce e interruttore
| # | Destinazione | Tipo | Valore |
|---|---|---|---|
| 1 | Switch On/OFF | C | true / false |
| 2 | Feedback | F | true / false |


Uscita analogica
| Ingresso | Uscita |
|---|---|
Un numero in msg.payload, nell’intervallo del dispositivo; msg.inputTarget è facoltativo (Analog Output) | 1 · Comando — il valore, ogni volta che il dispositivo viene comandato (app, scenario, automazione o flusso) |

Tapparella / veneziana
| # | Destinazione | Tipo | Valore |
|---|---|---|---|
| 1 | Up/Down output | C | false = salita, true = discesa |
| 2 | Stop output | C | true = arresto |
| 3 | Blind Position input | F | posizione 0–100 % |
| 4 | Blind Position output | C | posizione 0–100 % |
| 5 | Moving Up input | F | true durante la salita |
| 6 | Moving Down input | F | true durante la discesa |
| 7 | Slat Position input | F | angolo delle lamelle 0–100 % |
| 8 | Slat Position output | C | angolo delle lamelle 0–100 % |
Le posizioni seguono la regola di HyperVisu: 100 % indica la chiusura completa. Le destinazioni delle lamelle esistono solo sulle tapparelle con lamelle. Le uscite 1 e 2 si attivano a ogni comando, anche quando il valore si ripete.

Regolatore di temperatura
| # | Destinazione | Tipo | Valore |
|---|---|---|---|
| 1 | Setpoint | C | °C |
| 2 | Temperature | F | temperatura misurata, °C |
| 3 | Actual setpoint | F | °C |
| 4 | Mode Selection | C | numero di modalità: 1 Comfort, 2 Standby, 3 Notte |
| 5 | Actual mode | F | numero di modalità |

Dimmer
| # | Destinazione | Tipo | Valore |
|---|---|---|---|
| 1 | Switch On/OFF | C | true / false |
| 2 | Status feedback | F | true / false |
| 3 | Dimming setpoint | C | 0–100 % |
| 4 | Dimming feedback | F | 0–100 % |

Dimmer RGB
| # | Destinazione | Tipo | Valore |
|---|---|---|---|
| 1 | Switch On/OFF | C | true / false |
| 2 | Status feedback | F | true / false |
| 3 | RGB setpoint | C | {"red": 0–255, "green": 0–255, "blue": 0–255} |
| 4 | RGB feedback | F | stesso formato |

Dimmer per bianco regolabile
| # | Destinazione | Tipo | Valore |
|---|---|---|---|
| 1 | Switch On/OFF | C | true / false |
| 2 | Status feedback | F | true / false |
| 3 | Dimming setpoint | C | luminosità 0–100 % |
| 4 | Dimming feedback | F | luminosità |
| 5 | Temperature setpoint | C | temperatura di colore, nell’intervallo dell’oggetto del dispositivo |
| 6 | Temperature feedback | F | temperatura di colore |

Ingresso analogico e ingresso digitale
| Nodo | Ingresso | Uscita |
|---|---|---|
| Analog Input | Un numero in msg.payload, nell’intervallo del dispositivo; msg.inputTarget facoltativo (Analog Input) | 1 · il valore, ogni volta che il dispositivo ne comunica uno |
| Digital Input | true / false; msg.inputTarget facoltativo (Digital Input) | 1 · lo stato, ogni volta che il dispositivo ne comunica uno |
Si tratta di misure: un valore scritto da un flusso viene emesso dall’uscita solo dopo che il server lo ha memorizzato, non quando il flusso lo invia.


Ingresso testo
| Ingresso | Uscita |
|---|---|
Un testo in msg.payload; msg.inputTarget facoltativo (Text) | 1 · il testo, ogni volta che cambia sul server |
Il nodo accetta testi da un flusso solo per un dispositivo di testo VIRTUAL. Su KNX, un testo (DPT 16) contiene al massimo 14 caratteri.

Allarme
| # | Destinazione | Tipo | Valore |
|---|---|---|---|
| 1 | Arm Command | C | invia sempre true, indipendentemente dal contenuto del messaggio |
| 2 | Partial Arm Command | C | invia sempre true |
| 3 | Disarm Command | C | invia sempre true |
| 4 | Armed Status | F | true / false |
| 5 | Partial Armed Status | F | true / false |
| 6 | Disarmed Status | F | true / false |
| 7 | Alarm Status | F | true quando scatta l’allarme |
Non viene richiesto il PIN, anche quando l’allarme è protetto da un PIN.

Audio
| # | Destinazione | Tipo | Valore |
|---|---|---|---|
| 1 | Volume setpoint | C | 0–100 |
| 2 | Volume feedback | F | 0–100 |
| 3 | Zone On/Off | C | true / false |
| 4 | Zone feedback | F | true / false |
| 5 | Mute On/Off | C | true / false |
| 6 | Mute feedback | F | true / false |
| 7 | Play/Stop | C | true = riproduzione, false = arresto |
| 8 | Play/Stop feedback | F | true / false |
| 9 | Source selection | C | numero della sorgente |
| 10 | Source feedback | F | numero della sorgente |
| 11 | Previous/Next | C | false = precedente, true = successivo |
| 12 | Track Title | F | testo |
| 13 | Track Artist | F | testo |
L’uscita 11 si attiva a ogni pressione, anche quando il valore si ripete.

Ventilazione
| # | Destinazione | Tipo | Valore |
|---|---|---|---|
| 1 | Auto On/Off | C | true / false |
| 2 | Auto feedback | F | true / false |
| 3 | Slow On/Off | C | true / false |
| 4 | Slow feedback | F | true / false |
| 5 | Medium On/Off | C | true / false |
| 6 | Medium feedback | F | true / false |
| 7 | High On/Off | C | true / false |
| 8 | High feedback | F | true / false |
| 9 | Boost | C | true / false |
| 10 | Boost feedback | F | true / false |

Climatizzazione
| # | Destinazione | Tipo | Valore |
|---|---|---|---|
| 1 | On/Off | C | true / false |
| 2 | On/Off feedback | F | true / false |
| 3 | Heating Mode | C | true |
| 4 | Heating feedback | F | true / false |
| 5 | Cooling Mode | C | true |
| 6 | Cooling feedback | F | true / false |
| 7 | Auto Mode | C | true |
| 8 | Auto feedback | F | true / false |
| 9 | Setpoint | C | °C |
| 10 | Actual setpoint | F | °C |
| 11 | Temperature | F | temperatura misurata, °C |


Serratura
| # | Destinazione | Tipo | Valore |
|---|---|---|---|
| 1 | Lock/Unlock | C | true = bloccare, false = sbloccare |
| 2 | Feedback | F | true / false |

Contatore
| # | Destinazione | Tipo | Valore |
|---|---|---|---|
| 1 | Power/Flow | F | numero (W, oppure portata per acqua e gas) |
| 2 | Energy/Volume | F | numero (kWh, oppure volume) |
| 3 | Exported Energy | F | numero (kWh) |
| 4 | State Of Charge | F | numero (%) |
Senza msg.inputTarget, il valore viene inviato a Power/Flow. Un contatore ha solo gli oggetti del proprio ruolo (vedere «Panoramica dei tipi di widget»): un contatore di rete non ha stato di carica. Un valore scritto da un flusso viene emesso dall’uscita dopo che il server lo ha memorizzato.

Caricatore
| # | Destinazione | Tipo | Valore |
|---|---|---|---|
| 1 | Start/Stop | C | true = avvio, false = arresto |
| 2 | Charging | F | true / false |
| 3 | Charging Current | C | A |
| 4 | Connected | F | true quando è collegato un veicolo |
| 5 | Error | F | true / false |
| 6 | Actual Power | F | W |
| 7 | Last Energy | F | kWh dell’ultima sessione |
| 8 | Last duration | F | durata dell’ultima sessione |

Global Lights, Global Shutters e Scenario
| Nodo | Nella finestra | Ingresso | Uscita |
|---|---|---|---|
| Global Lights | Room o Category (scegliendone uno si svuota l’altro) | msg.inputTarget = On o Off; il contenuto del messaggio viene ignorato | — |
| Global Shutters | Room o Category | msg.inputTarget = Up o Down | — |
| Scenario | Scenario | Qualsiasi messaggio esegue lo scenario | — |
I nodi globali inviano lo stesso comando dei pulsanti globali dell’app: tutte le luci o tutte le tapparelle della stanza o categoria.


ℹ️ Nota: quando si riapre un nodo Global Lights o Global Shutters, entrambi gli elenchi mostrano un valore — l’elenco Category mostra semplicemente la prima voce. Il nodo agisce sull’elenco modificato per ultimo: qui la stanza, come indica il suo nome. Per passare a una categoria, selezionarla in Category (la stanza viene quindi svuotata).