El broker MQTT integrado
HyperVisu puede ejecutar su propio broker MQTT en el servidor. De este modo, los dispositivos se conectan directamente a HyperVisu en lugar de hacerlo a una máquina broker independiente que requiera instalación, protección y mantenimiento de actualizaciones. Los topics se vinculan exactamente igual que en cualquier otro broker (consulte «Integración MQTT»). El mismo broker también puede transmitir los valores de la propia instalación hacia el exterior, permitiendo que un panel de control, un sistema de gestión energética u otro controlador lean el estado del edificio.
Utilícelo cuando disponga de dispositivos MQTT y aún no cuente con un broker. Si ya utiliza uno (el integrado en una instalación Zigbee2MQTT, un Mosquitto en un servidor, un EMQX), manténgalo: HyperVisu funciona perfectamente como cliente y el broker integrado puede permanecer desactivado.
Requisitos: el protocolo MQTT habilitado (consulte «Servicios y protocolos») para poder vincular dispositivos, y una cuenta para cada dispositivo que se vaya a conectar.
Activación. El broker es un servicio opcional, por lo que requiere reiniciar para aparecer y se configura a continuación:
- Vaya a Servicios y active Broker MQTT en la lista de servicios opcionales.
- Haga clic en Reiniciar servidor y espere a que la página vuelva a conectarse.
- De nuevo en Servicios, haga clic en Configurar en la fila del Broker MQTT. Se abrirá la página Broker MQTT.
ℹ️ Nota: El conmutador de la página Servicios inicia y detiene el broker; todos los parámetros de la página Broker MQTT definen su comportamiento. Un cambio en la página Servicios requiere reiniciar el servidor; un cambio en la página Broker MQTT solo reinicia el propio broker.
Guardar cambios. Las modificaciones se acumulan hasta que se aplican: aparece una barra en la parte inferior de la página con Aplicar y Descartar. Aplicar guarda los ajustes y reinicia el broker; los dispositivos conectados se reconectan automáticamente en unos segundos. Volver a aplicar, en la parte superior del panel de Estado, vuelve a escribir los parámetros y reinicia incluso si no ha habido cambios; utilícelo si el broker se detuvo manualmente o si la página indica que los archivos en disco difieren de los ajustes guardados.
Estado: comprobación de funcionamiento y acceso de los dispositivos
El panel de Estado es el primer elemento a revisar.
- Una tarjeta por listener (MQTT y WebSockets), indicando la dirección de cada uno y si está Escuchando, Sin respuesta o Desactivado.
- Dirección a introducir en el dispositivo: la dirección que debe configurarse en un Shelly, un Tasmota o en la configuración de Zigbee2MQTT, junto con un botón Copiar. Se compone de la dirección del propio servidor y el puerto del listener estándar.
- Conexión propia de HyperVisu: la cuenta y la conexión que utiliza el propio HyperVisu para comunicarse con el broker. Se genera automáticamente la primera vez que se utiliza el broker; Reparar la vuelve a crear si la conexión ha sido editada o eliminada.
Si el broker nunca se ha iniciado, el panel indicará que el servicio no está en ejecución y remitirá a la página de Servicios.
Listeners: puertos de escucha del broker
Un listener es un puerto en el que el broker acepta conexiones. Hay dos disponibles, cada uno con un Puerto y una Dirección de enlace:
| Listener | Por defecto | Finalidad |
|---|---|---|
| MQTT | puerto 1883, act. | El listener habitual para dispositivos. Requiere autenticación; este listener no está cifrado, no abierto. |
| WebSockets | puerto 9001, des. | Para clientes MQTT ejecutados en navegadores y paneles de control que utilizan MQTT sobre WebSockets. |
La Dirección de enlace define el origen de las conexiones permitidas: 0.0.0.0 acepta conexiones desde la red, mientras que 127.0.0.1 las restringe exclusivamente al propio servidor.
Al menos un listener debe permanecer activo; de lo contrario, ningún equipo podría conectarse y la página no permitirá guardar. Dos listeners no pueden compartir el mismo puerto, y los puertos ya ocupados en el servidor (la interfaz web, la base de datos de histórico, paneles de control, Node-RED, streaming de cámaras, Home Assistant, la API de HyperVisu) serán rechazados explícitamente.
⚠️ Advertencia: Ninguno de los listeners cifra el tráfico transmitido, por lo que el broker debe mantenerse dentro de la red local. Enlázelo a
127.0.0.1si solo requiere acceso el propio servidor y nunca redirija sus puertos desde Internet.
Cuentas y accesos: permisos de conexión
⚠️ Advertencia: Un broker sin restricciones representa una vía de acceso a la instalación. Asigne a cada dispositivo su propia cuenta y mantenga deshabilitado el acceso anónimo.
Cuentas. Cada dispositivo que se conecte requiere un usuario y una contraseña. Haga clic en Añadir cuenta, introduzca un Usuario (letras, dígitos y . _ @ -) y una Contraseña, y aplique los cambios. La contraseña se procesa mediante hash en el momento de guardarse y no se puede recuperar, únicamente sustituir mediante el botón Contraseña en la fila de la cuenta. HyperVisu dispone de su propia cuenta, identificada como tal; el sistema la gestiona automáticamente y no puede eliminarse.
La página no permite guardar una configuración con el acceso anónimo desactivado y sin ninguna cuenta creada, ya que nada podría conectarse, ni siquiera HyperVisu.
Conexiones anónimas. La opción Permitir conexiones anónimas permite la conexión de cualquier cliente sin usuario ni contraseña. Está desactivada por defecto. Si se activa mientras un listener es accesible desde la red, la página mostrará una advertencia (Este broker quedaría abierto a toda la red) y bloqueará el guardado hasta marcar la casilla Entiendo los riesgos y deseo permitirlo. De lo contrario, cualquier usuario en la red podría leer y controlar los datos de la instalación.
Restricciones de topics. Sin reglas definidas, cualquier cuenta autenticada puede publicar y suscribirse a todos los topics. Active Restringir topics por cuenta y haga clic en Añadir regla. Cada regla define una Cuenta (escriba el usuario; si se deja en blanco, la regla se aplica a clientes anónimos), un Permiso (lectura, escritura, lectura/escritura o denegar) y un Filtro de topic, donde + equivale a un nivel y # al resto del árbol.
Configuración típica: la pasarela Zigbee recibe lectura/escritura en zigbee2mqtt/#, un panel de control recibe lectura en hypervisu/#, y el resto queda bloqueado.
ℹ️ Nota: Las reglas actúan como una lista restrictiva completa: una cuenta sin una regla que coincida con un topic será rechazada en este. La cuenta propia de HyperVisu es la excepción: mantiene siempre acceso total, garantizando que la activación de restricciones no desconecte al servidor de los topics vinculados a sus dispositivos. Cualquier regla asignada a dicha cuenta será ignorada.
Almacenamiento y límites
Estos parámetros protegen al servidor frente a comportamientos anómalos de dispositivos y definen la persistencia tras un reinicio.
| Parámetro | Por defecto | Función |
|---|---|---|
| Mantener mensajes retenidos tras el reinicio | act. | Guarda el estado del broker en disco para conservar los topics retenidos tras reiniciar. Sin esta opción, los valores retenidos se pierden al detener el broker y los widgets esperan a la siguiente publicación. |
| Intervalo de guardado (s) | 1800 | Frecuencia de escritura del estado en disco. Un intervalo mayor reduce los ciclos de escritura en la tarjeta de memoria del servidor. |
| Conexiones máximas | 200 | Número máximo de clientes simultáneos permitidos. -1 para ilimitado. |
| Tamaño máximo de paquete (bytes) | 0 | Tamaño máximo de mensaje admitido por el broker. 0 significa ilimitado. |
| Permitir mensajes retenidos | act. | Permite que los dispositivos soliciten al broker almacenar su último valor para nuevos suscriptores. Al desactivarlo, cada widget deberá esperar una nueva publicación tras reconectarse. |
💡 Consejo: Mantenga habilitados los mensajes retenidos. Permiten que la aplicación muestre los valores reales inmediatamente tras el reinicio del servidor, evitando widgets vacíos.
Publicación de estados de widgets en MQTT
HyperVisu puede publicar los valores de sus dispositivos en el broker, permitiendo que sistemas externos lean la instalación sin interactuar directamente con HyperVisu: un panel de control de Grafana, un gestor energético, un controlador de terceros u otro sistema del edificio.
Esta función está desactivada por defecto y, mientras permanezca así, no se publicará ningún dato. Al activar Publicar estados de widgets en MQTT, se muestran los siguientes ajustes:
| Parámetro | Por defecto | Función |
|---|---|---|
| Prefijo de topic | hypervisu | Primer segmento de cada topic. Solo admite segmentos simples, sin + ni #. |
| Incluir el número de serie en el topic | act. | Añade el número de serie del servidor tras el prefijo, permitiendo que dos instalaciones compartan el mismo broker sin colisiones. |
| Estilo de topic | Identificadores | Identificadores (estable) utiliza los números internos de dispositivo; Nombres (legible) utiliza los nombres de estancia y dispositivo. Los nombres facilitan la lectura, pero renombrar una estancia desplaza todos sus topics y afecta a los suscriptores. |
| Carga útil (Payload) | Solo valor | Solo valor publica el dato directo; JSON con contexto publica el valor junto con el nombre y la estancia del dispositivo, su unidad, su identificador y la marca temporal, permitiendo interpretar el mensaje sin conocer de antemano widget/42/1. |
| Intervalo mínimo (ms) | 1000 | Límite de tasa por objeto. El valor más reciente siempre se transmite; 0 publica absolutamente cada cambio. |
| Retener el último valor | act. | Permite que un cliente conectado posteriormente reciba el estado actual de forma inmediata sin esperar al siguiente cambio. |
| Publicar topic de disponibilidad | act. | Publica online / offline de forma retenida en <prefijo>/<serie>/status, permitiendo verificar si la lectura es en tiempo real o el último dato antes de una desconexión. Al desactivar la publicación, se retira el topic. |
| Solo estos widgets | des. | Desactivado publica todos los dispositivos. Activado permite seleccionar cuáles incluir. |
| Aceptar comandos mediante MQTT | des. | Permite a un suscriptor escribir valores para control. Consulte la advertencia inferior. |
La página muestra Aspecto del topic con un ejemplo dinámico según los cambios realizados. Con los valores por defecto, el dato de un dispositivo se publica en:
hypervisu/<serie>/widget/42/1/state
y utilizando Nombres (legible):
hypervisu/<serie>/salon/lampara-techo/1/state
El último segmento antes de state corresponde al número de objeto del dispositivo: se genera un topic por cada objeto de comunicación, no uno por dispositivo.
Con la opción JSON con contexto, el propio mensaje especifica su contenido:
{"value":21.5,"unit":"°C","name":"Termostato pasillo","room":"Baño","widget":46,"object":2,"type":"FLOAT","ts":"2026-09-09T07:51:22.436Z"}
El nombre y la estancia se leen en el momento de la publicación; renombrar un dispositivo modifica el siguiente mensaje sin alterar la estructura del topic. Esta es la diferencia respecto a Nombres (legible): los topics legibles cambian de ruta al renombrar, mientras que una carga útil legible no lo hace.
Recepción de comandos. Con Aceptar comandos mediante MQTT activo, publicar un valor en el topic …/set correspondiente actúa sobre el dispositivo exactamente igual que si se ejecutara desde la aplicación.
⚠️ Advertencia: Esto permite controlar el edificio a cualquier entidad con permisos de publicación en el broker. Actívelo únicamente con el acceso anónimo desactivado y con restricciones de topics configuradas; la interfaz bloquea directamente la combinación de comandos con acceso anónimo.
Los comandos se rechazan (y se contabilizan como tales) cuando el topic pertenece a un objeto de solo lectura o cuando la carga útil no coincide con el tipo de datos del objeto. El panel muestra el recuento de mensajes publicados y descartados, además de un distintivo con la cantidad de objetos publicados actualmente.
ℹ️ Nota: La publicación requiere tener activo el protocolo MQTT y una conexión establecida con un broker. Si se activa sin este requisito, el panel lo indicará en lugar de simular la publicación.
Exploración de topics en el broker
La sección Topics en el broker, al final de la página, muestra la actividad en tiempo real del broker; es el método más rápido para verificar si un dispositivo recién configurado se está comunicando correctamente.
- Opcionalmente, complete Limitar a un subárbol para acotar la búsqueda (
zigbee2mqttanaliza únicamentezigbee2mqtt/#). - Seleccione el tiempo de Escucha: 3, 4, 10 o 30 segundos.
- Haga clic en Escanear.
El resultado se estructura en un árbol según los niveles / de los propios topics, manteniendo la legibilidad incluso con cientos de entradas. Haga clic en una rama para desplegarla (la fila indica cuántos topics contiene) y seleccione un topic para ver su última carga útil. En payloads JSON, se detallan los campos inferiores con su tipo interpretado; en payloads simples, el tipo detectado. El botón de copia en la fila activa permite copiar el topic completo. Las opciones Expandir todo y Contraer todo se sitúan sobre el árbol; las búsquedas pequeñas se muestran expandidas por defecto.
Un nivel con un único elemento secundario se agrupa con su nivel superior (118/1/state en una sola fila en vez de tres), agilizando la navegación en prefijos profundos. Los topics retenidos aparecen en primer lugar en cada nivel.
Los topics propios publicados por HyperVisu muestran el nombre del dispositivo asociado cuando está disponible: un topic como hypervisu/<serie>/widget/42/1/state muestra el dispositivo al que pertenece junto a él, evitando tener que consultar el identificador.
Los topics retenidos son transmitidos por el broker en el momento en que se inicia la suscripción del escaneo, mostrando todo el árbol retenido incluso en análisis cortos. Si el escaneo no muestra datos, es posible que ningún dispositivo esté conectado aún o que solo publiquen por cambio de estado; pruebe con un intervalo de escucha mayor.
ℹ️ Nota: El escaneo consulta el broker en su estado de ejecución actual; los cambios sin guardar realizados en la página no se reflejan en el resultado. El panel lo advertirá mientras existan cambios pendientes.
El escaneo es de solo lectura: muestra la información existente sin realizar publicaciones. Para vincular uno de estos topics a un dispositivo, abra el objeto del dispositivo y seleccione el topic en el editor de objetos (consulte «Integración MQTT»); allí está disponible el mismo escaneo, completando automáticamente el tipo, la ruta JSON y los valores ON/OFF correspondientes.
Ejemplo práctico: enchufe Shelly en el broker integrado
Control de un enchufe Shelly Plus mediante HyperVisu sin disponer de un broker previo en la red.
- Servicios → active Broker MQTT → Reiniciar servidor. Asegúrese de que el protocolo MQTT también esté activo.
- Servicios → Configurar en la fila del Broker MQTT. En Cuentas y accesos, haga clic en Añadir cuenta: usuario
shelly, contraseña a elegir. Haga clic en Aplicar. - Anote la Dirección a introducir en el dispositivo indicada en el panel de Estado; por ejemplo,
192.168.1.60:1883. - En la interfaz web del propio Shelly, active MQTT, introduzca dicha dirección, el usuario
shellyy su contraseña, y guarde. El enchufe se reiniciará y establecerá conexión. - Vaya a Conexiones. Aparecerá la opción Usar el broker local; haga clic en ella y HyperVisu creará su propia conexión con el broker. Si ya se realizó previamente, la conexión estará disponible (el explorador de topics la requiere, por lo que debe realizarse antes de escanear).
- En la página del Broker MQTT, abra Topics en el broker y haga clic en Escanear. Aparecerán los topics del enchufe (
shellyplus1pm-a8032ab1/status/switch:0entre otros) con sus últimas cargas útiles. - En Dispositivos, añada un widget de Interruptor de luz llamado «Enchufe cocina», protocolo MQTT, asociado a esa conexión, y vincule sus objetos a los topics del enchufe mediante la opción Escanear broker en el editor de objetos.
- Conmute el enchufe desde la aplicación. El comando se transmitirá a través del broker integrado y el topic de estado del propio enchufe confirmará la acción.