TapHome

Configurare manuală

Configurați Packet Parser din TapHome pentru conectarea dispozitivelor terțe prin protocoale TCP/IP, inclusiv HTTP, TCP, UDP, FTP și MQTT.

Implementare în TapHome

În TapHome, Packet Parser este o interfață hardware (Setări → Hardware → Adăugați o nouă interfață → Packet parser) folosită pentru conectarea dispozitivelor terțe la controler. Aceste dispozitive pot comunica cu unitatea de control prin WiFi sau LAN, folosind protocolul TCP/IP.

Packet Parser folosește un limbaj de scripting propriu, creat special pentru sistemul TapHome. Acest limbaj servește la controlul și gestionarea dispozitivelor conectate și a comunicației lor cu controlerul. Faceți clic aici pentru mai multe informații despre limbajul de scripting TapHome

Ierarhie

Sistemul TapHome folosește o structură ierarhică pentru organizarea dispozitivelor conectate. În această structură, un Modul acționează ca dispozitiv părinte și poate comunica cu dispozitivele sale subordonate și le poate controla.

Modul

O interfață poate conține unul sau mai multe module, care în majoritatea cazurilor gestionează comunicația cu întregul dispozitiv fizic. Din punctul de vedere al configurării, Modulul definește:

  • Adresa IP sau numele mDNS al dispozitivului
  • Portul de comunicație
  • Conexiunea securizată: consultați secțiunea Autentificare din setările de service ale modulului
  • Ignorați erorile de certificat SSL

Dispozitiv

Reprezintă un element de comandă sau un senzor concret în sistemul TapHome. Trebuie să facă întotdeauna parte dintr-un Modul părinte.

Dispozitive acceptate:

  • Ieșire digitală
  • Ieșire analogică
  • Termostat
  • Comutator cu mai multe valori
  • Senzor de temperatură
  • Variabilă
  • Buton
  • Contor electric
  • Contact Reed
  • Jaluzele, marchize, vane de amestec
  • Lumină RGB
  • Lumină cu alb reglabil

Exemplu: Shelly Plug S Modulul conține informații despre adresa IP, are scripturi pentru citirea stării și a setărilor și pentru executarea acțiunilor de service. Include 2 dispozitive: o ieșire digitală (releu) și un contor electric care măsoară consumul dispozitivelor alimentate.

Scripturi pentru citire și scriere

Unitatea de control TapHome și dispozitivele conectate pot comunica prin cereri HTTP sau HTTPS GET / POST. Răspunsurile la aceste cereri pot fi analizate (parsate) cu un set de funcții specializate. De exemplu, poate exista o funcție concepută special pentru analiza răspunsurilor XML, o altă funcție pentru analiza răspunsurilor JSON și o altă funcție pentru analiza răspunsurilor de tip array de octeți. Aceste funcții facilitează interpretarea și utilizarea informațiilor primite în răspunsuri, ceea ce permite o comunicație mai eficientă cu unitatea de control și cu dispozitivele conectate.

TapHome definește mai multe atribute care pot conține limbaj de scripting:

  • Scriptul Initialize: rulează la pornirea dispozitivului (de ex. după repornirea unității de control)
  • Scriptul Read: setarea valorilor variabilelor globale sau citirea stărilor de eroare
  • Scriptul Read Value: script pentru citirea unei anumite valori (mărimi) de la un dispozitiv conectat (de ex. temperatura setată pe termostat sau temperatura măsurată de termostat)
  • Scriptul Write Value: scrierea valorii în dispozitivul conectat
  • Scriptul Listener: se execută la primirea fiecărui pachet. Mai multe informații în secțiunea separată de mai jos

Faceți clic aici pentru mai multe informații despre limbajul de scripting TapHome

Definirea stărilor de eroare din scripturi

Atribute și acțiuni de service

Scripturi și variabile auxiliare la nivelul modulului

Scripturi și variabile auxiliare la nivelul dispozitivului

Mai multe informații găsiți pe pagina de documentație Modbus

Protocoale acceptate

  • HTTP
  • TCP
  • UDP
  • FTP
  • MQTT

HTTP

SENDHTTPREQUEST

Trimite o cerere HTTP cu parametrii specificați, așteaptă răspunsul și returnează răspunsul ca șir JSON care conține Content, Headers și codul de rezultat HTTP. Funcția este acceptată doar în scripturile Packet parser cu protocolul HTTP.

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

Exemple:

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

SENDHTTPREQUEST("/getValue")		Rezultat:
{
  "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

Trimite datele specificate (șir sau Collection UInt8) prin protocolul TCP sau UDP. Dacă datele sunt un obiect de tip șir, sunt convertite implicit în octeți cu codificarea iso-8859-1. Funcția este acceptată doar în scripturile Packet parser cu protocolul TCP sau UDP. Octeții primiți pot fi procesați în scriptul Listener.

SENDDATA( string/Collection<UInt8> )

Exemple:

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

COMPLETESERVICEATTRIBUTE

Funcția se folosește în scripturile Listener din Packet parser cu protocolul TCP/UDP, pentru a semnala finalizarea cererii pentru valoarea unui atribut de service. De exemplu, creați o cerere în scriptul atributului de service cu funcția SENDDATA, iar după primirea datelor în scriptul Listener finalizați citirea atributului de service.

COMPLETESERVICEATTRIBUTE( attributeName, value, error )

Exemple:

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

COMPLETESERVICEACTION

Funcția se folosește în scripturile Listener din Packet parser cu protocolul TCP/UDP, pentru a semnala finalizarea cererii de acțiune de service. De exemplu, creați o cerere în scriptul acțiunii de service cu funcția SENDDATA, iar după primirea datelor în scriptul Listener finalizați acțiunea de service.

COMPLETESERVICEACTION( actionName, result )

Exemple:

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

FTP

FTPDOWNLOAD

Returnează datele fișierului (ca Collection UInt8) de pe serverul FTP. Funcția este acceptată doar în scripturile Packet parser cu protocolul FTP.

FTPDOWNLOAD( pathToFile )

Exemple:

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

FTPUPLOAD

Încarcă date (Collection UInt8 sau șir) într-un fișier pe serverul FTP.

FTPUPLOAD( pathToFile, data, mode )

Exemple:

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

MQTT

Pe lângă posibilitățile de comunicație menționate mai sus, sistemul TapHome permite și comunicația cu dispozitive terțe prin protocolul MQTT. MQTT, sau Message Queuing Telemetry Transport, este un protocol de mesagerie publish/subscribe cu consum redus de resurse, conceput pentru o comunicație eficientă și fiabilă între dispozitive în contexte machine-to-machine (M2M) și Internet of Things (IoT).

Pentru a permite comunicația cu dispozitive terțe prin MQTT, trebuie să creați un modul separat în Setări → Hardware → Adăugați o nouă interfață → MQTT Broker. Acest modul acționează ca intermediar între dispozitivele terțe și unitatea de control, permițându-le să comunice prin protocolul MQTT. MQTT Broker poate rula autonom pe unitatea de control, ceea ce permite o comunicație independentă și eficientă între dispozitivele terțe și sistemul TapHome.

MQTTPUBLISH

Funcția se folosește pe dispozitivele PacketParser cu protocolul MQTT pentru a publica un mesaj la brokerul MQTT.

MQTTPUBLISH( topic, message )

Exemple:

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

Scriptul Listener

Scriptul Listener este apelat la primirea fiecărui pachet; în cazul MQTT, scriptul Listener este apelat când sosește orice mesaj prin MQTT al cărui Topic corespunde filtrului de Topic setat în TapHome; pot exista sute de astfel de mesaje pe minut. Sunt importante două aspecte:

  • Filtrul de Topic trebuie setat cât mai restrictiv, astfel încât mesajele cu o valoare de Topic diferită să nu ajungă deloc și să nu activeze astfel scriptul Listener. De exemplu, dacă suntem interesați doar de topicul a.b.c.d, filtrul trebuie să fie a.b.c.d, nu doar a.b.

  • Unele dispozitive produc multe mesaje diferite cu același topic sau, uneori, trebuie setat topicul de exemplu la a.b, deoarece suntem interesați de mesajele a.b.c.d, dar și de a.b.x.y, ceea ce va face, desigur, ca și mesajele cu topicul a.b.k.l.m care nu ne interesează să ajungă. Acest lucru nu este o problemă în sine, dar unele dispozitive generează diverse actualizări de stare sau mesaje care conțin descrieri de câmpuri ale altor mesaje (metadate), care pot fi de sute de KB și pot sosi relativ des - la câteva secunde (de exemplu, Zigbee2MQTT).

Din motivele menționate mai sus, în MQTT, în cadrul unui script Listener, este foarte important să se decidă pe baza valorii Topic dacă este un mesaj relevant și, dacă nu, să se oprească imediat execuția scriptului fără a analiza inutil conținutul mesajului în acel moment. Algoritmul din controlerul TapHome conține mecanisme care împiedică supraîncărcarea MQTT cu mesaje. Totuși, nu se poate exclude ca un filtru de topic MQTT setat foarte larg și un număr mare de mesaje voluminoase să ducă la creșterea timpului de răspuns al controlerului.

Pachetul primit se află în variabila (structura) RECEIVEDMSG. Datele primite pot fi citite în variabila RECEIVEDMSG.Payload. Payload are tipul de date BLOB (large binary object), nu este un șir sau un array de octeți. Dacă payload-ul este de tip șir, trebuie folosită funcția TOSTRING, dar în general payload-ul poate fi orice. RECEIVEDMSG conține și date specifice protocolului, de exemplu RECEIVEDMSG.Topic pentru MQTT. Folosirea RECEIVEDMSG.TOPIC este o modalitate foarte rapidă și eficientă de a afla valoarea topicului, spre deosebire de metoda veche în care se folosea RECEIVEDBYTES.

Îmbunătățiri în versiunea 2024.1

În loc de:

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

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

se poate scrie astfel:

if RECEIVEDMSG.TOPIC = "my-topic"
  Va := todouble(TOSTRING(RECEIVEDMSG.PAYLOAD));
end

Avantajul acestei metode: se economisește un apel la PARSEJSON pentru a afla valoarea topicului. Dacă sosesc multe mesaje MQTT și doar o parte dintre ele sunt relevante, este mai avantajos să folosiți această metodă nouă.

RECEIVEDMSG conține și valori specifice MQTT - de ex. CLIENTID, DUP, CONTENTTYPE, EXPIRY - conținutul lor depinde de ceea ce trimite serverul MQTT. Sintaxa veche funcționează în continuare și va continua să funcționeze.

RECEIVEDMSG funcționează și cu TCP și UDP, nu doar cu MQTT. În acel caz, oferă doar proprietățile PAYLOAD și LENGTH.

Analiza pachetelor

Informațiile din setările de service ale modulelor Packet Parser conțin date statistice despre mesajele primite și trimise - numărul de mesaje din ultimele 5 și 30 de minute, numărul de octeți primiți, iar la MQTT informațiile sunt sortate după topicurile MQTT. Acestea ajută la depanarea scripturilor și la setarea celui mai potrivit filtru de topic, astfel încât să fie livrate cât mai puține mesaje pe care Core nu le procesează.