Packet Parser (HTTP, TCP, UDP, FTP, MQTT)

Configurazione manuale

Configurare il Packet Parser di TapHome per connettere dispositivi di terze parti tramite protocolli TCP/IP inclusi HTTP, TCP, UDP, FTP e MQTT.

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

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

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

Protocolli supportati

  • HTTP
  • TCP
  • UDP
  • FTP
  • MQTT

HTTP

SENDHTTPREQUEST

Invia una richiesta HTTP con parametri specificati, attende la risposta e la restituisce come stringa JSON con i valori Content, Headers e codice di stato HTTP. La funzione è supportata solo negli script Packet parser con protocollo HTTP.

1
2

SENDHTTPREQUEST( path, method, body, header1, header2… )
SENDHTTPREQUEST( HttpRequest )

Esempi:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

SENDHTTPREQUEST("/getValue")		Risultato:
{
  "Headers": [
    {
      "Key": "Content-Type",
      "Value": ["application/json"]
    },
    {
      "Key": "Content-Length",
      "Value": ["1007"]
    }
  ],
  "Content": "{\"value\":31}",
  "ReasonPhrase": "OK",
  "StatusCode": 200,
  "IsSuccess": true
}

1

SENDHTTPREQUEST("/doSomething", "POST", "someData", "header1:value1", "header2:value2", "header3:value3")

1
2
3
4
5
6
7
8
9

VAR request := HTTPREQUEST("/path", "PUT", "someData");
request.Headers := { "name1: value1", "name2: value2" … };
request.Method := "POST";
VAR response := SENDHTTPREQUEST(request);

IF response.IsSuccess
  VAR content := response.Content;
  …
END

TCP, UDP

SENDDATA

Invia i dati specificati (stringa o Collection) utilizzando il protocollo TCP o UDP. Se i dati sono una stringa, vengono implicitamente convertiti in byte utilizzando la codifica iso-8859-1. La funzione è supportata solo negli script Packet parser con protocollo TCP o UDP. I byte ricevuti possono essere elaborati nello script Listener.

1

SENDDATA( string/Collection<UInt8> )

Esempi:

1
2

SENDDATA(BYTECOLLECTION("0a dd ef a2"))
SENDDATA("{\"value\":212}")

COMPLETESERVICEATTRIBUTE

La funzione viene utilizzata negli script Listener nel Packet parser con protocollo TCP/UDP per notificare il completamento della lettura del valore di un attributo di servizio. Ad es. crei una richiesta nello script dell’attributo di servizio usando la funzione SENDDATA e, dopo aver ricevuto i dati nello script Listener, completi la lettura dell’attributo di servizio.

1

COMPLETESERVICEATTRIBUTE( attributeName, value, error )

Esempi:

1
2

COMPLETESERVICEATTRIBUTE("Uptime", "2d:21h:43m")
COMPLETESERVICEATTRIBUTE("Status", "", "Device is offline")

COMPLETESERVICEACTION

La funzione viene utilizzata negli script Listener nel Packet parser con protocollo TCP/UDP per notificare il completamento della richiesta di un’azione di servizio. Ad es. crei una richiesta nello script dell’azione di servizio usando la funzione SENDDATA e, dopo aver ricevuto i dati nello script Listener, completi l’azione di servizio.

1

COMPLETESERVICEACTION( actionName, result )

Esempi:

1
2

COMPLETESERVICEACTION("Reboot", "Rebooted successfully")
COMPLETESERVICEACTION("Enable cloud", "Device is offline")

FTP

FTPDOWNLOAD

Restituisce i dati del file (come Collection) dal server FTP. La funzione è supportata solo negli script Packet parser con protocollo FTP.

1

FTPDOWNLOAD( pathToFile )

Esempi:

1

FTPDOWNLOAD("/path/to/file")		(Result is Collection<UInt8>)

FTPUPLOAD

Carica dati (Collection o stringa) in un file sul server FTP.

1

FTPUPLOAD( pathToFile, data, mode )

Esempi:

1
2

FTPUPLOAD("/path/to/file", "some data", "write")
FTPUPLOAD("/path/to/file", BYTECOLLECTION("a7 ff e2"), "append")

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. 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

La funzione viene utilizzata sui dispositivi Packet Parser con protocollo MQTT per pubblicare un messaggio sul broker MQTT.

1

MQTTPUBLISH( topic, message )

Esempi:

1

MQTTPUBLISH("shellies/deviceid/relay/0/command", "off")

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 pacchetto ricevuto si trova nella variabile (struttura) RECEIVEDMSG. I dati ricevuti possono essere letti nella variabile RECEIVEDMSG.Payload. Il Payload ha tipo di dato BLOB (oggetto binario di grandi dimensioni), non è una stringa né un array di byte. Se il payload è di tipo stringa, deve essere utilizzata la funzione TOSTRING, ma in generale il payload può essere qualsiasi cosa. RECEIVEDMSG contiene anche dati specifici del protocollo, ad es. RECEIVEDMSG.Topic per MQTT. Usare RECEIVEDMSG.TOPIC è un modo molto veloce ed efficiente per determinare il valore del Topic, a differenza del vecchio metodo in cui si usava RECEIVEDBYTES.

Miglioramenti nella versione 2024.1

Invece di:

1
2
3
4
5

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

if parsejson(jsonResponse, "Topic") = "my-topic"
  Va := todouble(parsejson(jsonResponse, "Payload"));
end

può essere scritto così:

1
2
3

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, fornisce solo le proprietà PAYLOAD e LENGTH.

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.