TapHome

Ručna konfiguracija

Konfigurirajte Packet Parser u sustavu TapHome za povezivanje uređaja trećih strana preko protokola TCP/IP, uključujući HTTP, TCP, UDP, FTP i MQTT.

Primjena u sustavu TapHome

U sustavu TapHome Packet Parser je hardversko sučelje (Postavke → Hardver → Dodajte novo sučelje → Packet parser) koje služi za povezivanje uređaja trećih strana s centralnom jedinicom. Ti uređaji mogu komunicirati s centralnom jedinicom putem WiFi mreže ili LAN-a preko protokola TCP/IP.

Packet Parser koristi vlastiti skriptni jezik razvijen posebno za sustav TapHome. Taj jezik služi za upravljanje spojenim uređajima i njihovom komunikacijom s centralnom jedinicom. Kliknite ovdje za više informacija o skriptnom jeziku TapHome

Hijerarhija

Sustav TapHome koristi hijerarhijsku strukturu za organizaciju spojenih uređaja. U toj strukturi modul djeluje kao nadređeni uređaj i može komunicirati sa svojim podređenim uređajima i upravljati njima.

Modul

Sučelje može sadržavati jedan ili više modula, koji u većini slučajeva služe za komunikaciju s cijelim fizičkim uređajem. S gledišta konfiguracije modul definira:

  • IP adresu ili mDNS naziv uređaja
  • komunikacijski port
  • sigurnu vezu: pogledajte odjeljak Ovjera u naprednim postavkama modula
  • Ignorirajte pogreške SSL certifikata

Uređaj

Predstavlja određeni upravljački element ili senzor u sustavu TapHome. Uvijek mora biti dio jednog nadređenog modula.

Podržani uređaji:

  • Digitalni izlaz
  • Analogni izlaz
  • Termostat
  • Prekidač s više vrijednosti
  • Senzori za temperaturu
  • Varijabla
  • Prekidač
  • Električno brojilo
  • Kontakt statusa
  • Rolete, tende, miješajući ventili
  • RGB svjetlo
  • Podesiva bijela svjetlost

Primjer: Shelly Plug S Modul sadrži podatke o IP adresi i ima skripte za čitanje stanja, postavki i izvođenje servisnih radnji. Pokriva 2 uređaja: digitalni izlaz (relej) i brojilo električne energije koje mjeri potrošnju priključenih uređaja.

Skripte za čitanje i upis

Centralna jedinica TapHome i spojeni uređaji mogu komunicirati pomoću zahtjeva HTTP ili HTTPS GET / POST. Odgovori na te zahtjeve mogu se raščlaniti skupom specijaliziranih funkcija. Na primjer, može postojati funkcija posebno namijenjena raščlambi XML odgovora, druga funkcija za raščlambu JSON odgovora i još jedna funkcija za raščlambu odgovora u obliku polja bajtova. Te funkcije olakšavaju tumačenje i korištenje podataka primljenih u odgovorima te omogućuju učinkovitiju komunikaciju s centralnom jedinicom i spojenim uređajima.

TapHome definira više atributa koji mogu sadržavati skripte:

  • Initialize script: pokreće se pri pokretanju uređaja (npr. nakon ponovnog pokretanja centralne jedinice)
  • Read script: postavljanje vrijednosti globalnih varijabli ili čitanje stanja pogreške
  • Read Value script: skripta za čitanje određene vrijednosti (veličine) iz spojenog uređaja (npr. zadane temperature na termostatu ili izmjerene temperature na termostatu)
  • Write Value script: upis vrijednosti u spojeni uređaj
  • Skripta slušatelja: izvršava se pri primitku svakog paketa. Više informacija nalazi se u zasebnom odjeljku u nastavku

Kliknite ovdje za više informacija o skriptnom jeziku TapHome

Definiranje stanja pogreške iz skripti

Servisni atributi i radnje

Skripte i pomoćne varijable na modulu

Skripte i pomoćne varijable na uređaju

Više informacija potražite na stranici dokumentacije za Modbus

Podržani protokoli

  • HTTP
  • TCP
  • UDP
  • FTP
  • MQTT

HTTP

SENDHTTPREQUEST

Šalje HTTP zahtjev sa zadanim parametrima, čeka odgovor i vraća ga kao JSON niz znakova s vrijednostima Content, Headers i HTTP kodom rezultata. Funkcija je podržana samo u skriptama sučelja Packet parser s protokolom HTTP.

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

Primjeri:

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

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

Šalje zadane podatke (string ili Collection UInt8) preko protokola TCP ili UDP. Ako su podaci objekt string, implicitno se pretvaraju u bajtove pomoću kodiranja iso-8859-1. Funkcija je podržana samo u skriptama sučelja Packet parser s protokolom TCP ili UDP. Primljeni bajtovi mogu se obraditi u skripti slušatelja.

SENDDATA( string/Collection<UInt8> )

Primjeri:

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

COMPLETESERVICEATTRIBUTE

Funkcija se koristi u skriptama slušatelja sučelja Packet parser s protokolom TCP/UDP za javljanje dovršetka zahtjeva za vrijednost servisnog atributa. Npr. u skripti servisnog atributa izradite zahtjev pomoću funkcije SENDDATA, a nakon primitka podataka u skripti slušatelja dovršite čitanje servisnog atributa.

COMPLETESERVICEATTRIBUTE( attributeName, value, error )

Primjeri:

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

COMPLETESERVICEACTION

Funkcija se koristi u skriptama slušatelja sučelja Packet parser s protokolom TCP/UDP za javljanje dovršetka zahtjeva za servisnu radnju. Npr. u skripti servisne radnje izradite zahtjev pomoću funkcije SENDDATA, a nakon primitka podataka u skripti slušatelja dovršite servisnu radnju.

COMPLETESERVICEACTION( actionName, result )

Primjeri:

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

FTP

FTPDOWNLOAD

Vraća podatke datoteke (kao Collection UInt8) s FTP poslužitelja. Funkcija je podržana samo u skriptama sučelja Packet parser s protokolom FTP.

FTPDOWNLOAD( pathToFile )

Primjeri:

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

FTPUPLOAD

Prenosi podatke (Collection UInt8 ili string) u datoteku na FTP poslužitelju.

FTPUPLOAD( pathToFile, data, mode )

Primjeri:

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

MQTT

Osim prethodno navedenih mogućnosti komunikacije, sustav TapHome omogućuje i komunikaciju s uređajima trećih strana pomoću protokola MQTT. MQTT (Message Queuing Telemetry Transport) je jednostavan protokol za razmjenu poruka po načelu objave i pretplate (publish/subscribe), namijenjen učinkovitoj i pouzdanoj komunikaciji među uređajima u okruženjima komunikacije stroj-stroj (M2M) i interneta stvari (IoT).

Za omogućivanje komunikacije s uređajima trećih strana pomoću protokola MQTT potrebno je izraditi zaseban modul u izborniku Postavke → Hardver → Dodajte novo sučelje → MQTT Broker. Taj modul djeluje kao posrednik između uređaja trećih strana i centralne jedinice i omogućuje im komunikaciju protokolom MQTT. MQTT Broker može raditi samostalno na centralnoj jedinici, što omogućuje neovisnu i učinkovitu komunikaciju između uređaja trećih strana i sustava TapHome.

MQTTPUBLISH

Funkcija se koristi na uređajima PacketParser s protokolom MQTT za objavu poruke na MQTT brokeru.

MQTTPUBLISH( topic, message )

Primjeri:

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

Skripta slušatelja

Skripta slušatelja poziva se pri primitku svakog paketa. Kod protokola MQTT skripta slušatelja poziva se kada preko MQTT-a stigne bilo koja poruka čija tema (Topic) odgovara filtru tema postavljenom u sustavu TapHome; takvih poruka može biti i nekoliko stotina u minuti. Ovdje je važno spomenuti dvije stvari:

  • Filtar tema treba postaviti što je moguće restriktivnije, tako da poruke s drugom vrijednošću teme uopće ne stižu i ne aktiviraju skriptu slušatelja. Na primjer, ako nas zanima samo tema a.b.c.d, filtar treba biti a.b.c.d, a ne samo a.b.

  • Neki uređaji šalju mnogo različitih poruka s istom temom ili ponekad temu moramo postaviti npr. na a.b jer nas zanimaju poruke a.b.c.d, ali i a.b.x.y, zbog čega će naravno stizati i poruke s temom a.b.k.l.m koje nas ne zanimaju. To u načelu nije loše, ali neki uređaji generiraju razna ažuriranja stanja ili poruke koje sadrže opise polja drugih poruka (metapodatke), a one mogu biti duge i nekoliko stotina KB i stizati relativno često, svakih nekoliko sekundi (npr. Zigbee2MQTT).

Zbog navedenih razloga kod protokola MQTT u skripti slušatelja vrlo je važno na temelju vrijednosti teme odlučiti je li poruka relevantna, a ako nije, odmah zaustaviti izvršavanje skripte i u tom trenutku nepotrebno ne analizirati sadržaj poruke. Algoritam u centralnoj jedinici TapHome sadrži mehanizme koji sprječavaju da MQTT bude preopterećen porukama. Ipak se ne može isključiti da preširoko postavljen MQTT filtar tema i mnogo velikih poruka produlje vrijeme odziva centralne jedinice.

Primljeni paket nalazi se u varijabli (strukturi) RECEIVEDMSG. Primljeni podaci mogu se pročitati u varijabli RECEIVEDMSG.Payload. Payload ima vrstu podatka BLOB (veliki binarni objekt), nije niz znakova (string) ni polje bajtova. Ako je payload vrste string, mora se koristiti funkcija TOSTRING, ali općenito payload može biti bilo što. RECEIVEDMSG sadrži i podatke specifične za protokol, npr. RECEIVEDMSG.Topic za MQTT. Korištenje RECEIVEDMSG.TOPIC vrlo je brz i učinkovit način da se dozna vrijednost teme, za razliku od starog načina kada se koristio RECEIVEDBYTES.

Poboljšanja u verziji 2024.1

Umjesto:

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

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

može se napisati ovako:

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

Zašto je to bolje: štedi se jedan poziv funkcije PARSEJSON kojim se doznaje vrijednost teme. Ako stiže mnogo MQTT poruka, a samo su neke zanimljive, prikladnije je koristiti ovaj novi način.

RECEIVEDMSG nadalje sadrži vrijednosti specifične za MQTT, npr. CLIENTID, DUP, CONTENTTYPE, EXPIRY; njihov sadržaj ovisi o tome što šalje MQTT poslužitelj. Stara sintaksa i dalje radi i radit će.

RECEIVEDMSG radi i s protokolima TCP i UDP, ne samo s MQTT-om. U tom slučaju daje samo svojstva PAYLOAD i LENGTH.

Analiza paketa

Podaci u naprednim postavkama modula sučelja Packet Parser sadrže statistiku primljenih i poslanih poruka: broj poruka za zadnjih 5 i 30 minuta, broj primljenih bajtova, a za MQTT su podaci razvrstani po MQTT temama. To bi trebalo pomoći pri otklanjanju pogrešaka u skriptama i postavljanju najprikladnijeg filtra tema, kako bi stizalo što manje poruka koje Core ne obrađuje.