Expert - Interfaccia gateway OC

Questa interfaccia serve per comunicare in maniera semplice con l'HS/FS tramite il proprio software. L'HS/FS invia un telegramma a ogni modifica di un oggetto di c.. Per questa operazione, gli oggetti di c. vengono contrassegnati singolarmente o collettivamente.

Questa interfaccia è disponibile nella versione 1 (modo di compatibilità) a partire dalla versione firmware HS/FS 2.2.

A partire dal firmware HS/FS v4.7 si applica la versione 2: comunicazione crittografata tramite WebSocket (https).

1.Protocollo di comunicazione

1.1.Tipo di accesso

Per poter comunicare con l'HS/FS tramite l'interfaccia gateway OC, è necessario attivare in Expert (percorso Impostazioni progetto -> Rete -> Gateway OC) almeno uno dei metodi di accesso indicati di seguito.

Attivare il WebSocket
Attivare Modo di compatibilità

Per entrambi i metodi è disponibile un monitor HS per il collegamento all'interfaccia gateway OC.

1.1.1.Attivare il WebSocket

Con il WebSocket è possibile avere contemporaneamente fino a 10 accessi all'HS/FS.

La versione del monitor HS che utilizza questo metodo è parte integrante del software Expert e deve essere attivata in Dati principali -> Impostazioni progetto -> Interfaccia:

O

Deve essere attivata l'opzione Tutti

oppure

Deve essere attivata l'opzione Definito dall'utente,
così come
la casella di controllo hsmonitor.

In questo modo viene trasferito all'HS/FS anche il monitor HS, che può essere richiamato da browser tramite il seguente URL:

HTTPS://HS_IP/opt/hsmonitor/index.html

IP-ADR è l'indirizzo IP dell'HS/FS, completato eventualmente da una delle porte HTTPS attivate in HS/FS Expert ("Impostazioni progetto -> Rete -> Sicurezza").

1.1.2.Modo di compatibilità

Questo metodo è disponibile a partire dalla versione firmware 2.2 e consente una connessione non crittografata con l'HS/FS.
Con questo metodo è possibile avere contemporaneamente fino a 10 accessi all'HS/FS.

La versione di monitor HS funzionante con questo metodo è un programma eseguibile su PC Windows (hsmonitor.exe, a partire dalla versione v4.7 non più incluso nel volume di consegna).
Questo metodo può essere utilizzato in parallelo all'accesso tramite WebSocket.

2.Informazioni per gli sviluppatori

2.1.Autenticazione

Per stabilire la connessione WebSocket tra i propri software e l'HS/FS deve essere inserito un URL. L'URL da utilizzare contiene l'autenticazione necessaria e deve essere composto come segue:

wss://HS_IP/cogw?authorization=AUTH

IP-ADR è l'indirizzo IP dell'HS/FS, completato eventualmente da una delle porte HTTPS attivate in HS/FS Expert ("Impostazioni progetto -> Rete -> Sicurezza").

AUTH è la chiave adatta, indicata in Expert in "Impostazioni progetto -> Rete -> Gateway OC". Questo valore deve presentare codifica base64.

In caso di mancata autenticazione, non viene stabilita la connessione pendente e l'HS/FS restituisce il codice di stato 403 (Forbidden). Se la richiesta non è completa, l'HS/FS restituisce il codice di stato 400 (Bad Request).

Attenzione

A seguito della mancata autenticazione, l'indirizzo IP del client è bloccato per 5 secondi. In questo lasso di tempo il dispositivo restituisce sempre il codice di stato 503.

2.2.Comportamento in fase di avvio

Quando il dispositivo si avvia, il server HTTP è già disponibile ancora prima che venga completata la procedura di inizializzazione. In questo lasso di tempo il dispositivo restituisce sempre il codice di stato 503 a tutte le richieste. Inoltre la risposta presenta l'intestazione HTTP "Retry-After". Questo campo può essere valutato per ritentare automaticamente l'avviamento dopo il lasso di tempo in secondi indicato.

2.3.Comunicazione

La comunicazione con l'HS/FS avviene mediante dati sotto forma di strutture JSON.

2.3.1.Conversione indirizzi di gruppo

In HS/FS Expert l'indirizzo di gruppo viene indicato nella forma x/y/z o x/z. Nei telegrammi inviati all'HS/FS e ricevuti dall'HS/FS, l'indirizzo di gruppo è indicato in formato numerico. La conversione viene eseguita come segue:

Expert -> numerico
x/y/z viene convertito in: GRPADR = x*2048 + y*256 + z
x/z viene convertito in: GRPADR = x*2048 + z

numerico -> Expert
x = GRPADR / 2048, i valori decimali vengono ignorati
y = (GRPADR - x*2048) / 256, i valori decimali vengono ignorati
z = (GRPADR - x*2048 - y*256)

Nel formato numerico, l'indirizzo di gruppo è indicato nell'attributo "ganum" del file XML.

2.3.2.Telegramma a HS/FS

Struttura:
{"cmd": COMMAND, "ga": GRPADR, "value": VAL]} (con cmd = 1,2)

oppure

{"cmd": COMMAND, "ga": GRPADR} (con cmd = 3,4,5,6)

COMMAND è un numero intero compreso tra 1 e 6. Per le spiegazioni vedere la tabella successiva.

GRPADR è l'indirizzo di gruppo. Deve essere inserito in formato numerico e può essere calcolato sulla base dei formati impiegati in Expert.

L'indicazione del 3º parametro "value" è opzionale e dipende dal 1º parametro "cmd". Vedere la tabella seguente.

`COMMAND`	Descrizione	`VAL`
1	Setta valore assoluto	Float o Testo, a seconda dell'oggetto di c. in questione. Il testo deve presentare codifica base64.
2	Setta valore relativo	Float
3	Step+	Non viene indicato
4	Step-	Non viene indicato
5	Elenco +	Non viene indicato
6	Elenco -	Non viene indicato

2.3.3.Telegramma da HS/FS

È possibile inviare 3 diversi tipi di telegrammi da HS/FS:

Inizializzazione
Procedura d'inizializzazione conclusa
Telegramma successivo

2.3.3.1.Inizializzazione

Questo telegramma viene inviato dopo un riavvio per ogni oggetto di c. comunicato tramite il gateway OC.

Struttura:
{"cmd": 2, "ga": GRPADR, "value": VAL]}

GRPADR è l'indirizzo di gruppo. Deve essere inserito in formato numerico e può essere calcolato sulla base dei formati impiegati in Expert.

VAL può essere un numero intero o una stringa. Se si tratta di una stringa, presenta codifica base64.

2.3.3.2.Procedura d'inizializzazione conclusa

Questo telegramma viene inviato da HS/FS se dopo un riavvio è completata la procedura di inizializzazione di tutti gli oggetti di c. comunicati tramite il gateway OC.

Struttura:
{"cmd": 2}

2.3.3.3.Telegramma successivo

Questo telegramma viene inviato se è stato assegnato un valore all'oggetto di c. indicato. Ciò avviene anche se il valore precedente coincide con il nuovo valore dell'oggetto di c..

Struttura:
{"cmd": 1, "ga": GRPADR, "value": VAL]}

GRPADR è l'indirizzo di gruppo. Deve essere inserito in formato numerico e può essere calcolato sulla base dei formati impiegati in Expert.

VAL può essere un numero intero o una stringa. Se si tratta di una stringa, presenta codifica base64.

2.4.Nome in chiaro degli oggetti di c.

È possibile richiamare i nomi degli oggetti di comunicazione tramite il seguente URL sotto forma di file XML.

HTTPS://HS_IP/opt/sys/cobjects.xml

IP-ADR è l'indirizzo IP dell'HS/FS, completato eventualmente da una delle porte HTTPS attivate in HS/FS Expert ("Impostazioni progetto -> Rete -> Sicurezza").

Esempio: HTTPS://192.168.0.11:443/opt/sys/cobjects.xml
Struttura dei dati del file XML (esempio):

 <cobject
    id="911"
    used="0"
    type="eib"
    path="01 Lighting\2nd Floor\"
    fmt="EIS1+EIS2+EIS7_1BIT"
    fmtex="integer"
    name="FL02 Light"
    rem="0"
    init="0"
    min="0"
    max="1"
    step="0"
    list=""
    ga="1/2/1"
    ganum="2561"
    cogws="1"
    cogwr="0"
    scan="1"
    sbc="1"
    read="0"
    transmit="1"
 />

Tutti i campi vengono elaborati in HS/FS Expert nella voce di programma Oggetti di comunicazione. Per ulteriori informazioni sui vari campi consultare la guida online dell'HS/FS Expert nell'area relativa agli oggetti di comunicazione.

Attributo	Descrizione
id	Numero univoco dell'oggetto di comunicazione
used	1 = oggetto di comunicazione viene utilizzato nel progetto. 0 = nessun utilizzo.
type	Tipo di oggetto di comunicazione "internal" = oggetto di comunicazione interno "eib" = oggetto di comunicazione EIB
path	Cartella nella quale è salvato l'oggetto di comunicazione in HS/FS Expert.
fmt	Formato dati 1 Testo in chiaro (i testi si trovano nel file minmax.txt nella subdirectory di Expert-"/dat") `EIS1+EIS2+EIS7_1BIT EIS6_8BIT NONEIS_8BIT_RTR EIS5_16BIT EIS2+EIS6_8BIT EIS?_8BIT EIS10_16BIT_UNSIGNED EIS10_16BIT_SIGNED EIS11_32BIT_UNSIGNED EIS11_32BIT_SIGNED EIS?_14BYTE EIS3_3BYTE_TIME EIS4_3BYTE_DATE EIS?_4BIT EIS9_4BYTE EIS8_2BIT EIS?_DALI EIS?_SRO EIS?_3BYTE`
fmtex	Formato dati 2 `integer number text date time unknown`
name	Nome dell'oggetto di comunicazione
rem	1 = permanente in HS/FS 0 = non permanente
init	Valore init
min	Valore minimo
max	Valore massimo
step	Incremento
list	Elenco
ga	Indirizzo di gruppo come acquisito in HS/FS Expert
ganum	Indirizzo di gruppo (numerico)
cogws	Invio gateway OC
cogwr	Ricezione gateway OC
scan	1 = interroga all'avvio 0 = non interrogare all'avvio
sbc	1 = send by change 0 = nessun send by change
read	1 = leggibile 0 = non leggibile
transmit	1 = trasmetti 0 = non trasmettere