# About WebSocket

Using WebSocket, you can receive notifications of variables, alarms and system errors. To receive notifications, establishing a session and subscribing them is necessary.

WebSocket (Version 13) protocols can be used and maximum number of WebSocket sessions is 5.

If using security, send an authorization command. If authorization is not done or security level is not enough, you will not receive notification from display unit.

If there is no communication from client, the display unit will send Ping on WebSocket for every 10 seconds. If there is no response to 5 Pings (that is, if there is no communication from client including Pong for 60 seconds), the session will be closed from display unit.

### Variables

You can receive notifications when the value and/or quality of the variables created in screen editing software is changed.

To receive notifications, you need to subscribe the variables to monitor. If the subscribed variable(s) is an external variable(s), display unit starts to read the value(s) from external device(s).

Note:

- Variables of user data type (structure, array) are not supported.

- The maximum number of variables is 100 per session.

### Alarms/System Errors

When alarms or system errors are occurred/acknowledged/recovered in display unit, you can receive notifications. To receive notifications, you need to subscribe.

## Commands

Following are the commands:

Note: The example code is written in Java.

### Establishing Session

To establish a session for WebSocket.

#### Request

Item | Value
Methods | GET
URL | <Base URL>/ws Base URL
Parameters | N/A
Header |
Header | Value
Upgrade | websocket
Connection | Upgrade
Sec-WebSocket-Version | 13
Sec-WebSocket-Key | WebSocket Handshake Key
Body | N/A
Example | 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

#### Response

Item | Value
Status Code | Success to establish a session, display unit will send 101 (Switching Protocol).
Code | Notes
101 Switching Protocols | Success to establish a session.
429 Too Many Requests | Failed to establish a session because the maximum number of sessions has been reached.
400 Bad Request | Failed to establish a session. The reason is other than the above.
Header |
Header | Value
Upgrade | websocket
Connection | Upgrade
Sec-WebSocket-Accept | WebSocket Handshake
Body | N/A
Example | HTTP/1.1 101 Switching Protocols Upgrade: websocket Connection: Upgrade Sec-WebSocket-Accept: WLjfOfV0ERDw6E/NUUaBpqXnHFc=

### Authorization

If you use user management, send the authorization command first.

Item | Value
Sender | Client
Data |
Field | Data Type | Value | Notes
Authorization | string | "Bearer <token>" | Use token reply in Log-in API.
Example | { " Authorization ": " Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IlVzZXIxIiwibGV2ZWwiOjF9.eqVwAuo0KMqdggICllJVPs3IE67oHdUpo04w68md7kI " }

### Adding Monitoring Variables

Add variables to subscribe. If the number of monitoring variables exceeds the maximum number, it is truncated. For added variables, notification will be sent immediately as the initial value.

Item | Value
Sender | Client
Data |
Field | Data Type | Value | Notes
command | string | "add_monitor" | Add monitor variables.
variable | array of string | - | Array of variable name.
Example | { "command": "add_monitor", "variable": ["Variable1","Variable2"] }

### Removing Monitoring Variables

Remove variables to unsubscribe.

Item | Value
Sender | Client
Data |
Field | Data Type | Value | Notes
command | string | "remove_monitor" | Remove monitor variables.
variable | array of string | - | Array of variable name.
Example | { "command": " remove _monitor", "variable": ["Variable1","Variable2"] }

### Replacing Monitoring Variables

To replace all the subscribed variables. If the number of monitoring variables exceeds the maximum number, it is truncated.

For added variables, notification will be sent immediately as the initial value.

Item | Value
Sender | Client
Data |
Field | Data Type | Value | Notes
command | string | "replace_monitor" | Replace monitor variables.
variable | array of string | - | Array of variable name.
Example | { "command": " replace_monitor", "variable": ["Variable1","Variable2"] }

### Clearing Monitoring Variables

To remove all the subscribed variables.

Item | Value
Sender | Client
Data |
Field | Data Type | Value | Notes
command | string | "clear_monitor" | Clear monitoring variables.
Example | { "command": " clear_monitor", }

### Subscribing Alarms and System Errors

To subscribe alarms and system errors.

Item | Value
Sender | Client
Data |
Field | Data Type | Value | Notes
command | string | "subscribe" | Subscribe
alarm | array of string | - | Array of alarms name to subscribe. Alarm: “alarm” System error: “error”
Example | { "command": " subscribe ", " alarm ": ["alarm","error"] }

### Unsubscribing Alarms and System Errors

To unsubscribe alarms and system errors.

Item | Value
Sender | Client
Data |
Field | Data Type | Value | Notes
command | string | "unsubscribe" | Unsubscribe
alarm | array of string | - | Array of alarms name to unsubscribe. Alarm: “alarm” System error: “error”
Example | { "command": " unsubscribe", " alarm ": ["alarm","error"] }

### Variables Subscription

To receive notification from display unit when value or/and quality of the subscribed variable is changed.

Item | Value
Sender | Server (Display Unit)
Data |
Field | Data Type | Value | Notes
updated | string | "variable" | Variable
data | array of object | - | Array of variable information.
Variable information:
Field | Data Type | Value | Notes
name | string | Variable name | Variable name set in screen editing software.
quality | string | Quality | “good”: Good "invalid": Value is invalid “bad”: Error “unknown”: Never read
Value | boolean, number, string | The value of variable. | Only when quality is ”good”, this field is available. Data type of JSON depends on the data type of variable.
Example | { "updated":”variable”, "data": [ { “name”: “Variable1”, “quality”: “good”, “value”: 100 }, { “name”: “Variable2”, “quality”: “bad” }, { “name”: “Variable3”, “quality”: “unknown” } ] }

The following table lists the supported data types between screen editing software and WebSocket:

Data Type | WebSocket (JSON Type) | WebSocket Value Range
BOOL | boolean | true/false
BYTE, SINT, USINT, WORD, INT, UINT, DWORD, DINT, UDINT, LWORD, LINT, ULINT, REAL, LREAL, TIME | number | Value range of a 64-bit floating point value. *Accurate within 52 bits for LWORD, LINT, and ULINT. *Null when a REAL or LREAL value is NaN or INFINITY.
STRING, WSTRING | string | Characters supported by UTF-8
DATE, TIME_OF_DAY, DATE_AND_TIME | string | ISO 8601 format

Note: LWORD values are displayed as float on the display unit.

### Alarms Subscription

To receive notification from display unit when alarms are occurred/acknowledged/recovered/unacknowledged in the display unit.

Item | Value
Sender | Server (Display Unit)
Data |
Field | Data Type | Value | Notes
updated | string | "alarm" | Alarm
data | array of object | - | Array of alarm information.
Alarm information:
Field | Data Type | Value | Notes
message | string | Message | Message set in screen editing software.
parameter | number | Parameter | Parameter set in screen editing software.
status | string | Status | “Active”: Occurred “Ack”: Acknowledged “Return”: Recovered “UnACK”: Unacknowledged
time | string | Time | ISO-8601 format
type | string | Type | “HiHi”/”Hi”/”Lo”/”LoLo”
variable | string | Variable name | Variable name related to the alarm.
groupname | string | Group name | Group name of the alarm.
severity | number | Severity | Severity set in screen editing software.
value | boolean, number | The value of variable | Data type of JSON depends on the data type of variable.
Example | { "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 } ] }

### System Errors Subscription

To receive notification from display unit when system errors are occurred/acknowledged/recovered in the display unit.

Item | Value
Sender | Server (Display Unit)
Data |
Field | Data Type | Value | Notes
updated | string | "error" | System error
data | array of object | - | Array of system error information.
System error information:
Field | Data Type | Value | Notes
message | string | Message | System error message.
status | string | Status | “Active”: Occurred “Ack”: Acknowledged “Return”: Recovered
time | string | Time | ISO-8601 format
equipment | string | Equipment name | The external device name from which the error is generated is set in equipment name.
Example | { "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" } ] }