HyperVisu apre un socket TCP separato per ciascun oggetto?

No. Tutti gli oggetti associati a una connessione condividono un unico socket TCP persistente, garantendo la compatibilità con i dispositivi che accettano un solo client.

Perché un oggetto in ingresso non riceve mai alcun valore?

La chiave configurata deve essere presente nel frame di risposta ed è necessario un pattern di corrispondenza per estrarre il valore. Verificare entrambi i parametri nella documentazione dei comandi del dispositivo.

Come si configura un dispositivo che invia autonomamente il proprio stato?

Impostare l'intervallo di polling su 0 e lasciare vuoti i template di interrogazione non necessari. Per le trasmissioni UDP non sollecitate, configurare il campo Listen port.

Perché alcuni comandi vengono ignorati?

Verificare la struttura del frame nell'anteprima Frame sent, considerando che visualizza un valore di esempio e non l'invio reale. Aumentare il parametro Delay between commands se il dispositivo scarta richieste consecutive troppo ravvicinate.

Qual è la funzione del pulsante Test quando la connessione TCP è già attiva?

Mostra lo stato operativo corrente e i frame scambiati invece di aprire un secondo socket, evitando il rifiuto della connessione da parte di dispositivi a client singolo.

Integrazione TCP/UDP

Il protocollo TCP/UDP è dedicato ai dispositivi che utilizzano un linguaggio di comando semplice direttamente su un socket di rete, senza API web né modello a registri: lettori e matrici audio professionali (AUDAC XMP44 e moduli SourceCon), proiettori (PJLink), display e amplificatori collegati a bridge RS-232-over-IP, oltre a schede a microcontrollore personalizzate. È possibile definire i frame di comando inviati da HyperVisu alla variazione di un valore, i pattern per estrarre i dati dai frame di risposta inviati dal dispositivo e i frame di interrogazione opzionali per il polling. Tutte le specifiche del dispositivo sono gestite nella configurazione, senza richiedere logiche dedicate nel server.

Ogni connessione corrisponde a un dispositivo, su TCP (una connessione persistente, mantenuta attiva e riconnessa automaticamente) o UDP (datagrammi). Con TCP, tutti gli oggetti associati al dispositivo condividono lo stesso socket, come richiesto dai dispositivi che supportano un solo client attivo (es. AUDAC XMP44).

Requisiti: indirizzo IP e porta del dispositivo, documentazione dei comandi (sintassi dei frame, delimitatore, elenco dei comandi e risposte) e modalità di trasmissione (se invia le variazioni di stato in modo autonomo o richiede interrogazioni periodiche).

Connessioni. Il driver TCP/UDP supporta più connessioni: una connessione per dispositivo (vedere "Connessioni"). Campi:

Campo	Descrizione
Device address	Indirizzo IP o hostname del dispositivo.
Port	Porta TCP o UDP su cui il dispositivo è in ascolto (AUDAC XMP44: `5001`).
Poll Interval (seconds)	Intervallo di interrogazione del dispositivo. `0` per dispositivi che inviano lo stato in modo autonomo.
Transport	TCP · persistent connection o UDP · datagrams.
Frame delimiter	Separatore tra due frame — `\r\n` per la maggior parte dei protocolli di testo.
Payload encoding	ASCII text per protocolli testuali, HEX bytes per protocolli binari.
Listen port	Solo UDP. Per dispositivi che trasmettono verso una porta fissa; se lasciato vuoto, le risposte arrivano sulla porta di origine del server.
Heartbeat frame / Every	Solo TCP, opzionale. Frame inviato in caso di inattività per evitare la chiusura della connessione da parte del dispositivo (minimo ogni 5 s); l'anteprima Frame sent mostra i caratteri di controllo.
Connect timeout	Tempo massimo di attesa per l'accettazione della connessione da parte del dispositivo (ms, predefinito 5000).
Delay between commands	Molti dispositivi scartano comandi troppo ravvicinati; aumentare questo valore se alcuni comandi vengono ignorati (ms, predefinito 50).
Read everything on connect	Attivo: HyperVisu invia tutte le interrogazioni non appena il dispositivo risponde, visualizzando lo stato reale senza attendere il primo ciclo di polling.

La finestra Add connection richiede i campi Instance Name, Device address, Port, Poll Interval (seconds), Transport e Frame delimiter (valori predefiniti 30, TCP · persistent connection e \r\n). Gli altri parametri si trovano in Framing and timing sulla connessione salvata: selezionare la nuova connessione, configurarli e fare clic su Save connection.

Il pulsante Test nella finestra Add connection apre un socket verso l'indirizzo inserito per verificare la raggiungibilità di rete del dispositivo (non la corretta interpretazione dei frame). Su una connessione salvata, mentre il servizio mantiene attiva la connessione al dispositivo, Test restituisce lo stato in tempo reale e il conteggio dei frame in ingresso e in uscita, evitando di aprire un secondo socket.

Associazione di un oggetto (vedere "Associazione TCP/UDP" sotto). Per ciascun oggetto è necessario indicare una Key (chiave): un testo breve presente in tutte le risposte contenenti tale valore. Solo i frame in ingresso che includono la chiave vengono confrontati con il pattern di corrispondenza dell'oggetto (per AUDAC, il comando di feedback: OG1, FREQ2). Il confronto fa distinzione tra maiuscole e minuscole e la chiave non può contenere il carattere :. Più oggetti possono condividere la stessa chiave, ad esempio un oggetto di comando e il rispettivo oggetto di stato. Il sistema memorizza la stringa <connessione>:<chiave>. Il resto corrisponde alla stringa del tipo di dati dell'oggetto, generata dai campi dell'editor:

Campo	Memorizzato come	Significato
Payload encoding	`ASCII` / `HEX`	Primo elemento della stringa. Non modifica i dati inviati né l'interpretazione delle risposte: la codifica di riferimento è quella della connessione, in Framing and timing.
Command template	`SEND=`	Inviato alla variazione del valore (oggetti Out e In/Out). `${value}` viene sostituito con il valore effettivo.
Different commands for ON and OFF → Command for ON / Command for OFF	`SEND1=` / `SEND0=`	Per oggetti booleani controllati da due comandi distinti (`SPPLAY1` / `SPSTOP1`) anziché da un comando singolo con parametro 0/1. Lasciare OFF vuoto per pulsanti a impulso singolo.
Query template	`POLL=`	Inviato a ogni ciclo di polling e all'avvio della connessione (oggetti In e In/Out). Lasciare vuoto per dispositivi con invio autonomo dello stato.
Match pattern	`MATCH=`	Applicato a ogni frame in ingresso contenente la chiave; il valore estratto aggiorna l'oggetto. Senza questo pattern, un oggetto in ingresso non riceverà alcun valore.
Scale / Offset	`SCALE=` / `OFFSET=`	Lettura: valore = grezzo × scala + offset; per la scrittura viene applicata la formula inversa. Solo per valori numerici.
Acknowledge pattern / Acknowledge timeout (ms)	`ACK=` / `ACKTIMEOUT=`	Opzionale. Se impostato, la scrittura è considerata riuscita solo se un frame soddisfa il pattern entro il timeout specificato (predefinito 2000 ms).

I template utilizzano ${value}, oltre a ${value:d} per arrotondare un valore scalato a un numero intero (es. cursore 0–100 % per dispositivi che accettano solo argomenti interi), ${value:02d} per numeri interi completati con zeri iniziali e ${value:1f} per un numero fisso di decimali. In modalità HEX sono supportati ${value:u8}, ${value:u16be}, ${value:u16le}, ${value:u32be}, ${value:u32le} per byte a lunghezza fissa. \r, \n, \t e \xNN sono sequenze di escape per i byte. In modalità ASCII, se il template non include il delimitatore, questo viene aggiunto automaticamente.

I pattern di corrispondenza utilizzano i seguenti identificatori (tutti gli altri caratteri sono confrontati letteralmente):

Identificatore	Funzione
`\v`	un numero
`\h`	valore esadecimale, convertito in numero
`\a`	testo, fino al carattere letterale successivo nel pattern (per oggetti testo)
`\iTesto\i`	ignora il testo fino a "Testo"
`\sN`	salta N caratteri
`\d` `\w` `\.`	una cifra / una parola / qualsiasi carattere

L'editor mostra l'anteprima Frame sent con i caratteri di controllo visibili (# | D001 | hv | SOG1 | 28 | U | <CR><LF>) e la stringa memorizzata. Frame sent è una semplice anteprima: ogni ${value…} viene sostituito con il valore di prova 28, senza applicare formattazione o scalatura; per oggetti con comandi ON/OFF separati, viene visualizzato solo il comando ON. Non include il delimitatore aggiunto automaticamente dal server in modalità ASCII. Verificare sempre la corretta corrispondenza dei comandi e delle risposte con il dispositivo reale.

Editor dell'oggetto TCP/UDP per la regolazione del guadagno audio.

Comportamenti operativi

Direzione. Gli oggetti In verificano la corrispondenza dei pattern (ed eseguono il polling se è presente un template di interrogazione); gli oggetti Out inviano comandi; gli oggetti In/Out gestiscono entrambe le funzioni — l'eco inviato dal dispositivo funge da conferma, come per gli oggetti di stato KNX.
Un frame, più oggetti. Ogni frame in ingresso viene verificato su tutti gli oggetti in ingresso della connessione che contengono la relativa chiave; un singolo frame di stato può quindi aggiornare più oggetti contemporaneamente. Template di interrogazione identici vengono inviati una sola volta per ciclo di polling.
TCP. In caso di disconnessione, i tentativi di riconnessione avvengono con intervalli crescenti; alla riconnessione le interrogazioni vengono eseguite nuovamente se l'opzione Read everything on connect è attiva. I frame in uscita vengono gestiti tramite una coda distanziata dal valore impostato in Delay between commands.
UDP. Ogni datagramma corrisponde a un frame. L'invio autonomo di dati da parte del dispositivo richiede l'impostazione del campo Listen port.
I comandi inviati mentre il dispositivo non è raggiungibile falliscono senza bloccare il sistema; l'applicazione continua a mostrare l'ultimo stato noto.

Esempio pratico — Lettore multimediale AUDAC XMP44

Il lettore XMP44 è in ascolto sulla porta TCP 5001, accetta un solo client e utilizza frame con struttura # | D001 | <source> | <command> | <argument> | <checksum> | <CR><LF> (il carattere U è accettato come checksum generico). L'impostazione del guadagno di uscita utilizza SOG1 | <arg> con arg = 8 − dB; il dispositivo risponde con un frame di aggiornamento … | OG1 | <arg> | …, inviato anche in caso di modifica manuale dal pannello frontale. I comandi di riproduzione e arresto sono distinti (SPPLAY1, SPSTOP1).

Creare una connessione TCP/UDP (vedere "Connessioni"): indirizzo 192.168.1.60, porta 5001, trasporto TCP, delimitatore \r\n, intervallo di polling 30. Fare clic su Test, quindi su Create connection. Selezionare la nuova connessione e, nella sezione Framing and timing, mantenere attivo Read everything on connect e impostare l'heartbeat # | D001 | hv | GTPS | 0 | U | \r\n ogni 120 s. Fare clic su Save connection.
In Devices, aggiungere un widget Audio "XMP44 player" e selezionare questa connessione in Protocol.
Sull'oggetto volume (In/Out): chiave OG1, template di comando # | D001 | hv | SOG1 | ${value:d} | U | \r\n, template di interrogazione # | D001 | hv | GOG1 | 0 | U | \r\n, pattern di corrispondenza \i | OG1 | \i\v, scala -1, offset 8 — in questo modo il valore −20 dB viene inviato come 28 e un valore ricevuto pari a 28 viene interpretato come −20 dB.
Sull'oggetto play (Out, booleano): chiave PLAY1, attivare Different commands for ON and OFF: ON # | D001 | hv | SPPLAY1 | 0 | U | \r\n, OFF # | D001 | hv | SPSTOP1 | 0 | U | \r\n.
Sull'oggetto track title (In, testo): chiave SON1, template di interrogazione # | D001 | hv | GSON1 | 0 | U | \r\n, pattern di corrispondenza \i | SON1 | \i\a | .
Fare clic su Save object per ciascun oggetto, quindi su Apply changes nella barra laterale e confermare. Lo spostamento del cursore del volume invia SOG1, la risposta OG1 del dispositivo conferma il nuovo livello e qualsiasi regolazione effettuata dal pannello frontale si riflette nell'applicazione.

💡 Suggerimento: Consultare la documentazione dei comandi del dispositivo durante l'associazione: la chiave corrisponde al nome del feedback (OG1), che sui dispositivi AUDAC differisce dal comando di scrittura (SOG1).

Associazione TCP/UDP

Gli oggetti TCP/UDP vengono configurati nella finestra delle impostazioni dell'oggetto (vedere "Impostazioni oggetto, registrazione e notifiche"). Le sezioni disponibili sono:

Frame addressing

Campo Descrizione

Key Testo presente in tutte le risposte contenenti il valore di questo oggetto (es. OG1). Solo i frame in ingresso contenenti la chiave vengono elaborati con il pattern di corrispondenza; il confronto fa distinzione tra maiuscole e minuscole. Il carattere : non è consentito. La chiave può essere condivisa tra più oggetti (es. oggetto di comando e relativo oggetto di stato). L'indirizzo memorizzato è <connessione>:<chiave>.

Payload encoding ASCII text per protocolli testuali, HEX bytes per protocolli binari.

Campo	Descrizione
Key	Testo presente in tutte le risposte contenenti il valore di questo oggetto (es. `OG1`). Solo i frame in ingresso contenenti la chiave vengono elaborati con il pattern di corrispondenza; il confronto fa distinzione tra maiuscole e minuscole. Il carattere `:` non è consentito. La chiave può essere condivisa tra più oggetti (es. oggetto di comando e relativo oggetto di stato). L'indirizzo memorizzato è `<connessione>:<chiave>`.
Payload encoding	ASCII text per protocolli testuali, HEX bytes per protocolli binari.

Commands sent (oggetti in uscita)

Campo	Descrizione
Command template	Inviato alla variazione del valore. `${value}` viene sostituito con il valore (`${value:d}` lo arrotonda a un numero intero); `\r`, `\n`, `\xNN` sono sequenze di escape per i byte.
Different commands for ON and OFF	Oggetti booleani: mostra i campi Command for ON e Command for OFF per dispositivi che utilizzano due comandi separati anziché un singolo comando con parametro 0/1. Lasciare OFF vuoto per pulsanti a impulso singolo.
Acknowledge pattern / Acknowledge timeout (ms)	Opzionale. Se impostato, la scrittura è considerata riuscita solo se un frame soddisfa questo pattern entro il timeout indicato.

Values read back (oggetti in ingresso)

Campo	Descrizione
Query template	Inviato a ogni ciclo di polling e all'avvio della connessione. Lasciare vuoto per dispositivi che trasmettono lo stato in modo autonomo.
Match pattern	Applicato a ogni frame in ingresso contenente la chiave; il valore estratto aggiorna l'oggetto. Identificatori: `\v` numero · `\h` esadecimale convertito in numero · `\a` testo fino al carattere letterale successivo · `\iTesto\i` salta fino a "Testo" · `\sN` salta N caratteri · `\d` `\w` `\.` cifra / parola / qualsiasi carattere. Senza un pattern di corrispondenza l'oggetto non riceve alcun valore.
Scale / Offset	Lettura: valore = grezzo × scala + offset; per la scrittura viene applicata la formula inversa.

Sotto le sezioni, il riquadro Frame sent mostra l'anteprima del frame in uscita per un valore di prova con i caratteri di controllo visibili (… | 28 | U | <CR><LF>), mentre Stored as indica la stringa del tipo di dati che verrà salvata. I dettagli sulla sintassi dei pattern, i template e l'esempio AUDAC sono descritti nella sezione precedente.

Impostazioni dell'oggetto TCP/UDP per la regolazione del guadagno audio.

Integrazione TCP/UDP