Integración MQTT

Integración MQTT

MQTT conecta HyperVisu con el mundo de publicación/suscripción: Zigbee2MQTT, Tasmota, Shelly (modo MQTT), ESPHome, pasarelas de energía y cualquier firmware personalizado que se comunique con un broker MQTT. HyperVisu es un cliente MQTT: se suscribe a los topics en los que los dispositivos publican su estado y publica comandos en los topics que los dispositivos escuchan. No hay sondeos (polling): un dispositivo que cambia de estado publica de inmediato y el widget se actualiza al instante.

En el centro se ubica un broker. Puede ser uno que ya esté en funcionamiento (Mosquitto, EMQX, el incluido con una instalación de Zigbee2MQTT, …) o el broker integrado en HyperVisu, que el servidor puede ejecutar directamente para que los dispositivos se conecten a él (consulte «El broker MQTT integrado»). Todo lo expuesto en este artículo se aplica en ambos casos: el broker integrado es un broker estándar al que se accede mediante una conexión habitual.

Lo que necesita: la dirección y el puerto del broker, sus credenciales si las requiere, y los topics y el formato de payload del dispositivo (obtenidos de su documentación o leídos directamente del broker con el explorador de topics que se describe a continuación).

Conexiones. Active primero MQTT Protocol en la página Servicios (consulte «Servicios y protocolos»); por defecto está desactivado en un servidor nuevo. MQTT admite múltiples conexiones: una conexión por cada broker (consulte «Conexiones»). En Añadir conexión, seleccione la tarjeta MQTT: el cuadro de diálogo solicita un Nombre de instancia, la Dirección del broker, el Puerto, el ID de cliente y las credenciales, e incluye un botón Probar. El Certificado CA y las Opciones del broker (Keepalive, QoS por defecto, Topic de disponibilidad, Clean session) no se encuentran en este diálogo: se configuran en la conexión guardada, que se abre en su editor en cuanto hace clic en Crear conexión. El editor de conexiones contiene:

El botón Probar en una conexión MQTT realiza una comprobación real: el servidor se conecta al broker y espera su confirmación (en un plazo de 10 s). Un resultado correcto muestra Conexión establecida. En el diálogo Añadir conexión, Probar comprueba los valores introducidos antes de crear la conexión. En una conexión guardada, Probar verifica los datos almacenados, no los campos que aún no se hayan guardado: haga clic primero en Guardar conexión y luego en Probar. Una prueba correcta demuestra que la dirección, el puerto, las credenciales y la configuración TLS son aceptados por el broker; no confirma que un topic específico contenga datos.

El estado de la conexión muestra Conectado mientras el enlace con el broker esté activo. Si el broker deja de estar disponible, se reintenta la conexión cada pocos segundos indefinidamente; no requiere reiniciar el servidor.

📘 Nota: Tras crear o guardar una conexión, aparece Aplicar cambios con un contador en la barra lateral. La conexión ya está operativa sin este paso; al aplicar los cambios se recarga la configuración del servidor y se restablece el contador.

Vinculación de un objeto (consulte «Vinculación MQTT» a continuación). Para cada objeto se introduce un Topic; la administración lo almacena como <conexión>:<topic>, lo que permite que dos brokers utilicen el mismo nombre de topic. La dirección del objeto determina su comportamiento:

El códec de payload —cómo se convierte el payload en un valor y viceversa— se define mediante la cadena de tipo de datos del objeto, generada por el editor a partir de los siguientes campos:

La cadena tiene la estructura TIPO:parámetro:parámetro… — por ejemplo BOOL:PATH=state:ON=ON:OFF=OFF o FLOAT:SCALE=0.3937:PUB={"brightness":{{value}}}. Una cadena vacía significa «utilizar el payload sin procesar según el tipo del objeto». El editor de objetos no incluye un selector de tipo de datos: el tipo corresponde al indicado en el campo seleccionado en el explorador de topics (más adelante), y al hacer clic en un campo se adapta automáticamente el tipo del objeto. Los objetos de color (RGB) aceptan {"r","g","b"}, {"red","green","blue"}, [r,g,b], #RRGGBB y 255,128,0 en la entrada, y publican {"r":…,"g":…,"b":…} salvo que una plantilla especifique otro formato.

⚠️ Advertencia: Un comando retenido se vuelve a ejecutar cada vez que el dispositivo se reconecta al broker. Se debe retener el estado, no los comandos; el editor muestra una advertencia si se activa la retención en un objeto de salida.

Explorador de topics. MQTT es un protocolo cuyas direcciones pueden identificarse directamente en la red. En el editor de objetos, en Configuración del topic MQTT, haga clic en Escanear broker: el servidor escucha la totalidad del broker durante cuatro segundos e indica el número de topics detectados (los topics retenidos se reciben de inmediato, por lo que un escaneo rápido muestra la mayoría de los elementos útiles; para un dispositivo sin retención, genere una nueva lectura y escanee de nuevo). La lista se limita a un máximo de 500 topics. El editor de objetos no realiza escaneos parciales: abra Topic y escriba en Buscar topics… para filtrar los resultados, o introduzca el topic completo manualmente. Cada fila muestra el topic y su último payload, junto con una etiqueta de retenido. Seleccione un topic y:

• en un payload JSON, cada campo se desglosa en Seleccione el valor que debe seguir este objeto: un solo clic define la ruta JSON, el tipo de objeto y, en booleanos, los tokens ON/OFF con la sintaxis exacta del dispositivo;
• en un payload simple, Usar el payload sin procesar como establece el tipo.

Seleccione el topic antes de hacer clic en un campo: elegir otro topic restablece el formato del payload, la ruta JSON y los tokens. Esta acción no rellena Escala ni Offset.

También es posible introducir un topic que no haya aparecido en el escaneo: un topic de comando puede no haber sido publicado nunca, y un objeto de entrada puede requerir un comodín. Escríbalo en Topic y haga clic en Usar "…" en la lista.

Comportamientos a tener en cuenta

• Estado instantáneo tras un reinicio. El broker reenvía los mensajes retenidos en cada conexión o reconexión, de modo que los widgets muestran sus valores sin esperar a la siguiente publicación del dispositivo.
• Sin confirmaciones simuladas. Un comando solo se confirma cuando el dispositivo publica en su topic de estado (o el broker lo reenvía), exactamente igual que los objetos de estado en KNX. Si el dispositivo no responde, el widget no simula el cambio.
• Comandos durante una pérdida de conexión. Los comandos con QoS 1 o 2 se almacenan en cola mientras el broker no esté accesible y se entregan al restablecerse el enlace; los comandos con QoS 0 enviados a un broker inaccesible fallan y se registran en el log.
• Protección. Los payloads superiores a 64 KB se descartan con un aviso; se crea una única suscripción por cada filtro de topic distinto, con independencia de cuántos objetos lo compartan.

Ejemplo práctico: una lámpara regulable en Zigbee2MQTT

Zigbee2MQTT publica el estado de la lámpara en formato JSON en zigbee2mqtt/lamp ({"state":"ON","brightness":178}) y recibe comandos en zigbee2mqtt/lamp/set. La regulación de brillo va de 0 a 254.

1. Cree una conexión MQTT para el broker (consulte «Conexiones»): dirección del broker 192.168.1.10, puerto 1883 y las credenciales del broker Zigbee2MQTT si son necesarias. Haga clic en Probar; debe confirmar la conexión.
2. En Dispositivos, añada un widget de tipo Regulador llamado «Lámpara de oficina». En Protocolo, seleccione la conexión del broker por el nombre asignado. El dispositivo se genera con cuatro objetos: Conmutación ON/OFF, Respuesta de conmutación, Consigna de regulación y Respuesta de regulación.
3. En Conmutación ON/OFF (comando de encendido/apagado): introduzca zigbee2mqtt/lamp/set en Topic y haga clic en Usar "…" en la lista. Configure Token ON como ON, Token OFF como OFF y Plantilla de payload como {"state":"{{value}}"}. Escriba los tokens manualmente: los textos en gris ON y OFF son solo sugerencias; sin ellos, el conmutador publicará true o false.
4. En Respuesta de conmutación (estado de encendido/apagado): haga clic en Escanear broker, elija zigbee2mqtt/lamp y seleccione el campo state: el editor configurará la ruta JSON state y los tokens ON/OFF.
5. En Consigna de regulación (comando de brillo): topic zigbee2mqtt/lamp/set, Plantilla de payload {"brightness":{{value}}}, Escala 0.3937, Offset 0.
6. En Respuesta de regulación (estado de brillo): topic zigbee2mqtt/lamp, seleccione el campo brightness y configure la misma Escala 0.3937. Este factor equivale aproximadamente a 100/254: los valores recibidos se multiplican por él (Zigbee 0–254 pasa a 0–100 %) y los valores emitidos se dividen por él (0–100 % pasa a 0–254).
7. Haga clic en Guardar objeto en cada uno de ellos, luego en Aplicar cambios en la barra lateral y confirme.
8. Ajuste el brillo al 50 % en la aplicación. La lámpara recibe aproximadamente 127 y su respuesta devuelve cerca del 50 %. El deslizador se actualiza a partir del topic de estado y el accionamiento mediante un mando físico también actualiza la aplicación.

📘 Nota: El valor transmitido no se redondea: 50 % se publica como 127.000254. El editor de objetos no incluye un selector de tipo de datos, por lo que no es posible forzar un número entero en el objeto de comando. Asegúrese de que la lámpara admita valores decimales de brillo.

Vinculación MQTT

Los objetos MQTT se configuran en el cuadro de diálogo de ajustes del objeto (abra el objeto con Editar, consulte «Ajustes de objetos, registro y notificaciones»). La sección específica del protocolo se organiza en tres bloques:

Configuración del topic MQTT

Publicación (objetos de salida)

Suscripción (objetos de entrada)

Los campos se guardan como la cadena de tipo de datos del objeto (p. ej. BOOL:PATH=state:ON=ON:OFF=OFF); la sintaxis, el explorador de topics y un ejemplo práctico se detallan en la sección MQTT superior.