Wyróżnik protokołu: ' [0x60] Plik: Protokół HOTELP.pdf Wersja protokołu: 9.00 Wersja dokumentu 22 sierpnia 2017
Historia wersji. Wersja protokołu Data Zmiany 7.02 - - - 8.00 4.08-27.10.2010 9.00 6.20-17.04.2013 9.00-1.09 14.06.2017 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 Nowa ramka ustawianie komentarza abonenta SSC Wykaz stosowanych oznaczeń dotyczy central: CCT, CXS, MAC, IPL, IPM, IPU, IPS dotyczy central: CCT, CXS, MAC, IPL, IPM, IPU, IPS oraz NCP dotyczy tylko centrali NCP 2
Spis treści Historia wersji...2 Wykaz stosowanych oznaczeń...2 Wstęp...4 SPP1 [SetPulse Price 1]...4 SPP2 [Set Pulse Price 2]...4 SVC [Set Vat Charge]...4 SSC [Set Subscriber Comment]...4 SSO [Set Subscriber locale]...4 Protokół transmisyjny przesyłania sygnalizacji HOTELP na połączeniach TCP/IP...5 Komunikaty sygnalizacji HOTELP...6 WHO [Who are you] Informacja o centrali...6 SPP1 [SetPulse Price 1] Ustaw cenę impulsu pierwszego operatora...7 SPP2 [Set Pulse Price 2] Ustaw cenę impulsu drugiego operatora...7 SVC [Set Vat Charge] Ustaw stawkę VAT...8 GSD [Get Subscriber Data] Żądanie pobrania rekordu danych abonenta...9 SLC [Subscriber Limit and Counter] Rekord danych abonenta...9 CSP [Clear Subscriber Payment] Skasowanie opłaty i wyzerowania licznika abonenta...10 SSL [Set Subscriber Limit] Ustaw limit abonenta...11 SSC [Set Subscriber Comment] Ustaw komentarz abonenta...11 SSO [Set Subscriber locale] Ustaw lokalizacje abonenta...11 SAC [Set Alarm Clock] Ustaw budzik abonenta...12 ACS [Alarm Clock Status] Aktualny stan budzika...12 GCF [Get Call From] Pobierz rozmowy od dnia...13 GNC [Get Next Call] Pobierz następną rozmowę...13 COR [Call Outgoing Record] Rekord rozmowy wychodzącej- miejskiej...14 HSR [Hotel Status Record] Rekord zarejestrowanego stanu hotelowego...14 NCR [New Call Ready] Nowa rozmowa w buforze...15 RLA [Repeat Last Answer] Powtórz ostatnią odpowiedź...16 Załącznik 1...17 Opis odpowiedzi OK, ERROR, NA, BUSY, WAIT, EMPTY...17 Załącznik 2...18 Algorytm pobierania zarejestrowanych rozmów i stanów hotelowych z centrali...18 3
Wstęp Sygnalizacja HOTELP przeznaczona jest do pobierania informacji o zrealizowanych rozmowach wychodzących, 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 Komendy nieobsługiwane przez centralę NCP SPP1 [SetPulse Price 1] SPP2 [Set Pulse Price 2] SVC [Set Vat Charge] SSO [Set Subscriber locale] Ustawienie ceny impulsu pierwszego operatora Ustawienie ceny impulsu drugiego operatora Ustawienie stawki VAT Ustaw lokalizacje abonenta. 4
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 (hex) 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. 5
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: NCP-000 NO00001 v1.07.0100/09 2016.06.22 13:34'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. 6
SPP1 [SetPulse Price 1] Ustaw cenę impulsu pierwszego operatora Protokół HOTELP TE: SPP1 0.24 PBX: OK 0.24 -cena impulsu taryfikacyjnego pierwszego operatora OK, ERROR, NA patrz opis w załączniku 1 SPP2 [Set Pulse Price 2] Ustaw cenę impulsu drugiego operatora TE: SPP2 0.18 PBX: OK 0.18 -cena impulsu taryfikacyjnego drugiego operatora OK, ERROR, NA patrz opis w załączniku 1 7
SVC [Set Vat Charge] Ustaw stawkę VAT TE: SVC 22 PBX: OK 22 -stawka podatku VAT w procentach OK, ERROR, NA patrz opis w załączniku 1 8
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. 9
CSP [Clear Subscriber Payment] Skasowanie opłaty i wyzerowania licznika abonenta Protokół HOTELP TE: CSP 210_ PBX: OK 210_ - numer telefonu wewnętrznego. Zawsze cztery znaki np.231_, dopuszczalne znaki 0..9, _. OK, ERROR, NA patrz opis w załączniku 1 10
SSL [Set Subscriber Limit] Ustaw limit abonenta. Protokół HOTELP TE: SSL 210_ 0100 PBX: OK 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 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 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 11
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. 12
GCF [Get Call From] Pobierz rozmowy od dnia TE: GCF 1999.07.01 PBX: COR lub HSR lub EMPTY lub BUSY lub WAIT 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 13
COR [Call Outgoing Record] Rekord rozmowy wychodzącejmiejskiej PBX: COR 00 1999.08.01 18:06 231_ 06021234 0025 00247 0123.45 2701 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 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. 14
NCR [New Call Ready] Nowa rozmowa w buforze Protokół HOTELP PBX: NCR Opis: Centrala wysyła do TE informację o każdej nowej zarejestrowanej rozmowie lub stanie hotelowym wysyłając komunikat NCR. 15
RLA [Repeat Last Answer] Powtórz ostatnią odpowiedź. Protokół HOTELP TE: RLA PBX: LastFrame LastFrame -ostatnio nadana ramka odpowiedzi, ERROR, NA - patrz opis w załączniku 1 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 16
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 17
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 TAK Czy zgodny numer IP+1 Szukaj zgodnego rekordu w swojej bazie danych (porównaj całe rekordy). Kasuj wszystkie rozmowy występujące za znalezioną. TAK Czy IP=0 NIE NIE NA RLA Zeruj swój Id GCF (data ostatniej zarejestrowanej rozmowy) Algorytm pobierania danych z centrali 18