Wyróżnik protokołu: ' [0x60] Protokół HOTELP.pdf

Transkrypt

1 Wyróżnik protokołu: ' [0x60] Plik: Protokół HOTELP.pdf Wersja protokołu: 9.00 Wersja dokumentu 17 kwiecień 2013

2 Historia wersji. Wersja Wersja Data Zmiany protokołu firmware Brak zmian w protokole. Opis działania protokołu HOTELP na połączeniach TCP/IP (LAN) Nowa ramka - informacja o statusie budzika ACS. Nowy parametr numer fizyczny translacji w ramce COR Nowe ramki: ustawianie komentarza abonenta SSC ustawianie lokalizacji abonenta SSO 2

3 Spis treści Historia wersji...2 Wstęp...4 Protokoły transmisyjne...5 Protokół transmisyjny wysyłania sygnalizacji HOTELP po RS Protokół transmisyjny przesyłania sygnalizacji HOTELP na połączeniach TCP/IP...6 Komunikaty sygnalizacji HOTELP...7 WHO [Who are you] Informacja o centrali...7 SPP1 [SetPulse Price 1] Ustaw cenę impulsu pierwszego operatora...8 SPP2 [Set Pulse Price 2] Ustaw cenę impulsu drugiego operatora...8 SVC [Set Vat Charge] Ustaw stawkę VAT...9 GSD [Get Subscriber Data] Żądanie pobrania rekordu danych abonenta...10 SLC [Subscriber Limit and Counter] Rekord danych abonenta...10 CSP [Clear Subscriber Payment] Skasowanie opłaty i wyzerowania licznika abonenta...11 SSL [Set Subscriber Limit] Ustaw limit abonenta...12 SSC [Set Subscriber Comment] Ustaw komentarz abonenta...12 SSO [Set Subscriber locale] Ustaw lokalizacje abonenta...12 SAC [Set Alarm Clock] Ustaw budzik abonenta...13 ACS [Alarm Clock Status] Aktualny stan budzika...13 GCF [Get Call From] Pobierz rozmowy od dnia...14 GNC [Get Next Call] Pobierz następną rozmowę...14 NCR [New Call Ready] Nowa rozmowa w buforze...16 RLA [Repeat Last Answer] Powtórz ostatnią odpowiedź...17 Załącznik Opis odpowiedzi OK, ERROR, NA, BUSY, WAIT, EMPTY...18 Załącznik Algorytm pobierania zarejestrowanych rozmów i stanów hotelowych z centrali...19 Załącznik Przykład programu w języku C odbioru ramki i liczenia sumy kontrolnej na łączu RS

4 Wstęp Sygnalizacja HOTELP przeznaczona jest do pobierania informacji o zrealizowanych rozmowach, zapamiętanych stanach hotelowych, ustawiania i kasowania limitów kosztów połączeń, ustawiania czasu budzenia. Komunikacja może odbywać się przez łącze RS 232 lub poprzez sieć Ethernet za pośrednictwem wbudowanego modułu LAN. Wszystkie komunikaty sygnalizacji telefonicznej wysyłane i odbierane są z wyróżnikiem protokołu 0x60 [`]. Parametry rozdzielone są separatorem. Separatorem jest znak (spacja). Maksymalny czas odpowiedzi na zapytanie wynosi 5sek Nieznane komunikaty od centrali powinny być ignorowane 4

5 Protokoły transmisyjne Protokół transmisyjny wysyłania sygnalizacji HOTELP po RS 232 Komunikacja odbywa się po łączu szeregowym z prędkością 4800b/s bez bitu parzystości, 8 bitów danych, 1 bit stopu. Centrala PBX dołączona jest do komputera TE (Terminal Equipment) pętlą prądową z optoizolacją. W celu zasilenia transoptorów należy ustawić sygnały sterujące: DTR stan aktywny tzn. polaryzacja dodatnia, RTS stan nieaktywny tzn. polaryzacja ujemna. Składnia ramki CTIP przesyłanej łączem RS232: Flaga Ilość bajtów pola danych CRC nagłówka Wyróżnik protokołu Komunikaty HOTELP CRC ramki a b c d e f 1 bajt 1 bajt 1 bajt 1 bajt (b-1) bajtów 1 bajt (0x02) x60 sygnalizacja HOTELP KOMUNIKAT lub ODPOWIEDŹ gdzie: Flaga - znacznik początku ramki postaci 0x02 Ilość bajtów pola danych - długość pola informacyjnego wraz z długością wyróżnika protokołu w bajtach (ilość bajtów pola informacyjnego +1) CRC nagłówka -suma kontrolna nagłówka liczona jako: c = ((a XOR 0xff)+b) XOR 0xFF, Wyróżnik protokołu Komunikaty HOTELP CRC ramki - znacznik identyfikujący protokół, 0x60 dla HOTELP - komunikat wysyłany lub odbierany od centrali według opisu komunikatów HOTELP - suma kontrolna ramki liczona od bajtu flagi do ostatniego bajtu pola informacyjnego, obliczona następująco: f = ((((((((c+d) XOR 0xFF)+e1) XOR 0xFF)+ + e2) XOR 0xFF)+...+en) XOR 0xFF) wszystkie składniki są sumowane modulo 0xff (bez przeniesienia) Przykład programu w języku C odbioru ramki i liczenia sumy kontrolnej zamieszczony jest w załączniku 2 5

6 Protokół transmisyjny przesyłania sygnalizacji HOTELP na połączeniach TCP/IP Składnia ramki HOTELP przesyłanej protokołem TCP/IP: Wyróżnik protokołu Komunikaty HOTELP Znacznik końca linii 1 bajt n bajtów 2 bajty 0x60 sygnalizacja HOTELP KOMUNIKAT lub ODPOWIEDŹ 0x0D, 0x0A gdzie: Wyróżnik protokołu Komunikaty HOTELP Znacznik końca linii - znacznik identyfikujący protokół, 0x60 dla HOTELP - komunikat wysyłany lub odbierany od centrali według opisu komunikatów sygnalizacji HOTELP - każda ramka zakończona jest dwoma bajtami znacznika końca linii tekstowej: "\r\n" = 0xD,0xA = CR,LF Transmisja na połączeniach TCP/IP jest możliwa tylko w przypadku gdy centrala wyposażona jest wyłącznie w moduł LAN. Sygnalizacja dla protokołu HOTELP jest dostępna na porcie Adres IP centrali wpisany jest w konfiguracji centrali lub może być znaleziony automatycznie w oparciu o protokół firmowy USRP. 6

7 Komunikaty sygnalizacji HOTELP WHO [Who are you] Informacja o centrali TE: WHO PBX: MAC-6400 NO99999 v4.07/ :17'43 lub PBX: CCT-1668 NO99999 v2.01/ :13,44 Parametry odpowiedzi: MAC typ centrali. wykonane, NO numer seryjny centrali, v4.07/07 -numer wersji programu centralowego / numer wersji protokołu, data centralowa, 09: czas centralowy, przecinek jako separator sekund oznacza czas zimowy, apostrof czas letni Uwaga: Komunikat ten powinien być pierwszym komunikatem wysyłanym do centrali. 7

8 SPP1 [SetPulse Price 1] Ustaw cenę impulsu pierwszego operatora TE: SPP PBX: OK Parametry: cena impulsu taryfikacyjnego pierwszego operatora OK, ERROR, NA patrz opis w załączniku 1 Protokół HOTELP SPP2 [Set Pulse Price 2] Ustaw cenę impulsu drugiego operatora TE: SPP PBX: OK Parametry: cena impulsu taryfikacyjnego drugiego operatora OK, ERROR, NA patrz opis w załączniku 1 8

9 SVC [Set Vat Charge] Ustaw stawkę VAT TE: SVC 22 PBX: OK Parametry: 22 -stawka podatku VAT w procentach OK, ERROR, NA patrz opis w załączniku 1 9

10 GSD [Get Subscriber Data] Żądanie pobrania rekordu danych abonenta TE: GSD 210_ PBX: SLC 210_ Portiernia : :99 R Parametry komunikatu GSD: 210_ - numer telefonu wewnętrznego. Zawsze cztery znaki np.231_, dopuszczalne znaki 0..9, _. SLC - rekord danych abonenta patrz opis poniżej ERROR, NA, WAIT, BUSY - patrz opis w załączniku 1 SLC [Subscriber Limit and Counter] Rekord danych abonenta PBX: SLC 210_ Portiernia : :99 R Parametry odpowiedzi SLC: 210_ - numer telefonu wewnętrznego. Zawsze cztery znaki np.231_, dopuszczalne znaki 0..9, _ Portiernia - komentarz nadany abonentowi przez serwis centrali. Pole ma długość 12 znaków. Jeśli komentarz jest krótszy lub występują w nim spacje centrala uzupełni znakami _ łączna wartość opłat za rozmowy od ostatniego kasowania licznika (Brutto) data ostatniego kasowania licznika, format MM.DD 15:30 - czas ostatniego kasowania licznika, format GG:MM limit kwoty, po przekroczeniu której abonent traci prawo do połączeń wychodzących, wartość powyżej 9900 wyłącza limitowanie opłaty, wartość 0000 powoduje wyłączenie telefonu, 99:99 - czas budzenia dla abonenta, format GG:MM, 99:99 spowoduje wyłączenie budzenia, R - stan w jakim znajduje się abonent, pole o długości 1 znaku, możliwe wartości: B busy (zajętość), R ready (wolny), O out of order (uszkodzony) Opis: Jest to odpowiedź na komunikat GSD. 10

11 CSP [Clear Subscriber Payment] Skasowanie opłaty i wyzerowania licznika abonenta TE: CSP 210_ PBX: OK Protokół HOTELP Parametry: 210_ - numer telefonu wewnętrznego. Zawsze cztery znaki np.231_, dopuszczalne znaki 0..9, _. OK, ERROR, NA patrz opis w załączniku 1 11

12 SSL [Set Subscriber Limit] Ustaw limit abonenta. TE: SSL 210_ 0100 PBX: OK Protokół HOTELP Parametry: 210_ - numer telefonu wewnętrznego. Zawsze cztery znaki np.231_, dopuszczalne znaki 0..9, _ limit abonenta brutto (0000 blokada wyjścia do miasta, 9999 bez limitu) OK, ERROR, NA patrz opis w załączniku 1 SSC [Set Subscriber Comment] Ustaw komentarz abonenta. TE: SSC 210_ Jan_Nowak PBX: OK Parametry: 210_ - numer telefonu wewnętrznego. Zawsze cztery znaki np.231_, dopuszczalne znaki 0..9, _. Jan_Nowak - komentarz abonenta, maksymalnie 26 znaków, podkreślnik '_' zastępuje spacje, znaki zabronione 0x00..0x19, '~'(tylda), ';'(średnik). OK, ERROR Od wersji protokołu: 9.00 SSO [Set Subscriber locale] Ustaw lokalizacje abonenta. TE: SSO 210_ 1 2 PBX: OK Parametry: 210_ - numer telefonu wewnętrznego. Zawsze cztery znaki np.231_, dopuszczalne znaki 0..9, _. 1 - preferowany język (menu CTS), zakres 0..2 (gdzie dla wersji polskiej 0-pl, 1-en 2-de) 2 - zestaw zapowiedzi systemowych, zakres 0..3 (0-domyślny zestaw z firmware centrali) OK, ERROR Od wersji protokołu:

13 SAC [Set Alarm Clock] Ustaw budzik abonenta. TE: SAC 210_ 21:15 PBX: OK Parametr: 210_ - numer telefonu wewnętrznego. Zawsze cztery znaki np.231_, dopuszczalne znaki 0..9, _. 21:15 - czas budzenia, format GG:MM. Kasowanie budzika 99:99 OK, ERROR, NA patrz opis w załączniku 1 ACS [Alarm Clock Status] Aktualny stan budzika. PBX: ACS 210_ S 21:15 Parametr: 210_ - numer telefonu wewnętrznego. Zawsze cztery znaki np.231_, dopuszczalne znaki 0..9, _. S - status budzenia: S Set (ustawienie budzika), C Clear (wyłączenie budzika), A Acknowledge (potwierdzenie zrealizowania usługi budzenia ), N No Acknowledge (usługa budzenia nie zrealizowana ), 21:15 - czas budzenia, format GG:MM, dotyczy tylko ustawienia (inne stany czas = 99:99) Opis: Asynchroniczna informacja o statusie budzika wysyłana jest tylko w czasie rzeczywistym (nie jest możliwe późniejsze pobranie informacji o potwierdzeniu budzenia). Status wysyłany od wersji 7.04 protokołu. 13

14 GCF [Get Call From] Pobierz rozmowy od dnia TE: GCF PBX: COR lub HSR lub EMPTY lub BUSY lub WAIT Parametry: data postaci rok.miesiąc.dzień, od której centrala ma rozpocząć wyszukiwanie zdarzeń w buforze COR - rekord rozmowy wychodzącej - miejskiej (patrz opis poniżej) HSR - rekord stanu hotelowego (patrz opis poniżej) EMPTY, BUSY, WAIT - patrz załącznik 1 GNC [Get Next Call] Pobierz następną rozmowę. TE: GNC PBX: COR lub HSR lub EMPTY lub BUSY lub WAIT lub NA COR - rekord rozmowy wychodzącej - miejskiej (patrz opis poniżej) HSR - rekord stanu hotelowego (patrz opis poniżej) EMPTY, BUSY, WAIT - patrz załącznik 1 NA - centrala nie może wysłać kolejnego rekordu, należy pobrać rozmowę zapytaniem GCF 14

15 COR [Call Outgoing Record] Rekord rozmowy wychodzącej- miejskiej PBX: COR :06 231_ Parametry: 00 - zawsze 00 po zaptaniu GCF, po zapytaniu GNC data zakończenia rozmowy postaci rok.miesiąc.dzeń, 18:06 - czas zakończenia rozmowy postaci godzina:minuta, 231_ - numer telefonu abonenta, z którego przeprowadzono rozmowę numer wybrany przez abonenta, jeśli ilość cyfr jest mniejsza niż 16, numer zostanie uzupełniony znakami _, ilość impulsów taryfikacyjnych naliczonych w czasie rozmowy, czas trwania rozmowy w sekundach, suma wynikająca z ilości zliczonych impulsów oraz parametrów SPP1, SPP2, SPV numer fizyczny translacji, po której zostało wykonane połączenie (od wersji 7.04) Opis: Jest to odpowiedź na komunikat GCF lub GNC. HSR [Hotel Status Record] Rekord zarejestrowanego stanu hotelowego PBX: HSR :15 223_ 1234*#5 Parametry: 00 - zawsze 00 po zaptaniu GCF, po zapytaniu GNC data zarejestrowania zmiany stanu hotelowego, 07:15 - czas zarejestrowania zmiany stanu, 223_ - numer telefonu abonenta, z którego przeprowadzono rozmowę, 1234*#5 - numer zarejestrowany usługą #82 (ustaw stan hotelowy) jako stan hotelowy, dostępne cyfry: 0.. 9, * i #. Opis: Jest to odpowiedź na komunikat GCF lub GNC. 15

16 NCR [New Call Ready] Nowa rozmowa w buforze PBX: NCR Protokół HOTELP Opis: Centrala wysyła do TE informację o każdej nowej zarejestrowanej rozmowie lub stanie hotelowym wysyłając komunikat NCR. 16

17 RLA [Repeat Last Answer] Powtórz ostatnią odpowiedź. TE: RLA PBX: LastFrame LastFrame -ostatnio nadana ramka odpowiedzi, ERROR, NA - patrz opis w załączniku 1 Protokół HOTELP Opis: Centrala ponownie wysyła do TE ostatnio nadaną ramkę odpowiedzi. Rozkaz służy do pobrania ramki po stwierdzeniu przekłamania transmisji (np. błędna suma kontrolna). Nie jest wysyłana ponownie ramka NCR 17

18 Załącznik 1 Opis odpowiedzi OK, ERROR, NA, BUSY, WAIT, EMPTY PBX: OK PBX: ERROR PBX: NA PBX: BUSY PBX: WAIT PBX: EMPTY - poprawnie wykonano zadany komunikat - gdy zapytanie lub parametry mają nieprawidłową składnie lub wartość - rozkaz niedostępny - jeśli centrala jest zajęta i nie może obsłużyć zapytania, należy ponowić zapytanie po 10 sekundach - centrala przygotowuje odpowiedź, należy czekać - jeśli centrala nie ma już żadnych rekordów do wysłania 18

19 Załącznik 2 Algorytm pobierania zarejestrowanych rozmów i stanów hotelowych z centrali. NCR START GNC Ustaw TIMEOUT 5 sek. BUSY WAIT COR HSR CRC ERROR Czekaj 10 sek. EMPTY TIMEOUT STOP Zapisz rozmowę lub stan hotelowy Szukaj zgodnego rekordu w swojej bazie danych (porównaj całe rekordy). Kasuj wszystkie rozmowy występujące za znalezioną. TAK TAK Czy zgodny numer IP+1 NIE Czy IP=0 NIE NA RLA Zeruj swój Id GCF (data ostatniej zarejestrowanej rozmowy) Algorytm pobierania danych z centrali 19

20 Załącznik 3 Przykład programu w języku C odbioru ramki i liczenia sumy kontrolnej na łączu RS 232 unsigned char bufor_ramki[255], unsigned char crc, unsigned char rodzaj_ramki, unsigned char dlugosc_ramki, unsigned char c, unsigned char i, unsigned char index, unsigned char CRC(unsigned char crc,unsigned char bajt) { return (crc+bajt)^0xff, } unsigned char OdbiorRamki(unsigned char *Buf) { index=0, //pierwszy bajt ramki - rodzaj c=buf[index++], if(c!=0x02) goto CzekajNaNaglowek, rodzaj_ramki=c, crc=crc(0,c), //drugi bajt ramki c=buf[index++], dlugosc_ramki=c, crc=crc(crc,c), - dlugosc //trzeci bajt ramki - crc naglowka c=buf[index++], if(c!=crc) goto CzekajNaNaglowek, //czwarty i nastepne bajty ramki - informacja for(i=0,i<dlugosc_ramki,i++) { c=buf[index++], bufor_ramki[i]=c, crc=crc(crc,c), } //ostatni bajt ramki - crc ramki c=buf[index++], if(c!=crc) goto CzekajNaNaglowek, return dlugosc_ramki,//odebrana ramka CzekajNaNaglowek: return 0,//brak odebranej ramki } 20