DIVUS VISION API Software

Specificazioni

• Pruduttu: DIVUS VISION API
• Produttore: DIVUS GmbH
• Versione: 1.00 REV0 1 - 20240528
• Lieu: Pillhof 51, Appiano (BZ), Italia

Informazione di u produttu

L'API DIVUS VISION hè un strumentu software pensatu per l'interfaccia cù i sistemi DIVUS VISION. Permette à l'utilizatori di accede è cuntrullà diversi elementi in u sistema utilizendu protokolli MQTT.

FAQ

Q: Puderaghju aduprà l'API DIVUS VISION senza cunniscenza previa di PC o tecnulugia d'automatizazione?

A: U manuale hè adattatu per l'utilizatori cun cunniscenze precedente in questi spazii per assicurà un usu efficace di l'API.

INFORMAZIONI GENERALI

• DIVUS GmbH Pillhof 51 I-39057 Eppan (BZ) - Italia

Istruzzioni di operazione, manuali è software sò protetti da copyright. Tutti i diritti riservati. Copià, duplicate, traduzzione, traduzzione in tuttu o in parte ùn hè micca permessa. Un'eccezzioni si applica à a creazione di una copia di salvezza di u software per usu persunale.
U manuale hè sottumessu à cambià senza avvisu. Ùn pudemu micca guarantisci chì e dati cuntenuti in stu documentu è nantu à i supporti di almacenamento furniti sò senza errori è curretti. Suggerimenti per migliurà è suggerimenti nantu à l'errori sò sempre benvenuti. L'accordi s'applicanu ancu à l'annessi specifichi di stu manuale. E designazioni in stu documentu ponu esse marchi chì l'usu da terze parti per i so propiu scopi pò infringisce i diritti di i so pruprietari. Istruzzioni per l'usu: Leghjite stu manuale prima di usà per a prima volta è mantene in un locu sicuru per riferimentu futuru. Gruppu di destinazione: U manuale hè scrittu per l'utilizatori cun cunniscenza previa di PC è tecnulugia d'automatizazione.

CONVENZIONI DI PRESENTAZIONE

Introduzione

INTRODUZIONE GENERALE

Stu manuale descrive l'API VISION (Application Programming Interface) - una interfaccia per via di quale VISION pò esse indirizzata è cuntrullata da sistemi esterni.
In termini pratichi, questu significa chì pudete aduprà sistemi cum'è

• MQTT Explorer (https://www.microsoft.com/store/… - per a prova),
• assistente di casa (https://www.home-assistant.io/) o
• Node-RED (https://nodered.org/)

per cuntrullà l'elementi gestiti da VISION o leghje u so statutu. L'accessu è a cumunicazione si facenu via u protocolu MQTT, chì usa i cosiddetti temi per affruntà funzioni individuali o insemi di funzioni o per esse infurmatu nantu à i cambiamenti in elli. Un servitore MQTT (broker) hè utilizatu per questu scopu, chì gestisce a sicurità è a gestione / distribuzione di missaghji à i participanti. In questu casu, u servitore MQTT hè situatu direttamente nantu à u DIVUS KNX IQ è hè cunfiguratu apposta per questu scopu. Ancu l'API VISION pò ancu esse aduprata senza cunniscenze di prugrammazione, sta funziunalità hè adattata per l'utilizatori avanzati.

PREREQUISITI

Cum'è spiegatu in u manuale VISION, l'utilizatore API deve esse attivatu prima per automaticamente per pudè usà l'accessu API funziona solu cù e dati di autentificazione di l'utilizatori Api. In quantu à i diritti di l'utilizatori, l'attivazione per sta funziunalità pò esse cunfigurata sia nantu à tutti l'elementi individuali, sia nantu à l'elementi individuali. Vede Cap.0. Di sicuru, avete ancu bisognu di un prughjettu VISION in quale l'elementi chì vulete cuntrullà da l'esternu sò cumpletamente cunfigurati è a cunnessione cù elli hè stata pruvata cun successu. Per pudè affruntà elementi individuali via l'API, u so ID di l'elementu deve esse cunnisciutu: questu hè visualizatu à u fondu di a forma di paràmetri di l'elementu.

SICUREZZA

Per ragioni di sicurità, l'accessu à l'API hè pussibule solu in u locu (vale à dì micca via u nuvulu). U risicu di sicurità quandu attivate l'accessu API hè dunque bassu. Tuttavia, l'elementi rilevanti per a sicurità ùn deve esse attivati ​​o esplicitamente denegati per l'accessu API.

MQTT È I SO TERMI - BREVE SPIGAZIONE

• In MQTT, u rolu di a gestione centralizata è a distribuzione di tutti i missaghji hè quellu di u broker. Ancu u servitore MQTT è u broker MQTT ùn sò micca sinonimi (servitore hè un termini più largu per un rolu chì i clienti MQTT ponu ancu ghjucà), u broker hè sempre significatu in questu manuale quandu u servitore MQTT hè citatu. U DIVUS KNX IQ stessu ghjucà u rolu di broker MQTT / servitore MQTT in u cuntestu di stu manuale.
• Un servitore MQTT usa i cosiddetti temi: una struttura gerarchica cù quale e dati sò categurizzati, gestiti è publicati.
• A publicazione hà u scopu primariu di rende i dati dispunibuli à l'altri participanti per mezu di temi. Se vulete cambià un valore, scrivite à u tema desideratu inseme cù u cambiamentu di u valore desideratu, ancu utilizendu una azzione di publicazione. U dispusitivu di destinazione o u servitore MQTT leghje u cambiamentu desideratu chì l'affetta è l'adopta in cunseguenza. Per verificà chì u cambiamentu hè statu appiicatu, pudete guardà in u tema in tempu reale sottumessi per vede s'ellu ci hè riflessu u cambiamentu - se tuttu hà travagliatu bè.
• I clienti selezziunate i temi chì l'interessanu: questu hè chjamatu abbonamentu. Ogni volta chì un valore cambia in / sottu à un tema, tutti i clienti abbonati sò infurmati - vale à dì senza avè da dumandà esplicitamente se qualcosa hà cambiatu o quale hè u valore attuale.
• Pudete apre (o indirizzu) un canale di cumunicazione separatu cù u servitore MQTT inserendu ogni stringa unica chjamata client_id in un tema. U client_id deve esse usatu in u tema per processà i valori. Questu serve per identificà l'urìgine di ogni cambiamentu, aiuta cù qualsiasi errori è ùn affetta micca l'altri clienti, cum'è e risposti currispundenti da u servitore, cumpresi qualsiasi codice d'errore è messagi, ghjunghje ancu solu à u tema cù u stessu client_id (è cusì solu solu. quellu cliente). U client_id hè una stringa di caratteri unica chì si compone di qualsiasi cumminazzioni di i caratteri 0-9, az, AZ, "-", "_".
• In generale, i temi sottumessi di u servitore MQTT di u DIVUS KNX IQ cuntenenu l'statu di keyword, mentre chì i temi di pubblicazione cuntenenu a dumanda di keyword. Quelli chì anu statutu sò aghjurnati automaticamente appena ci hè un cambiamentu di valore esternu o appena un cambiamentu di valore hè statu dumandatu da u cliente stessu via una publicazione è hè stata appiicata cù successu. Quelli per a publicazione sò ancu divisi in quelli di tipu (request/)get è quelli di tipu (request/)set.
• I cambiamenti di valore è altri paràmetri facultativi sò aghjuntu à u tema cù u chjamatu payload. I paràmetri di l'elementi individuali (element-id, nome, tipu, funzioni)

A principal diferenza trà MQTT è u mudellu classicu di u cliente-servitore, induve u cliente dumanda è poi cambia dati, hè centrata nantu à i cuncetti di abbunamentu è publicazione. I participanti ponu pubblicà e dati, rendendu dispunibuli à l'altri, chì, s'ellu hè interessatu, ponu abbonà. Questa architettura permette di minimizzà u scambiu di dati è mantene sempre tutte e parti interessate à ghjornu. Più nantu à i dettagli quì: è paràmetri spiciali (uuid, filtri) sò da esse usatu quì. Ancu s'ellu ci sò parechje opzioni, a carica utile hè indicata formata cum'è JSON in stu manuale. JSON usa parentesi è virgule per rapprisintà e dati di qualsiasi struttura è cusì minimizza a dimensione di i pacchetti di dati per esse trasmessi. Più dettagli nantu à i carichi pagati ponu esse truvati più tardi in u manuale.

• Per scopi spiciali, hè pussibule di filtrà secondu u tipu di funzione, per esempiu per indirizzà solu on/off ie switch 1-bit. U paràmetru di filtri in u payload hè utilizatu per questu scopu. A filtrazione hè attualmente pussibule solu per u tipu di funzione.
• Per pudè indirizzà elementi individuali, u so elementu ID hè necessariu. Questu pò esse truvatu in VISION in u menù di proprietà di l'elementu o pò ancu esse lettu direttamente da e dati chì sò affissati davanti à ogni elementu dispunibule in l'abbunamentu generale di l'Explorer MQTT (elementi ci sò listati alfabeticamente per ID di l'elementu).

Configurazione per l'accessu API

CONFIGURAZIONE A VISIONE PER L'ACCESSU USER API

In VISION cum'è amministratore, andate à Configurazione - User / API Access Management, cliccate nant'à Users / API access and right-click on API User (o pressu è mantene) per apre a finestra di edizione. Ci truverete sti paràmetri è dati

• Abilita (checkbox)
  • L'utilizatore hè prima attivatu quì. Default hè disattivatu
• Nome d'utilizatore
  • Questa stringa hè necessaria per l'accessu via API - copiate da quì
• Codice
  • Questa stringa hè necessaria per l'accessu via API - copiate da quì
• Permissions
  • I diritti predeterminati per leghje è scrive i valori di l'elementi VISION ponu esse definiti quì, vale à dì ciò chì hè definitu quì s'applica à tutti l'elementi esistenti è futuri. Se vulete solu permette l'accessu à l'elementi individuali, ùn deve micca cambià sti diritti predeterminati

PERMISSIONS SU ELEMENTI INDIVIDUALI

Hè ricumandemu chì ùn cuncede micca l'accessu API à tuttu u prughjettu, ma solu à l'elementi desiderati. Procedi cumu seguitu

1. accede à VISION cum'è amministratore
2. selezziunà l'elementu desideratu è apre u so menu di paràmetri (cliccate cù u dirittu right o mantene premutu, dopu Settings)
3. sottu u menù Generale - Permissions, attivate "Override default permissions" è andate à u sottu-elementu Permissions, chì mostra a matrice di permessi.
4. attivate u permessu di cuntrollu quì, chì permette ancu u view permessu direttamente. Sè vo vulete solu leghje dati via l'accessu API, hè abbastanza per attivà u view permessu.
5. ripetite a stessa prucedura per tutti l'elementi chì vulete accede

Cunnessione via MQTT

INTRODUZIONE

Cum'è example, avemu da dimustrà l'accessu via l'API MQTT di u DIVUS KNX IQ cun un software relativamente simplice è liberu chjamatu MQTT Explorer (vede chap. 1.1), chì hè dispunibule per Windows, Mac è Linux. Una cunniscenza basica è una sperienza cù MQTT hè implicata.

DATI NECESSARI PER A CONNESSIONE

Cumu l'anu dettu prima (vede a sezione 2.1), u nome d'utilizatore è a password di l'utilizatore API sò richiesti. Eccu un finituview di tutti i dati chì devenu esse raccolti prima di stabilisce una cunnessione:

• Username Leghjite nantu à a pagina di dettagliu di l'utilizatore API
• Password Leghjite nantu à a pagina di dettagliu di l'utilizatore API
• Indirizzu IP Leghjite in i paràmetri di u lanciatore in General - Network - Ethernet (o via Synchronizer)
• Port 8884 (stu portu hè riservatu per questu scopu)

PRIMA CONNESSIONE CU MQTT EXPLORER E SUBSCRIBE GENERAL

Normalmente, MQTT distingue trà l'attività sottumette è publica. L'Explorer MQTT simplificà questu sottumettendu automaticamente à tutti i temi dispunibili (tema #) quandu a prima cunnessione hè fatta. In u risultatu, l'arburu chì porta à tutti l'elementi dispunibuli (vale à dì l'accessu d'utilizatore API cuncessu) pò esse vistu direttamente in l'area di a manca di a finestra MQTT Explorer dopu una cunnessione successu. Per inserisce più sughjetti di subscribe o per rimpiazzà u # cù un tema più specificu, andate à Avanzate in a finestra di cunnessione. U tema mostratu in cima à destra s'assumiglia à questu:

induve 7f4x0607849x444xxx256573x3x9x983 hè u nome d'utilizatore API è objects_list cuntene tutti l'elementi dispunibuli. Stu tema hè sempre tenutu à ghjornu, vale à dì ogni cambiamentu di valore hè riflessu quì in tempu reale. Se vulete abbunà solu à elementi individuali, inserite l'ID di l'elementu di l'elementu desideratu dopu objects_list/.

Nota: Stu tipu di abbonamentu currisponde à pocu pressu à a logica daretu à l'indirizzi di feedback KNX; mostra u statu attuale di l'elementi è pò esse usatu per verificà se i cambiamenti desiderati sò stati applicati bè. Se vulete solu leghje e dati ma micca cambià, stu tipu d'abbonamentu hè abbastanza.

Un unicu elementu simplice pare qualcosa cusì in notazione JSON

Nota: Tutti i valori anu a sintassi mostrata sopra, per esempiu { "valore": "1" } cum'è u risultatu di i temi di sottoscrizzione, mentre chì u valore hè scrittu direttamente in u payload per cambià un valore (vale à dì per i temi di pubblicazione) - i parentesi è "valore" sò omessi per esempiu "onoff": "1".

Cumandamenti avanzati

INTRODUZIONE

Ci sò 3 tipi di temi in generale:

1. Subscribe topic(s) per vede l'elementi dispunibuli è per ottene cambiamenti di valore in tempu reale
2. Abbonate à u sughjettu (s) per uttene e risposte à (i clienti ) publicà e dumande
3. Publicate u sughjettu (s) per uttene o per stabilisce elementi cù i so valori

Ci rifereremu dopu à sti tipi cù a numerazione mostrata quì (per esempiu temi di tipu 1, 2, 3). Più dettagli in e sezioni seguenti è in u cap. 4.2.

SUBSCRIBE TEMI PER VEDE L'ELEMENTI DISPONIBILI È PER OTTENERE CAMBIAMENTI DI VALORE IN TEMPU REALE

Quessi sò digià stati descritti

SUBSCRIBE TEMI PER OTTENERE E RISPOSTE À E RICHIESTE DI PUBBLICAZIONE DI U CLIENTE

Stu tipu di temi hè facultativu. Permette

• apre un canale di cumunicazione unicu cù u servitore MQTT usendu un client_id arbitrariu. Più nantu à questu in u cap. 4.2.2
• uttene u risultatu di e dumande di publicazione nantu à u tema di abbunamentu currispundente: successu o fallimentu cù codice d'errore è missaghju.

Ci sò diversi temi per uttene risposte per uttene o per stabilisce cumandamenti di publicazione. A diferenza currispondente in Una volta uttene i temi necessarii per u vostru sistema, pudete decide di sguassà stu passu è aduprà direttamente i temi di pubblicazione.

 PUBBLICATE TEMI PER OTTENERE O PASSARE ELEMENTI CU I SO VALORI

Questi temi utilizanu un percorsu simili à quelli per l'abbonamentu - l'unicu cambiamentu hè a parolla "richiesta" in u locu di u "status" utilizatu per abbunà. I percorsi tematici cumpleti sò mostrati più tardi in u cap. 4.2.2\ Un sugettu get dumandà à leghje l'elementi è i valori di u servitore MQTT. U payload pò esse usatu per filtrà basatu annantu à u tipu di funzione di l'elementi. Un tema stabilitu dumandà à cambià alcune parti di un elementu, cum'è detallatu in a so carica.

PREFIX PER CUMANDI E RISPOSTE CORRESPONDENTI

 BREVE SPIGAZIONE

Tutti i cumandamenti chì sò mandati à u servitore MQTT anu una parte iniziale cumuna, à dì:

SPIEGAZIONE DETAILATA

I temi in tempu reale (tipu 1) anu u prefissu generale (vede sopra) dopu seguitatu da

or

Per i cumandamenti stabiliti, u payload ovviamente ghjoca u rolu principali, postu chì cuntene i cambiamenti desiderati (vale à dì i valori cambiati per e funzioni di l'elementu). Un Avvertimentu: Ùn aduprate mai l'opzione di mantene in i vostri cumandamenti di tipu 3 perchè pò causà prublemi in u latu KNX.

EXAMPLE: PUBBLICATE PER CAMBIARE U VALORE(S) DI UN SINGU ELEMENTU

U casu più simplice hè di vulete cambià u valore di unu di l'elementi mostrati da l'abbonatu generale.
In generale, cambià / cambià una funzione di VISION via MQTT hè custituita da 3 passi, chì ùn sò micca tutti assolutamente necessarii, ma ricumandemu quantunque di eseguisce cum'è descrittu.

1. U tema chì cuntene a funzione chì vulemu edità hè sottumessu cù un client_id persunalizatu
2. U tema per edità hè publicatu inseme cù u payload cù i cambiamenti desiderati utilizendu u client_id sceltu in 1.
3. Per verificà, pudete vede a risposta in u tema (1.) - vale à dì s'ellu (2.) hà travagliatu o micca
4. In l'abbunamentu generale, induve tutti i valori sò aghjurnati quandu i cambiamenti sò fatti, pudete vede u cambiamentu di u valore desideratu se tuttu hà travagliatu bè.

I passi per fà questu sò:

1. selezziunà un client_id per esempiu "Divus" è inserisci in u percorsu dopu à u nome d'utilizatore API
   Questu hè u tema cumpletu per l'abbonamentu à u vostru propiu canali di cumunicazione cù u servitore MQTT. Questu dici à u servitore induve aspittà i risposti à i cambiamenti chì vulete mandà. Notate a parte di statutu / set chì definisce a. ch'ellu hè un tema di abbunamentu è b. chì uttene e risposte per stabilisce cumandamenti di tipu.
2. U tema di pubblicazione serà u listessu eccettu per cambià e parolle chjave di dumanda di statutu
3. ciò chì u cambiamentu deve esse custituitu hè scrittu in u payload. Eccu alcuni examples.
   • Spegnimentu di un elementu chì hà a funzione on/off (1 bit):
   • Accende un elementu chì hà a funzione on/off (1 bit). Inoltre, se parechji tali cumandamenti sò iniziati da u stessu cliente, u paràmetru uuid ("ID unicu", hè di solitu una stringa di 128 bit formattata cum'è 8-4-4-4-12 cifre esadecimale) pò esse usatu per assignà u risposta à a dumanda currispundente, postu chì stu paràmetru - se presente in a dumanda - pò ancu esse truvatu in a risposta.
   • Accende è stabilisce a luminosità di un dimmer à 50%
   • A risposta à u tema mostratu è abbonatu sopra (u so payload, per esse precisu) hè dunque, per example.
     A risposta sopra hè un example in u casu di un payload currettu, ancu s'è l'elementu ùn hà micca funzione dimming. Se ci sò prublemi più serii chì portanu a carica utile à ùn esse interpretata currettamente, a risposta sarà cusì (per esempiu):
     per una spiegazione di i codici d'errore è i missaghji, ma in generale, cum'è per http, 200 codici sò risposti pusitivi mentre 400 sò negativi.

EXAMPLE: PUBBLICATE PER CAMBIARE VALORI DI ELEMENTI MULTIPLE

A prucedura hè simile à quella mostrata prima per cambià un unicu elementu. A diferenza hè chì omette l'element_id da i temi è poi indicà u settore di element_ids davanti à e dati in u payload. Vede a sintassi è a struttura sottu.

FILTRÀ PER TIPO DI FUNZIONE IN QUESTIONS

U paràmetru di filtri in u payload permette solu a funzione (s) desiderata di un elementu per esse indirizzatu. A funzione on/off di un interruttore o dimmer hè chjamata "onoff", per esample, è u filtru currispundente hè definitu in questu modu:

A risposta allora pare cusì, per esempiuample

U parentesi quadratu indica chì pudete ancu filtrà per parechje funzioni, per esempiu

porta à una risposta cum'è questu:

Appendice

CODICI DI ERRORE

Errori in a cumunicazione MQTT risultatu in un codice numericu. A tavula seguente aiuta à scunfighjà.

PARAMETRI DI PAYLOAD

U payload supporta diversi paràmetri secondu u cuntestu. A tavula seguente mostra quali paràmetri ponu accade in quale temi

NOTE VERSIONI

• VERSIONE 1.00

Notizie:

• Prima publicazione

Documenti / Risorse

	DIVUS VISION API Software [pdfManuale d'usu VISION API Software, API Software, Software
	DIVUS Vision API Software [pdfGuida di l'utente Vision Software API, Vision, Software API, Software

Referenze

• Manuale d'usu