关于WebSocket

使用WebSocket，可接收变量、报警和系统错误的通知。要接收通知，需要建立会话并订阅它们。

可以使用WebSocket（版本13）协议，最大WebSocket会话数为5。

如果使用安全，则发送授权命令。如果未完成授权或安全级别不够，您将不会收到来自人机界面的通知。

如果客户端没有通讯，人机界面将每隔10秒在WebSocket上发送一次Ping。如果5次Ping没有响应（即客户端没有通讯，包括Pong 60秒），会话将从人机界面关闭。

变量

当画面编辑软件中所创建变量的值和/或质量发生变化时，您可以收到通知。

要接收通知，需要订阅要监视的变量。如果订阅的变量是外部变量，则人机界面开始从外接设备读取值。

注：

不支持用户数据类型（结构、数组）的变量。
最大变量数量为每个会话100。

报警/系统错误

当报警或系统错误在人机界面中发生/确认/恢复时，您可以接收通知。要接收通知，您需要订阅。

命令

下面是命令:

建立会话

建立WebSocket会话。

请求

项目

值

方法

GET

URL

<Base URL>/ws Base URL

参数

N/A

标题

标题	值
Upgrade	websocket
Connection	Upgrade
Sec-WebSocket-Version	13
Sec-WebSocket-Key	WebSocket Handshake Key

正文

N/A

示例

GET http://192.168.1.100:8000/api/v1/ws HTTP/1.1

Host: localhost:8082

Upgrade: websocket

Connection: Upgrade

Sec-WebSocket-Version: 13

Sec-WebSocket-Key: k3CyFjeNOBNzFZx4blx9kg==

Origin: ws://localhost:8082

响应

项目

值

状态代码

成功建立会话，人机界面将发送101（切换协议）。

代码	注
101 Switching Protocols	成功建立会话。
429 Too Many Requests	无法建立会话，因为已经达到了会话上限。
400 Bad Request	无法建立会话。不是以上原因。

标题

标题	值
Upgrade	websocket
Connection	Upgrade
Sec-WebSocket-Accept	WebSocket Handshake

正文

N/A

示例

HTTP/1.1 101 Switching Protocols

Upgrade: websocket

Connection: Upgrade

Sec-WebSocket-Accept: WLjfOfV0ERDw6E/NUUaBpqXnHFc=

授权

如果使用用户管理，请先发送授权命令。

项目

值

发件人

客户端

数据

字段	数据类型	值	注
Authorization	字符串	"Bearer <token>"	在登录API中使用令牌回复

示例

{

"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IlVzZXIxIiwibGV2ZWwiOjF9.eqVwAuo0KMqdggICllJVPs3IE67oHdUpo04w68md7kI "

}

添加监控变量

添加要订阅的变量。如果监控变量的数量超过最大值，则会被缩减。对于添加的变量，作为初始值将立即发送通知。

项目

值

发件人

客户端

数据

字段	数据类型	值	注
command	字符串	"add_monitor"	添加监控变量。
variable	字符串数组	-	变量名称数组。

示例

{

"command": "add_monitor",

"variable": ["Variable1","Variable2"]

}

移除监控变量

移除变量以取消订阅。

项目

值

发件人

客户端

数据

字段	数据类型	值	注
command	字符串	"remove_monitor"	移除监控变量。
variable	字符串数组	-	变量名称数组。

示例

{

"command": "remove_monitor",

"variable": ["Variable1","Variable2"]

}

替换监控变量

替换所有订阅的变量。如果监控变量的数量超过最大值，则会被缩减。

对于添加的变量，作为初始值将立即发送通知。

项目

值

发件人

客户端

数据

字段	数据类型	值	注
command	字符串	"replace_monitor"	替换监控变量。
variable	字符串数组	-	变量名称数组。

示例

{

"command": "replace_monitor",

"variable": ["Variable1","Variable2"]

}

清除监控变量

移除所有订阅的变量。

项目

值

发件人

客户端

数据

字段	数据类型	值	注
command	字符串	"clear_monitor"	清除监控变量。

示例

{

"command": "clear_monitor"

}

订阅报警和系统错误

订阅报警和系统错误。

项目

值

发件人

客户端

数据

字段

数据类型

值

注

command

字符串

"subscribe"

alarm

字符串数组

要订阅的报警名称数组。

报警: “alarm”

系统错误: “error”

示例

{

"command": "subscribe",

"alarm": ["alarm","error"]

}

取消订阅报警和系统错误

取消订阅报警和系统错误。

项目

值

发件人

客户端

数据

字段

数据类型

值

注

command

字符串

"unsubscribe"

取消订阅

alarm

字符串数组

要取消订阅的报警名称数组。

报警: “alarm”

系统错误: “error”

示例

{

"command": "unsubscribe",

"alarm": ["alarm","error"]

}

变量订阅

当订阅变量的值或/和质量发生变化时，从人机界面接收通知。

项目

值

发件人

服务器（人机界面）

数据

字段	数据类型	值	注
updated	字符串	"variable"	变量
data	对象数组	-	变量信息数组。

变量信息:

字段	数据类型	值	注
name	字符串	变量名称	画面编辑软件中设置的变量名称。
quality	字符串	质量	“good”: 良好 "invalid": 值无效 “bad”: 错误 “unknown”: 未读
Value	布尔、数字、字符串	变量值。	只有当质量为 ”good”时，该字段才可用。 JSON的数据类型取决于变量的数据类型。

示例

{

"updated":”variable”,

"data": [

{

“name”: “Variable1”,

“quality”: “good”,

“value”: 100

{

“name”: “Variable2”,

“quality”: “bad”

{

“name”: “Variable3”,

“quality”: “unknown”

}

]

}

下表列出了画面编辑软件和WebSocket之间支持的数据类型：

数据类型	WebSocket (JSON类型)	WebSocket 值范围
BOOL	布尔	true/false
BYTE, SINT, USINT, WORD, INT, UINT, DWORD, DINT, UDINT, LWORD, LINT, ULINT, REAL, LREAL, TIME	数字	64位浮点值的值范围。 LWORD、LINT和ULINT的精度在52位以内。当REAL或LREAL值为NaN或无穷大时为空。
STRING、WSTRING	字符串	UTF-8支持的字符
DATE, TIME_OF_DAY, DATE_AND_TIME	字符串	ISO 8601格式

注：LWORD 值以浮点数类型显示在人机界面上。

报警订阅

当人机界面发生/确认/恢复/未确认报警时，接收来自人机界面的通知。

项目

值

发件人

服务器（人机界面）

数据

字段	数据类型	值	注
updated	字符串	"alarm"	报警 (报警组)
data	对象数组	-	报警信息数组。

报警信息：

字段	数据类型	值	注
message	字符串	消息	画面编辑软件中设置的消息。
parameter	数字	参数	画面编辑软件中设置的参数。
status	字符串	状态	“Active”: 发生 “Ack”: 确认 “Return”: 已恢复 “UnACK”: 未确认
time	字符串	Time	ISO-8601格式
type	字符串	类型	“HiHi”/”Hi”/”Lo”/”LoLo”
variable	字符串	变量名称	与报警相关的变量名称。
groupname	字符串	组名称	报警的组名称。
severity	数字	严重级别	画面编辑软件中设置的严重级别。
value	布尔，数字	变量值	JSON的数据类型取决于变量的数据类型。

示例

{

"updated": “alarm”,

"data”:[

{

"message": "BOOL_Hi",

"parameter": 100,

"status": "Active",

"time": "2017-07-07T16:20:01",

"type": "Hi",

"variable": "BOOL_Internal"

“groupname”: “AlarmGroup1”,

“severity”: 1,

“value”: true

}

]

}

系统错误订阅

当人机界面中发生/确认/恢复系统错误时，接收来自人机界面的通知。

项目

值

发件人

服务器（人机界面）

数据

字段	数据类型	值	注
updated	字符串	"error"	系统错误
data	对象数组	-	系统错误信息的数组。

系统错误信息:

字段	数据类型	值	注
message	字符串	消息	系统错误消息。
status	字符串	状态	“Active”: 发生 “Ack”: 确认 “Return”: 已恢复
time	字符串	Time	ISO-8601格式
equipment	字符串	设备名称	从中生成错误的外接设备名称在设备名称中设置。

示例

{

"updated”:”error",

"data": [

{

"equipment": "MODBUS_Equipment",

"message": "MODBUS_Equipment:TCP connection open error (IP Address:127.0.0.2)",

"status": "Active",

"time": “2017-07-07T16:42:00"

}

]

}