Configurazione manuale

Implementazione in TapHome

In TapHome, il Packet Parser è un'interfaccia hardware (Impostazioni → Hardware → Aggiungi una nuova interfaccia → Packet parser) utilizzata per collegare dispositivi di terze parti al controller. Questi dispositivi possono comunicare con l'unità di controllo utilizzando il WiFi o la LAN tramite il protocollo TCP/IP.

Il Packet Parser utilizza un linguaggio di scripting proprietario, progettato appositamente per il sistema TapHome. Questo linguaggio viene utilizzato per controllare e gestire i dispositivi collegati e la loro comunicazione con il controllore. Fare clic qui per ulteriori informazioni sul linguaggio di scripting TapHome

Gerarchia

Il sistema TapHome utilizza una struttura gerarchica per organizzare i dispositivi collegati. In questa struttura, un modulo funge da dispositivo padre e può comunicare con i dispositivi figli 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. In termini di configurazione, un Modulo definisce:

• L'indirizzo IP o il nome del dispositivo mDNS
• porta di comunicazione
• Connessione sicura: Vedere la sezione Autenticazione in Servizio del modulo
• Ignorare gli errori del certificato SSL

Dispositivo

Rappresenta un controllo o un sensore specifico nel sistema TapHome. Deve sempre far parte di un modulo per un solo genitore.

Dispositivi supportati:

• Output digitale
• Uscita analogica
• Termostato
• Selettore
• Sensore di temperatura
• Variabile
• Pulsante
• Contatore elettrico
• Interruttore
• Persiane, tende da sole, miscelatori
• Luce RGB
• Luce bianca sintonizzabile

Script di lettura e scrittura

Il controller 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, può esserci una funzione specificamente progettata per analizzare le risposte XML, un'altra per analizzare le risposte JSON e un'altra ancora per analizzare le risposte degli array di byte. Queste funzioni facilitano l'interpretazione e l'utilizzo delle informazioni ricevute nelle risposte, consentendo una comunicazione più efficiente ed efficace con il controllore e i dispositivi collegati.

TapHome definisce una serie di attributi che possono essere inclusi nel linguaggio di script:

• Lo script Initialize: viene eseguito all'avvio del dispositivo (ad esempio, dopo un riavvio dell'unità di controllo).
• Lettura script: impostazione dei valori delle variabili globali o lettura delle condizioni di errore
• script Leggi valore: script per leggere un valore specifico (variabile) da un dispositivo collegato (ad esempio, la temperatura impostata su un termostato o la temperatura misurata su un termostato).
• Scrittura di un valore: scrittura di un valore su un dispositivo collegato
• Script listener: viene eseguito alla ricezione di ciascun pacchetto. Maggiori informazioni in una sezione separata di seguito

Protocolli supportati

• HTTP

• TCP

• UDP

• FTP

• MQTT

HTTP

SENDHTTPREQUEST

Invia una richiesta HTTP con i parametri specificati, attende una risposta e restituisce la risposta come stringa JSON con valori quali Contenuto, Intestazioni, Codice risultato HTTP. La funzione è supportata solo negli script del parser Packet con protocollo HTTP.

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

Examples:

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

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

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 UInt8) utilizzando il protocollo TCP o UDP. Se i dati sono un oggetto 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 in uno script Listener.

SENDDATA( string/Collection<UInt8> )

Examples:

SENDATA(BYTECOLLECTION(“0a dd ef a2”)
SENDATA(“{\”value\”:212}”)

COMPLETESERVICEATTRIBUTE

Questa funzione viene utilizzata negli script Listener del parser di pacchetti TCP/UDP per notificare al valore del Service Attribute la fine della richiesta.
Ad esempio, si crea una richiesta in uno script Service Attribute utilizzando la funzione SENDDATA e si termina la lettura del Service Attribute quando lo script Listener riceve i dati.

COMPLETESERVICEATTRIBUTE( attributeName, value, error )

Examples:

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

COMPLETESERVICEACTION

Questa funzione viene utilizzata negli script Listener di Packet Parser con protocollo TCP/UDP per notificare il completamento di una richiesta di azione di servizio.
Ad esempio, si crea una richiesta in uno script Azione di servizio utilizzando la funzione SENDDATA e si completa l'Azione di servizio dopo che lo script Listener ha ricevuto i dati.

COMPLETESERVICEACTION( actionName, result )

Examples:

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

FTP

FTPDOWNLOAD

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

FTPDOWNLOAD( pathToFile )

Examples:

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

FTPUPLOAD

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

FTPUPLOAD( pathToFile, data, mode )

Examples:

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

MQTT

Oltre alle opzioni di comunicazione di cui 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 leggero di pubblicazione/sottoscrizione di messaggi progettato per una comunicazione efficiente e affidabile tra dispositivi in contesti 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 una nuova interfaccia → MQTT Broker. Questo modulo funge da broker tra i dispositivi di terze parti e il controllore, permettendo loro di comunicare utilizzando il protocollo MQTT. Il modulo MQTT Broker può essere eseguito autonomamente sull'unità di controllo, consentendo una comunicazione indipendente ed efficiente tra dispositivi di terze parti e il sistema TapHome.

MQTTPUBLISH

La funzione viene utilizzata sui dispositivi PacketParser con il protocollo MQTT per pubblicare un messaggio al broker MQTT.

MQTTPUBLISH( topic, message )

Examples:

MQTTPUBLISH(“shellies/deviceid/relay/0/command”, “off”)

Listener script

Lo script dell'ascoltatore viene invocato alla ricezione di ogni pacchetto, in particolare per MQTT lo script dell'ascoltatore viene invocato quando arriva un qualsiasi messaggio via MQTT il cui Argomento corrisponde al filtro Argomento impostato in TapHome; possono esserci centinaia di questi messaggi al minuto. Due cose sono importanti da menzionare:

• 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 dell'ascoltatore. Ad esempio, se si è interessati solo all'argomento a.b.c.d, il filtro deve essere a.b.c.d, non solo a.b.
• Alcuni dispositivi producono molti messaggi diversi che hanno lo stesso argomento, oppure a volte dobbiamo impostare l'argomento, ad esempio, su a.b perché siamo interessati ai messaggi a.b.c.d ma anche a.b.x.y, il che ovviamente causerà l'arrivo di messaggi con argomento a.b.k.l.m che non ci interessano. In linea di principio questo non è un problema, ma alcuni dispositivi generano vari aggiornamenti di stato o messaggi che contengono descrizioni di campi di altri messaggi (metadati), e questi possono essere lunghi centinaia di KB e arrivare relativamente di frequente, ad esempio ogni pochi secondi (ad esempio, Zigbee2MQTT).

Per le ragioni sopra menzionate, in MQTT, in uno script ascoltatore, è molto importante decidere in base al valore 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 del controllore TapHome contiene meccanismi che impediscono a MQTT di essere sommerso dai messaggi. Tuttavia, non si può escludere che un filtro di argomenti MQTT impostato in modo molto lasco e un gran numero di messaggi di grandi dimensioni non causino un aumento del tempo di risposta del controllore.

Il pacchetto ricevuto si trova nella variabile (struttura) RECEIVEDMSG. I dati ricevuti possono essere letti nella variabile RECEIVEDMSG.Payload. Il payload è di tipo BLOB (large binary object), non è una stringa o un array di byte. Se il payload è di tipo stringa, è necessario utilizzare la funzione TOSTRING, ma in generale il payload può essere qualsiasi cosa. RECEIVEDMSG contiene anche dati specifici del protocollo, ad esempio RECEIVEDMSG.Topic per MQTT. L'uso di RECEIVEDMSG.TOPIC è un modo molto veloce ed efficiente per trovare il valore dell'argomento, a differenza del vecchio modo in cui si usava RECEIVEDBYTES.

Miglioramenti nella versione 2024.1

Invece di:

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

if parsejson(jsonResponse, "Topic") = "my-topic"

	Va := todouble(parsejson(jsonResponse, "Payload"));

end

si può scrivere così:

if RECEIVEDMSG.TOPIC = "my-topic"

	Va := todouble(TOSTRING(RECEIVEDMSG.PAYLOAD));

end

In che modo è meglio: si risparmia una chiamata a PARSEJSON per scoprire il valore dell'argomento. Se arrivano molti messaggi mqtt e solo alcuni sono interessanti, è più conveniente usare questo nuovo metodo.

RECEIVEDMSG contiene inoltre valori specifici di mqtt - ad esempio CLIENTID, DUP, CONTENTTYPE, EXPIRY - il cui contenuto dipende da ciò che il server mqtt sta inviando. La vecchia sintassi funziona ancora e funzionerà.

RECEIVEDMSG funziona anche con TCP e UDP, non solo con MQTT. In questo 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 argomenti MQTT. Questo dovrebbe aiutare a debuggare gli script e impostare il filtro degli argomenti più adatto, in modo che al Core vengano consegnati il minor numero possibile di messaggi che non vengono elaborati.