Logiciels HALO Smart Sensor API Basic Software
Avant
Ce document décrit le groupe d'installations du capteur intelligent Halo connu collectivement sous le nom d'API BASIC ou d'interface de programmation d'application. Cette discussion est destinée aux programmeurs ou aux intégrateurs qui souhaitent intégrer un ou plusieurs capteurs intelligents HALO (HALO) avec des composants ou systèmes logiciels tiers (non IPVideo). En général, l'API HALO est destinée à transférer efficacement des informations de HALO sur un réseau Ethernet conventionnel vers le programme externe. Pour atteindre cet objectif, l'API est divisée en trois sections : Event Driven Socket Connection, Heartbeat Socket Connection et Event Data. URL. L'interface BACnet est également présente et couverte dans un document séparé.
Conception d'API
L'API est conçue à l'aide de formats standard de l'industrie tels que TCP/IP. HTTP, HTTPS et JSON. La conception ne nécessite pas l'utilisation de techniques ou de bibliothèques spéciales ou propriétaires pour le développement du programme ou de l'application externe. L'API est flexible et peut être configurée et programmée pour fournir exactement les données requises et de la manière la plus efficace. Les détails du fonctionnement de chacune des sections ci-dessus sont traités dans les sections suivantes de ce guide.
Messagerie externe
Cette fonction est utilisée pour fournir des alertes ou des alarmes et des données d'événement à un programme externe, un système VMS, un serveur, etc. lorsqu'un événement est déclenché (est défini). Des messages optionnels peuvent également être activés pour signaler quand un événement s'efface (est réinitialisé). Cette livraison peut être effectuée sur une socket TCP/IP ou un serveur HTTP/S en temps réel. Il existe une gamme de protocoles configurables avec des contenus personnalisables. L'authentification et le cryptage sont disponibles.
Pulsation
Les messages de pulsation sont envoyés à un intervalle configurable (au lieu du moment où les événements sont déclenchés) pour fournir une preuve de disponibilité/en direct. Ils ont une gamme de fonctionnalités similaire à celle de la messagerie externe, mais sont généralement configurés pour contenir des informations générales sur l'état plutôt que des détails sur un événement particulier.
Données d'événement URL
Cette fonctionnalité n'est disponible que sous un NDA et ne doit être utilisée que lorsque le programme externe nécessite l'accès à toutes les valeurs d'événement, seuils et indicateurs d'état. Ces données sont généralement récupérées à la demande par le programme externe mais pas à une fréquence très élevée. Cette méthode entraîne généralement une certaine latence lorsqu'un taux d'interrogation modeste est utilisé. Les taux d'interrogation typiques vont d'une fois par minute à une fois toutes les 5 secondes avec un taux maximum absolu d'une fois par seconde. Cette méthode peut également être utilisée pour récupérer des données de support supplémentaires lorsqu'un événement (alerte) est reçu.
Détails de la messagerie externe
Une partie du HALO web La fenêtre contextuelle d'intégration de l'interface permet la configuration d'une seule connexion tierce où diverses valeurs peuvent être envoyées à un socket TCP distant ou à un serveur HTTP/HTTPS. Les espaces réservés (jetons) sont utilisés pour insérer des valeurs en direct dans le texte transmis. Bien qu'étiqueté « Messagerie externe », ce canal peut être utilisé à presque toutes les fins nécessitant des déclencheurs d'événements en temps réel, fournis activement par HALO. Cet arrangement est assez flexible car les sélections sur les "Actions" déterminent quels événements HALO sont transmis via ce canal.
En mode HTTP, les chaînes Set et Reset sont les URLs qui doivent être saisis et formatés selon les besoins du serveur de destination souhaité. Un champ Utilisateur et Mot de passe peut être utilisé pour l'authentification. Voir le mode HTTP ci-dessous.
En mode TCP, les chaînes Set et Reset ne sont que les données d'un seul message envoyé au socket TCP récepteur. Ils peuvent être formatés selon les besoins de la destination. La destination est spécifiée dans les champs Adresse et Port. Voir Mode TCP ci-dessous.
Pour l'un ou l'autre mode, l'état du message le plus récent est affiché, ce qui peut aider à résoudre les problèmes de connexion ou autres. Vous pouvez utiliser les boutons Event TEST de la fenêtre contextuelle Actions pour forcer un message :
Global On/Off pour Set ou Reset doit être activé pour activer ces types de messages. La réinitialisation n'est souvent pas utilisée car seul le début d'un événement est intéressant, mais cela peut varier. Chaque événement peut spécifier indépendamment s'il utilisera le message Set ou Reset dans la fenêtre contextuelle Actions. Les boutons du globe oculaire afficheront une représentation approximative de ce qui est envoyé après les substitutions de mots clés et la mise en forme. Repeat Holdoff peut être utilisé pour limiter les messages fréquents en retardant avant qu'un autre puisse être envoyé. Ceci est fait indépendamment par événement. HALO a un temps de maintien intégré pour les événements de 15 secondes pour empêcher le redéclenchement rapide des événements. Si vous vouliez vous assurer que pas plus d'un événement d'un type est envoyé par minute, vous pouvez régler le délai de répétition sur 1 (secondes).
Détails du rythme cardiaque
Les transmissions Heartbeat fonctionnent de la même manière que ci-dessus, sauf qu'il n'y a pas d'interaction avec la page Actions. Au lieu de cela, la transmission Heartbeat se produit sur une base régulière comme configuré avec le champ Interval, En mode HTTP, les chaînes Set et Reset sont les URLs qui doivent être saisis et formatés selon les besoins du serveur de destination souhaité. Un champ Utilisateur et Mot de passe peut être utilisé pour l'authentification. Voir le mode HTTP ci-dessous.
Bien que l'objectif principal du Heartbeat soit de fournir une preuve de vie d'un capteur intelligent HALO à une application distante, ce message peut également être utilisé pour transmettre des capteurs sélectionnés ou des informations sur l'état actuel de l'événement. Le EXampchier ci-dessus envoie un long paramètre de chaîne avec le URL qui incluent le nom Halo, une majorité de valeurs de capteur, et enfin Triggered=%ACTIVE% qui peut être vide ou une liste d'événements actuellement déclenchés.
Mode HTTP (et HTTPS)
Les chaînes de messagerie externe et de pulsation peuvent être http : ou https : URLs au besoin. Le chemin et les paramètres peuvent être saisis selon les besoins par le serveur de destination. Des mots-clés comme %NAME% (nom de l'appareil HALO) ou %EID% (ID d'événement) peuvent être insérés au besoin et seront remplacés par les données respectives lors de l'envoi du message. Une liste de mots-clés couramment utilisés est affichée pour une référence rapide.
Le URL chemin peut contenir des mots-clés ainsi que les paramètres du URL. Les paramètres peuvent être des paires NAME=VALUE ou un objet JSON, ou un format personnalisé selon le serveur de destination. ExampLes fichiers pour la messagerie externe incluraient %EID% pour indiquer l'événement qui a déclenché :
- https://server.com/event/%NAME%/%EID%
- https://server.com/event?location=%NAME%&event=%EID%
- https://server.com/event?{“location”:”:%NAME%”,”event”:”%EID%”}
ExampLes fichiers pour Heartbeat peuvent ajouter %ACTIVE% (événements actuellement déclenchés) ou une valeur de capteur :
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Les valeurs %SENSOR:…% utilisent les noms trouvés dans les en-têtes de colonne de capteur de droite dans le journal evtYYYYMMDD.csv files. Ce sont généralement :
Si le serveur de destination préfère HTTP PUT ou POST au lieu des requêtes GET, vous pouvez préfixer le URL avec PUT: ou POST:. Indépendamment, vous pouvez ajouter une charge utile JSON qui est populaire auprès de nombreux serveurs en ajoutant le mot-clé [JSONBODY] suivi d'un objet au format JSON. Example:
PUT : https://server.com/event[JSONBODY]{"location":"%NAME%","event":"%EID%"}
Le URL prend en charge les options d'adresse IP (et IPv6) et de port et de mot de passe utilisateur typiques, ou vous pouvez utiliser les champs Utilisateur et Mot de passe si nécessaire comme serveur de destination pour les méthodes d'authentification telles que Basic ou Digest :
https://username:password@123.321.123.321:9876/event…
Mode TCP
Les chaînes de messagerie externe et de pulsation sont uniquement destinées aux données, car les champs Adresse et Port spécifient la destination. L'adresse prend en charge les noms, IPv4 et IPv6.
La chaîne peut être formatée comme les parties de données des messages HTTP décrites ci-dessus, ou comme requis par le serveur de destination.
ExampLes fichiers pour la messagerie externe incluraient %EID% pour indiquer l'événement qui a déclenché :
emplacement=%NAME%,événement=%EID%
{"emplacement":":%NAME%","événement":"%EID%"}
ExampLes fichiers pour Heartbeat peuvent ajouter %ACTIVE% (événements actuellement déclenchés) ou une valeur de capteur :
emplacement=%NAME%&Triggered=%ACTIVE%
{"emplacement":":%NAME%","NH3":%SENSOR:NH3%}
Les cases à cocher dans les colonnes « Ensemble d'intégration » et « Réinitialisation de l'intégration » déterminent les événements qui déclenchent l'envoi. Plus d'informations sur la configuration des événements et des actions sont disponibles dans le Guide de l'administrateur HALO.
Livraison des messages d'événement JSON
Certains développeurs préfèrent recevoir des données d'événement au format JSON auto-étiqueté standard de l'industrie plutôt qu'en texte ASCII brut, car le premier est plus fiable et plus facile à analyser. Sur le HALO web Dans l'onglet "Messagerie", vous pouvez fournir des messages JSON dans les paramètres "Messagerie externe" "Set String" et "Reset String" et dans le "Heartbeat" "Message".
Examples:
Paramètres "Messagerie externe" Définissez la chaîne :
{ "device":"%NAME%", "event":"%EID%", "alarm":"yes" }
Cela enverra un seul message TCP ou UDP JSON au serveur spécifié indiquant le nom convivial de l'appareil, le nom de l'événement et qu'il vient de démarrer.
Chaîne de réinitialisation des paramètres "Messagerie externe" :
{ "device":"%NAME%", "event":"%EID%", "alarm":"no" }
Cela enverra un seul message TCP ou UDP JSON au serveur spécifié indiquant le nom convivial de l'appareil, le nom de l'événement et indiquant que la condition s'est maintenant arrêtée.
Message « battement de cœur » :
{ "device":"%NAME%", "alive":"%DATE% %TIME%" }
Cela enverra périodiquement un message TCP ou UDP JSON au serveur spécifié signalant que le HALO est actif à l'heure indiquée.
Documents / Ressources
 |
Logiciels HALO Smart Sensor API Basic Software [pdf] Guide de l'utilisateur Logiciel de base de l'API de capteur intelligent HALO |
