# WebSocket

Con l’uso di WebSocket è possibile ricevere notifiche di variabili, allarmi e errori di sistema. Per ricevere notifiche, occorre stabilire una sessione e se occorre sottoscriverle.

Si usano i protocolli WebSocket (versione 13) e il massimo numero di sessioni WebSocket è 5.

Quando si usa la Sicurezza, inviare il comando di autorizzazione. Se l’autorizzazione non è stata fatta o se il livello di protezione non è sufficiente, non si riceveranno le notifiche dal visualizzatore.

Quando non ci sono comunicazioni dal client, il visualizzatore invierà un Ping al WebSocket ogni 10 secondi. Se non ci sono risposte a 5 Ping (cioè, non ci sono comunicazioni dal client compresi i Pong per 60 secondi), la sessione viene chiusa dal visualizzatore.

### Variabili

Le notifiche si ricevono quando il valore e/o la qualità delle variabili create con il software di modifica delle schermate vengono modificati.

Per ricevere le notifiche occorre sottoscrivere le variabili da monitorare. Se le variabili sottoscritte sono variabili esterne, il visualizzatore inizia a leggere i valori dai dispositivi esterni.

Nota:

- Variabili di tipo di dati utente (strutture, array) non sono supportati.

- Il numero massimo di variabili è 100 per ogni sessione.

### Allarmi/Errori di sstema

Se nel visualizzatore si verificano/si riconoscono/si ripristinano allarmi o errori di sistema, si possono ricevere le notifiche Per ricevere le notifiche occorre sottoscrivere.

## Comandi

I comandi sono i seguenti:

Nota: il codice dell’esempio è scritto in Java.

### Stabilire la sessione

Stabilire la sessione per WebSocket.

#### Richiesta

Elemento | Valore
Metodi | GET
URL | <Base URL>/ws Base URL
Parametri | N/A
Intestazione |
Intestazione | Valore
Upgrade | websocket
Connection | Upgrade
Sec-WebSocket-Version | 13
Sec-WebSocket-Key | WebSocket Handshake Key
Corpo | N/A
Esempio | GET http://192.168.1.100:8000/api/v1/ws HTTP/1.1 Host: localhost:8082 Upgrade: websocket Connessione: Upgrade Sec-WebSocket-Version: 13 Sec-WebSocket-Key: k3CyFjeNOBNzFZx4blx9kg== Origin: ws://localhost:8082

#### Risposta

Elemento | Valore
Codice di stato | Autenticazione riuscita, il visualizzatore invierà 101 (Protocollo di commutazione).
Codice | Nota
101 Switching Protocols | Tentativo di stabilire la connessione riuscito.
429 Too Many Requests | Tentativo di stabilire la connessione non riuscito perché è stato raggiunto il numero massimo di sessioni.
400 Bad Request | Tentativo di stabilire la connessione non riuscito. La ragione è diversa da quella precedente.
Intestazione |
Intestazione | Valore
Upgrade | websocket
Connection | Upgrade
Sec-WebSocket-Accept | WebSocket Handshake
Corpo | N/A
Esempio | HTTP/1.1 101 Switching Protocols Upgrade: websocket Connessione: Upgrade Sec-WebSocket-Accept: WLjfOfV0ERDw6E/NUUaBpqXnHFc=

### Autorizzazione

Quando si utilizza la gestione utenti, inviare prima il comando di autorizzazione.

Elemento | Valore
Mittente | Client
Dati |
Campo | Tipo di dati | Valore | Nota
Authorization | stringa | "Bearer <token>" | Usare la risposta del token per accedere in API.
Esempio | { " Authorization ": " Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IlVzZXIxIiwibGV2ZWwiOjF9.eqVwAuo0KMqdggICllJVPs3IE67oHdUpo04w68md7kI " }

### Aggiunta delle variabili di monitoraggio

Aggiungere le variabili da sottoscrivere. Se il numero delle variabili di monitoraggio supera il numero massimo, viene troncato. Per le variabili aggiunte, la notifica viene inviata immediatamente come valore iniziale.

Elemento | Valore
Mittente | Client
Dati |
Campo | Tipo di dati | Valore | Nota
command | stringa | "add_monitor" | Aggiunta variabili da monitorare.
variable | array di stringhe | - | Array di nomi di variabili.
Esempio | { "command": "add_monitor", "variable": ["Variable1","Variable2"] }

### Rimozione variabili da monitorare.

Rimozione variabili per annullare la sottoscrizione.

Elemento | Valore
Mittente | Client
Dati |
Campo | Tipo di dati | Valore | Nota
command | stringa | "remove_monitor" | Rimozione variabili da monitorare.
variable | array di stringhe | - | Array di nomi di variabili.
Esempio | { "command": " remove _monitor", "variable": ["Variable1","Variable2"] }

### Sostituzione variabili da monitorare.

Per sostituire tutte le variabili sottoscritte. Se il numero delle variabili di monitoraggio supera il numero massimo, viene troncato.

Per le variabili aggiunte, la notifica viene inviata immediatamente come valore iniziale.

Elemento | Valore
Mittente | Client
Dati |
Campo | Tipo di dati | Valore | Nota
command | stringa | "replace_monitor" | Sostituire le variabili da monitorare.
variable | array di stringhe | - | Array di nomi di variabili.
Esempio | { "command": " replace_monitor", "variable": ["Variable1","Variable2"] }

### cancellazione variabili da monitorare.

Per rimuovere tutte le variabili sottoscritte.

Elemento | Valore
Mittente | Client
Dati |
Campo | Tipo di dati | Valore | Nota
command | stringa | "clear_monitor" | Cancellare le variabili da monitorare.
Esempio | { "command": " clear_monitor", }

### Sottoscrizione di allarmi ed errori di sistema

Sottoscrivere allarmi ed errori di sistema

Elemento | Valore
Mittente | Client
Dati |
Campo | Tipo di dati | Valore | Nota
command | stringa | "subscribe" | Sottoscrivere
alarm | array di stringhe | - | Array dei nomi di allarmi da sottoscrivere. Allarme: “alarm” Errore di sistema: “error”
Esempio | { "command": " subscribe ", " alarm ": ["alarm","error"] }

### Cancellazione sottoscrizione di allarmi ed errori di sistema

Cancellare sottoscrizione di allarmi ed errori di sistema.

Elemento | Valore
Mittente | Client
Dati |
Campo | Tipo di dati | Valore | Nota
command | stringa | "unsubscribe" | Cancellare la sottoscrizione
alarm | array di stringhe | - | Array dei nomi di allarmi di cui cancellare la sottoscrivere. Allarme: “alarm” Errore di sistema: “error”
Esempio | { "command": " unsubscribe", " alarm ": ["alarm","error"] }

### Sottoscrizione variabili

Per ricevere le notifiche dal visualizzatore quando il valore e/o la qualità delle variabili sottoscritte è stata modificata.

Elemento | Valore
Mittente | Server (visualizzatore)
Dati |
Campo | Tipo di dati | Valore | Nota
updated | stringa | "variable" | Variabile
data | array di oggetti | - | Array di informazioni delle variabili.
Informazioni delle variabili.
Campo | Tipo di dati | Valore | Nota
name | stringa | Nome variabile | Nome variabile impostato nel software di modifica delle schermate.
quality | stringa | Qualità | "good": Buono "invalid": Il valore non è valido "bad": Errore "unknown": Mai letto
Value | booleano, numero, stringa | Valore della variabile. | Questo campo è disponibile solo se la qualità è ”good”. Il tipo Dati JSON dipende dal tipo di dati della variabile.
Esempio | { "updated":”variable”, "data": [ { “name”: “Variable1”, “quality”: “good”, “value”: 100 }, { “name”: “Variable2”, “quality”: “bad” }, { “name”: “Variable3”, “quality”: “unknown” } ] }

La tabella seguente elenca i tipi di dati supportati tra il software di modifica delle schermate e WebSocket:

Tipo di dati | WebSocket (tipo JSON) | Range dei valori di WebSocket
BOOL | booleano | vero/falso
BYTE, SINT, USINT, WORD, INT, UINT, DWORD, DINT, UDINT, LWORD, LINT, ULINT, REAL, LREAL, TIME | numero | Range del valore del valore a 64 bit in virgola mobile. *Precisione interna a 52 bit per LWORD, LINT e ULINT. *Valore nullo se il valore REAL o LREAL è NaN o INFINITY.
STRING, WSTRING | stringa | Caratteri supportati da UTF-8
DATE, TIME_OF_DAY, DATE_AND_TIME | stringa | Formato ISO 8601

Nota: I valori LWORD sul visualizzatore si mostrano in virgola mobile.

### Sottoscrizione allarmi

Ricevere le notifiche dal visualizzatore quando nel visualizzatore gli allarmi si verificano/sono riconosciuti/sono ripristinati/ non sono riconosciuti.

Elemento | Valore
Mittente | Server (visualizzatore)
Dati |
Campo | Tipo di dati | Valore | Nota
updated | stringa | "alarm" | Allarme
data | array di oggetti | - | Array di informazioni degli allarmi.
Informazioni degli allarmi:
Campo | Tipo di dati | Valore | Nota
message | stringa | Messaggio | Messaggio impostato nel software di modifica delle schermate.
parameter | numero | Parametro | Parametro impostato nel software di modifica delle schermate.
status | stringa | Stato | "Active": Si è verificato "Ack": Riconosciuto "Return": Ripristinato "UnACK":: Non riconosciuto
time | stringa | Ora | Formato ISO-8601
type | stringa | Tipo | “HiHi”/”Hi”/”Lo”/”LoLo”
variable | stringa | Nome variabile | Nome variabile collegato a un allarme.
groupname | stringa | Nome gruppo | Nome gruppo di un allarme.
severity | numero | Gravità | Gravità impostata nel software di modifica delle schermate.
value | booleano, numero | Valore della variabile | Il tipo Dati JSON dipende dal tipo di dati della variabile.
Esempio | { "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 } ] }

### Sottoscrizione errori di sistema

Ricevere le notifiche dal visualizzatore quando si verificano/si riconoscono/si ripristinano errori di sistema nel visualizzatore.

Elemento | Valore
Mittente | Server (visualizzatore)
Dati |
Campo | Tipo di dati | Valore | Nota
updated | stringa | "error" | Errore di sistema
data | array di oggetti | - | Array di informazioni errori di sistema.
Informazioni errori di sistema:
Campo | Tipo di dati | Valore | Nota
message | stringa | Messaggio | Messaggio errori di sistema.
status | stringa | Stato | "Active": Si è verificato "Ack": Riconosciuto "Return": Ripristinato
time | stringa | Ora | Formato ISO-8601
equipment | stringa | Nome apparecchiatura | Il nome del dispositivo esterno da cui si è generato l’errore viene impostato nel nome apparecchiatura.
Esempio | { "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" } ] }