--- title: "Configurazione manuale" description: "Configura manualmente il Packet Parser di TapHome per integrare dispositivi HTTP, TCP, UDP, FTP e MQTT. Guida al linguaggio script." url: "https://taphome.com/it/docs/integration/packet-parser/manual/" language: it lastmod: 2026-11-06 generator: hugo ai: topics: ["packet-parser","third-party-integration","tcp-ip-protocols","mqtt","scripting","listener-script"] questions: ["Dove aggiungo un'interfaccia Packet Parser in TapHome?","Quali protocolli supporta il Packet Parser?","Come invio richieste HTTP dagli script TapHome?","Come elaboro i messaggi MQTT in arrivo nello script Listener?","Qual è il tipo di dati di RECEIVEDMSG.Payload e come lo converto?","Perché dovrei impostare il filtro topic MQTT il più restrittivo possibile?","Dove trovo le statistiche sui messaggi del Packet Parser?"] --- # Configurazione manuale Colleghi un dispositivo di terze parti aggiungendo l'interfaccia Packet Parser (Impostazioni → Hardware → Aggiungi nuova interfaccia) e script per HTTP, TCP, UDP, FTP o MQTT. Ultimo aggiornamento: 2026-11-06 Per collegare manualmente un dispositivo di terze parti in TapHome si aggiunge l'interfaccia hardware Packet Parser (Impostazioni → Hardware → Aggiungi nuova interfaccia → Packet parser) e si descrive la comunicazione nel linguaggio di scripting di TapHome tramite HTTP, TCP, UDP, FTP o MQTT. L'interfaccia contiene moduli con indirizzo IP o nome mDNS e porta, e dispositivi, ad esempio un'uscita digitale o un termostato, che leggono e scrivono valori tramite script. Serve un dispositivo di terze parti che comunichi via WiFi o LAN con il protocollo TCP/IP; per MQTT occorre inoltre un modulo MQTT Broker separato. Il risultato è un dispositivo in TapHome i cui valori i tuoi script leggono dal dispositivo fisico e scrivono su di esso. ## Implementazione in TapHome In TapHome, il Packet Parser è un'interfaccia hardware (Impostazioni → Hardware → Aggiungi nuova interfaccia → Packet parser) utilizzata per collegare dispositivi di terze parti al controller. Questi dispositivi possono comunicare con l'unità di controllo tramite WiFi o LAN utilizzando il protocollo TCP/IP. Il Packet Parser utilizza un linguaggio di scripting proprietario appositamente progettato per il sistema TapHome. Questo linguaggio viene impiegato per controllare e gestire i dispositivi collegati e la loro comunicazione con il controller. [Clicca qui per ulteriori informazioni sul linguaggio di scripting TapHome](https://taphome.com/it/docs/script/) ### Gerarchia Il sistema TapHome utilizza una struttura gerarchica per l'organizzazione dei dispositivi collegati. In questa struttura, un Modulo funge da dispositivo padre e può comunicare con i dispositivi figlio e controllarli. #### Modulo Un'interfaccia può contenere uno o più Moduli, che nella maggior parte dei casi coprono la comunicazione con l'intero dispositivo fisico. Da un punto di vista di configurazione, il Modulo definisce: - Indirizzo IP o nome mDNS di un dispositivo - Porta di comunicazione - Connessione sicura: vedi la sezione Autenticazione nelle Impostazioni di servizio di un Modulo - Ignora errori del certificato SSL #### Dispositivo Rappresenta un elemento di controllo specifico o un sensore nel sistema TapHome. Deve sempre far parte di un Modulo padre. Dispositivi supportati: - Uscita digitale - Uscita analogica - Termostato - Interruttore multivalore - Sensore di temperatura - Variabile - Pulsante - Contatore elettrico - Contatto reed - Persiane, tende da sole, valvole miscelatrici - Luce RGB - Luce bianca regolabile **Esempio: Shelly Plug S** Il Modulo contiene informazioni sull'indirizzo IP, dispone di script per leggere lo stato, le impostazioni e per eseguire azioni di servizio. Copre 2 Dispositivi: un'uscita digitale (relè) e un contatore elettrico che misura i dispositivi alimentati. ### Script per lettura e scrittura L'unità di controllo TapHome e i dispositivi collegati possono comunicare utilizzando richieste HTTP o HTTPS GET / POST. Le risposte a queste richieste possono essere analizzate utilizzando un insieme di funzioni specializzate. Ad esempio, potrebbe esserci una funzione appositamente progettata per analizzare risposte XML, un'altra funzione per analizzare risposte JSON e un'altra ancora per analizzare risposte sotto forma di array di byte. Queste funzioni rendono più semplice interpretare e utilizzare le informazioni ricevute nelle risposte, permettendo una comunicazione con l'unità di controllo e i dispositivi connessi più efficiente ed efficace. TapHome definisce molteplici attributi che possono contenere linguaggio di script: - **Script di inizializzazione:** viene eseguito all'avvio del dispositivo (es. dopo il riavvio dell'unità di controllo) - **Script di lettura:** impostazione dei valori delle variabili globali o lettura di stati di errore - **Script di lettura valore:** script per leggere un valore specifico (grandezza) da un dispositivo connesso (es. temperatura impostata sul termostato o temperatura misurata dal termostato) - **Script di scrittura valore:** scrive il valore sul dispositivo connesso - **Script listener:** viene eseguito quando viene ricevuto ogni pacchetto. Maggiori informazioni in una sezione separata più avanti [Clicca qui per ulteriori informazioni sul linguaggio di scripting TapHome](https://taphome.com/it/docs/script/) #### Definizione degli stati di errore negli script #### Attributi e azioni di servizio #### Script e variabili ausiliarie sul Modulo #### Script e variabili ausiliarie sul Dispositivo Vedi ulteriori informazioni sulla [pagina di documentazione Modbus](https://taphome.com/it/docs/integration/modbus/) ## Protocolli supportati - HTTP - TCP - UDP - FTP - MQTT ### HTTP #### SENDHTTPREQUEST Invia una richiesta HTTP in uno script Packet parser con il protocollo HTTP, attende la risposta e restituisce un oggetto `httpresponse` con `Content`, `StatusCode`, `ReasonPhrase`, `IsSuccess` e `Headers`. Una richiesta con metodo, corpo e intestazioni propri si costruisce con `HTTPREQUEST` — parametri ed esempi: [SENDHTTPREQUEST](https://taphome.com/it/docs/script/packet-parser/#sendhttprequest), [HTTPREQUEST](https://taphome.com/it/docs/script/packet-parser/#httprequest). ```taphome VAR response := SENDHTTPREQUEST("/getValue"); IF(response.IsSuccess, PARSEJSON(response.Content, "value"), NaN) ``` ### TCP, UDP #### SENDDATA Invia una stringa o una `collection` tramite TCP o UDP; la risposta del dispositivo viene elaborata nello script listener — [SENDDATA](https://taphome.com/it/docs/script/packet-parser/#senddata). #### COMPLETESERVICEATTRIBUTE Nello script listener completa la lettura di un attributo di servizio il cui script ha inviato la richiesta con `SENDDATA` — [COMPLETESERVICEATTRIBUTE](https://taphome.com/it/docs/script/packet-parser/#completeserviceattribute). #### COMPLETESERVICEACTION Nello script listener completa un'azione di servizio il cui script ha inviato la richiesta con `SENDDATA` — [COMPLETESERVICEACTION](https://taphome.com/it/docs/script/packet-parser/#completeserviceaction). ### FTP #### FTPDOWNLOAD Restituisce il contenuto di un file sul server FTP come `collection` — [FTPDOWNLOAD](https://taphome.com/it/docs/script/packet-parser/#ftpdownload). #### FTPUPLOAD Scrive o aggiunge in coda dati (una stringa o una `collection`) a un file sul server FTP — [FTPUPLOAD](https://taphome.com/it/docs/script/packet-parser/#ftpupload). ### MQTT Oltre alle opzioni di comunicazione menzionate sopra, il sistema TapHome consente anche la comunicazione con dispositivi di terze parti utilizzando il protocollo MQTT. MQTT, o Message Queuing Telemetry Transport, è un protocollo di messaggistica publish/subscribe leggero progettato per una comunicazione efficiente e affidabile tra dispositivi in contesti di machine-to-machine (M2M) e Internet of Things (IoT). Per abilitare la comunicazione con dispositivi di terze parti tramite MQTT, è necessario creare un modulo separato in Impostazioni → Hardware → Aggiungi nuova interfaccia → [MQTT Broker](https://taphome.com/it/docs/integration/packet-parser/mqtt-broker/). Questo modulo funge da intermediario tra i dispositivi di terze parti e l'unità di controllo, permettendo loro di comunicare tramite il protocollo MQTT. Il broker MQTT può essere eseguito in modo autonomo sull'unità di controllo, consentendo una comunicazione indipendente ed efficiente tra i dispositivi di terze parti e il sistema TapHome. #### MQTTPUBLISH Pubblica un messaggio sul broker MQTT da un dispositivo Packet parser con il protocollo MQTT — [MQTTPUBLISH](https://taphome.com/it/docs/script/packet-parser/#mqttpublish). ## Script listener Lo script listener viene invocato ogni volta che viene ricevuto un pacchetto; specificamente per MQTT lo script listener viene eseguito quando arriva un qualsiasi messaggio via MQTT il cui Topic corrisponde al Topic-filter impostato in TapHome; ce ne possono essere centinaia di questi messaggi al minuto. Due cose importanti da menzionare qui: - Il filtro Topic deve essere impostato nel modo più restrittivo possibile, in modo che i messaggi con un valore Topic diverso non arrivino affatto e quindi non attivino lo script listener. Ad esempio, se siamo interessati solo al topic a.b.c.d, il filtro dovrebbe essere a.b.c.d, non solo a.b. - Alcuni dispositivi producono molti messaggi differenti che hanno lo stesso topic, oppure a volte dobbiamo impostare il topic ad es. a.b perché siamo interessati ai messaggi a.b.c.d ma anche a.b.x.y, il che ovviamente farà arrivare anche messaggi con topic a.b.k.l.m che non ci interessano. Questo non è negativo di per sé, ma alcuni dispositivi generano vari aggiornamenti di stato o messaggi che contengono descrizioni di altri messaggi (metadati), e questi possono essere di centinaia di KB di lunghezza e arrivare relativamente spesso – ogni pochi secondi (ad es. Zigbee2MQTT). Per i motivi sopra menzionati, in MQTT, in uno script listener è molto importante decidere in base al valore del Topic se si tratta di un messaggio rilevante e, in caso contrario, interrompere immediatamente l'esecuzione dello script e non analizzare inutilmente il contenuto del messaggio in quel momento. L'algoritmo nel controller TapHome contiene meccanismi per impedire che MQTT venga sovraccaricato dai messaggi. Tuttavia, non si può escludere che un filtro di topic MQTT troppo permissivo e un grande numero di messaggi di grandi dimensioni possa causare un aumento del tempo di risposta del controller. Il messaggio ricevuto si trova in `RECEIVEDMSG`: `Payload` è un blob (converti il testo con `TOSTRING`), `Topic` il topic MQTT, `Protocol` il protocollo e `Length` la dimensione. Leggere `RECEIVEDMSG.Topic` è un modo veloce per decidere se un messaggio è rilevante, a differenza del più vecchio `RECEIVEDBYTES`. Tutte le proprietà ed esempi: [Script listener](https://taphome.com/it/docs/script/listener-scripts/). ### Miglioramenti nella versione 2024.1 Invece di: ```taphome VAR jsonResponse := TOSTRING(RECEIVEDBYTES); if parsejson(jsonResponse, "Topic") = "my-topic" Va := todouble(parsejson(jsonResponse, "Payload")); end ``` può essere scritto così: ```taphome if RECEIVEDMSG.TOPIC = "my-topic" Va := todouble(TOSTRING(RECEIVEDMSG.PAYLOAD)); end ``` In che modo è meglio? Evita una chiamata a PARSEJSON per scoprire qual è il valore del Topic. Se ci sono molti messaggi MQTT in ingresso e solo alcuni sono interessanti, è più comodo utilizzare questo nuovo metodo. RECEIVEDMSG contiene inoltre valori specifici di MQTT – ad es. CLIENTID, DUP, CONTENTTYPE, EXPIRY – il cui contenuto dipende da ciò che invia il server MQTT. La vecchia sintassi funziona ancora e continuerà a funzionare. `RECEIVEDMSG` funziona anche con TCP e UDP, non solo con MQTT; in tal caso contiene `Payload`, `Length` e `Protocol` (`"tcp"` o `"udp"`) — [RECEIVEDMSG](https://taphome.com/it/docs/script/listener-scripts/#receivedmsg). ## Analisi dei pacchetti Le informazioni nelle Impostazioni di servizio dei moduli Packet Parser contengono dati statistici sui messaggi ricevuti e inviati – conteggi per gli ultimi 5 e 30 minuti, numero di byte ricevuti e, per MQTT, le informazioni sono ordinate per topic MQTT. Questo dovrebbe aiutare nel debug degli script e nell'impostare il filtro di topic più adatto, per garantire che il minor numero possibile di messaggi non elaborati dal Core venga consegnato.