Oprogramowanie HALO Smart Sensor API Oprogramowanie podstawowe
Do przodu
Niniejszy dokument opisuje grupę funkcji Halo Smart Sensor znanych zbiorczo jako BASIC API lub Application Programming Interface. Niniejsza dyskusja jest przeznaczona dla programistów lub integratorów zainteresowanych integracją jednego lub większej liczby czujników HALO Smart Sensors (HALO) z komponentami oprogramowania lub systemami stron trzecich (innymi niż IPVideo). Zasadniczo API HALO ma na celu wydajne przesyłanie informacji z HALO przez konwencjonalną sieć Ethernet do programu zewnętrznego. Aby osiągnąć ten cel, API jest podzielone na trzy sekcje: Event Driven Socket Connection, Heartbeat Socket Connection i Event Data URLInterfejs BACnet jest również obecny i omówiony w oddzielnym dokumencie.
Projektowanie API
Interfejs API jest zaprojektowany przy użyciu standardowych formatów branżowych, takich jak TCP/IP, HTTP, HTTPS i JSON. Projekt nie wymaga żadnych specjalnych lub zastrzeżonych technik lub bibliotek do wykorzystania w rozwoju zewnętrznego programu lub aplikacji. Interfejs API jest elastyczny i można go skonfigurować i zaprogramować tak, aby dostarczał dokładnie wymagane dane i w najbardziej wydajny sposób. Szczegóły działania każdej z powyższych sekcji są omówione w kolejnych sekcjach tego przewodnika.
Wiadomości zewnętrzne
Ta funkcja służy do dostarczania alertów lub alarmów i danych zdarzeń do zewnętrznego programu, systemu VMS, serwera itp., gdy zdarzenie jest wyzwalane (ustawiane). Opcjonalne wiadomości mogą być również włączone, aby sygnalizować, gdy zdarzenie zostanie wyczyszczone (zresetowane). Ta dostawa może być realizowana do gniazda TCP/IP lub serwera HTTP/S w czasie rzeczywistym. Istnieje szereg konfigurowalnych protokołów z dostosowywalną zawartością. Dostępne są uwierzytelnianie i szyfrowanie.
Bicie serca
Wiadomości Heartbeat są wysyłane w konfigurowalnym odstępie czasu (zamiast, gdy wyzwalane są zdarzenia), aby zapewnić dowód na żywo/dostępności. Mają podobny zakres możliwości jak wiadomości zewnętrzne, ale zazwyczaj są skonfigurowane tak, aby zawierały ogólne informacje o stanie, a nie szczegóły dotyczące konkretnego zdarzenia.
Dane zdarzenia URL
Ta funkcja jest dostępna tylko na podstawie umowy NDA i powinna być używana tylko wtedy, gdy program zewnętrzny wymaga dostępu do dowolnych i wszystkich wartości zdarzeń, progów i flag stanu. Te dane są zazwyczaj pobierane na żądanie przez program zewnętrzny, ale nie z bardzo dużą częstotliwością. Ta metoda zazwyczaj powoduje pewne opóźnienie, gdy używana jest umiarkowana częstotliwość odpytywania. Typowe częstotliwości odpytywania wahają się od jednej na minutę do jednej na 5 sekund, przy czym maksymalna częstotliwość wynosi raz na sekundę. Ta metoda może być również używana do pobierania dodatkowych danych pomocniczych, gdy zostanie odebrane zdarzenie (alert).
Szczegóły wiadomości zewnętrznych
Fragment HALO web Okno dialogowe integracji interfejsu umożliwia konfigurację pojedynczego połączenia stron trzecich, w którym różne wartości mogą być wysyłane do zdalnego gniazda TCP lub serwera HTTP/HTTPS. Symbole zastępcze (tokeny) służą do wstawiania wartości na żywo do przesyłanego tekstu. Chociaż kanał ten jest oznaczony jako „Zewnętrzne wiadomości”, można go używać do niemal każdego celu wymagającego wyzwalaczy zdarzeń w czasie rzeczywistym, aktywnie dostarczanych przez HALO. Ten układ jest dość elastyczny, ponieważ wybory w „Akcjach” określają, które zdarzenia HALO są przesyłane przez ten kanał.
W trybie HTTP ciągi Set i Reset to URLs, które muszą zostać wprowadzone i sformatowane zgodnie z wymaganiami żądanego serwera docelowego. Pole Użytkownik i Hasło może być użyte do uwierzytelnienia. Zobacz tryb HTTP poniżej.
W trybie TCP ciągi Set i Reset to tylko dane pojedynczej wiadomości, która jest wysyłana do gniazda TCP odbiorcy. Mogą być formatowane według potrzeb przez miejsce docelowe. Miejsce docelowe jest określone w polach Address i Port. Zobacz poniżej TCP Mode.
W obu trybach wyświetlany jest status z ostatniej wiadomości, co może pomóc w naprawie połączenia lub innych problemów. Możesz użyć przycisków Event TEST w wyskakującym okienku Actions, aby wymusić wiadomość:
Global On/Off dla Set lub Reset musi być włączony, aby włączyć te typy wiadomości. Reset często nie jest używany, ponieważ tylko początek zdarzenia jest interesujący, ale to może się różnić. Każde zdarzenie może niezależnie określać, czy będzie używać wiadomości Set czy Reset w wyskakującym okienku Actions. Przyciski z gałką oczną wyświetlą przybliżoną reprezentację tego, co jest wysyłane po podstawieniach słów kluczowych i formatowaniu. Repeat Holdoff może być używany do ograniczania częstych wiadomości poprzez opóźnianie przed wysłaniem kolejnej. Odbywa się to niezależnie dla każdego zdarzenia. HALO ma wbudowany czas wstrzymania dla zdarzeń wynoszący 15 sekund, aby zapobiec szybkiemu ponownemu wyzwalaniu zdarzeń. Jeśli chcesz mieć pewność, że nie więcej niż 1 zdarzenie danego typu jest wysyłane na minutę, możesz ustawić Repeat Holdoff na 60 (sekund).
Szczegóły bicia serca
Transmisje Heartbeat działają w podobny sposób jak powyżej, z tą różnicą, że nie ma interakcji ze stroną Akcje. Zamiast tego transmisja Heartbeat odbywa się regularnie, zgodnie z konfiguracją pola Interval. W trybie HTTP ciągi Set i Reset są URLs, które muszą zostać wprowadzone i sformatowane zgodnie z wymaganiami żądanego serwera docelowego. Pole Użytkownik i Hasło może być użyte do uwierzytelnienia. Zobacz tryb HTTP poniżej.
Chociaż głównym celem Heartbeat jest dostarczenie dowodu żywotności inteligentnego czujnika HALO do zdalnej aplikacji, ta wiadomość może być również używana do przesyłania wybranych czujników lub bieżących informacji o stanie zdarzenia.amppowyższy kod wysyła długi parametr ciągu z URL zawierające nazwę Halo, większość wartości czujników i na koniec Triggered=%ACTIVE%, które może być puste lub zawierać listę aktualnie wyzwolonych zdarzeń.
Tryb HTTP (i HTTPS)
Zewnętrzne komunikaty i ciągi Heartbeat mogą mieć postać http: lub https: URLs w razie potrzeby. Ścieżka i parametry mogą być wprowadzane w razie potrzeby przez serwer docelowy. Słowa kluczowe, takie jak %NAME% (nazwa urządzenia HALO) lub %EID% (identyfikator zdarzenia), mogą być wstawiane w razie potrzeby i zostaną zastąpione odpowiednimi danymi podczas wysyłania wiadomości. Lista powszechnie używanych słów kluczowych jest wyświetlana w celu szybkiego odniesienia.
Ten URL ścieżka może zawierać słowa kluczowe, jak również parametry URLParametrami mogą być pary NAZWA=WARTOŚĆ lub obiekt JSON, lub niestandardowy format w zależności od serwera docelowego. Np.ampPliki dla komunikatów zewnętrznych będą zawierać %EID% wskazujący zdarzenie, które zostało wyzwolone:
- https://server.com/event/%NAME%/%EID%
- https://server.com/event?location=%NAME%&event=%EID%
- https://server.com/event?{“location”:”:%NAME%”,”event”:”%EID%”}
ExampPliki dla Heartbeat mogą dodać %ACTIVE% (aktualnie wyzwolone zdarzenia) lub wartość czujnika:
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Wartości %SENSOR:…% używają nazw znalezionych w nagłówkach prawej kolumny czujnika w pliku dziennika evtYYYYMMDD.csv files. Są to zazwyczaj:
Jeśli serwer docelowy preferuje żądania HTTP PUT lub POST zamiast GET, możesz dodać prefiks URL za pomocą PUT: lub POST:. Niezależnie możesz dodać ładunek JSON, który jest popularny na wielu serwerach, dodając słowo kluczowe [JSONBODY], a następnie obiekt w formacie JSON. Np.ampna:
PUT:https://server.com/event[JSONBODY]{“location”:”%NAME%”,”event”:”%EID%”}
Ten URL obsługuje typowe opcje adresu IP (oraz IPv6), portu i hasła użytkownika lub możesz użyć pól Użytkownik i Hasło, jeśli to konieczne, jako serwera docelowego dla metod uwierzytelniania, takich jak Podstawowa lub Digest:
https://username:password@123.321.123.321:9876/event…
Tryb TCP
Zewnętrzne komunikaty i ciągi Heartbeat są przeznaczone tylko do danych, ponieważ pola Address i Port określają miejsce docelowe. Address obsługuje nazwy, IPv4 i IPv6.
Ciąg znaków może być sformatowany tak jak fragmenty danych wiadomości HTTP opisane powyżej lub zgodnie z wymaganiami serwera docelowego.
ExampPliki dla komunikatów zewnętrznych będą zawierać %EID% wskazujący zdarzenie, które zostało wyzwolone:
lokalizacja=%NAME%,wydarzenie=%EID%
{„lokalizacja”:”:%NAME%”,”wydarzenie”:”%EID%”}
ExampPliki dla Heartbeat mogą dodać %ACTIVE% (aktualnie wyzwolone zdarzenia) lub wartość czujnika:
lokalizacja=%NAME%&Wyzwalane=%ACTIVE%
{„lokalizacja”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Pola wyboru w kolumnach „Integration Set” i „Integration Reset” określają, które zdarzenia wyzwalają wysyłanie. Więcej informacji na temat konfiguracji zdarzeń i akcji można znaleźć w Podręczniku administratora HALO.
Dostarczanie komunikatów zdarzeń JSON
Niektórzy deweloperzy wolą otrzymywać dane zdarzeń sformatowane jako standardowy w branży samooznaczony JSON zamiast zwykłego tekstu ASCII, ponieważ ten pierwszy jest bardziej niezawodny i łatwiejszy do przeanalizowania. W przypadku HALO web na karcie „Wiadomości” możesz dostarczać wiadomości JSON w ustawieniach „Wiadomości zewnętrznych” „Ustaw ciąg” i „Resetuj ciąg” oraz w „Heartbeat” „Wiadomość”.
Examples:
Ustawienia „Wiadomości zewnętrznych” Ustaw ciąg:
{ „urządzenie”:”%NAME%”, „zdarzenie”:”%EID%”, „alarm”:”tak” }
Spowoduje to wysłanie pojedynczej wiadomości JSON TCP lub UDP do określonego serwera, zawierającej nazwę przyjaznego urządzenia, nazwę zdarzenia oraz informację o jego uruchomieniu.
Ustawienia „Wiadomości zewnętrznych” Resetuj ciąg:
{ „urządzenie”:”%NAME%”, „zdarzenie”:”%EID%”, „alarm”:”nie” }
Spowoduje to wysłanie pojedynczej wiadomości JSON TCP lub UDP do określonego serwera, w której podana zostanie nazwa przyjaznego urządzenia, nazwa zdarzenia oraz informacja, że stan został zatrzymany.
Wiadomość „Heartbeat”:
{ „urządzenie”:”%NAME%”, „żywy”:”%DATE% %TIME%” }
Spowoduje to okresowe wysyłanie wiadomości JSON TCP lub UDP do określonego serwera informującej, że HALO jest aktywne o określonej godzinie.
Dokumenty / Zasoby
 |
Oprogramowanie HALO Smart Sensor API Oprogramowanie podstawowe [plik PDF] Instrukcja użytkownika Podstawowe oprogramowanie HALO Smart Sensor API |
