Software s HALO Smart Sensor API Basissoftware
Nach vorne
Dieses Dokument beschreibt die Gruppe von Funktionen des Halo Smart Sensor, die zusammen als BASIC API oder Application Programming Interface bezeichnet werden. Diese Diskussion richtet sich an Programmierer oder Integratoren, die daran interessiert sind, einen oder mehrere HALO Smart Sensors (HALOs) mit Softwarekomponenten oder -systemen von Drittanbietern (nicht IPVideo) zu integrieren. Im Allgemeinen soll die HALO API Informationen effizient von HALO über ein herkömmliches Ethernet-Netzwerk an das externe Programm übertragen. Um dieses Ziel zu erreichen, ist die API in drei Abschnitte unterteilt: Ereignisgesteuerte Socket-Verbindung, Heartbeat-Socket-Verbindung und Ereignisdaten URL. Eine BACnet-Schnittstelle ist ebenfalls vorhanden und wird in einem separaten Dokument behandelt.
API-Design
Die API ist unter Verwendung von Industriestandardformaten wie TCP/IP, HTTP, HTTPS und JSON konzipiert. Das Design erfordert keine speziellen oder proprietären Techniken oder Bibliotheken für die Entwicklung des externen Programms oder der Anwendung. Die API ist flexibel und kann so konfiguriert und programmiert werden, dass sie genau die erforderlichen Daten auf die effizienteste Weise liefert. Die Einzelheiten zur Funktionsweise der einzelnen oben genannten Abschnitte werden in den folgenden Abschnitten dieses Handbuchs behandelt.
Externe Nachrichtenübermittlung
Diese Funktion wird verwendet, um Warnungen oder Alarme und Ereignisdaten an ein externes Programm, VMS-System, einen Server usw. zu übermitteln, wenn ein Ereignis ausgelöst (festgelegt) wird. Optionale Nachrichten können auch aktiviert werden, um zu signalisieren, wenn ein Ereignis gelöscht (zurückgesetzt) wird. Diese Übermittlung kann in Echtzeit an einen TCP/IP-Socket oder einen HTTP/S-Server erfolgen. Es gibt eine Reihe konfigurierbarer Protokolle mit anpassbaren Inhalten. Authentifizierung und Verschlüsselung sind verfügbar.
Herzschlag
Heartbeat-Nachrichten werden in einem konfigurierbaren Intervall gesendet (anstatt wenn Ereignisse ausgelöst werden), um den Nachweis der Live-/Verfügbarkeit zu erbringen. Sie verfügen über eine ähnliche Palette an Funktionen wie externe Nachrichten, werden jedoch normalerweise so konfiguriert, dass sie allgemeine Statusinformationen und keine Details zu einem bestimmten Ereignis enthalten.
Ereignisdaten URL
Diese Funktion ist nur unter einer Geheimhaltungsvereinbarung verfügbar und sollte nur verwendet werden, wenn das externe Programm Zugriff auf alle Ereigniswerte, Schwellenwerte und Statusflags benötigt. Diese Daten werden im Allgemeinen auf Anfrage vom externen Programm abgerufen, jedoch nicht mit sehr hoher Frequenz. Bei dieser Methode tritt im Allgemeinen eine gewisse Latenz auf, wenn eine moderate Abfragerate verwendet wird. Typische Abfrageraten reichen von einmal pro Minute bis einmal alle 5 Sekunden mit einer absoluten Höchstrate von einmal pro Sekunde. Diese Methode kann auch verwendet werden, um zusätzliche unterstützende Daten abzurufen, wenn ein Ereignis (Alarm) empfangen wird.
Details zu externen Nachrichten
Ein Abschnitt des HALO web Das Popup zur Schnittstellenintegration ermöglicht die Konfiguration einer einzelnen Drittanbieterverbindung, über die verschiedene Werte an einen Remote-TCP-Socket oder einen HTTP/HTTPS-Server gesendet werden können. Platzhalter (Tokens) werden verwendet, um Live-Werte in den übertragenen Text einzufügen. Obwohl dieser Kanal als „Externe Nachrichtenübermittlung“ bezeichnet wird, kann er für fast jeden Zweck verwendet werden, der Echtzeit-Ereignisauslöser erfordert, die aktiv von HALO bereitgestellt werden. Diese Anordnung ist recht flexibel, da die Auswahl unter „Aktionen“ bestimmt, welche HALO-Ereignisse über diesen Kanal übertragen werden.
Im HTTP-Modus sind die Set- und Reset-Strings die URLs, die eingegeben und entsprechend den Anforderungen des gewünschten Zielservers formatiert werden müssen. Zur Authentifizierung können Benutzer- und Kennwortfelder verwendet werden. Siehe HTTP-Modus unten.
Im TCP-Modus sind die Set- und Reset-Strings nur die Daten einer einzelnen Nachricht, die an den empfangenden TCP-Socket gesendet wird. Sie können je nach Bedarf des Ziels formatiert werden. Das Ziel wird in den Feldern „Adresse“ und „Port“ angegeben. Siehe TCP-Modus weiter unten.
In beiden Modi wird der Status der letzten Nachricht angezeigt, der bei der Behebung von Verbindungs- oder anderen Problemen hilfreich sein kann. Sie können die Schaltflächen „Ereignistest“ im Popup „Aktionen“ verwenden, um eine Nachricht zu erzwingen:
Globales Ein/Aus für Set oder Reset muss eingeschaltet sein, um diese Nachrichtentypen zu aktivieren. Reset wird oft nicht verwendet, da nur der Beginn eines Ereignisses von Interesse ist, aber das kann variieren. Jedes Ereignis kann unabhängig angeben, ob es entweder die Set- oder die Reset-Nachricht im Popup „Aktionen“ verwendet. Die Augenschaltflächen zeigen eine grobe Darstellung dessen an, was nach Schlüsselwortersetzungen und Formatierung gesendet wird. Repeat Holdoff kann verwendet werden, um häufige Nachrichten zu drosseln, indem verzögert wird, bevor eine weitere gesendet werden kann. Dies wird unabhängig pro Ereignis durchgeführt. HALO hat eine integrierte Haltezeit für Ereignisse von 15 Sekunden, um ein schnelles erneutes Auslösen von Ereignissen zu verhindern. Wenn Sie sicherstellen möchten, dass nicht mehr als 1 Ereignis eines Typs pro Minute gesendet wird, können Sie Repeat Holdoff auf 60 (Sekunden) einstellen.
Heartbeat-Details
Die Heartbeat-Übertragungen funktionieren ähnlich wie die oben beschriebenen, außer dass keine Interaktion mit der Seite „Aktionen“ stattfindet. Stattdessen erfolgt die Heartbeat-Übertragung regelmäßig, wie im Feld „Intervall“ konfiguriert. Im HTTP-Modus sind die Zeichenfolgen „Set“ und „Reset“ die URLs, die eingegeben und entsprechend den Anforderungen des gewünschten Zielservers formatiert werden müssen. Zur Authentifizierung können Benutzer- und Kennwortfelder verwendet werden. Siehe HTTP-Modus unten.
Während der Hauptzweck des Heartbeats darin besteht, einer Remote-Anwendung den Nachweis der Funktionsfähigkeit eines HALO Smart Sensors zu erbringen, kann diese Nachricht auch verwendet werden, um ausgewählte Sensoren oder aktuelle Ereignisstatusinformationen zu übertragen. Die Example oben sendet einen langen String-Parameter mit dem URL Dazu gehören der Halo-Name, die meisten Sensorwerte und zuletzt Triggered=%ACTIVE%, das leer sein oder eine Liste aktuell ausgelöster Ereignisse sein kann.
HTTP- (und HTTPS-)Modus
Externe Messaging- und Heartbeat-Zeichenfolgen können http: oder https: sein. URLs nach Bedarf. Pfad und Parameter können nach Bedarf vom Zielserver eingegeben werden. Schlüsselwörter wie %NAME% (HALO-Gerätename) oder %EID% (Ereignis-ID) können nach Bedarf eingefügt werden und werden beim Senden der Nachricht durch die entsprechenden Daten ersetzt. Zur schnellen Referenz wird eine Liste häufig verwendeter Schlüsselwörter angezeigt.
Der URL Der Pfad kann Schlüsselwörter sowie die Parameter für die URL. Die Parameter können NAME=VALUE-Paare oder ein JSON-Objekt oder ein benutzerdefiniertes Format sein, abhängig vom Zielserver. BeispielampDateien für externe Nachrichten enthalten %EID%, um das ausgelöste Ereignis anzuzeigen:
- https://server.com/event/%NAME%/%EID%
- https://server.com/event?location=%NAME%&event=%EID%
- https://server.com/event?{“location”:”:%NAME%”,”event”:”%EID%”}
ExampDateien für Heartbeat könnten %ACTIVE% (aktuell ausgelöste Ereignisse) oder einen Sensorwert hinzufügen:
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Die %SENSOR:…%-Werte verwenden die Namen, die in den rechten Sensorspaltenüberschriften im evtYYYYMMDD.csv-Protokoll zu finden sind. files. Sie sind typischerweise:
Wenn der Zielserver HTTP PUT oder POST anstelle von GET-Anfragen bevorzugt, können Sie das URL mit PUT: oder POST:. Unabhängig davon können Sie eine JSON-Nutzlast hinzufügen, die bei vielen Servern beliebt ist, indem Sie das Schlüsselwort [JSONBODY] gefolgt von einem JSON-formatierten Objekt hinzufügen. Beispielampauf:
PUT:https://server.com/event[JSONBODY]{„Standort“:“%NAME%“,“Ereignis“:“%EID%“}
Der URL unterstützt typische IP-Adressen (und IPv6) sowie Port- und Benutzer-Passwort-Optionen, oder Sie können die Felder „Benutzer“ und „Passwort“ bei Bedarf als Zielserver für Authentifizierungsmethoden wie „Basic“ oder „Digest“ verwenden:
https://username:password@123.321.123.321:9876/event…
TCP-Modus
Externe Messaging- und Heartbeat-Zeichenfolgen dienen nur für Daten, da die Felder „Adresse“ und „Port“ das Ziel angeben. Die Adresse unterstützt Namen, IPv4 und IPv6.
Die Zeichenfolge kann wie die oben beschriebenen Datenteile von HTTP-Nachrichten oder nach Bedarf des Zielservers formatiert werden.
ExampDateien für externe Nachrichten enthalten %EID%, um das ausgelöste Ereignis anzuzeigen:
Ort=%NAME%,Ereignis=%EID%
{„Ort“:“:%NAME%“, „Ereignis“:“%EID%“}
ExampDateien für Heartbeat könnten %ACTIVE% (aktuell ausgelöste Ereignisse) oder einen Sensorwert hinzufügen:
Standort=%NAME%&Ausgelöst=%ACTIVE%
{„Standort“:“:%NAME%“,“NH3“:%SENSOR:NH3%}
Kontrollkästchen in den Spalten „Integrationssatz“ und „Integrationsreset“ bestimmen, welche Ereignisse das Senden auslösen. Weitere Informationen zum Einrichten von Ereignissen und Aktionen finden Sie im HALO-Administratorhandbuch.
Übermittlung von JSON-Ereignismeldungen
Einige Entwickler bevorzugen es, Ereignisdaten im selbstbeschrifteten JSON-Format nach Industriestandard zu erhalten, statt im reinen ASCII-Textformat, da ersteres zuverlässiger und einfacher zu analysieren ist. Auf dem HALO web Auf der Registerkarte „Messaging“ der Seite können Sie JSON-Nachrichten in den „External Messaging“-Einstellungen „Set String“ und „Reset String“ und im „Heartbeat“-Bereich „Message“ angeben.
Examples:
„Externe Nachrichten“ Einstellungen Zeichenfolge festlegen:
{ „Gerät“:“%NAME%“, „Ereignis“:“%EID%“, „Alarm“:“Ja“ }
Dadurch wird eine einzelne TCP- oder UDP-JSON-Nachricht an den angegebenen Server gesendet, die den benutzerfreundlichen Gerätenamen, den Ereignisnamen und den gerade gestarteten Zustand enthält.
Zeichenfolge zum Zurücksetzen der Einstellungen für „Externe Nachrichten“:
{ „Gerät“:“%NAME%“, „Ereignis“:“%EID%“, „Alarm“:“nein“ }
Dadurch wird eine einzelne TCP- oder UDP-JSON-Nachricht an den angegebenen Server gesendet, die den benutzerfreundlichen Gerätenamen und den Ereignisnamen enthält sowie darüber informiert, dass der Zustand nun beendet ist.
„Heartbeat“-Meldung:
{ „Gerät“:“%NAME%“, „aktiv“:“%DATE% %TIME%“ }
Dadurch wird in regelmäßigen Abständen eine TCP- oder UDP-JSON-Nachricht an den angegebenen Server gesendet, die meldet, dass HALO zum angegebenen Zeitpunkt aktiv ist.
Dokumente / Ressourcen
 |
Software s HALO Smart Sensor API Basissoftware [pdf] Benutzerhandbuch HALO Smart Sensor API Basissoftware |
