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

Konfiguracja manualna

Skonfiguruj Packet Parser TapHome, aby łączyć urządzenia zewnętrzne za pomocą protokołów TCP/IP, w tym HTTP, TCP, UDP, FTP i MQTT.

Implementacja w TapHome

W TapHome Packet Parser to interfejs sprzętowy (Ustawienia → Sprzęt → Dodaj nowy interfejs → Packet parser), który służy do połączenia urządzeń zewnętrznych z kontrolerem. Te urządzenia mogą komunikować się z jednostką sterującą za pomocą Wi‑Fi lub LAN poprzez protokół TCP/IP.

Packet Parser używa własnego języka skryptowego zaprojektowanego specjalnie dla systemu TapHome. Język ten służy do sterowania i zarządzania podłączonymi urządzeniami oraz ich komunikacją z kontrolerem. Kliknij tutaj, aby uzyskać więcej informacji o języku skryptowym TapHome

Hierarchia

System TapHome używa hierarchicznej struktury do organizowania podłączonych urządzeń. W tej strukturze Moduł (Module) działa jako urządzenie nadrzędne i może komunikować się z urządzeniami podrzędnymi i je kontrolować.

Moduł

Interfejs może zawierać jeden lub więcej modułów, które w większości przypadków obejmują komunikację z całym fizycznym urządzeniem. Z punktu widzenia konfiguracji Moduł definiuje:

  • Adres IP lub nazwę mDNS urządzenia
  • Port komunikacyjny
  • Bezpieczne połączenie: zobacz sekcję Uwierzytelnianie w ustawieniach usługi Modułu
  • Ignoruj błędy certyfikatu SSL

Urządzenie

Reprezentuje konkretny element sterujący lub czujnik w systemie TapHome. Zawsze musi być częścią jednego nadrzędnego Modułu.

Obsługiwane urządzenia:

  • Wyjście cyfrowe
  • Wyjście analogowe
  • Termostat
  • Przełącznik wielowartościowy
  • Czujnik temperatury
  • Zmienna
  • Przycisk
  • Licznik energii
  • Kontakt reedowy
  • Żaluzje, markizy, zawory mieszające
  • Światło RGB
  • Światło białe regulowane

Przykład: Shelly Plug S
Moduł zawiera informacje o adresie IP, ma skrypty do odczytu stanu, ustawień i wykonywania akcji serwisowych. Dotyczy 2 urządzeń: wyjścia cyfrowego (przekaźnik) i licznika energii mierzącego podłączone urządzenia.

Skrypty do odczytu i zapisu

Jednostka TapHome i podłączone urządzenia mogą komunikować się za pomocą żądań HTTP lub HTTPS GET/POST. Odpowiedzi na te żądania mogą być parsowane za pomocą zestawu wyspecjalizowanych funkcji. Na przykład może istnieć funkcja zaprojektowana specjalnie do parsowania odpowiedzi XML, inna funkcja do parsowania odpowiedzi JSON, a jeszcze inna do parsowania odpowiedzi w postaci tablic bajtów. Funkcje te ułatwiają interpretację i wykorzystanie informacji otrzymanych w odpowiedziach, co umożliwia bardziej wydajną i skuteczną komunikację z kontrolerem i podłączonymi urządzeniami.

TapHome definiuje wiele atrybutów, które mogą zawierać język skryptowy:

  • Skrypt inicjalizacyjny: uruchamiany po uruchomieniu urządzenia (np. po ponownym uruchomieniu kontrolera)
  • Skrypt odczytu: służy do ustawiania wartości zmiennych globalnych lub odczytywania stanów błędów
  • Skrypt odczytu wartości: skrypt do odczytu określonej wartości (wielkości) z podłączonego urządzenia (np. nastawiona temperatura na termostacie lub zmierzona temperatura w termostacie)
  • Skrypt zapisu wartości: służy do zapisu wartości do podłączonego urządzenia
  • Skrypt nasłuchujący: wykonywany po otrzymaniu każdego pakietu. Więcej informacji w sekcji poniżej

Kliknij tutaj, aby uzyskać więcej informacji o języku skryptowym TapHome

Definiowanie stanów błędów w skryptach

Atrybuty i akcje serwisowe

Skrypty i zmienne pomocnicze w module

Skrypty i zmienne pomocnicze na urządzeniu

Zobacz więcej informacji na stronie dokumentacji Modbus

Obsługiwane protokoły

  • HTTP
  • TCP
  • UDP
  • FTP
  • MQTT

HTTP

SENDHTTPREQUEST

Wysyła żądanie HTTP z podanymi parametrami, oczekuje na odpowiedź i zwraca odpowiedź jako ciąg JSON z wartościami Content, Headers, kodem odpowiedzi HTTP. Funkcja obsługiwana jest wyłącznie w skryptach Packet parser z protokołem HTTP.

1
2

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

Przykłady:

 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
}

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

Wysyła określone dane (ciąg znaków lub Collection) przy użyciu protokołu TCP lub UDP. Jeśli dane są obiektem typu string, są domyślnie konwertowane na bajty przy użyciu kodowania ISO‑8859‑1. Funkcja obsługiwana jest wyłącznie w skryptach Packet parser z protokołem TCP/UDP. Odebrane bajty można przetwarzać w skrypcie nasłuchującym.

1

SENDDATA( string/Collection<UInt8> )

Przykłady:

1
2

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

COMPLETESERVICEATTRIBUTE

Funkcja używana w skryptach nasłuchujących w Packet parser z protokołem TCP/UDP do powiadamiania o zakończeniu żądania wartości atrybutu serwisowego. Np. tworzysz żądanie w skrypcie atrybutu serwisowego za pomocą funkcji SENDDATA i po otrzymaniu danych w skrypcie nasłuchującym kończysz odczyt wartości atrybutu serwisowego.

1

COMPLETESERVICEATTRIBUTE( attributeName, value, error )

Przykłady:

1
2

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

COMPLETESERVICEACTION

Funkcja używana w skryptach nasłuchujących w Packet parser z protokołem TCP/UDP do powiadamiania o zakończeniu żądania akcji serwisowej. Np. tworzysz żądanie w skrypcie akcji serwisowej przy użyciu funkcji SENDDATA i po otrzymaniu danych w skrypcie nasłuchującym kończysz akcję serwisową.

1

COMPLETESERVICEACTION( actionName, result )

Przykłady:

1
2

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

FTP

FTPDOWNLOAD

Zwraca dane pliku (jako Collection) z serwera FTP. Funkcja obsługiwana jest wyłącznie w skryptach Packet parser z protokołem FTP.

1

FTPDOWNLOAD( pathToFile )

Przykłady:

1

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

FTPUPLOAD

Wysyła dane (Collection lub string) do pliku na serwerze FTP.

1

FTPUPLOAD( pathToFile, data, mode )

Przykłady:

1
2

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

MQTT

Oprócz wymienionych powyżej opcji komunikacji system TapHome umożliwia również komunikację z urządzeniami zewnętrznymi za pomocą protokołu MQTT. MQTT, czyli Message Queuing Telemetry Transport, to lekki protokół publish/subscribe zaprojektowany do wydajnej i niezawodnej komunikacji między urządzeniami w kontekście M2M i IoT.

Aby umożliwić komunikację z urządzeniami zewnętrznymi za pomocą MQTT, konieczne jest utworzenie osobnego modułu w Ustawienia → Sprzęt → Dodaj nowy interfejs → MQTT Broker. Ten moduł działa jako pośrednik między urządzeniami zewnętrznymi a kontrolerem, umożliwiając im komunikację za pomocą protokołu MQTT. Broker MQTT może być uruchomiony autonomicznie na kontrolerze, zapewniając niezależną i wydajną komunikację między urządzeniami zewnętrznymi a systemem TapHome.

MQTTPUBLISH

Funkcja używana na urządzeniach Packet Parser z protokołem MQTT do publikowania wiadomości do brokera MQTT.

1

MQTTPUBLISH( topic, message )

Przykłady:

1

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

Skrypt nasłuchujący

Skrypt nasłuchujący jest wywoływany po otrzymaniu każdego pakietu; w szczególności dla MQTT skrypt nasłuchujący uruchamia się, gdy jakakolwiek wiadomość przyjdzie przez MQTT, której temat (Topic) pasuje do filtra tematu ustawionego w TapHome; takich wiadomości może być kilkaset na minutę. Warto wspomnieć o dwóch kwestiach:

  • Filtr tematu (Topic) musi być ustawiony tak restrykcyjnie, jak to możliwe, aby wiadomości o innej wartości Topic w ogóle nie docierały i tym samym nie aktywowały skryptu nasłuchującego. Na przykład jeśli interesuje nas tylko temat a.b.c.d, filtr powinien brzmieć a.b.c.d, a nie tylko a.b.

  • Niektóre urządzenia generują wiele różnych wiadomości, które mają ten sam temat, lub czasami musimy ustawić temat np. na a.b, ponieważ interesują nas wiadomości a.b.c.d, ale także a.b.x.y, co oczywiście spowoduje, że nadejdą również wiadomości o temacie a.b.k.l.m, którymi nie jesteśmy zainteresowani. Zasadniczo nie jest to złe, ale niektóre urządzenia generują różne aktualizacje statusu lub wiadomości zawierające opisy pól innych wiadomości (metadane) i mogą mieć długość setek KB oraz przychodzić stosunkowo często – co kilka sekund (np. Zigbee2MQTT).

Z powodu wyżej wymienionych powodów w MQTT, w skrypcie nasłuchującym bardzo ważne jest podejmowanie decyzji na podstawie wartości Topic, czy wiadomość jest istotna; jeśli nie, natychmiast przerwij wykonywanie skryptu i nie analizuj treści wiadomości w tym momencie. Algorytm w kontrolerze TapHome zawiera mechanizmy zapobiegające przeciążeniu MQTT dużą liczbą wiadomości. Niemniej nie można wykluczyć, że bardzo luźno ustawiony filtr tematów MQTT i duża liczba dużych wiadomości nie spowodują wzrostu czasu odpowiedzi kontrolera.

Odebrany pakiet znajduje się w zmiennej (strukturze) RECEIVEDMSG. Odebrane dane można odczytać w zmiennej RECEIVEDMSG.Payload. Payload ma typ danych BLOB (duży obiekt binarny), nie jest ciągiem znaków ani tablicą bajtów. Jeśli payload jest typu string, należy użyć funkcji TOSTRING, ale ogólnie payload może być dowolny. RECEIVEDMSG zawiera także dane specyficzne dla protokołu, np. RECEIVEDMSG.Topic dla MQTT. Użycie RECEIVEDMSG.TOPIC to bardzo szybki i wydajny sposób na poznanie wartości tematu, w przeciwieństwie do starego sposobu, gdy używano RECEIVEDBYTES.

Ulepszenia w wersji 2024.1

Zamiast:

1
2
3
4
5

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

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

można zapisać tak:

1
2
3

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

Dlaczego to lepiej – oszczędza jedno wywołanie PARSEJSON, aby dowiedzieć się, jaka jest wartość tematu. Jeśli nadchodzi wiele wiadomości MQTT, a tylko niektóre z nich są interesujące, nowa metoda jest wygodniejsza.

RECEIVEDMSG zawiera ponadto wartości specyficzne dla MQTT – np. CLIENTID, DUP, CONTENTTYPE, EXPIRY – ich zawartość zależy od tego, co serwer MQTT wysyła. Stara składnia nadal działa i będzie działać.

RECEIVEDMSG działa również z TCP i UDP, nie tylko z MQTT. W tym przypadku dostarcza jedynie właściwości PAYLOAD i LENGTH.

Analiza pakietów

Informacje w ustawieniach serwisowych modułów Packet Parser zawierają dane statystyczne dotyczące odebranych i wysłanych wiadomości – liczniki za ostatnie 5 i 30 minut, liczbę odebranych bajtów, a dla MQTT dane są sortowane według tematów MQTT. Powinno to pomóc w debugowaniu skryptów i ustawieniu najodpowiedniejszego filtra tematu, aby zapewnić, że jak najmniej wiadomości, które nie są przetwarzane przez Core, zostanie dostarczonych.