Konfiguracja manualna

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ę Poświadczenie w ustawieniach serwisowych 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 elektryczny
• Kontaktron
• Żaluzje, markizy, zawory mieszające
• Światło RGB
• Regulowane białe światło

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 listener: 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 w skrypcie Packet parser z protokołem HTTP, czeka na odpowiedź i zwraca obiekt httpresponse z Content, StatusCode, ReasonPhrase, IsSuccess i Headers. Żądanie z własną metodą, treścią i nagłówkami tworzy się przez HTTPREQUEST — parametry i przykłady: SENDHTTPREQUEST, HTTPREQUEST.

VAR response := SENDHTTPREQUEST("/getValue");
IF(response.IsSuccess, PARSEJSON(response.Content, "value"), NaN)

TCP, UDP#

SENDDATA#

Wysyła tekst lub collection<uint8> przez TCP lub UDP; odpowiedź urządzenia jest przetwarzana w skrypcie listener — SENDDATA.

COMPLETESERVICEATTRIBUTE#

W skrypcie listener kończy odczyt atrybutu serwisowego, którego skrypt wysłał żądanie przez SENDDATA — COMPLETESERVICEATTRIBUTE.

COMPLETESERVICEACTION#

W skrypcie listener kończy akcję serwisową, której skrypt wysłał żądanie przez SENDDATA — COMPLETESERVICEACTION.

FTP#

FTPDOWNLOAD#

Zwraca zawartość pliku z serwera FTP jako collection<uint8> — FTPDOWNLOAD.

FTPUPLOAD#

Zapisuje lub dopisuje dane (tekst lub collection<uint8>) do pliku na serwerze FTP — FTPUPLOAD.

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#

Publikuje wiadomość do brokera MQTT z urządzenia Packet parser z protokołem MQTT — MQTTPUBLISH.

Skrypt listener#

Skrypt listener jest wywoływany po otrzymaniu każdego pakietu; w szczególności dla MQTT skrypt listener 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 listener. 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 listener 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 spowodują wzrost czasu odpowiedzi kontrolera.

Odebrana wiadomość znajduje się w RECEIVEDMSG: Payload to blob (tekst przekonwertujesz przez TOSTRING), Topic to temat MQTT, Protocol to protokół, a Length rozmiar. Odczyt RECEIVEDMSG.Topic to szybki sposób, aby zdecydować, czy wiadomość jest istotna, w przeciwieństwie do starszego RECEIVEDBYTES. Wszystkie właściwości i przykłady: Skrypty listener.

Ulepszenia w wersji 2024.1#

Zamiast:

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

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

można zapisać tak:

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; tam niesie Payload, Length i Protocol ("tcp" lub "udp") — RECEIVEDMSG.

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.