Sterbox 4.1.0 A P I
Transkrypt
Sterbox 4.1.0 A P I
Sterbox API od wersji 4.1.0 1. Media komunikacyjne. Media fizyczne: LAN, RS-485 LAN RS-485 Bezpośrednia komunikacja protokołem Sterbox. Niezbędna „widoczność” adresów IP. Połączenie TCP/IP z ponawianiem pakietów. Tak Tak/* Aplikacja „Sterbox PC” (OS: Windows – bez mobile, iOS, Android). Aplikacja podstawia serwer na „localhost”. Opis w „Program PC” Tak Nie Poprzez e-mail, protokołem Sterbox *uproszczony, patrz opis szczegółowy Tak Nie Sterbox 4.1.0 API 2. Zasoby Sterbox służące do komunikacji. W Sterboxie do odbioru i wysyłania informacji o sygnałach cyfrowych oraz wartości analogowych używa się makrocel: „Terminal porty cyfrowe”, „Terminal porty analogowe” oraz tablic zmiennych tekstowych i liczbowych. Typ Ilość makrocel Ilość makrocel Tabela Tabela zmiennych liczbowych Sterb terminali terminali zmiennych oxa cyfrowych analogowych tekstowych WPTC 8 makrocel, w 8 makrocel, w 127 i każdej 8 wejść każdej 8 wejść zmiennych WPTD i 8 wyjść i 8 wyjść po 256 znaków (bajtów) każda 64 zmienne, wartość może przyjmować od -40265,0000 do +40264,9999. WCTC * i WCTD * w przyszłości. * * * Dostęp do Sterboxa na jego adresie IP i porcie (Ustawienia generalne, Port Ster) standardowo: 7080. W sieci RS-485 dostęp bezpośredni. Hasło sterowania ustawiane również w Ustawienia generalne. Po wprogramowaniu jakiejkolwiek makroceli terminala Sterbox na RS-485 wysyła okresowo pakiet rozgłoszeniowy. 3 Protokół komunikacyjny. Nagłówek Bajt Wartość Opis 0x00 0xD5 Synchro 0x01 0x80 Kod nowego polecenia 0x02 0x0D Ilość danych nagłówka 0x03 0x Hash hasła dostępu Strona 1 Sterbox API od wersji 4.1.0 0x04 0x 0x05 0x 0x06 0x 0x07 0xHL 0x08 opcje nadawcy i odbiorcy ( 0x0 - sterbox, 0x1 - klawiatura, 0x2 - wyświetlacz, 0x3 - ramon, 0xF - wszyscy ) (nibel H>nadawca, nibel L->odbiorca) numer sprzętowy (fabryczny) nadawcy 0x09 0x0A numer sprzętowy (fabryczny) odbiorcy ( 0xFFFF - adres rozgłoszeniowy ) (za pierwszym razem 0xFFFF, potem odebrany ze STB) 0x0B 0x0C 0x0D kod rozkazu (od 0x50 do 0x57 bo 8 terminali<-makrocel w STB, kierunek ze STB do terminala, w drugim kierunku 0x40 do 0x47 ) 0x0D lub 0x01 opcje rozkazu wartość 0x0D – oblicz i sprawdź CRC32, ) 0x01 – ignoruj CRC32 ← tylko dla RS-485 0x0E ilość danych h 0x0F ilość danych l 0x10 CRC32 0x11 0x12 0x13 0x14 0x00 do 0x07 Ilość makrocel z którymi jest wymieniana komunikacja, pierwsza zaadresowana w bajt nagłówka 0x0C Wymiana danych z makrocelami terminali cyfrowych i analogowych, ta paczka bajtów jest powtarzana tyle razy ile określono w bajcie 0x00 poniższej tabeli. 0x00 0x01 0x02 0x03 0x04 Stan wejść (Sterbox → terminal) lub wyjść (terminal → Sterbox) makroceli, interpretacja bitowa 0x00 do 0x4 Operacja na bitach odbiornika: 0x00 → nic nie rób, 0x01 → wpisz wprost, 0x02 → OR, 0x03 → AND, 0x04 → XOR Makrocela analogowa, wejście 1 (Sterbox → terminal) / wyjście 1 (terminal → Sterbox), 32 bity ze znakiem, stały przecinek, 4 znaki po przecinku 0x05 0x06 0x07 0x08 Makrocela analogowa, wejście 2 (Sterbox → terminal) / wyjście 2 (terminal → Sterbox), 32 bity ze znakiem, stały przecinek, 4 znaki po przecinku 0x09 Strona 2 Sterbox API od wersji 4.1.0 0x0A Makrocela analogowa, wejście 3 (Sterbox → terminal) / wyjście 3 (terminal → Sterbox), 32 bity ze znakiem, stały przecinek, 4 znaki po przecinku 0x0B 0x0C 0x0D 0x0E Makrocela analogowa, wejście 4 (Sterbox → terminal) / wyjście 4 (terminal → Sterbox), 32 bity ze znakiem, stały przecinek, 4 znaki po przecinku 0x0F 0x10 0x11 0x12 Makrocela analogowa, wejście 5 (Sterbox → terminal) / wyjście 5 (terminal → Sterbox), 32 bity ze znakiem, stały przecinek, 4 znaki po przecinku 0x13 0x14 0x15 0x16 Makrocela analogowa, wejście 6 (Sterbox → terminal) / wyjście 6 (terminal → Sterbox), 32 bity ze znakiem, stały przecinek, 4 znaki po przecinku 0x17 0x18 0x19 0x20 Makrocela analogowa, wejście 7 (Sterbox → terminal) / wyjście 7 (terminal → Sterbox), 32 bity ze znakiem, stały przecinek, 4 znaki po przecinku 0x21 0x22 0x23 0x24 Makrocela analogowa, wejście 8 (Sterbox → terminal) / wyjście 8 (terminal → Sterbox), 32 bity ze znakiem, stały przecinek, 4 znaki po przecinku 0x25 0x26 0x27 0x28 Operacja dla portów analogowych. Kolejne bity od MSB, 0 – nic nie rób, 1 – wpisz wprost, określają sposób potraktowania danych wejść/wyjść od 1 do 8. 0x29 0x00 Zawsze 0x00 Operacje na tablicach Kod roz Kod odpKoKod błędu Opis Opcje 0x16 0x17 Odczyt zmiennej numerycznej sterbox-a Odczyt zmiennej tekstowej sterbox-a Numer zmiennej Numer zmiennej 0x46 0x47 0x08 + 0x00 0x08 + 0x00 Strona 3 Sterbox API od wersji 4.1.0 4. Opis serwera wewnętrznego programu "Sterbox_PC" wersji 4.1.0 1. Dostęp do sterbox-ów. W ustawieniach programu można zdefiniować do czterech sterbox-ów. Z poziomu serwera wewnętrznego uzyskujemy dostęp do poszczególnych sterboxów poprzez wybór nazwy bramy „cgi” zgodnie z poniższą tabelą. Nazwa bramy Sterbox sterbox.cgi Domyślny sterbox czyli pierwszy z konfiguracji sterbox1.cgi Pierwszy sterbox z konfiguracji sterbox2.cgi Drugi sterbox z konfiguracji sterbox3.cgi Trzeci sterbox z konfiguracji sterbox4.cgi Czwarty sterbox z konfiguracji Komunikację ze sterbox-em należy realizować metodą „POST”. Poniżej przykład do JavaScript. var request = new XMLHttpRequest (); var text = "<d0=l>"; request.open ("POST","sterbox.cgi",true); request.setRequestHeader ("Content-Type", "application/x-www-form-urlencoded"); request.onreadystatechange = function () { if ( request.readyState == 4) { test = request.responseText; } } request.send (text); 2. Dostęp do zasobów sterbox-a. Poprzez wewnętrzny serwer możemy wymieniać dane w oparciu o makrocele terminalowe sterbox-a. W sterbox-ie można aktualnie wprogramować do ośmiu makroceli terminalowych cyfrowych i ośmiu makroceli analogowych. Wymiana danych wygląda następująco w sensie chronologiocznym: • formatujemy polecenie dla sterbox-a z informacjami o stanach cyfrowych i analogowych dla wyjść terminalowych makroceli. • przekazujemy polecenie do bramy „cgi”. • z bramy „cgi” otrzymujemy informację o poprzednim stanie wejść terminalowych makroceli. • serwer komunikuje się ze sterbox-em i wysyła nowe stany wyjść makroceli terminalowych i jednocześnie odbiera stany wejść które będą dostępne przy kolejnej wymianie informacji z bramą „cgi”. Tak więc należy pamiętać, że informacje z wejść makroceli terminalowych są opóźnione o jeden cykl wymiany danych ze sterbox-em. Najlepszym rozwiązaniem jest ciągła wymiana danych celem odświeżania danych wejściowych. Możemy również uzyskać ze sterbox-a stany zmiennych numerycznych i tekstowych. Zmiana stanu zmiennych w sterbox-ie jest bardzo prosta, wysyłamy do bramy „cgi” odpowiednio sformatowane polecenie. Odczyt jest trochę bardziej skomplikowany ponieważ musimy wymusić na serwerze odpowiednim poleceniem odczytanie zmiennej ze sterbox-a. Aktualna zawartość zmiennej jest dostępna dopiero po fizycznym odczycie jej ze sterbox-a, czyli po chwili. Strona 4 Sterbox API od wersji 4.1.0 Należy pamiętać jeszcze o jednej kwestii. Wysłanie polecenia dla wyjść konkretnej makroceli terminalowej powoduje zawsze wygenerowanie zwrotnej informacji o stanie wejść makroceli. Jeżeli chcemy tylko odczytywać dane musimy użyć polecenia wymuszającego odczyt stanów wejść. Polecenia wymuszania odczytu: Polecenie od zakresu Polecenie do zakresu Opis <m0?> <m7?> Wymuszenie odczytu stanu wejść makroceli terminalowej 1 do 8. <t0?> <t126?> Wymuszenie odczytu zmiennej tekstowej sterbox-a od 0 do 126. <n0?> <n63?> Wymuszenie odczytu zmiennej numerycznaj sterbox-a od 0 do 63. Polecenia sterujące i zwrotne informacje o stanie wejść-wyjść cyfrowych: Polecenie od zakresu Polecenie do zakresu Opis <d0=l> lub <d0=h> <d7=l> lub <d7=h> Makrocela terminalowa 1 sterowanie wyjściami i stan wejść. <d8=l> lub <d8=h> <d15=l> lub <d15=h> Makrocela terminalowa 2 sterowanie wyjściami i stan wejść. <d16=l> lub <d16=h> <d23=l> lub <d23=h> Makrocela terminalowa 3 sterowanie wyjściami i stan wejść. <d24=l> lub <d24=h> <d31=l> lub <d31=h> Makrocela terminalowa 4 sterowanie wyjściami i stan wejść. <d32=l> lub <d32=h> <d39=l> lub <d39=h> Makrocela terminalowa 5 sterowanie wyjściami i stan wejść. <d40=l> lub <d40=h> <d47=l> lub <d47=h> Makrocela terminalowa 6 sterowanie wyjściami i stan wejść. <d48=l> lub <d48=h> <d55=l> lub <d55=h> Makrocela terminalowa 7 sterowanie wyjściami i stan wejść. Strona 5 Sterbox API od wersji 4.1.0 <d56=l> lub <d56=h> <d63=l> lub <d63=h> Makrocela terminalowa 8 sterowanie wyjściami i stan wejść. Polecenia sterujące i zwrotne informacje o stanie wejść-wyjść analogowych: Polecenie od zakresu Polecenie do zakresu Opis <a0=wartość> <a7=wartość> Makrocela terminalowa 1 sterowanie wyjściami i stan wejść. <a8=wartość> <a15=wartość> Makrocela terminalowa 2 sterowanie wyjściami i stan wejść. <a16=wartość> <a23=wartość> Makrocela terminalowa 3 sterowanie wyjściami i stan wejść. <a24=wartość> <a31=wartość> Makrocela terminalowa 4 sterowanie wyjściami i stan wejść. <a32=wartość> <a39=wartość> Makrocela terminalowa 5 sterowanie wyjściami i stan wejść. <a40=wartość> <a47=wartość> Makrocela terminalowa 6 sterowanie wyjściami i stan wejść. <a48=wartość> <a55=wartość> Makrocela terminalowa 7 sterowanie wyjściami i stan wejść. <a56=wartość> <a63=wartość> Makrocela terminalowa 8 sterowanie wyjściami i stan wejść. Polecenia sterujące i zwrotne informacje o stanie zmiennych tekstowych: Polecenie od zakresu Polecenie do zakresu Opis <t0=tekst> <t126=tekst> Stan zmiennej tekstowej. Uwaga na kodowanie znaków. W poleceniu można przekazać bezpośrednio kody znaków tylko z zakresu 0x20 do 0x7F. Znaki spoza zakresów zarówno przy zapisie jak i odczycie są przesyłane za pomocą kodów hex zapisanych jak poniżej. Tekst poniżej zawiera znak o kodzie 0x80 i 0x0D oraz 0x0A <t0=Tekst \80 zawiera zakodowane znaki\0D\0A> Polecenia sterujące i zwrotne informacje o stanie zmiennych numerycznych: Polecenie od zakresu Polecenie do zakresu Opis <n0=wartość> <n63=wartość> Stan zmiennej numerycznej. Strona 6