MQTT es un protocolo ligero de publicación y suscripción para intercambiar mensajes entre dispositivos y aplicaciones.
¿Qué ocurre si queremos integrar en Home Assistant los datos de un autómata programable (PLC) industrial, un script en Python que hemos programado para extraer datos de una web financiera, o el software Zigbee2MQTT que vimos en categorías anteriores?
En domótica se utiliza para conectar sistemas que no comparten fabricante ni lenguaje. Aunque históricamente se asoció el nombre con MQ Telemetry Transport, MQTT es hoy el nombre oficial, no un acrónimo que debamos expandir.
¿Qué es MQTT y por qué es fundamental?
Históricamente, en la web hemos utilizado el protocolo HTTP basado en el modelo Cliente-Servidor. En HTTP, si queremos saber la temperatura de un sensor, el cliente tiene que preguntarle constantemente al servidor: “¿Cuál es la temperatura? ¿Y ahora? ¿Y ahora?” (lo que se conoce como Polling). Esto consume muchísimo ancho de banda y energía.
MQTT resuelve este problema utilizando un paradigma completamente distinto: el modelo de Publicación/Suscripción (Pub/Sub).
En una arquitectura MQTT existen tres piezas fundamentales:
- El Broker (El servidor central): Es el director de orquesta. Recibe todos los mensajes de los dispositivos emisores y se encarga de repartirlos instantáneamente a los dispositivos que estén interesados en esa información.
- Publicadores (Publishers): Los dispositivos o scripts que generan datos y los envían al Broker.
- Suscriptores (Subscribers): Los dispositivos o programas que se conectan al Broker y le dicen: “Avísame inmediatamente si llega información sobre este tema concreto”.
La gran ventaja arquitectónica de MQTT es el desacoplamiento. El termómetro del salón (Publicador) no necesita saber la dirección IP ni el lenguaje en el que está programado Home Assistant (Suscriptor). Ambos solo necesitan saber la IP del Broker. El Broker actúa como intermediario absoluto.
Estructura de la información: topics y payloads
Para que el Broker sepa a quién debe enviar cada mensaje, MQTT no utiliza direcciones IP de destino, sino que utiliza Temas (Topics).
Los topics
Un Topic es simplemente una cadena de texto que actúa como un canal de enrutamiento. Se estructura jerárquicamente utilizando barras diagonales (/), de forma muy similar a las carpetas de un disco duro.
Ejemplos de Topics bien estructurados:
casa/planta_baja/salon/temperaturacasa/garaje/puerta/estadozigbee2mqtt/sensor_movimiento_pasillo
Los suscriptores pueden suscribirse a un tema exacto, o utilizar comodines (Wildcards) para escuchar múltiples canales a la vez.
- El comodín
+sustituye a un solo nivel: Suscribirse acasa/+/temperaturanos dará la temperatura de todas las habitaciones. - El comodín
#sustituye a todos los niveles restantes: Suscribirse azigbee2mqtt/#nos entregará absolutamente todos los mensajes que genere nuestra red Zigbee.
El payload
El Payload es el contenido real del mensaje. Para el Broker MQTT, el payload es simplemente un bloque de bytes crudos; no le importa lo que contenga.
En domótica, el payload suele ser un número simple (22.5), una cadena de texto (encendido), o, en integraciones avanzadas como Zigbee2MQTT, un objeto JSON que agrupa múltiples datos en un solo mensaje:
{
"temperatura": 22.5,
"humedad": 45,
"bateria": 98,
"enlace_lqi": 255
}
QoS y mensajes retenidos
MQTT tiene dos conceptos que conviene conocer desde el principio: QoS (Quality of Service) y Retain.
El QoS indica el nivel de garantía de entrega del mensaje. Para la mayoría de sensores domésticos, QoS 0 suele ser suficiente. Para órdenes o estados importantes, algunos sistemas usan QoS 1, que garantiza que el mensaje llegue al menos una vez. Como casi siempre, más garantía implica algo más de complejidad.
El flag Retain le dice al Broker que guarde el último mensaje de un Topic y se lo entregue automáticamente a cualquier cliente que se suscriba después. Esto es muy útil para estados: si Home Assistant se reinicia, puede recuperar el último valor conocido de casa/salon/temperatura sin esperar a que el sensor publique otra vez.
No uséis retain sin pensar en todos los mensajes. En estados tiene sentido. En comandos puede ser peligroso. Si retenéis un comando como abrir_garaje, un cliente que se conecte más tarde podría recibirlo y ejecutarlo fuera de contexto. Y eso ya no tiene tanta gracia.
Instalación de Mosquitto en Home Assistant OS
Existen muchos brokers MQTT, como EMQX o HiveMQ. Para una instalación doméstica, una de las opciones más extendidas y ligeras es Eclipse Mosquitto.
Mosquitto está escrito en C y consume pocos recursos para una instalación doméstica normal.
Paso 1: instalar e iniciar Mosquitto
La forma más sencilla es instalar la aplicación oficial Mosquitto broker desde Home Assistant. Al configurar la integración MQTT con esta aplicación, Home Assistant puede generar y gestionar automáticamente sus credenciales internas.
- Ve a Ajustes > Aplicaciones.
- Abre la tienda y busca Mosquitto broker.
- Instálalo y asegúrate de marcar las opciones “Iniciar en el arranque” y “Vigilancia” (Watchdog).
- Inicia el complemento.
A nivel de red, Mosquitto abrirá el puerto estándar 1883 (TCP) en la dirección IP de tu servidor Home Assistant (por ejemplo, 192.168.1.50). Todos tus dispositivos físicos en la red local deberán apuntar a esa IP y a ese puerto.
Ese puerto 1883 debe quedarse dentro de vuestra red local. No expongáis MQTT directamente a Internet salvo que sepáis muy bien lo que estáis haciendo y tengáis TLS, autenticación fuerte y una necesidad real. Para una vivienda normal, no hace ninguna falta.
Paso 2: crear credenciales para otros clientes
Para Zigbee2MQTT, microcontroladores u otros clientes externos, añadiremos usuarios específicos en la configuración de la aplicación Mosquitto. No conviene compartir una sola contraseña entre todos los dispositivos si podemos evitarlo.
Paso 3: configurar la integración MQTT
La aplicación es el servidor, mientras que la integración MQTT convierte Home Assistant en cliente. Son dos piezas distintas, aunque el asistente actual puede configurarlas de forma conjunta.
- Ve a Ajustes > Dispositivos y Servicios > Integraciones.
- Home Assistant debería detectar Mosquitto y mostrar una tarjeta de “MQTT” con el botón “Configurar”.
- Si no aparece, añade la integración MQTT y sigue el asistente. No introduzcas
127.0.0.1por costumbre: la dirección depende de dónde se ejecute el broker.
MQTT Discovery: entidades automáticas
Si has configurado todo correctamente, ahora tienes una autopista de datos bidireccional lista para usarse.
Podrías crear entidades manualmente en tu archivo configuration.yaml diciéndole a Home Assistant: “Crea un sensor de temperatura y lee su valor del topic casa/salon/temp”. Sin embargo, esto es un trabajo tedioso.
Para solucionarlo, Home Assistant introdujo el protocolo MQTT Discovery.
Si un dispositivo (como Zigbee2MQTT o un script avanzado) soporta este estándar, publicará un mensaje JSON especial en el topic de configuración (típicamente bajo la jerarquía homeassistant/sensor/...).
Este mensaje contiene el nombre, el icono, la unidad y los topics de datos. Home Assistant lo lee y crea las entidades automáticamente, sin que tengamos que declararlas una a una en YAML.
La herramienta imprescindible: MQTT Explorer
Cuando trabajamos con MQTT en integraciones maker o cuando escribimos nuestros propios scripts en Python, el mayor problema es que los mensajes viajan invisibles por la red. Si Home Assistant no muestra el dato, no sabemos si el fallo está en el publicador, en la configuración de la entidad o en la red.
Para depurar estos problemas resulta muy útil utilizar un cliente que permita inspeccionar topics y payloads.
La herramienta estándar en la industria es MQTT Explorer (gratuito y disponible para Windows, Mac y Linux).
Al conectarlo a tu servidor (usando la IP de Home Assistant, puerto 1883 y tu mqtt_user), esta herramienta te mostrará de forma gráfica e inmediata el árbol jerárquico completo de todos los Topics que están circulando por tu Broker, el contenido de sus payloads y un registro histórico de los valores.
Es el equivalente a un WireShark simplificado y enfocado exclusivamente a tu capa de IoT.
Mosquitto nos permite conectar Zigbee2MQTT, scripts y equipos de terceros sin acoplarlos directamente a Home Assistant.
