Software de API DIVUS VISION

Especificacións

• Produto: DIVUS VISION API
• Fabricante: DIVUS GmbH
• Versión: 1.00 REV0 1 – 20240528
• Lugar: Pillhof 51, Eppan (BZ), Italia

Información do produto

A API DIVUS VISION é unha ferramenta de software deseñada para interactuar cos sistemas DIVUS VISION. Permite aos usuarios acceder e controlar varios elementos dentro do sistema mediante protocolos MQTT.

FAQ

P: Podo usar a API DIVUS VISION sen coñecementos previos sobre PC ou tecnoloxía de automatización?

R: O manual está adaptado para usuarios con coñecementos previos nestas áreas para garantir un uso eficiente da API.

INFORMACIÓN XERAL

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

As instrucións de funcionamento, os manuais e o software están protexidos por dereitos de autor. Todos os dereitos reservados. Non se permite copiar, duplicar, traducir, traducir total ou parcialmente. Unha excepción aplícase á creación dunha copia de seguridade do software para uso persoal.
O manual está suxeito a cambios sen previo aviso. Non podemos garantir que os datos contidos neste documento e nos soportes de almacenamento subministrados estean libres de erros e sexan correctos. As suxestións de mellora e as suxestións sobre erros sempre son benvidas. Os acordos tamén se aplican aos anexos específicos deste manual. As designacións deste documento poden ser marcas comerciais cuxo uso por terceiros para os seus propios fins pode infrinxir os dereitos dos seus propietarios. Instrucións para o usuario: lea este manual antes de utilizalo por primeira vez e garda-lo nun lugar seguro para futuras consultas. Destinatarios: O manual está redactado para usuarios con coñecementos previos de PC e tecnoloxía de automatización.

CONVENCIÓNS DE PRESENTACIÓN

Introdución

INTRODUCIÓN XERAL

Este manual describe a VISION API (Application Programming Interface), unha interface a través da cal VISION se pode dirixir e controlar desde sistemas externos.
En termos prácticos, isto significa que pode utilizar sistemas como

• MQTT Explorer (https://www.microsoft.com/store/… – para proba),
• Asistente de fogar (https://www.home-assistant.io/) ou
• Nodo-VERMELLO (https://nodered.org/)

para controlar os elementos xestionados por VISION ou ler o seu estado. O acceso e a comunicación realízanse a través do protocolo MQTT, que utiliza os chamados temas para abordar funcións individuais ou conxuntos de funcións ou para informarse sobre cambios nos mesmos. Para este fin utilízase un servidor MQTT (corredor), que se encarga da seguridade e da xestión/distribución de mensaxes aos participantes. Neste caso, o servidor MQTT está situado directamente no DIVUS KNX IQ e está especialmente configurado para este fin. Aínda que a API VISION tamén se pode usar sen coñecementos de programación, esta funcionalidade é adecuada para usuarios avanzados.

REQUISITOS

Como se explica no manual de VISION, o usuario da API debe estar activado primeiro por defecto para poder utilizalo, o acceso á API só funciona utilizando os datos de autenticación dos usuarios da API. Polo que respecta aos dereitos de usuario, a activación desta funcionalidade pódese configurar en todos os elementos ou en elementos individuais. Ver cap.0. Por suposto, tamén necesitas un proxecto VISION no que os elementos que queres controlar desde o exterior estean totalmente configurados e a conexión con eles foi probada con éxito. Para poder abordar elementos individuais a través da API, debe coñecerse o seu ID de elemento: móstrase na parte inferior do formulario de configuración do elemento

SEGURIDADE

Por motivos de seguridade, o acceso á API só é posible localmente (é dicir, non a través da nube). Polo tanto, o risco de seguridade ao activar o acceso á API é baixo. Non obstante, os elementos relevantes para a seguridade non se deben activar ou denegar explícitamente para o acceso á API.

MQTT E OS SEUS TERMOS – BREVE EXPLICACIÓN

• En MQTT, o papel da xestión e distribución centralizadas de todas as mensaxes é o do corredor. Aínda que servidor MQTT e intermediario MQTT non son sinónimos (servidor é un termo máis amplo para un papel que tamén poden desempeñar os clientes MQTT), neste manual sempre se enténdese ao corredor cando se menciona o servidor MQTT. O propio DIVUS KNX IQ desempeña o papel de corredor MQTT / servidor MQTT no contexto deste manual.
• Un servidor MQTT utiliza os chamados temas: unha estrutura xerárquica coa que se categorizan, xestionan e publican os datos.
• A publicación ten como obxectivo principal poñer os datos a disposición doutros participantes a través de temas. Se queres cambiar un valor, escribe no tema desexado xunto co cambio de valor desexado, tamén mediante unha acción de publicación. O dispositivo de destino ou o servidor MQTT le o cambio desexado que o afecta e adóptao en consecuencia. Para comprobar que o cambio se aplicou, podes buscar no tema en tempo real subscrito para ver se o cambio se reflicte alí, se todo funcionou ben.
• Os clientes seleccionan os temas que lles interesan: isto chámase subscrición. Cada vez que un valor cambia dentro/debaixo dun tema, todos os clientes subscritos son informados, é dicir, sen ter que preguntar expresamente se algo cambiou ou cal é o valor actual.
• Pode abrir (ou dirixir) unha canle de comunicación separada co servidor MQTT introducindo calquera cadea única chamada client_id nun tema. O cliente_id debe usarse no tema para procesar valores. Isto serve para identificar a orixe de cada cambio, axuda con calquera erro e non afecta aos demais clientes, xa que as respostas correspondentes do servidor, incluídos os códigos de erro e as mensaxes, tamén só chegan ao tema co mesmo client_id (e polo tanto só ese cliente). O client_id é unha cadea de caracteres única que consta de calquera combinación dos caracteres 0-9, az, AZ, “-“, “_”.
• En xeral, os temas de subscrición do servidor MQTT do DIVUS KNX IQ conteñen o estado da palabra clave, mentres que os temas de publicación conteñen a solicitude de palabra clave. Aqueles con estado actualízanse automaticamente en canto hai un cambio de valor externo ou tan pronto como o propio cliente solicitou un cambio de valor a través dunha publicación e se aplique con éxito. As de publicación divídense ademais en tipo (request/)get e as de tipo (request/)set.
• Os cambios de valor e outros parámetros opcionais engádense ao tema coa chamada carga útil. Os parámetros dos elementos individuais (element-id, nome, tipo, funcións)

A principal diferenza entre MQTT e o modelo clásico cliente-servidor, onde o cliente solicita e despois cambia datos, céntrase nos conceptos de subscribir e publicar. Os participantes poderán publicar os datos, poñéndoos a disposición dos demais, que se interesan poden subscribirse a eles. Esta arquitectura permite minimizar o intercambio de datos e aínda manter actualizados a todas as partes interesadas. Máis información sobre os detalles aquí: e os parámetros especiais (uuid, filtros) deben usarse aquí. Aínda que hai varias opcións, a carga útil móstrase con formato JSON neste manual. JSON usa corchetes e comas para representar datos de calquera estrutura e, polo tanto, minimiza o tamaño dos paquetes de datos que se van transmitir. Máis detalles sobre as cargas útiles pódense atopar máis adiante no manual.

• Para propósitos especiais, é posible filtrar segundo o tipo de función, por exemplo, para dirixir só on/off, é dicir, interruptores de 1 bit. Para este fin úsase o parámetro de filtros da carga útil. Actualmente só é posible filtrar por tipo de función.
• Para poder abordar elementos individuais, é necesario o seu ID de elemento. Isto pódese atopar en VISION no menú de propiedades dos elementos ou tamén se pode ler directamente a partir dos datos que se amosan diante de cada elemento dispoñible na subscrición xeral do MQTT Explorer (os elementos están listados alfabeticamente por ID de elemento).

Configuración para o acceso API

CONFIGURACIÓN DA VISIÓN PARA O ACCESO DE USUARIOS DA API

En VISION como administrador, vai a Configuración - Xestión de acceso de usuario/API, fai clic en Usuarios/Acceso a API e fai clic co botón dereito en Usuario API (ou mantén premido) para abrir a xanela de edición. Alí atoparás estes parámetros e datos

• Activar (casilla de verificación)
  • O usuario habilita primeiro aquí. O valor predeterminado está desactivado
• Nome de usuario
  • Esta cadea é necesaria para acceder a través da API; cópiaa desde aquí
• Contrasinal
  • Esta cadea é necesaria para acceder a través da API; cópiaa desde aquí
• Permisos
  • Os dereitos predeterminados para ler e escribir os valores dos elementos VISION pódense definir aquí, é dicir, o que aquí se define aplícase a todos os elementos existentes e futuros. Se só queres permitir o acceso a elementos individuais, non deberías cambiar estes dereitos predeterminados

PERMISOS SOBRE ELEMENTOS INDIVIDUAIS

Recoméndase que non conceda acceso API a todo o proxecto, senón só aos elementos desexados. Proceda do seguinte xeito

1. inicia sesión en VISION como administrador
2. seleccione o elemento desexado e abra o seu menú de configuración (faga clic co botón dereito ou manteña premido, despois Configuración)
3. baixo a entrada do menú Xeral - Permisos, active "Anular permisos predeterminados" e despois vai ao subelemento Permisos, que mostra a matriz de permisos.
4. active aquí o permiso de control, que tamén habilita o view permiso directamente. Se só quere ler datos a través do acceso á API, é suficiente activar o view permiso.
5. repita o mesmo procedemento para todos os elementos aos que queres acceder

Conexión vía MQTT

INTRODUCIÓN

Como example, demostraremos o acceso a través da API MQTT do DIVUS KNX IQ cun software gratuíto e relativamente sinxelo chamado MQTT Explorer (ver cap. 1.1), que está dispoñible para Windows, Mac e Linux. Implica un coñecemento básico e experiencia con MQTT.

DATOS NECESARIOS PARA A CONEXIÓN

Como se mencionou anteriormente (consulte a sección 2.1), son necesarios o nome de usuario e o contrasinal do usuario da API. Aquí hai un remateview de todos os datos que se deben recoller antes de establecer unha conexión:

• Nome de usuario Lea na páxina de detalles do usuario da API
• Contrasinal Lea na páxina de detalles do usuario da API
• Enderezo IP Ler na configuración do lanzador en Xeral - Rede - Ethernet (ou a través do sincronizador)
• Porto 8884 (este porto está reservado para este fin)

PRIMEIRA CONEXIÓN CON MQTT EXPLORER E SUBSCRICIÓN XERAL

Normalmente, MQTT distingue entre as actividades subscribir e publicar. MQTT Explorer simplifica isto ao subscribirse automaticamente a todos os temas dispoñibles (tema #) cando se fai a primeira conexión. Como resultado, a árbore que conduce a todos os elementos dispoñibles (é dicir, o acceso do usuario API concedido) pódese ver directamente na área esquerda da xanela do MQTT Explorer despois dunha conexión exitosa. Para introducir máis temas de subscrición ou substituír o # por un tema máis específico, vai a Avanzado na xanela de conexión. O tema que se mostra na parte superior dereita parece algo así:

onde 7f4x0607849x444xxx256573x3x9x983 é o nome de usuario da API e objects_list contén todos os elementos dispoñibles. Este tema mantense sempre actualizado, é dicir, calquera cambio de valor reflíctese alí en tempo real. Se só quere subscribirse a elementos individuais, introduza o ID do elemento desexado despois da lista_obxectos/.

Nota: Este tipo de subscrición corresponde aproximadamente á lóxica detrás dos enderezos de comentarios KNX; mostra o estado actual dos elementos e pódese utilizar para comprobar se se aplicaron correctamente os cambios desexados. Se só queres ler datos pero non cambialos, este tipo de subscrición é suficiente.

Un único elemento simple parece algo así en notación JSON

Nota: Todos os valores teñen a sintaxe mostrada arriba, por exemplo { “valor”: “1” } como saída dos temas de subscrición, mentres que o valor escríbese directamente na carga útil para cambiar un valor (é dicir, para publicar temas). Os corchetes e o “valor” omítense, por exemplo, “onoff”: “1”.

Comandos avanzados

INTRODUCIÓN

En xeral, hai 3 tipos de temas:

1. Subscríbete a temas para ver os elementos dispoñibles e para obter cambios de valor en tempo real
2. Subscríbete a temas para obter as respostas a (os clientes ) publicar solicitudes
3. Publicar tema(s) para obter ou establecer elementos cos seus valores

Máis adiante referirémonos a estes tipos utilizando a numeración que se mostra aquí (por exemplo, temas de tipo 1, 2, 3). Máis detalles nos seguintes apartados e no cap. 4.2.

SUBSCRIBE TEMAS PARA VER OS ELEMENTOS DISPOÑIBLES E PARA OBTER CAMBIOS DE VALOR EN TEMPO REAL

Estes xa foron descritos

SUBSCRÍBETE PARA OBTER AS RESPOSTAS ÁS SOLICITUDES DE PUBLICACIÓN DO CLIENTE

Este tipo de temas é opcional. Permite

• abra unha canle de comunicación única co servidor MQTT mediante un cliente_id arbitrario. Máis sobre iso no cap. 4.2.2
• obter o resultado das solicitudes de publicación sobre o tema de subscrición correspondente: éxito ou fracaso con código de erro e mensaxe.

Hai diferentes temas para obter respostas para obter ou configurar comandos de publicación. A diferenza correspondente en Unha vez que teñas claros os temas necesarios para o teu sistema, podes decidir eliminar este paso e usar directamente os temas de publicación.

 PUBLICAR TEMAS PARA CONSEGUIR OU POÑER ELEMENTOS COS SEUS VALORES

Estes temas usan un camiño similar aos para subscribirse: o único cambio é a palabra "solicitude" en lugar do "estado" usado para subscribirse. Os camiños dos temas completos móstranse máis adiante no cap. 4.2.2\ Un tema get solicitará ler os elementos e valores do servidor MQTT. A carga útil pódese usar para filtrar en función do tipo de función dos elementos. Un tema determinado solicitará cambiar algunhas partes dun elemento, como se detalla na súa carga útil.

PREFIXO PARA COMANDOS E RESPOSTAS CORRESPONDENTES

 BREVE EXPLICACIÓN

Todos os comandos que se envían ao servidor MQTT teñen unha parte inicial común, a saber:

EXPLICACIÓN DETALLADA

Os temas en tempo real (tipo 1) terán o prefixo xeral (ver arriba) seguido de

or

Para os comandos establecidos, a carga útil obviamente xoga o papel principal xa que contén os cambios desexados (é dicir, os valores modificados para as funcións do elemento). A Aviso: non use nunca a opción de conservar nos seus comandos de tipo 3 xa que pode causar problemas no lado de KNX.

EXAMPLE: PUBLICAR PARA CAMBIAR O(S) VALOR(S) DUN SOLO ELEMENTO

O caso máis sinxelo é querer cambiar o valor dun dos elementos mostrados pola subscrición xeral.
En xeral, cambiar/cambiar unha función de VISION a través de MQTT consta de 3 pasos, non todos absolutamente necesarios, pero recomendamos, con todo, realizalos tal e como se describe.

1. O tema que contén a función que queremos editar está subscrito mediante un client_id personalizado
2. O tema para editar publícase xunto coa carga útil cos cambios desexados usando o client_id escollido en 1.
3. Para comprobar, podes ver a resposta no tema (1.) - é dicir, se (2.) funcionou ou non
4. Na subscrición xeral, onde todos os valores se actualizan cando se fan cambios, podes ver os cambios de valor desexados se todo funcionou ben.

Os pasos para facelo son:

1. seleccione un client_id, por exemplo, “Divus” e insíreo na ruta despois do nome de usuario da API
   Este é o tema completo para subscribirse á túa propia canle de comunicación co servidor MQTT. Isto indica ao servidor onde espera as respostas aos cambios que pretende enviar. Observe a parte de estado/configuración que define a. que é un tema de subscrición e b. que obterá as respostas para establecer comandos de tipo.
2. O tema de publicación será o mesmo, excepto para cambiar as palabras clave de solicitude de estado
3. en que debe consistir o cambio está escrito na carga útil. Aquí tes algúns examples.
   • Desactivar un elemento que teña a función on/off (1 bit):
   • Acender un elemento que teña a función on/off (1 bit). Ademais, se se inician varios destes comandos dende o mesmo cliente, o parámetro uuid ("ID único", adoita ser unha cadea de 128 bits con formato hexadecimal de 8-4-4-4-12 díxitos) pódese utilizar para asignar a resposta á consulta correspondente, xa que este parámetro, se está presente na consulta, tamén se pode atopar na resposta.
   • Acender e configurar o brillo dun atenuador ao 50 %
   • A resposta ao tema mostrado e subscrito anteriormente (a súa carga útil, para ser precisos) é entón, por exemploample.
     A resposta anterior é un example no caso dunha carga útil correcta, aínda que o elemento non ten función de atenuación. Se hai problemas máis graves que provocan que a carga útil non se interprete correctamente, a resposta terá o seguinte aspecto (por exemplo):
     para unha explicación dos códigos de erro e das mensaxes, pero en xeral, como para http, 200 códigos son respostas positivas mentres que 400 son negativas.

EXAMPLE: PUBLICAR PARA CAMBIAR VALORES DE MÚLTIPLES ELEMENTOS

O procedemento é semellante ao mostrado anteriormente para cambiar un só elemento. A diferenza é que omites o element_id dos temas e despois indicas o conxunto de element_ids diante dos datos dentro da carga útil. Vexa a sintaxe e estrutura a continuación.

FILTRAR POR TIPO DE FUNCIÓN NAS CONSULTAS

O parámetro de filtros da carga útil só permite abordar a(s) función(s) desexada(s) dun elemento. A función on/off dun interruptor ou dimmer chámase "onoff", por exemploample, e o filtro correspondente defínese deste xeito:

A resposta é así, por exemploample

O corchete indica que tamén pode filtrar por varias funcións, p

leva a unha resposta como esta:

Apéndice

CÓDIGOS DE ERRO

Os erros na comunicación MQTT dan como resultado un código numérico. A seguinte táboa axuda a desglosalo.

PARÁMETROS DA CARGA ÚTIL

A carga útil admite diferentes parámetros dependendo do contexto. A seguinte táboa mostra que parámetros poden aparecer en que temas

NOTAS DE VERSIÓN

• VERSIÓN 1.00

Novas:

• Primeira publicación

Documentos/Recursos

	Software de API DIVUS VISION [pdfManual do usuario Software API VISION, Software API, Software
	Software de API DIVUS Vision [pdfGuía do usuario Vision API Software, Vision, API Software, Software

Referencias

• Manual de usuario