Protokół integracji (AMX, Lutron, Crestron, Control4, Clipsal)

System TapHome potrafi integrować się z innymi systemami za pomocą prostego protokołu integracyjnego ASCII. Umożliwia to innym systemom pobieranie informacji i sterowanie urządzeniami TapHome.

Obsługiwane warstwy komunikacyjne

• RS485
• TCP/IP
• UDP/IP

Opis protokołu

Protokół obsługuje następujące polecenia:

HELP, LIST, GET, SET, ACTION, HEADER, AUTOSEND

Każde polecenie musi być zakończone znakami CRLF (0x0D 0x0A, \r\n).

Polecenie HELP

Polecenie HELP wyświetla podstawowe informacje o obsługiwanych poleceniach.

HEADER [ON/OFF] włącza/wyłącza wysyłanie nagłówka.

LIST wyświetla wszystkie udostępnione urządzenia.

GET [ID] pobiera urządzenie o identyfikatorze ID.

SET [ID ST VAL1 .. VALN] ustawia urządzenie o identyfikatorze ID, status ST i wartości VAL1 do VALN.

ACTION [ID NUM VAL] wykonuje na urządzeniu o identyfikatorze ID akcję o numerze NUM z wartością VAL.

PUSHALL [ON/OFF] włącza/wyłącza wysyłanie zmian we wszystkich urządzeniach.

Polecenie HEADER

Polecenie HEADER przełącza między dwoma możliwymi sposobami wyjścia danych. Gdy nagłówek jest włączony (ON), wraz z danymi wysyłane są informacje opisowe. Gdy nagłówek jest wyłączony (OFF), wysyłane są tylko dane.

HEADER bez parametrów wysyła informację o aktualnym stanie nagłówka.

HEADER ON włącza wysyłanie nagłówka.

HEADER OFF wyłącza wysyłanie nagłówka.

Polecenie LIST

Polecenie LIST wyświetla wszystkie udostępnione urządzenia.

Wyświetlane są następujące informacje:

ID urządzenia – numeryczny identyfikator.

Typ urządzenia – opis tekstowy typu urządzenia (Blind, Switch, …).

Nazwa urządzenia – jak ustawiono w systemie TapHome.

Status urządzenia – informacja tekstowa.

Przykładowy wynik polecenia LIST:

1
2
3
4
5
6
7
8

ID:137,Type:Blind,Name:Virtual blind,Status:OK
ID:51,Type:Switch,Name:Ex Switch,Status:OK
ID:2,Type:MultiValueSwitch,Name:Heating & Cooling,Status:OK
ID:205,Type:PushButton,Name:Push button,Status:OK
ID:242,Type:Dimmer,Name:Analog output,Status:OK
ID:68,Type:Thermostat,Name:Thermostat 1,Status:UnknownError
ID:145,Type:Variable,Name:KNXVariable,Status:OK
ID:143,Type:Variable,Name:Sun azimuth,Status:OK

Polecenie GET

Polecenie GET wymaga jednego parametru – identyfikatora urządzenia. Zwraca status urządzenia oraz wartości jako liczby.

Przykładowy wynik polecenia GET 137:

1

ID:137,DeviceStatus:0,BlindsLevel:41,BlindsSlope:41

Przykład, gdy nagłówek jest wyłączony:

1

137,0,41,41

Polecenie SET

Polecenie SET wymaga co najmniej trzech parametrów. Najpierw identyfikator urządzenia, następnie nowy status urządzenia do ustawienia, a na końcu co najmniej jednej wartości do ustawienia. Dla urządzeń z więcej niż jedną wartością wszystkie wartości powinny następować po sobie – na przykład żaluzja wymaga podania zarówno nowego poziomu, jak i nowego kąta.

Przykład odpowiedzi na polecenie SET 137 0 35 80 (z nagłówkiem i bez nagłówka):

1
2

ID:137,DeviceStatus:0,BlindsLevel:35,BlindsSlope:80
137,0,35,80

Polecenie ACTION

Polecenie ACTION wykonuje na urządzeniu o identyfikatorze ID akcję o numerze NUM z wartością VAL. Akcje zdefiniowane są tylko dla żaluzji. Istnieją trzy numery akcji dla żaluzji:

0 zatrzymanie żaluzji

1 regulacja poziomu z aktualnej pozycji o ±wartość

2 regulacja kąta lameli z aktualnej pozycji o ±wartość

Przykładowy wynik polecenia ACTION 137 1 -20:

1

ID:137,AdjustBlindsLevel:-20

Polecenie PUSHALL

Polecenie PUSHALL włącza wysyłanie zmian wszystkich urządzeń. Informacje są wysyłane w tym samym formacie co odpowiedź na polecenie GET. Należy pamiętać, że gdy używane jest na linii RS485, może wystąpić konflikt na magistrali prowadzący do rozbieżności danych. Dlatego sugerujemy używanie tego polecenia tylko na liniach w pełnym dupleksie, takich jak RS232 lub RS422. Istnieje również możliwość włączenia go na linii RS485 w systemach, w których nie będą używane polecenia SET ani ACTION – to znaczy tylko w systemach monitorujących. W liniach RS485, gdzie wymagane są polecenia SET i ACTION, sugerujemy użycie okresowego pobierania za pomocą polecenia GET zamiast automatycznego monitorowania.

Tryb adresowy

Gdy ustawione jest unikalne ID interfejsu, możliwe jest użycie wszystkich poleceń w trybie adresowym. W tym mode nagłówek z adresem poprzedza samą komendę. Nagłówki adresowe to sekwencja !InterfaceID:, gdzie InterfaceID jest ustawiony w konfiguracji interfejsu. Każda linia odpowiedzi będzie również poprzedzona tym samym nagłówkiem. Tylko interfejs o poprawnym adresie odpowie – błędne adresowanie nie zostanie odzwierciedlone w odpowiedzi.

Przykład żądania w trybie adresowym za pomocą polecenia !2:LIST:

1

klad_adresa;

Konfiguracja

Aby udostępnić urządzenia w protokole integracyjnym, najpierw przejdź do Udostępnianie urządzeń i wybierz Dodaj nowy interfejs. Z dostępnych interfejsów wybierz jeden z Protokół integracyjny RS485, Protokół integracyjny TCP lub Protokół integracyjny UDP:

Po dodaniu interfejsu, zgodnie z typem, wypełnij pozostałe parametry. Ustaw unikalny identyfikator interfejsu dla każdego interfejsu, jeśli chcesz używać trybu adresowego.

Wybierz terminal do komunikacji i wypełnij parametry komunikacyjne dla RS485. Ustaw wszystkie parametry linii szeregowej zgodnie z wymaganiami podłączonego klienta.

Ustaw port TCP dla interfejsu podrzędnego:

Ustaw port UDP dla interfejsu podrzędnego:

Następnie użyj opcji Dodaj urządzenie, aby dodać swoje urządzenia do udostępnionych urządzeń:

Wybierz urządzenie z listy oferowanych urządzeń. Należy pamiętać, że już dodane urządzenia są wyszarzone.

Po dodaniu urządzenia zostaje ono wyświetlone na liście urządzeń dla interfejsu protokołu integracyjnego:

Kliknij urządzenie, aby wyświetlić informacje o nim, zmienić automatycznie wygenerowany identyfikator urządzenia lub usunąć urządzenie z udostępnionych urządzeń.

Obsługiwane urządzenia

Poniższe urządzenia są obecnie obsługiwane do udostępniania w protokole integracyjnym:

Termostat, Przełącznik, Przełącznik wielowartościowy, Przycisk, Kontakt reed, Dimer / Wyjście analogowe, Zmienna, Żaluzja, Światło RGB.

DEVICE_ID

Nadawany kolejno każdemu urządzeniu na liście udostępnionych urządzeń. Można go ręcznie zmienić na dowolną wartość.

ERROR

0 … OK

1 … Bateria niska

2 … Bateria krytyczna

3 … Uszkodzony

4 … Błąd komunikacji

5 … Nieznany błąd

6 … Błąd autoryzacji

7 … Błąd konfiguracji

BUTTON PRESSED

1 … Krótkie naciśnięcie

2 … Długie naciśnięcie

3 … Podwójne naciśnięcie

4 … Potrójne naciśnięcie

Debugowanie komunikacji RS485

Dla połączeń RS485 możliwe jest podłączenie do komputera adaptera USB–RS485. Żądania i odpowiedzi będą widoczne w aplikacji konsolowej.

Standardowy konwerter USB do RS485

http://sk.farnell.com/ftdi/usb-rs485-we-1800-bt/cable-usb-rs485-serial-converter/dp/1740357

Uwaga: ten konwerter nie jest galwanicznie izolowany, więc należy połączyć GND konwertera z GND Core.

Oprogramowanie terminalowe dla Windows

HTerm: http://www.der-hammer.info/terminal/

Jak ustawić terminal HTerm

1. Ustaw właściwości połączenia tak, aby odpowiadały ustawieniom interfejsu TapHome Integration Protocol. (Uwaga: domyślna szybkość transmisji to 9600)
2. Ustaw Newline na znak LF
3. Ustaw Send on Enter: CR-LF
4. Wpisz polecenie (np. “HELP”)
5. Odczytaj odpowiedź

Uwaga: jeśli chcesz zobaczyć zmiany urządzeń TapHome w konsoli, użyj polecenia PUSHALL ON.

Debugowanie komunikacji TCP

W celu debugowania komunikacji TCP można użyć terminala Putty (https://putty.org/). Użyj następujących ustawień dla połączenia TCP:

Najpierw ustaw typ połączenia na Raw, a następnie wprowadź adres IP Core oraz port ustawiony w udostępnionych ustawieniach protokołu integracyjnego TCP.