Wyróżnik protokołu: ' [0x60] Plik: Protokół HOTELP.pdf Wersja protokołu: 9.00 Wersja dokumentu 17 kwiecień 2013
Historia wersji. Wersja Wersja Data Zmiany protokołu firmware 7.02 - - Brak zmian w protokole. Opis działania protokołu HOTELP na połączeniach TCP/IP (LAN) 8.00 4.08 27.10.2010 Nowa ramka - informacja o statusie budzika ACS. Nowy parametr numer fizyczny translacji w ramce COR. 9.00 6.20 17.04.2013 Nowe ramki: ustawianie komentarza abonenta SSC ustawianie lokalizacji abonenta SSO 2
Spis treści Historia wersji...2 Wstęp...4 Protokoły transmisyjne...5 Protokół transmisyjny wysyłania sygnalizacji HOTELP po RS 232...5 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 1...18 Opis odpowiedzi OK, ERROR, NA, BUSY, WAIT, EMPTY...18 Załącznik 2...19 Algorytm pobierania zarejestrowanych rozmów i stanów hotelowych z centrali...19 Załącznik 3...21 Przykład programu w języku C odbioru ramki i liczenia sumy kontrolnej na łączu RS 232...21 3
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
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) 0-250 0x60 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
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 5527. Adres IP centrali wpisany jest w konfiguracji centrali lub może być znaleziony automatycznie w oparciu o protokół firmowy USRP. 6
Komunikaty sygnalizacji HOTELP WHO [Who are you] Informacja o centrali TE: WHO PBX: MAC-6400 NO99999 v4.07/07 2010.10.27 09:17'43 lub PBX: CCT-1668 NO99999 v2.01/07 2005.12.24 02:13,44 Parametry odpowiedzi: MAC-6400 -typ centrali. wykonane, NO99999 -numer seryjny centrali, v4.07/07 -numer wersji programu centralowego / numer wersji protokołu, 2010.10.27 -data centralowa, 09:17 43 -czas centralowy, przecinek jako separator sekund oznacza czas zimowy, apostrof czas letni Uwaga: Komunikat ten powinien być pierwszym komunikatem wysyłanym do centrali. 7
SPP1 [SetPulse Price 1] Ustaw cenę impulsu pierwszego operatora TE: SPP1 0.24 PBX: OK Parametry: 0.24 -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: SPP2 0.18 PBX: OK Parametry: 0.18 -cena impulsu taryfikacyjnego drugiego operatora OK, ERROR, NA patrz opis w załączniku 1 8
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
GSD [Get Subscriber Data] Żądanie pobrania rekordu danych abonenta TE: GSD 210_ PBX: SLC 210_ Portiernia 0001.24 12.31 15:30 1234 99: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 0001.24 12.31 15:30 1234 99: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 _. 0001.24 - łączna wartość opłat za rozmowy od ostatniego kasowania licznika (Brutto). 12.31 - data ostatniego kasowania licznika, format MM.DD 15:30 - czas ostatniego kasowania licznika, format GG:MM 1234 - 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
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
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, _. 0100 - 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: 9.00 12
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
GCF [Get Call From] Pobierz rozmowy od dnia TE: GCF 1999.07.01 PBX: COR lub HSR lub EMPTY lub BUSY lub WAIT Parametry: 1999.07.01 - 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
COR [Call Outgoing Record] Rekord rozmowy wychodzącej- miejskiej PBX: COR 00 1999.08.01 18:06 231_ 06021234 0025 00247 0123.45 2701 Parametry: 00 - zawsze 00 po zaptaniu GCF, - 01...99 po zapytaniu GNC 1999.08.01 - 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ę. 06021234 - numer wybrany przez abonenta, jeśli ilość cyfr jest mniejsza niż 16, numer zostanie uzupełniony znakami _, 0025 - ilość impulsów taryfikacyjnych naliczonych w czasie rozmowy, 00247 - czas trwania rozmowy w sekundach, 0123.45 - suma wynikająca z ilości zliczonych impulsów oraz parametrów SPP1, SPP2, SPV. 2701 - 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 00 1999.09.01 07:15 223_ 1234*#5 Parametry: 00 - zawsze 00 po zaptaniu GCF, - 01...99 po zapytaniu GNC 1999.09.01 - 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
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
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
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
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
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