sitewhere发送和接收设备数据【译】

发送和接收设备数据 - 将设备和其他代理连接到SiteWhere

 

将数据发送到SiteWhere

SiteWhere旨在灵活地发送和接收来自设备和其他代理的数据。大多数流行的通信协议和编码都支持开箱即用，但系统的设计也很容易扩展。每个系统租户可以配置任意数量的协议，以便与设备进行通信。默认情况下，租户被配置为通过MQTT进行通信，支持多种编码以允许与多种类型的设备进行交互。

 

使用REST服务

无论如何在每个租户的基础上配置设备通信，核心SiteWhere服务器实例都会提供REST服务 这可以控制全局和特定于租户的数据。REST服务需要经过身份验证的用户和租户授权令牌来控制哪些功能可供特定用户使用。经过身份验证的用户（取决于权限）可以对所有系统实体执行创建/读取/更新/删除操作。可以直接从REST服务提交和查询各种类型的设备事件数据。让设备通过REST服务直接与SiteWhere交互是一种可接受的方法，尽管HTTP的开销限制了可伸缩性。其他协议，如MQTT和AMQP允许更高效的连接并提供双向通信。

详见：sitwhere REST Services 文档【译】

使用JSON接收设备数据

SiteWhere支持大多数协议的JSON有效负载，包括MQTT，AMQP，WebSockets和直接套接字连接。默认的SiteWhere租户配置连接到MQTT代理，并侦听SiteWhere / input / json主题上的JSON有效负载。租户配置文件中的以下部分启用了此功能：

<!-- Event source for JSON device requests over MQTT -->
<sw:mqtt-event-source sourceId="json" hostname="localhost" port="1883"
topic="SiteWhere/input/json">
<sw:json-device-request-decoder/>
</sw:mqtt-event-source>

JSON数据包格式

以下部分显示了结构化为与SiteWhere交互的JSON数据的示例。所有JSON数据包都共享一些通用信息，如下所示：

{
"hardwareId": "(unique hardware id)",
"type": "(indicator for request type)",
"request": {
...
}
}

领域	描述
硬件ID	硬件ID，用于唯一标识租户内的设备。这通知系统哪个设备正在生成事件。
类型	设备的请求类型。这表明如何解释请求部分中的数据。
请求	请求内容特定于正在发送的数据包类型，如类型字段所示。

注册设备

在设备可以发送事件数据之前，它们必须在系统中注册。SiteWhere将在系统命令通道上发回一个响应，以指示设备是否可以注册。它还会显示设备是否已经注册。下面的JSON数据包可用于注册设备：

{
"hardwareId": "123-TEST-4567890",
"type": "RegisterDevice",
"request": {
"hardwareId": "123-TEST-4567890",
"specificationToken": "964e7613-dab3-4fb3-8919-266a91370884",
"siteToken": "bb105f8d-3150-41f5-b9d1-db04965668d3"
}
}

领域	描述
硬件ID	设备的唯一标识符。没有两个设备可以共享相同的硬件ID。
specificationToken	令牌指定正在注册的设备的类型。规格可以在SiteWhere管理应用程序中注册。
siteToken	指示设备将与哪个站点相关联。如果未指定站点令牌，则该设备将与系统中的第一个站点相关联。（可选的）

发送测量事件

SiteWhere支持将与设备相关的测量值存储为事件数据。用于发送设备测量的JSON格式如下所示：

{
"hardwareId": "123-TEST-4567890",
"type": "DeviceMeasurements",
"request": {
"measurements": { 
"fuel.level": 87.1,
"engine.temp": 170
},
"updateState": true,
"eventDate": "2016-02-10T19:40:03.391Z"
}
}

设备测量创建请求支持以下字段：

领域	描述
测量	一个或多个测量，每个测量具有唯一的标识符和数值。
updateState	指示是否应将这些测量结果存储在设备分配中以指示上次已知状态。随着时间的推移，每个唯一标识符的最新值将与相关信息（如事件发生日期）一起存储。（可选的）
活动日期	发起此事件的日期。如果未通过，SiteWhere将假定当前日期。（可选的）

发送警报事件

SiteWhere支持将异常情况的警报存储为事件数据。下面显示了发送设备警报的JSON格式：

{
"hardwareId": "123-TEST-4567890",
"type":"DeviceAlert",
"request": {
"type": "engine.overheat",
"level": "Warning",
"message": "The engine is about to overheat! Turn the machine off!",
"updateState": false,
"eventDate": "2016-02-10T19:40:03.391Z",
"metadata": { 
"name1": "value1",
"name2": "value2"
}
}
}

设备警报创建请求支持以下字段：

领域	描述
类型	警报类型指示器。这是一个特定于应用程序的标识符，用于指示已生成的警报的类型。
水平	警戒级别。该字段表示警报条件的严重程度。警报级别的有效值包括“ 信息”，“ 警告”，“ 错误 ”和“ 严重”。值的含义是特定于应用程序的，可用于触发条件处理逻辑。
信息	错误消息文本。这可以是一个人类可读的值或可以在服务器上解释的编码值。
updateState	指示是否应将警报存储在设备分配中以指示上次已知状态。随着时间的推移，每个唯一警报类型的最新值将与相关信息（如事件发生日期）一起存储。（可选的）
活动日期	发起此事件的日期。如果未通过，SiteWhere将假定当前日期。（可选的）

发送位置事件

SiteWhere支持将设备位置信息存储为事件数据。下面显示了用于发送设备位置的JSON格式：

{
"hardwareId": "123-TEST-4567890",
"type":"DeviceLocation",
"request": {
"latitude": "33.75",
"longitude": "-84.39",
"elevation": "0",
"updateState": true,
"eventDate": "2016-02-10T19:40:03.390Z"
}
}

设备位置创建请求支持以下字段：

领域	描述
纬度	位置的纬度分量。
经度	位置的经度分量。
海拔	位置的高程组件。
updateState	指示是否应将此位置存储在设备分配中以指示上次已知状态。随着时间的推移，最近的位置将与相关信息（例如事件发生的日期）一起存储。（可选的）
活动日期	发起此事件的日期。如果未通过，SiteWhere将假定当前日期。（可选的）

确认设备命令

在设备接收和/或处理来自SiteWhere的命令后，它可以选择确认该命令。响应由SiteWhere关联，以便每个命令调用都与一个响应列表关联。下面显示了用于发送确认的JSON格式：

{
"hardwareId": "123-TEST-4567890",
"type": "Acknowledge",
"request": {
"response": "Pinged Me!",
"originatingEventId": "56bf72cba76cfa4ff7901e8d",
"updateState": false,
"eventDate": "2016-02-13T18:15:39.563Z"
}
}

确认请求支持以下字段：

领域	描述
响应	响应消息。
originatingEventId	用于启动命令的命令调用的唯一事件ID。这是作为命令有效载荷的一部分。
updateState	这没有任何意义，可以省略或设置为假。（可选的）
活动日期	发起此事件的日期。如果未通过，SiteWhere将假定当前日期。（可选的）

 

使用JSON发送设备数据

 

SiteWhere支持与设备的双向通信，允许系统命令和自定义命令直接发布到设备。当前可以通过MQTT和Twilio SMS消息发送命令，但可以为其他协议创建自定义命令交付提供程序。默认SiteWhere租户配置连接到MQTT代理，并将命令路由到由设备硬件ID确定的MQTT主题。系统命令在主题SiteWhere / system / [hardwareId] 上发送，同时在SiteWhere / commands / [hardwareId]上发送自定义命令。租户配置文件中的以下部分启用了此功能：

<!-- Used for devices that expect JSON invocations -->
<sw:mqtt-command-destination destinationId="json"
hostname="localhost" port="1883">
<sw:json-command-encoder/>
<sw:hardware-id-topic-extractor commandTopicExpr="SiteWhere/commands/%s"
systemTopicExpr="SiteWhere/system/%s"/>
</sw:mqtt-command-destination>

请注意，将SiteWhere配置为将MQTT有效内容编码为符合SiteWhere规范的JSON包的json-command-encoder元素。

接收系统命令

系统命令是从SiteWhere发送到设备的一些数据，用于通知它发生在服务器上的事件。例如，如果设备已经注册，则注册响应作为系统命令发送。所有的系统命令都有一些共同的字段：

{
"systemCommand": {
"type": "RegistrationAck",
"reason": "NewRegistration"
},
"nestingContext": {
"gateway": {
"createdDate": "2016-02-13T11:00:39.465-0500",
"createdBy": "system",
"deleted": false,
"hardwareId": "123-TEST-4567890",
"siteToken": "bb105f8d-3150-41f5-b9d1-db04965668d3",
"specificationToken": "964e7613-dab3-4fb3-8919-266a91370884",
"deviceElementMappings": [],
"comments": "Device created by on-demand registration.",
"assignmentToken": "aefecc20-2eb3-41f1-a52e-b5dc17557f67",
"metadata": {}
},
"nested": null,
"path": null
},
"assignment": {
"createdDate": "2016-02-13T11:00:39.467-0500",
"createdBy": "system",
"deleted": false,
"token": "aefecc20-2eb3-41f1-a52e-b5dc17557f67",
"deviceHardwareId": "123-TEST-4567890",
"assignmentType": "Unassociated",
"siteToken": "bb105f8d-3150-41f5-b9d1-db04965668d3",
"status": "Active",
"activeDate": "2016-02-13T11:00:39.467-0500",
"state": {},
"metadata": {}
}
}

领域	描述
systemCommand	从服务器发送的命令内容。
nestingContext	提供有关命令目标的信息。由于SiteWhere支持复合设备，嵌套上下文可以提供关于哪个包含的设备是命令目标（通过路径）的信息。
分配	有关设备当前分配的信息。

设备注册响应

设备发出设备注册请求后，SiteWhere将异步处理请求并在系统通道上发送响应。注册响应的JSON格式如下所示：

{
"systemCommand": {
"type": "RegistrationAck",
"reason": "NewRegistration"
},
"nestingContext": {
...
},
"assignment": {
...
}
}

以下信息在注册响应中返回（在systemCommand部分中）：

领域	描述
类型	注册响应的类型始终为RegistrationAck。
原因	指示注册结果。如果注册成功，可能的值是NewRegistration和AlreadyRegistered。对于失败的注册，可能的值是NewDevicesNotAllowed，InvalidSpecificationToken和SiteTokenRequired。

设备自定义命令请求

除了系统命令之外，每个设备规范还可以包含任何数量的与之相关的自定义命令。要调用命令，SiteWhere会创建一个命令调用事件，该事件指定调用该命令的实体以及诸如命令参数值的详细信息。该命令然后被路由到编码它的命令目的地。下面显示了使用JSON编码方案从目标接收到的命令的示例;

{
"command": {
"command": {
"createdDate": "2016-02-13T13:50:12.352-0500",
"createdBy": "admin",
"updatedDate": null,
"updatedBy": null,
"deleted": false,
"token": "b24ce333-b1a1-4de5-9ca0-cc1d09d697f1",
"specificationToken": "964e7613-dab3-4fb3-8919-266a91370884",
"namespace": "http://www.test.com",
"name": "blinkLed",
"description": "Blinks an LED on the device.",
"parameters":[
{
"name":"color",
"type":"String",
"required":true
},
{
"name":"count",
"type":"Int32",
"required":false
}],
"metadata":{}
},
"invocation": {
"id": "56bf7c84a76cfa4ff7901e94",
"eventType": "CommandInvocation",
"siteToken": "bb105f8d-3150-41f5-b9d1-db04965668d3",
"deviceAssignmentToken": "aefecc20-2eb3-41f1-a52e-b5dc17557f67",
"assignmentType": "Unassociated",
"eventDate": "2016-02-13T13:57:08.274-0500",
"receivedDate": "2016-02-13T13:57:08.274-0500",
"initiator": "REST",
"initiatorId": "admin",
"target": "Assignment",
"commandToken": "b24ce333-b1a1-4de5-9ca0-cc1d09d697f1",
"parameterValues": {
"color":"#ff0000",
"count":"3"
},
"status": "Pending",
"metadata": {}
},
"parameters": {
"color": "#ff0000",
"count": 3
}
},
"nestingContext":{
...
},"assignment":{
...
}
}

以下信息通过命令调用发送：

领域	描述
命令	关于被调用的命令的信息。这是从设备规范中提取出来的，并指出独立于当前调用的命令定义。
调用	包含有关命令调用事件的详细信息，例如谁启动了该命令以及传递了哪些参数。

参考：https://sitewhere1.sitewhere.io/userguide/sending-data.html