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).

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:

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

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" } ] }