Manual de usuario del software API DIVUS VISION

Software API DIVUS VISIÓN

Presupuesto

• Producto: API DIVUS VISIÓN
• Fabricante: DIVUS GmbH
• Versión: 1.00 REV0 1 – 20240528
• Ubicación: Pillhof 51, Eppan (BZ), Italia

Información del producto

La API DIVUS VISION es una herramienta de software diseñada para interactuar con los sistemas DIVUS VISION. Permite a los usuarios acceder y controlar varios elementos dentro del sistema utilizando protocolos MQTT.

Preguntas frecuentes

P: ¿Puedo utilizar la API DIVUS VISION sin conocimientos previos de PC o tecnología de automatización?

R: El manual está diseñado para usuarios con conocimientos previos en estas áreas para garantizar el uso eficiente de la API.

INFORMACIÓN GENERAL

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

Las instrucciones de funcionamiento, los manuales y el software están protegidos por derechos de autor. Reservados todos los derechos. No se permite copiar, duplicar, traducir, traducir total o parcialmente. Se aplica una excepción a la creación de una copia de seguridad del software para uso personal.
El manual está sujeto a cambios sin previo aviso. No podemos garantizar que los datos contenidos en este documento y en los medios de almacenamiento suministrados estén libres de errores y sean correctos. Las sugerencias de mejora y los consejos sobre errores siempre son bienvenidos. Los acuerdos también se aplican a los anexos específicos de este manual. Las designaciones en este documento pueden ser marcas cuyo uso por parte de terceros para sus propios fines puede infringir los derechos de sus propietarios. Instrucciones para el usuario: lea este manual antes de usarlo por primera vez y guárdelo en un lugar seguro para consultarlo en el futuro. Grupo objetivo: El manual está escrito para usuarios con conocimientos previos de PC y tecnología de automatización.

CONVENCIONES DE PRESENTACIÓN

Introducción

INTRODUCCIÓN GENERAL

Este manual describe la API de VISION (interfaz de programación de aplicaciones), una interfaz a través de la cual se puede abordar y controlar VISION desde sistemas externos.
En términos prácticos, esto significa que se pueden utilizar sistemas como

• Explorador MQTT (https://www.microsoft.com/store/… - para las pruebas),
• Asistente de hogar (https://www.home-assistant.io/) o
• Nodo-ROJO (https://nodered.org/)

controlar los elementos gestionados por VISION o leer su estado. El acceso y la comunicación se realizan a través del protocolo MQTT, que utiliza los llamados temas para abordar funciones individuales o conjuntos de funciones o para recibir información sobre cambios en ellas. Para ello se utiliza un servidor MQTT (broker), que se encarga de la seguridad y de la gestión/distribución de mensajes a los participantes. En este caso, el servidor MQTT se encuentra directamente en el DIVUS KNX IQ y está configurado especialmente para este fin. Aunque VISION API también se puede utilizar sin conocimientos de programación, esta funcionalidad es adecuada para usuarios avanzados.

REQUISITOS

Como se explica en el manual de VISION, el usuario de la API debe estar activado primero de forma predeterminada para poder utilizarlo. El acceso a la API solo funciona utilizando los datos de autenticación de los usuarios de la API. En lo que respecta a los derechos de usuario, la activación de esta funcionalidad se puede configurar en todos los elementos o en elementos individuales. Ver Capítulo 0. Por supuesto, también necesitas un proyecto VISION en el que los elementos que quieres controlar desde el exterior estén completamente configurados y se haya probado con éxito la conexión con los mismos. Para poder abordar elementos individuales a través de la API, se debe conocer su ID de elemento: esto se muestra en la parte inferior del formulario de configuración del elemento.

SEGURIDAD

Por motivos de seguridad, el acceso a la API sólo es posible localmente (es decir, no a través de la nube). Por tanto, el riesgo de seguridad al activar el acceso API es bajo. Sin embargo, los elementos relevantes para la seguridad no deben habilitarse ni denegarse explícitamente para el acceso a la API.

MQTT Y SUS TÉRMINOS – BREVE EXPLICACIÓN

• En MQTT, la función de gestión y distribución centralizada de todos los mensajes es la del intermediario. Aunque servidor MQTT y broker MQTT no son sinónimos (servidor es un término más amplio para una función que también pueden desempeñar los clientes MQTT), en este manual siempre se hace referencia al broker cuando se menciona el servidor MQTT. El propio DIVUS KNX IQ desempeña el papel de intermediario MQTT/servidor MQTT en el contexto de este manual.
• Un servidor MQTT utiliza los llamados temas: una estructura jerárquica con la que se clasifican, gestionan y publican los datos.
• La publicación tiene el objetivo principal de poner los datos a disposición de otros participantes a través de temas. Si desea cambiar un valor, escriba en el tema deseado junto con el cambio de valor deseado, utilizando también una acción de publicación. El dispositivo de destino o el servidor MQTT lee el cambio deseado que le afecta y lo adopta en consecuencia. Para comprobar que el cambio se ha aplicado, puede consultar el tema en tiempo real suscrito para ver si el cambio se refleja allí, si todo ha funcionado bien.
• Los clientes seleccionan los temas que les interesan: esto se llama suscripción. Cada vez que cambia un valor dentro o debajo de un tema, se informa a todos los clientes suscritos, es decir, sin tener que preguntar explícitamente si algo ha cambiado o cuál es el valor actual.
• Puede abrir (o abordar) un canal de comunicación separado con el servidor MQTT ingresando cualquier cadena única llamada client_id en un tema. El client_id debe usarse en el tema para procesar valores. Esto sirve para identificar el origen de cada cambio, ayuda con cualquier error y no afecta a los demás clientes, ya que las respuestas correspondientes del servidor, incluidos los códigos y mensajes de error, también llegan solo al tema con el mismo client_id (y por lo tanto solo ese cliente). client_id es una cadena de caracteres única que consta de cualquier combinación de los caracteres 0-9, az, AZ, “-“, “_”.
• En general, los temas de suscripción del servidor MQTT del DIVUS KNX IQ contienen el estado de la palabra clave, mientras que los temas de publicación contienen la solicitud de palabra clave. Aquellos con estado se actualizan automáticamente tan pronto como hay un cambio de valor externo o tan pronto como el propio cliente solicita un cambio de valor a través de una publicación y se aplica con éxito. Los de publicación se dividen a su vez en los de tipo (solicitud/)obtener y los de tipo (solicitud/)conjunto.
• Los cambios de valores y otros parámetros opcionales se agregan al tema con la llamada carga útil. Los parámetros de los elementos individuales (id-elemento, nombre, tipo, funciones)

La principal diferencia entre MQTT y el modelo clásico cliente-servidor, donde el cliente solicita y luego cambia datos, se centra en los conceptos de suscripción y publicación. Los participantes podrán publicar datos, poniéndolos a disposición de otros, quienes, si están interesados, podrán suscribirse a ellos. Esta arquitectura permite minimizar el intercambio de datos y mantener actualizadas a todas las partes interesadas. Más sobre los detalles aquí: y aquí se deben utilizar parámetros especiales (uuid, filtros). Aunque hay varias opciones, la carga útil se muestra formateada como JSON en este manual. JSON utiliza corchetes y comas para representar datos de cualquier estructura y así minimiza el tamaño de los paquetes de datos a transmitir. Más detalles sobre las cargas útiles se pueden encontrar más adelante en el manual.

• Para fines especiales, es posible filtrar según el tipo de función, por ejemplo, para direccionar sólo encendido/apagado, es decir, interruptores de 1 bit. El parámetro de filtros en la carga útil se utiliza para este propósito. Actualmente, el filtrado sólo es posible por tipo de función.
• Para poder abordar elementos individuales, se requiere su ID de elemento. Esto se puede encontrar en VISION en el menú de propiedades del elemento o también se puede leer directamente desde los datos que se muestran delante de cada elemento disponible en la suscripción general del Explorador MQTT (los elementos se enumeran alfabéticamente por ID de elemento).

Configuración para el acceso API

CONFIGURACIÓN DE VISION PARA EL ACCESO DE USUARIOS API

En VISION como administrador, vaya a Configuración – Gestión de acceso de usuario/API, haga clic en Usuarios/Acceso de API y haga clic derecho en Usuario de API (o presione y mantenga presionado) para abrir la ventana de edición. Allí encontrarás estos parámetros y datos.

• Habilitar (casilla de verificación)
  • El usuario se habilita primero aquí. El valor predeterminado está deshabilitado
• Nombre de usuario
  • Esta cadena es necesaria para acceder a través de API; cópiela desde aquí
• Contraseña
  • Esta cadena es necesaria para acceder a través de API; cópiela desde aquí
• Permisos
  • Los derechos predeterminados para leer y escribir los valores de los elementos VISION se pueden definir aquí, es decir, lo que se define aquí se aplica a todos los elementos existentes y futuros. Si solo desea permitir el acceso a elementos individuales, no debe cambiar estos derechos predeterminados

PERMISOS SOBRE ELEMENTOS INDIVIDUALES

Se recomienda no otorgar acceso API a todo el proyecto, sino solo a los elementos deseados. Proceder de la siguiente

1. inicie sesión en VISION como administrador
2. seleccione el elemento deseado y abra su menú de configuración (haga clic derecho o mantenga presionado, luego Configuración)
3. En la entrada del menú General – Permisos, active “Anular permisos predeterminados” y luego vaya al subelemento Permisos, que muestra la matriz de permisos.
4. active aquí el permiso de control, que también habilita la view permiso directamente. Si solo desea leer datos a través del acceso API, es suficiente con habilitar el view permiso.
5. repite el mismo procedimiento para todos los elementos a los que quieras acceder

Conexión vía MQTT

INTRODUCCIÓN

Como exampEn este ejemplo, demostraremos el acceso a través de la API MQTT del DIVUS KNX IQ con un software gratuito relativamente sencillo llamado MQTT Explorer (ver capítulo 1.1), que está disponible para Windows, Mac y Linux. Se implica un conocimiento básico y experiencia con MQTT.

DATOS REQUERIDOS PARA LA CONEXIÓN

Como se mencionó anteriormente (consulte la sección 2.1), se requieren el nombre de usuario y la contraseña del usuario de la API. Aquí hay un finalview de todos los datos que deben recopilarse antes de establecer una conexión:

• Nombre de usuario Leer en la página de detalles del usuario API
• Contraseña Leída en la página de detalles del usuario API
• Dirección IP Leída en la configuración del iniciador en General – Red – Ethernet (o mediante Sincronizador)
• Puerto 8884 (este puerto está reservado para este propósito)

PRIMERA CONEXIÓN CON MQTT EXPLORER Y SUSCRIPCIÓN GENERAL

Normalmente, MQTT distingue entre las actividades de suscripción y publicación. MQTT Explorer simplifica esto suscribiéndose automáticamente a todos los temas disponibles (número de tema) cuando se realiza la primera conexión. Como resultado, el árbol que conduce a todos los elementos disponibles (es decir, acceso de usuario API concedido) se puede ver directamente en el área izquierda de la ventana del Explorador MQTT después de una conexión exitosa. Para ingresar más temas de suscripción o reemplazar el # con un tema más específico, vaya a Avanzado en la ventana de conexión. El tema que se muestra en la esquina superior derecha se parece a esto:

donde 7f4x0607849x444xxx256573x3x9x983 es ​​el nombre de usuario de la API y object_list contiene todos los elementos disponibles. Este tema siempre se mantiene actualizado, es decir, cualquier cambio de valor se refleja allí en tiempo real. Si solo desea suscribirse a elementos individuales, ingrese el ID del elemento deseado después de lista_objetos/.

Nota: Este tipo de suscripción corresponde aproximadamente a la lógica detrás de las direcciones de retroalimentación KNX; muestra el estado actual de los elementos y puede usarse para verificar si los cambios deseados se han aplicado exitosamente. Si sólo desea leer datos pero no cambiarlos, este tipo de suscripción es suficiente.

Un único elemento simple se parece a esto en notación JSON

Nota: Todos los valores tienen la sintaxis que se muestra arriba, por ejemplo, { “valor”: “1” } como resultado de los temas de suscripción, mientras que el valor se escribe directamente en la carga útil para cambiar un valor (es decir, para temas de publicación): los corchetes y Se omite el “valor”, por ejemplo, “onoff”: “1”.

Comandos avanzados

INTRODUCCIÓN

Hay 3 tipos de temas en general:

1. Suscríbase a los temas para ver los elementos disponibles y obtener cambios de valor en tiempo real
2. Suscríbase a los temas para obtener las respuestas a (Los clientes ) publicar solicitudes
3. Publicar tema(s) para obtener o establecer elementos con sus valores

Más adelante nos referiremos a estos tipos utilizando la numeración que se muestra aquí (por ejemplo, temas del tipo 1, 2, 3). Más detalles en los siguientes apartados y en el cap. 4.2.

SUSCRÍBETE A LOS TEMAS PARA VER LOS ELEMENTOS DISPONIBLES Y OBTENER CAMBIOS DE VALOR EN TIEMPO REAL

Estos ya han sido descritos

SUSCRÍBETE A TEMAS PARA OBTENER LAS RESPUESTAS A LAS SOLICITUDES DE PUBLICACIÓN DEL CLIENTE

Este tipo de temas es opcional. Permite

• abra un canal de comunicación único con el servidor MQTT utilizando un client_id arbitrario. Más sobre esto en el cap. 4.2.2
• Obtenga el resultado de las solicitudes de publicación en el tema de suscripción correspondiente: éxito o fracaso con código de error y mensaje.

Hay diferentes temas para obtener respuestas para obtener o configurar comandos de publicación. La diferencia correspondiente en Una vez que tenga claros los temas necesarios para su sistema, puede decidir eliminar este paso y utilizar directamente los temas de publicación.

 PUBLICAR TEMAS PARA OBTENER O CONFIGURAR ELEMENTOS CON SUS VALORES

Estos temas utilizan una ruta similar a la de suscripción; el único cambio es la palabra "solicitud" en lugar del "estado" utilizado para suscribirse. Las rutas completas de los temas se muestran más adelante en el capítulo. 4.2.2\ Un tema de obtención solicitará leer los elementos y valores del servidor MQTT. La carga útil se puede utilizar para filtrar según el tipo de función de los elementos. Un tema establecido solicitará cambiar algunas partes de un elemento, como se detalla en su carga útil.

PREFIJO PARA COMANDOS Y RESPUESTAS CORRESPONDIENTES

 BREVE EXPLICACIÓN

Todos los comandos que se envían al servidor MQTT tienen una parte inicial común, a saber:

EXPLICACIÓN DETALLADA

Los temas en tiempo real (tipo 1) tendrán el prefijo general (ver arriba) seguido de

or

Para los comandos set, la carga útil obviamente juega el papel principal ya que contendrá los cambios deseados (es decir, valores modificados para las funciones del elemento). Una advertencia: nunca utilice la opción retener en sus comandos de tipo 3, ya que puede causar problemas en el lado KNX.

EXAMPLE: PUBLICAR PARA CAMBIAR EL VALOR DE UN ÚNICO ELEMENTO

El caso más sencillo es querer cambiar el valor de uno de los elementos que muestra la suscripción general.
En términos generales, cambiar/cambiar una función de VISION a través de MQTT consta de 3 pasos, no todos los cuales son absolutamente necesarios, pero recomendamos realizarlos como se describe.

1. El tema que contiene la función que queremos editar está suscrito utilizando un client_id personalizado.
2. El tema a editar se publica junto con la carga útil con los cambios deseados utilizando el client_id elegido en 1.
3. Para comprobarlo, puede ver la respuesta en el tema (1.), es decir, si (2.) funcionó o no.
4. En la suscripción general, donde todos los valores se actualizan cuando se realizan cambios, puede ver los cambios de valores deseados si todo ha funcionado bien.

Los pasos para realizar esto son:

1. seleccione un client_id, por ejemplo, "Divus" e insértelo en la ruta después del nombre de usuario de API
   Este es el tema completo para suscribirse a su propio canal de comunicación con el servidor MQTT. Esto le indica al servidor dónde espera las respuestas a los cambios que desea enviar. Observe la parte de estado/conjunto que define a. que sea un tema de suscripción y b. que obtendrá las respuestas para establecer comandos de tipo.
2. El tema de publicación será el mismo excepto por cambiar las palabras clave de solicitud de estado.
3. en qué debería consistir el cambio está escrito en la carga útil. Aquí hay algunos ex.ampLes.
   • Apagar un elemento que tiene la función on/off (1 bit):
   • Encendido de un elemento que tiene la función encendido/apagado (1 bit). Además, si se inician varios comandos de este tipo desde el mismo cliente, el parámetro uuid ("ID único", normalmente es una cadena de 128 bits con formato hexadecimal de 8-4-4-4-12 dígitos) se puede utilizar para asignar el respuesta a la consulta correspondiente, ya que este parámetro, si está presente en la consulta, también se puede encontrar en la respuesta.
   • Encendido y ajuste del brillo de un atenuador al 50%
   • La respuesta al tema mostrado y suscrito anteriormente (su carga útil, para ser precisos) es entonces, por ejemploampel.
     La respuesta anterior es un ex.ample en el caso de una carga útil correcta, aunque el elemento no tenga función de regulación. Si hay problemas más serios que hacen que la carga útil no se interprete correctamente, la respuesta se verá así (por ejemplo):
     para obtener una explicación de los códigos y mensajes de error, pero en general, como para http, 200 códigos son respuestas positivas mientras que 400 son negativas.

EXAMPLE: PUBLICAR PARA CAMBIAR VALORES DE MÚLTIPLES ELEMENTOS

El procedimiento es similar al mostrado antes para cambiar un solo elemento. La diferencia es que omites el element_id de los temas y luego indicas el conjunto de element_ids delante de los datos dentro de la carga útil. Consulte la sintaxis y la estructura a continuación.

FILTRAR POR TIPO DE FUNCIÓN EN CONSULTAS

El parámetro de filtros en la carga útil permite abordar solo las funciones deseadas de un elemento. La función de encendido/apagado de un interruptor o atenuador se llama “onoff”, por ej.amparchivo, y el filtro correspondiente se define de esta manera:

La respuesta entonces se ve así, por ejemplo.ample

El corchete indica que también puede filtrar por varias funciones, por ejemplo

conduce a una respuesta como esta:

Apéndice

CODIGOS DE ERROR

Los errores en la comunicación MQTT dan como resultado un código numérico. La siguiente tabla ayuda a desglosarlo.

PARÁMETROS DE LA CARGA ÚTIL

La carga útil admite diferentes parámetros según el contexto. La siguiente tabla muestra qué parámetros pueden ocurrir en qué temas.

NOTAS DE LA VERSIÓN

• VERSIÓN 1.00

Noticias:

• Primera publicación