# 关于WebSocket

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

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

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

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

### 变量

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

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

注：

- 不支持用户数据类型（结构、数组）的变量。

- 最大变量数量为每个会话100。

### 报警/系统错误

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

## 命令

下面是命令:

注：示例代码用Java编写。

### 建立会话

建立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: “alarm” System error: “error”
示例 | { "command": " subscribe ", " alarm ": ["alarm","error"] }

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

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

项目 | 值
发件人 | 客户端
数据 |
字段 | 数据类型 | 值 | 注
command | 字符串 | "unsubscribe" | 取消订阅
alarm | 字符串数组 | - | 要取消订阅的报警名称数组。 Alarm: “alarm” System error: “error”
示例 | { "command": " unsubscribe", " alarm ": ["alarm","error"] }

### 变量订阅

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

项目 | 值
发件人 | 服务器（人机界面）
数据 |
字段 | 数据类型 | 值 | 注
updated | 字符串 | "variable" | 变量
data | 对象数组 | - | 变量信息数组。
变量信息:
字段 | 数据类型 | 值 | 注
name | 字符串 | 变量名称 | 画面编辑软件中设置的变量名称。
quality | 字符串 | 质量 | “good”: Good "无效": 值无效 “bad”: Error “unknown”: Never read
Value | 布尔、数字、字符串 | 变量值。 | Only when quality is ”good”, this field is available. 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”: Occurred “Ack”: 已确认 “Return”: Recovered “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”: Occurred “Ack”: Acknowledged “Return”: Recovered
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" } ] }