Software s HALO Smart Sensor API Software básico Guía del usuario

Software básico HALO Smart Sensor API

Adelante

Este documento describe el grupo de funciones del sensor inteligente Halo conocido colectivamente como API BÁSICA o interfaz de programación de aplicaciones. Esta discusión está destinada a programadores o integradores que estén interesados ​​en integrar uno o más HALO Smart Sensors (HALO) con componentes o sistemas de software de terceros (que no sean IPVideo). En general, la API de HALO está destinada a transferir información de manera eficiente desde HALO a través de una red Ethernet convencional al programa externo. Para lograr este objetivo, la API se divide en tres secciones: conexión de socket controlada por eventos, conexión de socket de latido y datos de eventos. URL. La interfaz BACnet también está presente y se trata en un documento separado.

Diseño de API

La API está diseñada utilizando formatos estándar de la industria como TCP/IP. HTTP, HTTPS y JSON. El diseño no requiere el uso de técnicas o bibliotecas especiales o patentadas en el desarrollo del programa o aplicación externa. La API es flexible y se puede configurar y programar para entregar exactamente los datos necesarios y de la manera más eficiente. Los detalles del funcionamiento de cada una de las secciones anteriores se tratan en las siguientes secciones de esta guía.

Mensajería externa

Esta función se utiliza para enviar alertas o alarmas y datos de eventos a un programa externo, sistema VMS, servidor, etc. cuando se activa (se establece) un evento. También se pueden habilitar mensajes opcionales para señalar cuándo se borra (se restablece) un evento. Esta entrega se puede realizar a un socket TCP/IP o servidor HTTP/S en tiempo real. Existe una variedad de protocolos configurables con contenidos personalizables. La autenticación y el cifrado están disponibles.

Latido del corazón

Los mensajes de latido se envían en un intervalo configurable (en lugar de cuando se activan los eventos) para proporcionar prueba de actividad/disponibilidad. Tienen una gama de capacidades similar a la mensajería externa, pero normalmente se configurarían para contener información de estado general en lugar de detalles sobre un evento en particular.

Datos de eventos URL

Esta función solo está disponible bajo un NDA y solo debe usarse cuando el programa externo requiere acceso a todos y cada uno de los valores, umbrales e indicadores de estado del evento. Estos datos generalmente se recuperan a pedido del programa externo, pero no con una frecuencia muy alta. Este método generalmente genera cierta latencia cuando se utiliza una tasa de sondeo modesta. Las tasas de sondeo típicas varían de una vez por minuto a una vez cada 5 segundos con una tasa máxima absoluta de una vez por segundo. Este método también se puede utilizar para recuperar datos de respaldo adicionales cuando se recibe un evento (alerta).

Detalles de mensajería externa

Una sección del HALO web La ventana emergente de integración de interfaz proporciona la configuración de una única conexión de terceros donde se pueden enviar varios valores a un socket TCP remoto o a un servidor HTTP/HTTPS. Los marcadores de posición (tokens) se utilizan para insertar valores activos en el texto transmitido. Aunque está etiquetado como "Mensajería externa", este canal se puede utilizar para casi cualquier propósito que requiera activadores de eventos en tiempo real, entregados activamente por HALO. Esta disposición es bastante flexible porque las selecciones en las "Acciones" determinan qué eventos HALO se transmiten a través de este canal.

En modo HTTP, las cadenas Set y Reset son las URLs que deben ingresarse y formatearse según lo requiera el servidor de destino deseado. Se puede utilizar un campo de Usuario y Contraseña para la autenticación. Consulte el modo HTTP a continuación.

En el modo TCP, las cadenas Establecer y Restablecer son solo los datos de un único mensaje que se envía al socket TCP receptor. Se pueden formatear según lo necesite el destino. El destino se especifica en los campos Dirección y Puerto. Consulte Modo TCP a continuación.

Para cualquier modo, se muestra el estado del mensaje más reciente, lo que puede ayudar a solucionar problemas de conexión u otros. Puede usar los botones de PRUEBA de eventos en la ventana emergente Acciones para forzar un mensaje:

La activación/desactivación global para configurar o restablecer debe estar activada para habilitar esos tipos de mensajes. El reinicio a menudo no se utiliza porque solo interesa el inicio de un evento, pero eso puede variar. Cada evento puede especificar de forma independiente si utilizará el mensaje Establecer o Restablecer en la ventana emergente Acciones. Los botones oculares mostrarán una representación aproximada de lo que se envía después de la sustitución y el formato de palabras clave. La repetición de espera se puede utilizar para limitar los mensajes frecuentes retrasando el envío de otro. Esto se hace de forma independiente por Evento. HALO tiene un tiempo de espera incorporado para eventos de 15 segundos para evitar que los eventos se vuelvan a activar rápidamente. Si desea asegurarse de que no se envíe más de 1 evento de un tipo por minuto, puede configurar la espera de repetición en 60 (segundos).

Detalles de los latidos del corazón

Las transmisiones de Heartbeat funcionan de manera similar a las anteriores excepto que no hay interacción con la página Acciones. En cambio, la transmisión Heartbeat se produce de forma regular según lo configurado con el campo Intervalo. En el modo HTTP, las cadenas Establecer y Restablecer son las URLs que deben ingresarse y formatearse según lo requiera el servidor de destino deseado. Se puede utilizar un campo de Usuario y Contraseña para la autenticación. Consulte el modo HTTP a continuación.

Si bien el objetivo principal de Heartbeat es proporcionar prueba de vida de un sensor inteligente HALO a una aplicación remota, este mensaje también se puede utilizar para transmitir sensores seleccionados o información del estado del evento actual. La exampEl archivo anterior envía un parámetro de cadena larga con el URL que incluyen el nombre de Halo, la mayoría de los valores del sensor y, por último, Triggered=%ACTIVE%, que podría estar vacío o una lista de eventos activados actualmente.

Modo HTTP (y HTTPS)

Las cadenas de mensajería externa y latidos pueden ser http: o https: URLsegún sea necesario. La ruta y los parámetros se pueden ingresar según los necesite el servidor de destino. Se pueden insertar palabras clave como %NAME% (nombre del dispositivo HALO) o %EID% (identificación del evento) según sea necesario y se reemplazarán con los datos respectivos cuando se envíe el mensaje. Se muestra una lista de palabras clave de uso común para referencia rápida.
El URL La ruta puede contener palabras clave, así como los parámetros del URL. Los parámetros pueden ser pares NOMBRE=VALOR o un objeto JSON, o un formato personalizado según el servidor de destino. ExampLos archivos de mensajería externa incluirían %EID% para indicar el evento que desencadenó:

• https://server.com/event/%NAME%/%EID%
• https://server.com/event?location=%NAME%&event=%EID%
• https://server.com/event?{“location”:”:%NAME%”,”event”:”%EID%”}

ExampLos archivos para Heartbeat pueden agregar %ACTIVE% (eventos activados actualmente) o un valor de sensor:

• https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
• https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
  Los valores %SENSOR:…% utilizan los nombres que se encuentran en los encabezados de las columnas del sensor de la derecha en el registro evtAAAAMMDD.csv. files. Normalmente son:

Si el servidor de destino prefiere HTTP PUT o POST en lugar de solicitudes GET, puede anteponer el URL con PUT: o POST:. De forma independiente, puede agregar una carga útil JSON que es popular en muchos servidores agregando la palabra clave [JSONBODY] seguida de un objeto con formato JSON. Exampen:
PUT:https://server.com/event[JSONBODY]{“ubicación”:”%NAME%”,”evento”:”%EID%”}
El URL admite direcciones IP típicas (e IPv6) y opciones de puerto y contraseña de usuario, o puede usar los campos Usuario y Contraseña si es necesario como servidor de destino para métodos de autenticación como Básico o Digest:
https://username:password@123.321.123.321:9876/event…

Modo TCP

Las cadenas de mensajería externa y latido son solo para datos, ya que los campos Dirección y Puerto especifican el destino. La dirección admite nombres, IPv4 e IPv6.
La cadena se puede formatear como las partes de datos de los mensajes HTTP descritos anteriormente, o según lo requiera el servidor de destino.
ExampLos archivos de mensajería externa incluirían %EID% para indicar el evento que desencadenó:
ubicación=%NOMBRE%,evento=%EID%
{“ubicación”:”:%NOMBRE%”,”evento”:”%EID%”}
ExampLos archivos para Heartbeat pueden agregar %ACTIVE% (eventos activados actualmente) o un valor de sensor:
ubicación=%NOMBRE%&Triggered=%ACTIVE%
{“ubicación”:”:%NOMBRE%”,”NH3”:%SENSOR:NH3%}

Las casillas de verificación en las columnas “Conjunto de integración” y “Restablecimiento de integración” determinan qué eventos activan el envío. Más información sobre la configuración de eventos y acciones está disponible en la Guía del administrador de HALO.

Entrega de mensajes de eventos JSON
Algunos desarrolladores prefieren recibir datos de eventos formateados como JSON autoetiquetado estándar de la industria en lugar de texto ASCII simple, ya que el primero es más confiable y más fácil de analizar. en el halo web En la pestaña “Mensajería” de la página, puede proporcionar mensajes JSON en las configuraciones “Mensajería externa”, “Establecer cadena” y “Restablecer cadena” y en el “Mensaje” de “Heartbeat”.

Exampellos:
Cadena de configuración de “mensajería externa”:

{ “dispositivo”:”%NOMBRE%”, “evento”:”%EID%”, “alarma”:”sí” }
Esto enviará un único mensaje TCP o UDP JSON al servidor especificado informando el nombre descriptivo del dispositivo, el nombre del evento y que acaba de iniciarse.

Cadena de restablecimiento de configuración de “Mensajería externa”:
{ “dispositivo”:”%NOMBRE%”, “evento”:”%EID%”, “alarma”:”no” }
Esto enviará un único mensaje TCP o UDP JSON al servidor especificado informando el nombre descriptivo del dispositivo, el nombre del evento y que la condición ahora se ha detenido.

Mensaje de “latido del corazón”:
{ “dispositivo”:”%NOMBRE%”, “vivo”:”%FECHA% %TIEMPO%” }
Esto enviará periódicamente un mensaje TCP o UDP JSON al servidor especificado informando que HALO está activo en el momento indicado.