软件 HALO Smart Sensor API 基础软件
向前
本文档描述了 Halo 智能传感器的一组设施，统称为 BASIC API 或应用程序编程接口。 本讨论旨在供有兴趣将一个或多个 HALO 智能传感器 (HALO) 与第 3 方（非 IPVideo）软件组件或系统集成的程序员或集成商使用。 通常，HALO API 旨在通过传统以太网将信息从 HALO 有效地传输到外部程序。 为了实现这一目标，API 分为三个部分：事件驱动套接字连接、心跳套接字连接和事件数据 URL. BACnet 接口也存在并包含在单独的文档中。
API 设计
API 是使用 TCP/IP 等行业标准格式设计的。 HTTP、HTTPS 和 JSON。 该设计不需要在外部程序或应用程序的开发中使用任何特殊或专有技术或库。 API 非常灵活，可以进行配置和编程，以最有效的方式准确交付所需的数据。 本指南的以下部分介绍了上述每个部分的操作细节。
外部消息
此工具用于在触发（设置）事件时向外部程序、VMS 系统、服务器等传递警报或警报和事件数据。 还可以启用可选消息以在事件清除（重置）时发出信号。 这种传送可以实时发送到 TCP/IP 套接字或 HTTP/S 服务器。 有一系列具有可定制内容的可配置协议。 可以进行身份验证和加密。
心跳
心跳消息以可配置的时间间隔（而不是触发事件时）发送，以提供活动/可用性证明。 它们具有与外部消息传递类似的功能范围，但通常配置为包含一般状态信息而不是特定事件的详细信息。
活动数据 URL
此工具仅在 NDA 下可用，并且仅在外部程序需要访问任何和所有事件值、阈值和状态标志时使用。 这些数据通常由外部程序按需检索，但频率不是很高。 当使用适度的轮询速率时，此方法通常会产生一些延迟。 典型的轮询速率范围从每分钟一次到每 5 秒一次，绝对最大速率为每秒一次。 此方法还可用于在收到事件（警报）时检索其他支持数据。
外部消息详细信息
HALO 的一部分 web 接口集成弹出窗口提供单个第 3 方连接的配置，其中可以将各种值发送到远程 TCP 套接字或 HTTP/HTTPS 服务器。 占位符（令牌）用于将实时值插入到传输的文本中。 尽管标记为“外部消息传递”，但该通道几乎可用于任何需要实时事件触发器的目的，由 HALO 主动提供。 这种安排非常灵活，因为“操作”上的选择决定了哪些 HALO 事件通过该通道传输。
在 HTTP 模式下，设置和重置字符串是 URLs 必须按照所需目标服务器的要求输入和格式化。 用户和密码字段可用于身份验证。 请参阅下面的 HTTP 模式。
在 TCP 模式下，设置和重置字符串只是发送到接收 TCP 套接字的单个消息的数据。 它们可以根据目的地的需要进行格式化。 目的地在地址和端口字段中指定。 请参阅下面的 TCP 模式。
对于任何一种模式，都会显示最新消息的状态，这有助于修复连接或其他问题。 您可以使用 Actions 弹出窗口上的 Event TEST 按钮来强制发送消息：
设置或重置的全局开/关必须为开才能启用这些类型的消息。 通常不使用重置，因为只对事件的开始感兴趣，但这可能会有所不同。 每个事件都可以独立指定它是否将使用“操作”弹出窗口上的“设置”或“重置”消息。 眼球按钮将显示关键字替换和格式化后发送的内容的粗略表示。 重复延迟可用于通过在发送另一条消息之前延迟来限制频繁消息。 这是每个事件独立完成的。 HALO 具有 15 秒的内置事件保持时间，以防止快速重新触发事件。 如果您想确保每分钟发送的类型不超过 1 个，您可以将重复延迟设置为 60（秒）。
心跳细节
心跳传输的功能与上述类似，只是没有与“操作”页面的交互。 相反，心跳传输按照间隔字段的配置定期发生，在 HTTP 模式下，设置和重置字符串是 URLs 必须按照所需目标服务器的要求输入和格式化。 用户和密码字段可用于身份验证。 请参阅下面的 HTTP 模式。
虽然 Heartbeat 的主要目的是向远程应用程序提供 HALO 智能传感器的使用寿命证明，但此消息也可用于传输选定的传感器或当前事件状态信息。 前任ample 上面发送一个长字符串参数 URL 其中包括 Halo 名称、大部分传感器值，最后是 Triggered=%ACTIVE%，它可能为空或当前触发的事件列表。
HTTP（和 HTTPS）模式
外部消息和心跳字符串可以是 http: 或 https: URLs 根据需要。 目标服务器可以根据需要输入路径和参数。 可以根据需要插入 %NAME%（HALO 设备名称）或 %EID%（事件 id）等关键字，并在发送消息时将其替换为相应的数据。 显示常用关键字列表以供快速参考。
这 URL 路径可以包含关键字以及参数 URL. 参数可能是 NAME=VALUE 对或 JSON 对象，或自定义格式，具体取决于目标服务器。 前任amp外部消息的文件将包括 %EID% 以指示触发的事件：
- https://server.com/event/%NAME%/%EID%
- https://server.com/event?location=%NAME%&event=%EID%
- https://server.com/event?{“location”:”:%NAME%”,”event”:”%EID%”}
ExampHeartbeat 的文件可能会添加 %ACTIVE%（当前触发的事件）或传感器值：
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
%SENSOR:…% 值使用 evtYYYYMMDD.csv 日志中右侧传感器列标题中的名称 files。 它们通常是：
如果目标服务器更喜欢 HTTP PUT 或 POST 而不是 GET 请求，您可以在 URL 使用 PUT: 或 POST:。 独立地，您可以通过添加 [JSONBODY] 关键字后跟 JSON 格式的对象来添加在许多服务器中流行的 JSON 有效负载。 前任amp乐：
PUT：https://server.com/event[JSONBODY]{“location”:”%NAME%”,”event”:”%EID%”}
这 URL 支持典型的 IP 地址（和 IPv6）以及端口和用户密码选项，或者如果需要，您可以使用用户和密码字段作为基本或摘要等身份验证方法的目标服务器：
https://username:password@123.321.123.321:9876/event…
TCP 模式
外部消息和心跳字符串仅用于数据，因为地址和端口字段指定了目的地。 地址支持名称、IPv4 和 IPv6。
该字符串的格式可以与上述 HTTP 消息的数据部分类似，也可以根据目标服务器的要求进行格式化。
Examp外部消息的文件将包括 %EID% 以指示触发的事件：
位置=%NAME%，事件=%EID%
{“位置”:”:%NAME%”,”事件”:”%EID%”}
ExampHeartbeat 的文件可能会添加 %ACTIVE%（当前触发的事件）或传感器值：
位置=%NAME%&触发=%ACTIVE%
{“位置”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
“Integration Set”和“Integration Reset”列中的复选框确定哪些事件触发发送。 HALO 管理员指南中提供了有关事件和操作设置的更多信息。
JSON 事件消息的传递
一些开发人员更喜欢接收格式化为行业标准自标记 JSON 格式的事件数据，而不是纯 ASCII 文本，因为前者更可靠且更易于解析。 在光环上 web 页面“消息”选项卡，您可以在“外部消息”设置“设置字符串”和“重置字符串”以及“心跳”“消息”中提供 JSON 消息。
Examp莱斯：
“外部消息”设置设置字符串：
{ “设备”：“%NAME%”，“事件”：“%EID%”，“警报”：“是” }
这将向指定的服务器发送一条 TCP 或 UDP JSON 消息，报告友好的设备名称、事件名称以及它刚刚启动。
“外部消息”设置重置字符串：
{ “设备”：“%NAME%”，“事件”：“%EID%”，“警报”：“否” }
这将向指定的服务器发送一条 TCP 或 UDP JSON 消息，报告友好的设备名称、事件名称以及条件现已停止。
“心跳”消息：
{ “设备”:”%NAME%”, “活着”:”%DATE% %TIME%” }
这将定期向指定的服务器发送 TCP 或 UDP JSON 消息，报告 HALO 在指定时间处于活动状态。
文件/资源
 |
软件 HALO Smart Sensor API 基础软件 [pdf] 用户指南 HALO 智能传感器 API 基础软件 |
