El plugin Grafana MQTT datasource permite que un dashboard se suscriba a topics del broker y dibuje los valores en el momento en que se publican, sin ninguna base de datos de por medio. En este tutorial instalarás el plugin, lo conectarás a broker.connectmq.com, construirás paneles en vivo a partir de payloads numéricos y JSON, y sabrás exactamente cuándo conviene añadir en su lugar una base de datos de series temporales.
Cómo funciona el Grafana MQTT datasource
La mayoría de los orígenes de datos de Grafana se basan en consultas: un panel pide a una base de datos un rango de tiempo y dibuja el resultado. El origen de datos MQTT es distinto. Es un origen de datos en streaming construido sobre Grafana Live. Cuando se abre un panel, el servidor de Grafana se suscribe al topic que indiques, y cada mensaje se envía al navegador por un WebSocket y se añade a la gráfica.
Ese diseño tiene dos consecuencias que debes entender antes de construir algo serio:
- La latencia es excelente. Un valor publicado por un dispositivo aparece en el panel casi de inmediato, lo que es ideal para puestas en marcha, demos en vivo y vistas de tipo sala de control.
- No hay historial. El plugin solo muestra lo que llegó mientras el panel estaba abierto. Recarga el dashboard y la gráfica empieza vacía. No puedes alejarte para ver el día de ayer, porque el día de ayer nunca se guardó.
Ten presentes ambas cosas. El origen de datos MQTT es una ventana al flujo en vivo, no un registro de él.
Instalar el plugin
El ID del plugin es grafana-mqtt-datasource. En una instalación nativa de Grafana:
grafana cli plugins install grafana-mqtt-datasource
sudo systemctl restart grafana-server
Las versiones antiguas de Grafana usan el binario grafana-cli en lugar de grafana cli. Con Docker, deja que el contenedor lo instale al arrancar:
services:
grafana:
image: grafana/grafana:11.3.0
ports:
- "3000:3000"
environment:
GF_INSTALL_PLUGINS: grafana-mqtt-datasource
volumes:
- grafana-data:/var/lib/grafana
volumes:
grafana-data:
Ejecuta docker compose up -d y abre http://localhost:3000. El inicio de sesión por defecto es admin / admin, y Grafana te pide que lo cambies.
Configurar la conexión
En Grafana, ve a Connections, después a Data sources y luego a Add data source, y busca MQTT. La página de ajustes pide una URI y credenciales opcionales.
| Ajuste | Servidor MQTT público gratuito (pruebas) | Broker privado (producción) |
|---|---|---|
| URI | tcp://broker.connectmq.com:1883 |
tls://broker.connectmq.com:8883 |
| Username | vacío | YOUR_USERNAME |
| Password | vacío | YOUR_PASSWORD |
| Opciones TLS | ninguna | Deja la CA vacía; el certificado de Let's Encrypt es de confianza pública |
Haz clic en Save and test. Una confirmación en verde significa que el servidor de Grafana, no tu navegador, ha llegado al broker. Esa distinción importa en redes restringidas: el servidor necesita acceso saliente al puerto 1883 u 8883. Si tu versión del plugin muestra un campo de client ID y te conectas a un broker MQTT gestionado que vincula los client IDs a las credenciales, introduce el client ID emitido junto con tu usuario.
Publicar algunos datos de prueba
Elige un prefijo único como connectmq/demo/a1b2c3 para que tus topics de prueba no se mezclen en el broker público. Este bucle de Bash publica una temperatura numérica simple cada dos segundos:
ID=a1b2c3
while true; do
T=$(awk -v r=$RANDOM 'BEGIN { printf "%.2f", 20 + r / 32767 * 5 }')
mosquitto_pub -h broker.connectmq.com -p 1883 -i "pub-$ID" \
-t "connectmq/demo/$ID/room1/temperature" -m "$T"
sleep 2
done
Y este publica un objeto JSON con varios valores:
ID=a1b2c3
while true; do
T=$(awk -v r=$RANDOM 'BEGIN { printf "%.2f", 20 + r / 32767 * 5 }')
H=$(awk -v r=$RANDOM 'BEGIN { printf "%.1f", 40 + r / 32767 * 15 }')
mosquitto_pub -h broker.connectmq.com -p 1883 -i "pubjson-$ID" \
-t "connectmq/demo/$ID/room1/telemetry" \
-m "{\"temperature\": $T, \"humidity\": $H}"
sleep 2
done
Para muchos dispositivos a la vez, ejecuta el simulador de dispositivos MQTT en Python y apunta los paneles a los topics de dispositivos individuales.
Construir un panel en vivo con el Grafana MQTT datasource
- Crea un dashboard nuevo y añade una visualización.
- Selecciona el origen de datos MQTT.
- En el editor de consultas, introduce el topic, por ejemplo
connectmq/demo/a1b2c3/room1/temperature. - Elige la visualización Time series. Los valores empiezan a aparecer en segundos.
- Fija el rango de tiempo del dashboard en algo corto, como los últimos 5 minutos. No hace falta la actualización automática, porque el panel funciona en streaming.
Para el topic JSON, el plugin convierte cada clave numérica del objeto en su propio campo, así que temperature y humidity se convierten en dos series en el mismo panel. Usa field overrides para poner la humedad en un eje a la derecha o dar a cada serie su propia unidad. Los paneles Stat y Gauge funcionan bien para valores actuales únicos; fija su cálculo en "Last" para que muestren siempre la lectura más reciente.
Las versiones recientes del plugin aceptan los comodines + y # en el campo de topic, algo práctico para vigilar un grupo de sensores en un solo panel. Si tu versión rechaza los comodines, añade una consulta por topic, ya que cada panel puede contener varias consultas.
Problemas habituales y soluciones
| Síntoma | Causa | Solución |
|---|---|---|
| "Save and test" falla | El servidor de Grafana no llega al broker | Prueba desde el servidor con mosquitto_sub; revisa los cortafuegos y el esquema de la URI |
| El panel sigue vacío | El topic no coincide o aún no se ha publicado nada | Confírmalo con mosquitto_sub -t "connectmq/demo/a1b2c3/#" -v |
| Gráfica vacía tras recargar | Comportamiento esperado; no se guarda historial | Añade una base de datos de series temporales para el historial |
| Texto en lugar de números | El payload incluye unidades, como 21.5 C |
Publica números sueltos o números JSON |
| El panel se congela en el navegador | Tasa de mensajes muy alta en un topic | Publica con menos frecuencia o agrega antes de publicar |
| Unauthorized en un broker privado | Credenciales o client ID incorrectos | Vuelve a copiar los valores del portal del broker |
Cuándo añadir una base de datos de series temporales
El origen de datos en streaming es la herramienta adecuada para un conjunto reducido de tareas. En cuanto necesites historial, agregación o alertas a lo largo del tiempo, pon una base de datos entre el broker y Grafana.
| Requisito | Solo origen de datos MQTT | Telegraf + InfluxDB + Grafana |
|---|---|---|
| Vista en vivo por debajo del segundo | Sí | Casi, limitada por el intervalo de volcado |
| Ver la semana pasada | No | Sí |
| Medias, mín./máx. por hora | No | Sí, en la consulta |
| Reglas de alerta sobre ventanas de tiempo | Limitadas | Sí |
| Sobrevive a recargar el dashboard | No | Sí |
| Componentes adicionales que ejecutar | Ninguno | Dos |
Un patrón habitual combina ambos: un panel respaldado por base de datos para la tendencia y un panel en streaming para el valor actual. El tutorial del Telegraf MQTT consumer muestra cómo escribir los mismos topics en InfluxDB, y el stack TIG con Docker Compose te da el stack completo en un solo archivo con dashboards aprovisionados. Una vez que hay historial, son posibles las alertas de Grafana sobre datos de sensores IoT.
Notas para producción
El broker público lo puede leer cualquiera, así que úsalo solo para datos de prueba. Para equipos reales, conecta Grafana a un broker privado protegido con TLS. Un broker MQTT gestionado de ConnectMQ ofrece TLS en el puerto 8883 y credenciales desde el portal, y Grafana se conecta a él como cualquier otro cliente MQTT. Recuerda que cada conexión del servidor de Grafana cuenta para el límite de conexiones de tu plan, que en el plan Serverless (Free) es de 25.
Para casos de uso solo en el navegador en los que no quieres ningún servidor de Grafana, una pequeña página web que use MQTT sobre WebSocket en el puerto 8084 puede mostrar los valores en vivo directamente. Para elegir el stack cliente adecuado para eso o para el código de los dispositivos, consulta la guía de bibliotecas cliente MQTT. La propia página del plugin Grafana MQTT data source documenta sus opciones actuales.
Empieza con ConnectMQ
Apunta el plugin al servidor MQTT público gratuito broker.connectmq.com, con datos de prueba, y tendrás un panel en vivo en minutos. Cuando el dashboard vaya a mostrar dispositivos reales, ejecuta tu broker en ConnectMQ, donde también tienes un cliente MQTT en el navegador y un explorador de topics en vivo para comprobar los topics antes de conectar los paneles. Crea un broker Serverless gratuito en app.connectmq.com sin tarjeta de crédito. ¿Planificas un despliegue mayor? Nuestra guía del broker MQTT en la nube cubre qué cambia a escala.
Preguntas frecuentes
¿Almacena datos el Grafana MQTT datasource?
No. Envía los mensajes en streaming a los paneles abiertos mediante Grafana Live y no guarda nada cuando el panel se cierra. Usa una base de datos de series temporales como InfluxDB cuando necesites historial.
¿Puedo usar comodines en el campo de topic?
Las versiones recientes del plugin admiten + y #. En versiones antiguas, añade una consulta por topic.
¿Qué formatos de payload funcionan con el plugin?
Los payloads numéricos simples y los objetos JSON con valores numéricos son los que mejor funcionan. Cada clave JSON numérica se convierte en un campo independiente en el panel.
¿Se conecta el navegador directamente al broker?
No. El servidor de Grafana mantiene la conexión MQTT y reenvía los datos a los navegadores mediante Grafana Live, así que solo el servidor necesita acceso de red al broker.
