Manuale utente del software DIVUS VISION API

DIVUS VISION API è uno strumento software progettato per l'interfacciamento con i sistemi DIVUS VISION. Consente agli utenti di accedere e controllare vari elementi all'interno del sistema utilizzando i protocolli MQTT.

Domande frequenti

D: Posso utilizzare DIVUS VISION API senza avere una conoscenza preliminare di PC o tecnologia di automazione?

R: Il manuale è pensato su misura per gli utenti con conoscenze pregresse in queste aree per garantire un utilizzo efficiente dell'API.

INFORMAZIONI GENERALI

DIVUS GmbH Pillhof 51 I-39057 Appiano (BZ) – Italia

Le istruzioni per l'uso, i manuali e il software sono protetti dal diritto d'autore. Tutti i diritti riservati. Non è consentita la copia, la duplicazione, la traduzione, la traduzione totale o parziale. Fa eccezione la creazione di una copia di backup del software per uso personale.
Il manuale è soggetto a modifiche senza preavviso. Non possiamo garantire che i dati contenuti in questo documento e sui supporti di memorizzazione forniti siano esenti da errori e corretti. Suggerimenti per miglioramenti e suggerimenti su errori sono sempre benvenuti. Gli accordi si applicano anche agli allegati specifici del presente manuale. Le denominazioni presenti in questo documento possono essere marchi il cui utilizzo da parte di terzi per propri scopi può violare i diritti dei rispettivi proprietari. Istruzioni per l'utente: leggere questo manuale prima di utilizzarlo per la prima volta e conservarlo in un luogo sicuro per riferimento futuro. Gruppo target: Il manuale è stato scritto per utenti con conoscenze pregresse di PC e tecnologia di automazione.

CONVENZIONI DI PRESENTAZIONE

Introduzione

INTRODUZIONE GENERALE

Questo manuale descrive l'API VISION (Application Programming Interface), un'interfaccia attraverso la quale VISION può essere indirizzata e controllata da sistemi esterni.
In termini pratici, ciò significa che è possibile utilizzare sistemi come

Esploratore MQTT (https://www.microsoft.com/store/… – per testare),

Assistente domestico (https://www.home-assistant.io/) O
Nodo-ROSSO (https://nodered.org/)

per controllare gli elementi gestiti da VISION o leggerne lo stato. L'accesso e la comunicazione avvengono tramite il protocollo MQTT, che utilizza i cosiddetti argomenti per indirizzare singole funzioni o insiemi di funzioni o per essere informato sulle modifiche delle stesse. A questo scopo viene utilizzato un server MQTT (broker) che si occupa della sicurezza e della gestione/distribuzione dei messaggi ai partecipanti. In questo caso il server MQTT si trova direttamente sul DIVUS KNX IQ ed è appositamente configurato per questo scopo. Sebbene la VISION API possa essere utilizzata anche senza conoscenze di programmazione, questa funzionalità è adatta per utenti esperti.

PREREQUISITI

Come spiegato nel manuale VISION l'utenza API deve essere prima attivata di default per poterla utilizzare l'accesso API funziona solo utilizzando i dati di autenticazione degli utenti Api. Per quanto riguarda i diritti dell'utente, l'attivazione di tale funzionalità potrà poi essere configurata o su tutti oppure su singoli elementi. Vedi Cap.0. Naturalmente è necessario anche un progetto VISION in cui gli elementi che si desidera controllare dall'esterno siano completamente configurati e il collegamento con essi sia stato testato con successo. Per poter indirizzare i singoli elementi tramite l'API, è necessario conoscere il loro ID elemento: questo viene visualizzato nella parte inferiore del modulo delle impostazioni dell'elemento

SICUREZZA

Per motivi di sicurezza l'accesso API è possibile solo localmente (quindi non tramite cloud). Il rischio per la sicurezza durante l'attivazione dell'accesso API è quindi basso. Tuttavia, gli elementi rilevanti per la sicurezza non dovrebbero essere abilitati o negati esplicitamente per l'accesso all'API.

MQTT E I SUOI TERMINI – BREVE SPIEGAZIONE

In MQTT il ruolo di gestione e distribuzione centralizzata di tutti i messaggi è quello del broker. Sebbene server MQTT e broker MQTT non siano sinonimi (server è un termine più ampio per un ruolo che possono svolgere anche i client MQTT), in questo manuale si intende sempre il broker quando viene menzionato il server MQTT. Lo stesso DIVUS KNX IQ svolge il ruolo di broker MQTT/server MQTT nel contesto di questo manuale.
Un server MQTT utilizza i cosiddetti argomenti: una struttura gerarchica con la quale i dati vengono categorizzati, gestiti e pubblicati.

La pubblicazione ha l'obiettivo primario di rendere i dati disponibili agli altri partecipanti attraverso argomenti. Se si vuole modificare un valore si scrive nell'argomento desiderato insieme alla variazione di valore desiderata, anche utilizzando un'azione di pubblicazione. Il dispositivo di destinazione o il server MQTT legge la modifica desiderata che lo riguarda e la adotta di conseguenza. Per verificare che la modifica sia stata applicata, puoi controllare nell'argomento in tempo reale sottoscritto per vedere se la modifica si riflette lì, se tutto ha funzionato bene.
I clienti selezionano gli argomenti che li interessano: questo si chiama abbonamento. Ogni volta che cambia un valore all'interno/sotto di un argomento, tutti i clienti iscritti vengono informati, ovvero senza dover chiedere esplicitamente se è cambiato qualcosa o qual è il valore attuale.

È possibile aprire (o indirizzare) un canale di comunicazione separato con il server MQTT inserendo una stringa univoca denominata client_id in un argomento. Il client_id deve essere utilizzato nell'argomento per elaborare i valori. Questo serve a identificare l'origine di ogni modifica, aiuta in caso di errori e non influisce sugli altri client, poiché anche le corrispondenti risposte del server, compresi eventuali codici di errore e messaggi, raggiungono il topic solo con lo stesso client_id (e quindi solo quel cliente). Il client_id è una stringa di caratteri univoca composta da qualsiasi combinazione dei caratteri 0-9, az, AZ, “-“, “_”.
In generale, gli argomenti di sottoscrizione del server MQTT del DIVUS KNX IQ contengono lo stato della parola chiave, mentre gli argomenti di pubblicazione contengono la richiesta di parola chiave. Quelli con stato vengono aggiornati automaticamente non appena si verifica una modifica del valore esterno o non appena una modifica del valore è stata richiesta dal cliente stesso tramite una pubblicazione ed è stata applicata con successo. Quelli per la pubblicazione si dividono ulteriormente in quelli di tipo (request/)get e quelli di tipo (request/)set.

Le modifiche ai valori e altri parametri opzionali vengono aggiunti all'argomento con il cosiddetto payload. I parametri dei singoli elementi (elemento-id, nome, tipo, funzioni)

La principale differenza tra MQTT e il classico modello client-server, in cui il client richiede e poi modifica i dati, è incentrata sui concetti di sottoscrizione e pubblicazione. I partecipanti possono pubblicare i dati, rendendoli disponibili ad altri, che se interessati possono sottoscriverli. Questa architettura consente di ridurre al minimo lo scambio di dati mantenendo comunque aggiornate tutte le parti interessate. Maggiori dettagli qui: e i parametri speciali (uuid, filtri) devono essere utilizzati qui. Sebbene siano disponibili diverse opzioni, in questo manuale il payload viene mostrato formattato come JSON. JSON utilizza parentesi e virgole per rappresentare i dati di qualsiasi struttura e quindi riduce al minimo la dimensione dei pacchetti di dati da trasmettere. Maggiori dettagli sui payload sono disponibili più avanti nel manuale.

Per scopi speciali è possibile filtrare in base al tipo di funzione, ad esempio per indirizzare solo gli interruttori on/off, ovvero a 1 bit. A questo scopo viene utilizzato il parametro filter nel payload. Il filtraggio è attualmente possibile solo per tipo di funzione.
Per poter indirizzare i singoli elementi è necessario il loro ID elemento. Questo può essere trovato in VISION nel menu delle proprietà dell'elemento o può anche essere letto direttamente dai dati visualizzati davanti a ciascun elemento disponibile nella sottoscrizione generale di MQTT Explorer (gli elementi sono elencati in ordine alfabetico per ID elemento).

Configurazione per l'accesso API

CONFIGURAZIONE DI VISION PER L'ACCESSO UTENTE API

In VISION come amministratore, vai su Configurazione – Gestione accesso utente/API, fai clic su Utenti/Accesso API e fai clic con il pulsante destro del mouse su Utente API (o tieni premuto) per aprire la finestra di modifica. Lì troverai questi parametri e dati

Abilita (casella di controllo)
- Qui l'utente viene abilitato per la prima volta. L'impostazione predefinita è disabilitata
Nome utente
- Questa stringa è necessaria per l'accesso tramite API: copiala da qui
Password
- Questa stringa è necessaria per l'accesso tramite API: copiala da qui
Permessi
- Qui è possibile definire i diritti predefiniti per la lettura e la scrittura dei valori degli elementi VISION, ovvero ciò che qui viene definito vale per tutti gli elementi esistenti e futuri. Se desideri consentire l'accesso solo a singoli elementi, non dovresti modificare questi diritti predefiniti

AUTORIZZAZIONI SUI SINGOLI ELEMENTI

Si consiglia di non concedere l'accesso API all'intero progetto, ma solo agli elementi desiderati. Procedi come segue

accedere a VISION come amministratore
seleziona l'elemento desiderato e apri il menu delle impostazioni (fai clic con il pulsante destro del mouse o tieni premuto, quindi Impostazioni)

sotto la voce di menu Generale – Autorizzazioni, attivare “Override default permessi” e poi recarsi nella sottovoce Autorizzazioni, che riporta la matrice dei permessi.
attivare qui l'autorizzazione di controllo, che abilita anche il view permesso direttamente. Se si desidera solo leggere i dati tramite l'accesso API è sufficiente abilitare il view permesso.
ripeti la stessa procedura per tutti gli elementi a cui vuoi accedere

Connessione tramite MQTT

INTRODUZIONE

Come un example, dimostreremo l'accesso tramite l'API MQTT del DIVUS KNX IQ con un software gratuito relativamente semplice chiamato MQTT Explorer (vedi cap. 1.1), disponibile per Windows, Mac e Linux. È implicita una conoscenza ed esperienza di base con MQTT.

DATI NECESSARI PER LA CONNESSIONE

Come accennato in precedenza (vedere sezione 2.1), sono richiesti il nome utente e la password dell'utente API. Ecco un overview di tutti i dati che devono essere raccolti prima che venga stabilita una connessione:

Nome utente Leggi nella pagina dei dettagli dell'utente API
Password Leggi nella pagina dei dettagli dell'utente API

Indirizzo IP Leggilo nelle impostazioni del launcher in Generale – Rete – Ethernet (o tramite Sincronizzatore)
Porta 8884 (questa porta è riservata a questo scopo)

PRIMA CONNESSIONE CON MQTT EXPLORER E GENERAL SUBSCRIBE

Normalmente MQTT distingue tra le attività di sottoscrizione e pubblicazione. MQTT Explorer semplifica tutto ciò iscrivendosi automaticamente a tutti gli argomenti disponibili (argomento n.) quando viene effettuata la prima connessione. In questo modo, dopo una connessione riuscita, l'albero che porta a tutti gli elementi disponibili (ovvero all'accesso utente API concesso) può essere visualizzato direttamente nell'area sinistra della finestra MQTT Explorer. Per inserire ulteriori argomenti di iscrizione o per sostituire il # con un argomento più specifico, vai su Avanzate nella finestra di connessione. L'argomento mostrato in alto a destra è simile a questo:

dove 7f4x0607849x444xxx256573x3x9x983 è il nome utente dell'API e object_list contiene tutti gli elementi disponibili. Questo argomento è sempre aggiornato, ovvero qualsiasi modifica dei valori viene riflessa in tempo reale. Se desideri iscriverti solo a singoli elementi, inserisci l'ID dell'elemento desiderato dopo object_list/.

Nota: questo tipo di iscrizione corrisponde grosso modo alla logica degli indirizzi di feedback KNX; mostra lo stato attuale degli elementi e può essere utilizzato per verificare se le modifiche desiderate sono state applicate con successo. Se si desidera solo leggere i dati ma non modificarli, questo tipo di abbonamento è sufficiente.

Un singolo elemento semplice assomiglia a questo nella notazione JSON

Nota: tutti i valori hanno la sintassi mostrata sopra, ad esempio { "valore": "1" } come output degli argomenti di sottoscrizione, mentre il valore viene scritto direttamente nel payload per modificare un valore (ad esempio per gli argomenti di pubblicazione) - le parentesi e I “valori” vengono omessi, ad esempio “onoff”: “1”.

Comandi avanzati

INTRODUZIONE

In generale esistono 3 tipi di argomenti:

Iscriviti agli argomenti per vedere gli elementi disponibili e ottenere modifiche ai valori in tempo reale
Iscriviti agli argomenti per ottenere le risposte a (i clienti ) pubblicare le richieste

Pubblica argomenti per ottenere o impostare elementi con i relativi valori

A queste tipologie faremo riferimento in seguito utilizzando la numerazione qui riportata (es. argomenti di tipo 1, 2, 3). Maggiori dettagli nei paragrafi successivi e nel cap. 4.2.

ISCRIVITI AI TOPICS PER VEDERE GLI ELEMENTI DISPONIBILI E OTTENERE CAMBIAMENTI DI VALORE IN TEMPO REALE

Questi sono già stati descritti

ISCRIVITI AI TOPIC PER OTTENERE RISPOSTE ALLE RICHIESTE DI PUBBLICAZIONE DEL CLIENTE

Questo tipo di argomenti è facoltativo. Permette di

aprire un canale di comunicazione univoco con il server MQTT utilizzando un client_id arbitrario. Maggiori informazioni al riguardo nel cap. 4.2.2
ottenere il risultato delle richieste di pubblicazione sull'argomento di sottoscrizione corrispondente: successo o fallimento con codice di errore e messaggio.

Esistono diversi argomenti per ottenere risposte o per impostare comandi di pubblicazione. La corrispondente differenza in Una volta individuati gli argomenti necessari per il tuo sistema, puoi decidere di rimuovere questo passaggio e utilizzare direttamente gli argomenti di pubblicazione.

PUBBLICARE ARGOMENTI PER OTTENERE O IMPOSTARE ELEMENTI CON I LORO VALORI

Questi argomenti utilizzano un percorso simile a quelli per l'iscrizione: l'unica modifica è la parola "richiesta" al posto dello "stato" utilizzato per iscriversi. I percorsi tematici completi sono mostrati più avanti nel cap. 4.2.2\ Un argomento get richiederà di leggere gli elementi e i valori del server MQTT. Il payload può essere utilizzato per filtrare in base al tipo di funzione degli elementi. Un argomento impostato richiederà di modificare alcune parti di un elemento, come dettagliato nel suo payload.

PREFISSO PER COMANDI E RISPOSTE CORRISPONDENTI

BREVE SPIEGAZIONE

Tutti i comandi che vengono inviati al server MQTT hanno una parte iniziale comune, ovvero:

SPIEGAZIONE DETTAGLIATA

Gli argomenti in tempo reale (tipo 1) avranno il prefisso generale (vedi sopra) seguito poi da

Per i comandi set, il payload ovviamente gioca il ruolo principale poiché conterrà le modifiche desiderate (cioè i valori modificati per le funzioni dell'elemento). Un avvertimento: non utilizzare mai l'opzione di conservazione nei comandi di tipo 3 poiché potrebbe causare problemi sul lato KNX.

EXAMPLE: PUBBLICA PER MODIFICARE IL VALORE DI UN SINGOLO ELEMENTO

Il caso più semplice è quello di voler cambiare il valore di uno degli elementi mostrati dalla sottoscrizione generale.
In linea generale la modifica/commutazione di una funzione di VISION tramite MQTT prevede 3 passaggi, non tutti sono assolutamente necessari, ma consigliamo comunque di eseguirli come descritto.

L'argomento che contiene la funzione che vogliamo modificare viene sottoscritto utilizzando un client_id personalizzato
L'argomento da modificare viene pubblicato insieme al payload con le modifiche desiderate utilizzando il client_id scelto in 1.

Per verificare potete vedere la risposta nell'argomento (1.) – cioè se (2.) ha funzionato oppure no
Nella sottoscrizione generale, dove tutti i valori vengono aggiornati quando vengono apportate modifiche, puoi vedere le modifiche dei valori desiderate se tutto ha funzionato correttamente.

I passaggi per farlo sono:

seleziona un client_id ad esempio “Divus” e inseriscilo nel percorso dopo il nome utente dell'API
Questo è l'argomento completo per l'iscrizione al proprio canale di comunicazione con il server MQTT. Questo indica al server dove ti aspetti le risposte alle modifiche che intendi inviare. Notare la parte status/set che definisce a. che si tratta di un argomento di iscrizione e b. che otterrà le risposte per impostare i comandi di tipo.
L'argomento di pubblicazione sarà lo stesso, ad eccezione del cambio delle parole chiave di richiesta di stato
in cosa dovrebbe consistere la modifica è scritto nel payload. Ecco alcuni exampmeno.
- Spegnimento di un elemento che ha la funzione on/off (1 bit):
- Accensione di un elemento che ha la funzione on/off (1 bit). Inoltre, se diversi comandi di questo tipo vengono avviati dallo stesso client, il parametro uuid ("ID univoco", solitamente è una stringa a 128 bit formattata come 8-4-4-4-12 cifre esadecimali) può essere utilizzato per assegnare il risposta alla query corrispondente, in quanto questo parametro – se presente nella query – si trova anche nella risposta.
- Accensione e impostazione della luminosità di un dimmer al 50%
- La risposta all'argomento mostrato e sottoscritto sopra (il suo payload, per la precisione) è quindi, ad esamplui.
  La risposta sopra è un example nel caso di un carico utile corretto, sebbene l'elemento non abbia funzione di oscuramento. Se ci sono problemi più seri che portano il payload a non essere interpretato correttamente, la risposta sarà simile a questa (es.):
  per la spiegazione dei codici e dei messaggi di errore ma in generale, come per http, 200 codici sono risposte positive mentre 400 sono negative.

EXAMPLE: PUBBLICA PER MODIFICARE I VALORI DI PIÙ ELEMENTI

La procedura è simile a quella mostrata prima per modificare un singolo elemento. La differenza è che ometti element_id dagli argomenti e quindi indichi l'insieme di element_id davanti ai dati all'interno del payload. Vedere la sintassi e la struttura di seguito.

FILTRA PER TIPO DI FUNZIONE NELLE QUERY

Il parametro filter nel payload consente di indirizzare solo le funzioni desiderate di un elemento. La funzione on/off di un interruttore o dimmer è chiamata “onoff”, ad esample, e il filtro corrispondente è definito in questo modo:

La risposta quindi è questa, ad esample

La parentesi quadra indica che puoi anche filtrare in base a diverse funzioni, ad es

porta ad una risposta come questa:

Appendice

CODICI DI ERRORE

Gli errori nella comunicazione MQTT risultano in un codice numerico. La tabella seguente aiuta a scomporlo.

PARAMETRI DEL CARICO UTILE

Il payload supporta parametri diversi a seconda del contesto. La tabella seguente mostra quali parametri possono verificarsi in quali argomenti

NOTE SULLA VERSIONE

1.00 VERSIONE

Notizia:

• Prima pubblicazione

Documenti / Risorse

	Software API DIVUS VISION [pdf] Manuale d'uso Software API VISION, Software API, Software
	Software API DIVUS Vision [pdf] Guida utente Software API Vision, Visione, Software API, Software

Riferimenti

Manuale d'uso

Software API DIVUS VISION

Informazioni sul prodotto