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"

}

]

}