Programari API DIVUS VISION

Especificacions

• Producte: DIVUS VISION API
• Fabricant: DIVUS GmbH
• Versió: 1.00 REV0 1 – 20240528
• Lloc: Pillhof 51, Eppan (BZ), Itàlia

Informació del producte

L'API DIVUS VISION és una eina de programari dissenyada per connectar-se amb sistemes DIVUS VISION. Permet als usuaris accedir i controlar diversos elements dins del sistema mitjançant els protocols MQTT.

Preguntes freqüents

P: Puc utilitzar l'API DIVUS VISION sense coneixements previs de PC o tecnologia d'automatització?

R: El manual està dissenyat per a usuaris amb coneixements previs en aquestes àrees per garantir un ús eficient de l'API.

INFORMACIÓ GENERAL

• DIVUS GmbH Pillhof 51 I-39057 Eppan (BZ) – Itàlia

Les instruccions d'operació, els manuals i el programari estan protegits per drets d'autor. Tots els drets reservats. No es permet la còpia, la duplicació, la traducció, la traducció total o parcial. Una excepció s'aplica a la creació d'una còpia de seguretat del programari per a ús personal.
El manual està subjecte a canvis sense previ avís. No podem garantir que les dades contingudes en aquest document i en els suports d'emmagatzematge subministrats estiguin lliures d'errors i correctes. Els suggeriments de millora i els suggeriments sobre errors sempre són benvinguts. Els acords també s'apliquen als annexos específics d'aquest manual. Les designacions d'aquest document poden ser marques comercials l'ús de les quals per part de tercers per a les seves pròpies finalitats pot infringir els drets dels seus propietaris. Instruccions per a l'usuari: llegiu aquest manual abans d'utilitzar-lo per primera vegada i guardeu-lo en un lloc segur per consultar-lo en el futur. Destinataris: El manual està escrit per a usuaris amb coneixements previs de PC i tecnologia d'automatització.

CONVENCIONS DE PRESENTACIÓ

Introducció

INTRODUCCIÓ GENERAL

Aquest manual descriu l'API VISION (Interfície de programació d'aplicacions), una interfície mitjançant la qual VISION es pot adreçar i controlar des de sistemes externs.
En termes pràctics, això vol dir que podeu utilitzar sistemes com ara

• MQTT Explorer (https://www.microsoft.com/store/… – per provar),
• Assistent a la llar (https://www.home-assistant.io/) o
• Node-VERMELL (https://nodered.org/)

per controlar els elements gestionats per VISION o llegir-ne l'estat. L'accés i la comunicació es produeixen mitjançant el protocol MQTT, que utilitza els anomenats temes per abordar funcions individuals o conjunts de funcions o per informar-se dels canvis que s'hi fan. Amb aquesta finalitat s'utilitza un servidor MQTT (broker), que gestiona la seguretat i la gestió/distribució de missatges als participants. En aquest cas, el servidor MQTT es troba directament al DIVUS KNX IQ i està especialment configurat per a aquesta finalitat. Tot i que l'API VISION també es pot utilitzar sense coneixements de programació, aquesta funcionalitat és adequada per a usuaris avançats.

REQUISITS

Tal com s'explica al manual VISION, l'usuari de l'API s'ha d'activar primer per defecte per poder utilitzar-lo, l'accés a l'API només funciona amb les dades d'autenticació dels usuaris de l'Api. Pel que fa als drets d'usuari, l'activació d'aquesta funcionalitat es pot configurar després en tots els elements o en individuals. Vegeu cap.0. Per descomptat, també necessiteu un projecte VISION en el qual els elements que voleu controlar des de l'exterior estiguin totalment configurats i la connexió amb ells s'hagi provat amb èxit. Per poder adreçar-se a elements individuals mitjançant l'API, cal conèixer el seu identificador d'element: es mostra a la part inferior del formulari de configuració de l'element.

SEGURETAT

Per motius de seguretat, l'accés a l'API només és possible localment (és a dir, no a través del núvol). Per tant, el risc de seguretat en activar l'accés a l'API és baix. No obstant això, els elements rellevants per a la seguretat no s'han d'habilitar ni denegar explícitament per a l'accés a l'API.

MQTT I ELS SEUS TERMES – BREU EXPLICACIÓ

• A MQTT, el paper de la gestió i distribució centralitzada de tots els missatges és el del corredor. Tot i que servidor MQTT i broker MQTT no són sinònims (servidor és un terme més ampli per a un paper que també poden jugar els clients MQTT), en aquest manual sempre s'entén el broker quan s'esmenta el servidor MQTT. El mateix DIVUS KNX IQ té la funció d'agent MQTT / servidor MQTT en el context d'aquest manual.
• Un servidor MQTT utilitza els anomenats temes: una estructura jeràrquica amb la qual les dades es classifiquen, es gestionen i es publiquen.
• La publicació té l'objectiu principal de posar les dades a disposició d'altres participants mitjançant temes. Si voleu canviar un valor, escriviu al tema desitjat juntament amb el canvi de valor desitjat, utilitzant també una acció de publicació. El dispositiu de destinació o el servidor MQTT llegeix el canvi desitjat que l'afecta i l'adopta en conseqüència. Per comprovar que el canvi s'ha aplicat, podeu mirar al tema subscrit en temps real per veure si el canvi s'hi reflecteix, si tot ha anat bé.
• Els clients seleccionen els temes que els interessen: això s'anomena subscripció. Cada vegada que un valor canvia dins/a sota d'un tema, s'informa a tots els clients subscrits, és a dir, sense haver de preguntar explícitament si alguna cosa ha canviat o quin és el valor actual.
• Podeu obrir (o adreçar) un canal de comunicació independent amb el servidor MQTT introduint qualsevol cadena única anomenada client_id en un tema. El client_id s'ha d'utilitzar al tema per processar valors. Això serveix per identificar l'origen de cada canvi, ajuda amb qualsevol error i no afecta els altres clients, ja que les respostes corresponents del servidor, inclosos els codis d'error i missatges, també només arriben al tema amb el mateix client_id (i per tant només aquest client). El client_id és una cadena de caràcters única que consta de qualsevol combinació dels caràcters 0-9, az, AZ, “-“, “_”.
• En general, els temes de subscripció del servidor MQTT del DIVUS KNX IQ contenen l'estat de la paraula clau, mentre que els temes de publicació contenen la sol·licitud de paraula clau. Els que tenen l'estat s'actualitzen automàticament tan bon punt hi ha un canvi de valor extern o tan bon punt el mateix client ha sol·licitat un canvi de valor mitjançant una publicació i s'ha aplicat correctament. Els de publicació es divideixen a més en els de tipus (request/)get i els de tipus (request/)set.
• Els canvis de valor i altres paràmetres opcionals s'afegeixen al tema amb l'anomenada càrrega útil. Els paràmetres dels elements individuals (element-id, nom, tipus, funcions)

La principal diferència entre MQTT i el model client-servidor clàssic, on el client demana i després canvia dades, es centra en els conceptes de subscripció i publicació. Els participants poden publicar dades, posant-les a disposició d'altres persones, que si hi estan interessats poden subscriure-s'hi. Aquesta arquitectura permet minimitzar l'intercanvi de dades i mantenir totes les parts interessades actualitzades. Més informació sobre els detalls aquí: i els paràmetres especials (uuid, filtres) s'han d'utilitzar aquí. Tot i que hi ha diverses opcions, la càrrega útil es mostra en format JSON en aquest manual. JSON utilitza claudàtors i comes per representar dades de qualsevol estructura i, per tant, minimitza la mida dels paquets de dades que s'han de transmetre. Més detalls sobre les càrregues útils es poden trobar més endavant al manual.

• Per a propòsits especials, és possible filtrar segons el tipus de funció, per exemple, per adreçar només activació/desactivació, és a dir, interruptors d'1 bit. El paràmetre de filtres de la càrrega útil s'utilitza per a aquest propòsit. Actualment només es pot filtrar per tipus de funció.
• Per poder abordar elements individuals, cal el seu identificador d'element. Això es pot trobar a VISION al menú de propietats de l'element o també es pot llegir directament des de les dades que es mostren davant de cada element disponible a la subscripció general de l'Explorador MQTT (els elements s'enumeren alfabèticament per ID d'element).

Configuració per a l'accés a l'API

CONFIGURANT LA VISIÓ PER A L'ACCÉS D'USUARI DE L'API

A VISION com a administrador, aneu a Configuració - Gestió d'accés d'usuari/API, feu clic a Usuaris/Accés a l'API i feu clic amb el botó dret a Usuari de l'API (o premeu i manteniu premut) per obrir la finestra d'edició. Allà trobareu aquests paràmetres i dades

• Activa (casella de selecció)
  • L'usuari s'habilita primer aquí. El valor predeterminat està desactivat
• Nom d'usuari
  • Aquesta cadena és necessària per accedir mitjançant l'API; copieu-la des d'aquí
• Contrasenya
  • Aquesta cadena és necessària per accedir mitjançant l'API; copieu-la des d'aquí
• Permisos
  • Els drets per defecte per llegir i escriure els valors dels elements VISION es poden definir aquí, és a dir, el que es defineix aquí s'aplica a tots els elements existents i futurs. Si només voleu permetre l'accés a elements individuals, no hauríeu de canviar aquests drets per defecte

PERMISOS EN ELEMENTS INDIVIDUALS

Es recomana que no concediu accés API a tot el projecte, sinó només als elements desitjats. Procediu de la següent manera

1. inicieu sessió a VISION com a administrador
2. seleccioneu l'element desitjat i obriu el seu menú de configuració (feu clic amb el botó dret o manteniu premut i després Configuració)
3. a l'entrada del menú General - Permisos, activeu "Anul·la els permisos predeterminats" i després aneu al subelement Permisos, que mostra la matriu de permisos.
4. activeu aquí el permís de control, que també habilita el view permís directament. Si només voleu llegir dades mitjançant l'accés a l'API, n'hi ha prou amb habilitar el view permís.
5. repetiu el mateix procediment per a tots els elements als quals voleu accedir

Connexió mitjançant MQTT

INTRODUCCIÓ

Com a exampmostrarem l'accés mitjançant l'API MQTT del DIVUS KNX IQ amb un programari lliure relativament senzill anomenat MQTT Explorer (vegeu el cap. 1.1), que està disponible per a Windows, Mac i Linux. Hi ha un coneixement bàsic i experiència amb MQTT.

DADES NECESSARIS PER A LA CONNEXION

Com s'ha esmentat anteriorment (vegeu la secció 2.1), es requereix el nom d'usuari i la contrasenya de l'usuari de l'API. Aquí hi ha un acabatview de totes les dades que s'han de recollir abans d'establir una connexió:

• Nom d'usuari Llegiu-lo a la pàgina de detalls de l'usuari de l'API
• Contrasenya Llegiu-la a la pàgina de detalls de l'usuari de l'API
• Adreça IP Llegiu-la a la configuració del llançador a General - Xarxa - Ethernet (o mitjançant Sincronitzador)
• Port 8884 (aquest port està reservat per a aquest propòsit)

PRIMERA CONEXIÓ AMB MQTT EXPLORER I SUBSCRIPCIÓ GENERAL

Normalment, MQTT distingeix entre les activitats subscriure i publicar. MQTT Explorer simplifica això mitjançant la subscripció automàtica a tots els temes disponibles (tema #) quan es fa la primera connexió. Com a resultat, l'arbre que condueix a tots els elements disponibles (és a dir, l'accés d'usuari de l'API concedit) es pot veure directament a l'àrea de l'esquerra de la finestra de l'Explorador MQTT després d'una connexió correcta. Per introduir més temes de subscripció o per substituir el # per un tema més específic, aneu a Avançat a la finestra de connexió. El tema que es mostra a la part superior dreta s'assembla a això:

on 7f4x0607849x444xxx256573x3x9x983 és el nom d'usuari de l'API i objects_list conté tots els elements disponibles. Aquest tema es manté sempre actualitzat, és a dir, qualsevol canvi de valor es reflecteix allà en temps real. Si només voleu subscriure's a elements individuals, introduïu l'ID de l'element desitjat després de llista_objectes/.

Nota: aquest tipus de subscripció correspon aproximadament a la lògica que hi ha darrere de les adreces de comentaris KNX; mostra l'estat actual dels elements i es pot utilitzar per comprovar si els canvis desitjats s'han aplicat correctament. Si només voleu llegir les dades però no canviar-les, n'hi ha prou amb aquest tipus de subscripció.

Un únic element simple sembla una cosa així en notació JSON

Nota: Tots els valors tenen la sintaxi que es mostra més amunt, per exemple, { “valor”: “1” } com a sortida dels temes de subscripció, mentre que el valor s'escriu directament a la càrrega útil per canviar un valor (és a dir, per publicar temes): els claudàtors i "valor" s'omet, per exemple, "onoff": "1".

Comandes avançades

INTRODUCCIÓ

Hi ha 3 tipus de temes en general:

1. Subscriu-te a temes per veure els elements disponibles i per obtenir canvis de valor en temps real
2. Subscriu-te a temes per obtenir les respostes a (els clients ) publicar sol·licituds
3. Publicar temes per obtenir o establir elements amb els seus valors

Més endavant ens referirem a aquests tipus utilitzant la numeració que es mostra aquí (p. ex. temes de tipus 1, 2, 3). Més detalls als apartats següents i al cap. 4.2.

SUBSCRIU-TE TEMES PER VEURE ELS ELEMENTS DISPONIBLES I PER OBTENIR CANVIS DE VALOR EN TEMPS REAL

Aquestes ja s'han descrit

SUBSCRIU-TE TEMES PER OBTENIR LES RESPOSTES A LES SOL·LICITUDES DE PUBLICACIÓ DEL CLIENT

Aquest tipus de temes és opcional. Permet

• obriu un canal de comunicació únic amb el servidor MQTT mitjançant un client_id arbitrari. Més sobre això al cap. 4.2.2
• obtenir el resultat de les sol·licituds de publicació sobre el tema de subscripció corresponent: èxit o fracàs amb codi d'error i missatge.

Hi ha diferents temes per obtenir respostes per obtenir o per configurar ordres de publicació. La diferència corresponent en Un cop tingueu clars els temes necessaris per al vostre sistema, podeu decidir eliminar aquest pas i utilitzar directament els temes de publicació.

 PUBLICAR TEMES PER ACONSEGUIR O POSAR ELEMENTS AMB ELS SEUS VALORS

Aquests temes utilitzen un camí similar als de la subscripció: l'únic canvi és la paraula "sol·licitud" en lloc de l'"estat" utilitzat per subscriure's. Els camins complets del tema es mostren més endavant al cap. 4.2.2\ Un tema get demanarà llegir els elements i valors del servidor MQTT. La càrrega útil es pot utilitzar per filtrar segons el tipus de funció dels elements. Un tema definit demanarà canviar algunes parts d'un element, tal com es detalla a la seva càrrega útil.

PREFIX PER A COMANDS I RESPOSTES CORRESPONENTS

 BREVE EXPLICACIÓ

Totes les ordres que s'envien al servidor MQTT tenen una part inicial comuna, és a dir:

EXPLICACIÓ DETALLADA

Els temes en temps real (tipus 1) tindran el prefix general (vegeu més amunt) seguit de

or

Per a les ordres establertes, la càrrega útil, òbviament, juga el paper principal, ja que contindrà els canvis desitjats (és a dir, els valors modificats per a les funcions de l'element). Avís: no utilitzeu mai l'opció de conservació a les vostres ordres de tipus 3, ja que pot causar problemes al costat KNX.

EXAMPLE: PUBLICAR PER CANVIAR EL(S) VALOR(S) D'UN SOL ELEMENT

El cas més senzill és voler canviar el valor d'un dels elements mostrats per la subscripció general.
En termes generals, canviar/canviar una funció de VISION mitjançant MQTT consta de 3 passos, no tots absolutament necessaris, però, tanmateix, recomanem dur-los a terme tal com es descriu.

1. El tema que conté la funció que volem editar està subscrit mitjançant un client_id personalitzat
2. El tema per editar es publica juntament amb la càrrega útil amb els canvis desitjats mitjançant el client_id escollit a 1.
3. Per comprovar, podeu veure la resposta al tema (1.), és a dir, si (2.) va funcionar o no.
4. A la subscripció general, on tots els valors s'actualitzen quan es fan canvis, podeu veure els canvis de valor desitjats si tot ha funcionat bé.

Els passos per fer això són:

1. seleccioneu un client_id, per exemple, "Divus" i inseriu-lo al camí després del nom d'usuari de l'API
   Aquest és el tema complet per subscriure's al teu propi canal de comunicació amb el servidor MQTT. Això indica al servidor on espereu les respostes als canvis que voleu enviar. Observeu la part d'estat/conjunt que defineix a. que és un tema de subscripció i b. que obtindrà les respostes per establir ordres de tipus.
2. El tema de publicació serà el mateix excepte per canviar les paraules clau de sol·licitud d'estat
3. en què ha de consistir el canvi s'escriu a la càrrega útil. Aquí teniu alguns examples.
   • Apagat d'un element que tingui la funció d'encesa/apagada (1 bit):
   • Encesa d'un element que té la funció d'encesa/apagada (1 bit). A més, si s'inicien diverses d'aquestes ordres des del mateix client, el paràmetre uuid ("ID únic", sol ser una cadena de 128 bits amb format hexadecimal de 8-4-4-4-12 dígits) es pot utilitzar per assignar el resposta a la consulta corresponent, ja que aquest paràmetre, si està present a la consulta, també es pot trobar a la resposta.
   • Encendre i ajustar la brillantor d'un regulador al 50%
   • La resposta al tema mostrat i subscrit anteriorment (la seva càrrega útil, per ser exactes) és llavors, per exempleample.
     La resposta anterior és un example en el cas d'una càrrega útil correcta, encara que l'element no té funció d'atenuació. Si hi ha problemes més greus que fan que la càrrega útil no s'interpreti correctament, la resposta serà així (p. ex.):
     per a una explicació dels codis d'error i missatges, però en general, com per a http, 200 codis són respostes positives mentre que 400 són negatives.

EXAMPLE: PUBLICAR PER CANVIAR VALORS DE MÚLTIPLES ELEMENTS

El procediment és similar al que es mostra abans per canviar un sol element. La diferència és que ometeu l'element_id dels temes i després indiqueu el conjunt d'element_ids davant de les dades dins de la càrrega útil. Vegeu la sintaxi i l'estructura a continuació.

FILTRAR PER TIPUS DE FUNCIÓ A LES CONSULTES

El paràmetre de filtres a la càrrega útil només permet abordar la funció o funcions desitjades d'un element. La funció d'encesa/apagada d'un interruptor o regulador s'anomena "onoff", per exempleample, i el filtre corresponent es defineix d'aquesta manera:

Aleshores, la resposta es veu així, per exempleample

El claudàtor indica que també podeu filtrar per diverses funcions, p

porta a una resposta com aquesta:

Apèndix

CODIS D’ERROR

Els errors en la comunicació MQTT donen lloc a un codi numèric. La taula següent ajuda a desglossar-lo.

PARÀMETRES DE LA CÀRREGA ÚTIL

La càrrega útil admet diferents paràmetres segons el context. La taula següent mostra quins paràmetres es poden produir en quins temes

NOTES DE LA VERSIÓ

• VERSIÓ 1.00

Notícies:

• Primera publicació

Documents/Recursos

	Programari API DIVUS VISION [pdfManual d'usuari Programari API VISION, programari API, programari
	Programari API DIVUS Vision [pdfGuia de l'usuari Vision API Software, Vision, API Software, Software

Referències

• Manual d'usuari