Modbus

Modbus to prosty protokół komunikacyjny, często używany do integracji urządzeń HVAC. Wykorzystuje komunikację master-slave, gdzie na wspólnej magistrali może być podłączonych kilka urządzeń, przy czym każde musi mieć unikalne Slave ID, a urządzenie master zawsze odpytuje poszczególne urządzenia slave, które następnie odpowiadają.

Topologia Master - Slave

W większości przypadków TapHome jest używany w trybie, w którym jednostka sterująca Core jest Modbus Master, a podłączone urządzenia są Modbus Slave. To konfiguruje się w sekcji Sprzęt → Modbus RTU lub Modbus TCP. Jednak możliwe jest także użycie odwrotnego kierunku, gdy TapHome Core udostępnia informacje o swoich urządzeniach innemu systemowi nadrzędnemu. Jest to zdefiniowane w sekcji Uwidocznij urządzenia → Modbus RTU albo Modbus TCP.

Warstwy fizyczne

Modbus może komunikować się poprzez różne warstwy fizyczne:

• przez linię szeregową, typowo RS485 – nazywa się to Modbus RTU
• przez sieć LAN za pomocą protokołu TCP/IP
• przez sieć LAN za pomocą protokołu UDP – obecnie system TapHome go nie obsługuje

Rejestry Modbus

Modbus definiuje 4 typy rejestrów:

Numer rejestru ma 16 bitów, co oznacza, że może mieć wartość od 0 do 65535. Na rejestrach można wykonywać operacje:

• odczyt wielu rejestrów
• zapis jednego rejestru
• zapis wielu rejestrów

Niektóre implementacje Modbus dodają dodatkowe polecenia: raport Slave ID, maskowanie bitowe, zapis i odczyt naraz itp., ale te nie są wspierane przez TapHome. {.is-warning}

Informacje o tym, co jest zapisane w którym rejestrze i w jakim formacie, są częścią dokumentacji urządzenia dostarczonej przez dostawcę lub producenta urządzenia. Przykład dokumentacji Modbus od dostawcy urządzenia Modbus:

Typ rejestru C (Cewka), indeks 58, ponieważ ma tylko 2 wartości (otwarte / zamknięte) i oprócz odczytu umożliwia także zapis, odpowiadający typowi urządzenia TapHome – wyjściu cyfrowemu.

Skrócone wskazówki integracji urządzenia Modbus z TapHome

1. Podłącz urządzenie do odpowiedniej magistrali (dla Modbus RTU i ASCII) lub do sieci LAN (dla Modbus TCP). Dla Modbus TCP upewnij się, że jest w tej samej sieci co kontroler TapHome Core, np. za pomocą Fing (iOS, Android) lub IP Scanner (Windows).
2. W TapHome → Sprzęt dodaj nowy interfejs Modbus RTU lub Modbus TCP i ustaw parametry komunikacyjne zgodnie z dokumentacją. Dla Modbus RTU są to Baud rate, Stop bits, Parity, Data bits, dla Modbus TCP jest to adres IP.
3. W dokumentacji urządzenia Modbus sprawdź, jakiego Slave ID używa. W przypadku Modbus TCP bywa on oznaczany jako Unit ID. Jeśli chcesz użyć kilku urządzeń na jednej liniowej magistrali z Modbus RTU, musisz zmienić Slave ID każdego z nich tak, aby był unikalny dla danej linii.
4. Test komunikacji – za pomocą narzędzia Operacje ręczne spróbuj odczytać niektóre informacje zgodnie z dokumentacją (tabela Modbus) dla danego urządzenia. Jeśli wszystko działa, powinieneś zobaczyć odczytaną wartość.
5. Jeśli test komunikacji zakończył się powodzeniem, utwórz Moduł, który reprezentuje urządzenie Modbus.
6. Wybierz, które informacje z dokumentacji Modbus chcesz prezentować w systemie TapHome i utwórz odpowiadające im urządzenia. Zacznij od odczytu wartości (Read script), a w przypadku aktorów kontynuuj zapisem (Write script).
7. Jeśli podstawowe funkcje urządzenia działają, dodaj definicje Error, Warning lub Information do skryptów.
8. W razie potrzeby możesz także zdefiniować Atrybuty usług i Działania serwisowe dla urządzeń i modułów TapHome.
9. Jeśli wszystko jest ustawione i poprawnie się komunikuje, wyeksportuj Moduł do pliku XML, aby móc go użyć następnym razem. Możesz także przyczynić się do społeczności na github.com/taphome-official/modbus_templates.

Implementacja w TapHome

Ta dokumentacja jest przeznaczona dla scenariusza, w którym jednostka sterująca TapHome Core jest Modbus Master, a fizyczne urządzenia dodane do sekcji Sprzęt → Modbus RTU / TCP są urządzeniami Modbus Slave.

Interfejs

Sprzęt → Modbus RTU: urządzenia są podłączone do określonej magistrali, z podstawowymi parametrami transmisji RS485, takimi jak baudrate, parity, stop bits, oraz informacją, czy dane są ASCII czy binarne. Do tej samej magistrali mogą być podłączone tylko urządzenia o identycznych ustawieniach komunikacyjnych. Poprawna komunikacja może działać tylko wtedy, gdy kable A i B są prawidłowo podłączone. Sprzęt → Modbus TCP: urządzenia są podłączone do tej samej sieci LAN co TapHome Core. Zdefiniowany jest jeden port TCP, wspólny dla wszystkich urządzeń podłączonych do tego interfejsu.

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 unikalne Slave ID podłączonego urządzenia dla Modbus RTU oraz adres IP dla Modbus TCP.

Urządzenie

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

5 klimatyzatorów podłączonych do jednej magistrali używa wspólnego interfejsu Modbus RTU, który określa port magistrali, prędkość transmisji i inne parametry komunikacyjne. Interfejs ten zawiera 5 modułów, z których każdy reprezentuje jedną jednostkę klimatyzacyjną z unikalnym Slave ID. Każdy moduł ma pod sobą zdefiniowane urządzenia, takie jak termostat, tryb chłodzenia/grzania, moc wentylatora lub nachylenie lameli. Pojedyncze urządzenia mają zdefiniowane polecenia do odczytu i/lub zapisu wartości Modbus.

Obsługiwane urządzenia:

• Wyjście cyfrowe
• Wyjście analogowe
• termostat
• Przełącznik wielowartościowy
• Czujnik temperatury
• Licznik elektryczny
• Kontaktron
• Przycisk
• Zmienna

Skrypty do odczytu i zapisu wartości Modbus

Urządzenia TapHome komunikują się z fizycznymi urządzeniami Modbus za pomocą skryptów.

Więcej informacji o języku skryptowym, zwłaszcza o sekcji Operacje bitowe

Do komunikacji z urządzeniami Modbus wyznaczone są sekcje skryptów:

• Skrypt inicjalizacyjny: uruchamia się, gdy urządzenie się uruchomi (np. po ponownym uruchomieniu jednostki sterującej)
• Skrypt odczytu: ustawienie wartości zmiennych globalnych lub odczytanie stanów błędów
• Skrypt odczytu wartości: skrypt odczytujący konkretną wartość (wielkość fizyczną) z urządzenia Modbus (np. zadaną temperaturę na termostacie lub odczytaną temperaturę na termostacie)
• Skrypt zapisu wartości: zapisuje wartość do urządzenia Modbus

Funkcje do komunikacji z urządzeniami Modbus

MODBUSR (Modbus Read)

Funkcja odczytu rekordu z Modbus. W zależności od typu danych może to być 1 rejestr (dla 16-bitowych typów danych), 2 rejestry (dla 32-bitowych typów danych) lub więcej rejestrów (dla typów danych String).

MODBUSR(typ_rejestru, adres_rejestru, typ_danych, [OPCJONALNIE: liczba_znaków jeśli data_type=String])

Przykład: MODBUSR(H, 20, Int16)/100 Odczytaj rejestr H numer (lub adres) 20 i zinterpretuj go jako 16-bitową liczbę całkowitą ze znakiem. Na koniec podziel tę wartość przez 100 (przesuń przecinek o 2 miejsca w lewo).

Adres rejestru można również podać w formacie szesnastkowym, np. wartość 20 można zapisać jako 0x14.

MODBUSW (Modbus Write)

MODBUSW(typ_rejestru, adres_rejestru, typ_danych, wartość_do_zapisu)

Przykład: MODBUSW(H, 20, Int16, Te * 100) Do rejestru H o adresie 20 zapisz wartość zmiennej Te pomnożoną przez 100 (przesuń przecinek dziesiętny o 2 miejsca w prawo).

MODBUSWNE (Modbus Write if Not Equal)

Takie samo jak MODBUSW, z tą różnicą, że odczytuje wartość z rejestru przed zapisem i zapisuje ją dopiero wtedy, gdy wartość do zapisania różni się od tej odczytanej. Całkowita operacja trwa dłużej, a jej typowe zastosowanie to konfigurowanie właściwości urządzeń Modbus, gdzie konfiguracja zapisywana jest do pamięci EEPROM z ograniczoną liczbą zapisów.

Funkcje MODBUSR, MODBUSW i MODBUSWNE można używać tylko w skryptach Modbus. Jeśli są używane w innych skryptach, są uznawane za błąd.

Typy danych Modbus

Zawartość rejestrów jest zdefiniowana w tabeli Modbus. Ponieważ rozmiar pojedynczego rejestru Modbus to 16 bitów, najczęściej używane są 16-bitowe wartości Int16 lub UInt16, a miejsca dziesiętne określa się przez podzielenie przez 10 lub 100. Niektóre urządzenia Modbus używają również 16-bitowych rejestrów z liczbami zmiennoprzecinkowymi (Float), mogą też mieć zmienioną kolejność bajtów (big endian, little endian) lub zapisywać jedną liczbę w dwóch rejestrach (32-bitowe warianty). Czasem najprościej jest ustalić właściwy typ danych, używając narzędzia bezpośrednio w aplikacji TapHome (Operacje ręczne), gdzie można odczytać 1 lub więcej rejestrów i dynamicznie przełączać typ danych.

• Int16: -32768 do 32767
• Uint16: 0 do 65535
• Int32: -2147483648 do 2147483647
• Uint32: 0 do 4294967295
• Float: liczba zmiennoprzecinkowa pojedynczej precyzji IEEE 754
• Bool: 0 = false, 1 = true
• BigEndianInt16 = Int16
• LittleEndianInt16
• BigEndianUint16 = Uint16
• LittleEndianUint16
• BigEndianInt32 / BigEndianInt32ByteSwap
• LittleEndianInt32 / LittleEndianInt32ByteSwap
• BigEndianUint32 / BigEndianUint32ByteSwap
• LittleEndianUint32 / LittleEndianUint32ByteSwap
• BigEndianFloat / BigEndianFloatByteSwap
• LittleEndianFloat / LittleEndianFloatByteSwap
• String: format BCD może być także używany dzięki funkcjom TOBCD() i FROMBCD()

Interwał aktualizacji i zapytań

Każde urządzenie w interfejsie Modbus ma zdefiniowany atrybut Poll Interval. Określa on, jak często jednostka sterująca TapHome powinna odpyt(yw)ać nowe wartości z urządzenia Modbus. Komunikacja Modbus jest typu Master-Slave, dlatego informacje z urządzenia Modbus mogą docierać do TapHome tylko wtedy, gdy TapHome ich zażąda. Im dłuższy jest Poll Interval, tym później wartość w TapHome zostanie zaktualizowana. Zbyt krótki Poll Interval może oznaczać, że TapHome będzie niepotrzebnie obciążał magistralę, pobierając zbędne wartości, i może nie mieć czasu obsłużyć wszystkich urządzeń w danym okresie. Na przykład przy Modbus RTU i niższych prędkościach Baud Rate, np. 9600, jedno żądanie/odpowiedź może trwać kilkadziesiąt ms. Dla termometrów zazwyczaj wystarcza interwał 15000 ms (15 s), dla przycisków – przeciwnie, jak najkrótszy, np. 50 ms. Niektóre urządzenia Modbus oczekują, że master będzie okresowo zapisywał aktualną wartość do rejestru. Do tego służy atrybut Periodic Write.

Definicja błędów ze skryptów

W niektórych skryptach można definiować błąd / ostrzeżenie / informację na urządzeniu na podstawie informacji odczytanych z rejestrów Modbus danego urządzenia. Te komunikaty wyświetlane są w TapHome tak samo jak wewnętrzne komunikaty błędów TapHome. Opcjonalnie można dodać kod błędu, jeśli jest to praktyczne z perspektywy serwisu urządzenia Modbus.

Na urządzeniu można zdefiniować tylko jedną wiadomość błędu bez kodu lub tylko jedną wiadomość błędu dla danego kodu błędu.

ADDERROR(), ADDWARNING(), ADDINFO() ADDERROR([Opcjonalnie: custom_code], tekst)

Przykład: w sekcji Read Script urządzenia Analog Output znajduje się kod:

1
2
3
4
5
6
7

ADDERROR("Error without code");
ADDWARNING("Warning without code");
ADDINFO("Info without code");

ADDERROR(1, "Error with code");
ADDWARNING(1, "Warning with code");
ADDINFO(1,"Info with code");

…co objawia się na urządzeniu komunikatami:

Atrybuty serwisowe i akcje

Oprócz wartości (lub kilku wartości, jak na przykład termostat) z podłączonego urządzenia Modbus moduły i urządzenia TapHome mogą odczytywać także atrybuty serwisowe lub wykonywać akcje serwisowe. Nie są one dostępne na pulpicie dla zwykłych użytkowników systemu, ale służą jedynie do prezentowania bardziej szczegółowych informacji o urządzeniu Modbus, bez przeciążania systemu dużą liczbą zmiennych i akcji.

Atrybuty usług wyświetlają się w ustawieniach serwisu modułu lub urządzenia TapHome. Zazwyczaj służą do wyświetlania informacji o urządzeniu, takich jak model, numer seryjny, wersja firmware, wersja sprzętu, czas od ostatniego restartu itp. Są to użyteczne informacje z perspektywy serwisu urządzenia Modbus, ale nie ma sensu tworzyć dla nich osobnych urządzeń TapHome.

Działania serwisowe wyświetlają się w ustawieniach serwisu modułu lub urządzenia TapHome, na samym dole jako przyciski. Po naciśnięciu wykonają zaprogramowaną akcję Modbus, która zapisze żądane informacje do rejestru. Przykład użycia: ustawienie lub zmiana Slave ID, oznaczenie wymiany filtra, ustawienie licznika na żądaną wartość, resetowanie urządzenia itp.

Skrypty i pomocnicze zmienne na module

Zmienne globalne modułu

Zmienne zdefiniowane na module są używane we wszystkich skryptach modułu i są udostępniane wszystkim urządzeniom przypisanym do tego modułu.

Init Script

Opcjonalny. Uruchamia się przy starcie modułu. Jeśli jest wypełniony i jeszcze się nie zakończył, nie będą dozwolone żadne inne skrypty.

• 💬 Wartość zwrotna: ignorowana
• ⚙️ Dostęp do zmiennych: zmienne globalne modułu
• ⚠️ Wsparcie błędów: nie

Read Script

Uruchamia się przy każdym zapytaniu modułu.

• 💬 Wartość zwrotna: ignorowana
• ⚙️ Dostęp do zmiennych: zmienne globalne modułu
• ⚠️ Wsparcie błędów: tak

Write Script

Uruchamiany:

• przy zmianie wartości zmiennej urządzenia
• jeśli włączony jest atrybut „Periodic Write", uruchomi się automatycznie
• 💬 Wartość zwrotna: ignorowana
• ⚙️ Dostęp do zmiennych: zmienne globalne modułu, wartości urządzeń przypisanych do danego modułu (uwaga, nie są to zmienne globalne urządzenia – skrypt modułu nie ma do nich dostępu). Służy to w przypadkach, gdy trzeba zapisać wartości wielu urządzeń danego modułu do jednego rejestru.
• ⚠️ Wsparcie błędów: nie

Atrybuty usług

Każde urządzenie może mieć nieograniczoną liczbę atrybutów serwisowych. Skrypty są wykonywane za każdym razem, gdy użytkownik (z uprawnieniami serwisowymi) otworzy ekran ustawień serwisowych urządzenia w aplikacji. Są wykonywane po odczycie z modułu Modbus.

• 💬 Wartość zwrotna: wyświetla się jako wartość danego atrybutu
• ⚙️ Dostęp do zmiennych: zmienne globalne modułu, zmienne globalne urządzenia
• ⚠️ Wsparcie błędów: nie

Działania serwisowe

Każde urządzenie może mieć nieograniczoną liczbę serwisowych akcji. Skrypty są wykonywane, gdy użytkownik (z uprawnieniami serwisowymi) otworzy aplikację na ekranie ustawień serwisowych urządzenia i naciśnie jeden z zdefiniowanych przycisków o nazwie danej akcji serwisowej. Każda akcja serwisowa jest zdefiniowana swoją nazwą, parametrami i skryptem wykonywania.

• 💬 Wartość zwrotna: ignorowana
• ⚙️ Dostęp do zmiennych: zmienne globalne modułu, zmienne globalne urządzenia, parametry wprowadzone przez użytkownika
• ⚠️ Wsparcie błędów: nie

Narzędzia pomocnicze

Dodaj z szablonu

Umożliwia konfigurację komunikacji Modbus ze sterowanym urządzeniem bez jakiejkolwiek wiedzy o protokole Modbus lub o tym, jak go skonfigurować w TapHome. Gotowe szablony znajdziesz:

• bezpośrednio w aplikacji: Dodaj z szablonu → wybierz konkretne urządzenie → wypełnij podstawowe informacje i potwierdź. Wszystkie te szablony są zarządzane społecznościowo w projekcie git na https://github.com/taphome/modbus_templates i każdy może zaproponować nowe modyfikacje. To, co trafia do aplikacji, musi być zatwierdzone przez zespół TapHome.
• we własnym pliku XML: Dodaj z szablonu → Dodaj z pliku . Możesz stworzyć własny plik XML, który definiuje cały szablon bezpośrednio na module Modbus, w menu kontekstowym (trzy kropki w prawym górnym rogu), akcją Zapisz jako szablon. Będziemy wdzięczni za pomoc w rozszerzaniu liczby obsługiwanych urządzeń i wniesienie swojego pliku XML do wspólnego projektu społecznościowego git.

Więcej informacji o konfiguracji komunikacji Modbus za pomocą szablonów

Operacje ręczne

Praktyczne narzędzie do szybkiej weryfikacji tabeli Modbus. Umożliwia:

• odczytanie kolejnych X rejestrów od określonego rejestru i następnie dynamiczne przełączanie odczytywanych wartości na różne typy danych
• zapis wartości do danego rejestru

Skanowanie Slave ID

Powszechną praktyką przy konfigurowaniu komunikacji z urządzeniem Modbus jest to, że fabryczne domyślne Slave ID różni się od 1 i niełatwo jest odszukać właściwy numer. Do tego służy to narzędzie. Może skanować podany zakres Slave ID, próbując odczytać z wybranego rejestru zawsze z aktualnie testowanym Slave ID.

Informacje o rejestrach

Znajduje się na dole modułu Modbus. Dla każdego używanego rejestru podaje informacje o:

• nazwie urządzenia TapHome, które odczytuje z niego lub zapisuje do niego
• dacie i godzinie ostatniego pomyślnego odczytu z rejestru
• ostatniej wartości odczytanej z rejestru
• dacie i godzinie ostatniego pomyślnego zapisu w rejestrze
• ostatniej zapisanej wartości do rejestru

Zaawansowane ustawienia

Prefetch

TapHome tworzy listę rejestrów do odczytu i zapisu z urządzeń Modbus w zależności od ustawionego Poll Interval. Prefetch to proces, dzięki któremu jednostka sterująca będzie wstępnie odczytywać do pamięci wartości, które będą potrzebne podczas aktualizacji. Celem jest zminimalizowanie liczby żądań i powrotnych transmisji. Prefetch jest kontrolowany przez 2 ustawienia:

• Max prefetch register group size (umieszczone w ustawieniach serwisowych modułu): określa maksymalną liczbę rejestrów, które można odczytać lub zapisać jednym żądaniem komunikacji Modbus.
• Prefetch mode (ustawiane dla każdego urządzenia):
  • No prefetch. Prefetch dla tego urządzenia nie będzie wykonywany. Oznacza to, że wartości będą odczytywane indywidualnie i dokładnie w momencie wykonywania skryptu. Przykład użycia: przy komunikacji z konwerterem DALI nie można odczytać wartości konkretnego światła bezpośrednio, trzeba o to poprosić, konwerter ją przygotuje i dopiero wtedy ją zwróci. Jakiekolwiek wcześniejsze odczytywanie jest w tym przypadku bezsensowne.
  • Isolated prefetch. Prefetch odczytuje naraz kilka rejestrów, ale tylko te, które są zdefiniowane w tym urządzeniu. Na przykład, gdy potrzebuję rejestrów 3 i 4 w urządzeniu termostatu, a rejestry 1, 2, 5, 6 są używane w innych urządzeniach, to żądanie rejestrów 3 i 4 zostanie wykonane osobno tylko dla tych dwóch rejestrów. Niektóre urządzenia Modbus tego wymagają.
  • Normal prefetch. Wszystkie żądane rejestry z urządzeń, które mają być odświeżone, będą odczytywane z minimalną liczbą żądań. W przypadku nieciągłej sekwencji rejestrów odczytane będą także te, które nie są używane, jeśli były wcześniej pomyślnie odczytane. Przykład: żądane są rejestry 99 i 101. Jeśli rejestr 100 był wcześniej pomyślnie odczytany, a Max prefetch register group size jest ustawiony na 3 lub więcej, odczytane zostaną 3 rejestry jednym żądaniem począwszy od rejestru 99. Jeśli rejestr 100 nie był nigdzie używany i nigdy nie był odczytany pomyślnie, istnieje ryzyko, że odczyt przez taki rejestr zwróci Modbus Exception, np. „Illegal data address" jako odpowiedź na całe żądanie.

Prefetch może być również modyfikowany bezpośrednio ze skryptu: jeśli podczas odczytu użyjemy rejestru SC lub SH (zamiast C lub H), to wartość odczytywana jest jeden rejestr po drugim podczas wykonywania skryptu i nie jest pobierana z pamięci podręcznej. Podobnie przy zapisie, jeśli użyjemy rejestru SC lub SH (zamiast C lub H), wartość zapisywana jest jeden rejestr po drugim i inną funkcją Modbus. Protokół Modbus obsługuje 4 funkcje zapisu: zapis wielu H, zapis wielu C, zapis jednego H lub jednego C naraz. Uwaga: nie wszystkie urządzenia obsługują wszystkie te funkcje. W ten sposób, jeśli zajdzie potrzeba, można łączyć odczyt i zapis „jeden po drugim".

TCP Port (Modbus TCP)

W większości przypadków domyślną wartością jest 502, ale niektóre urządzenia mogą nasłuchiwać na innym porcie.

Limit czasu odczytu / zapisu

Czas, po którym TapHome zakończy oczekiwanie na odpowiedź i zgłosi błąd „Timeout". Oznacza to, że urządzenie nie odpowiedziało w danym przedziale.

• Wolne urządzenia Modbus mogą wymagać dłuższych limitów czasu (1+ sekundy).
• Zbyt wysokie wartości limitu czasu mogą bezzasadnie opóźniać inne urządzenia Modbus oczekujące na odpowiedź.

Opóźnienie między żądaniami

Opóźnienie, które TapHome wstawia pomiędzy poszczególnymi żądaniami do urządzenia Modbus.

📌 Ważne informacje o urządzeniach:

• Niektóre urządzenia Modbus TCP wymagają nawet 5000 ms między żądaniami.
• Niektóre urządzenia Modbus RTU umożliwiają krótsze opóźnienia i komunikują się szybciej.

Użycie komunikacji ASCII

Modbus ASCII jest rzadziej spotykanym wariantem standardu, w którym komunikacja nie jest binarna, lecz zamiast tego używa znaków ASCII.

• Te urządzenia zazwyczaj wymagają ustawienia 7 bitów danych.