MQTT es un protocolo de mensajes ligero que usan muchísimos aparatos domóticos para hablar con Home Assistant: Zigbee2MQTT, los enchufes con Tasmota, muchos Shelly, Frigate, robots con Valetudo o una placa ESP32 con tu propio programa. Si alguno de ellos está en tu casa, tarde o temprano vas a necesitar MQTT.
Este es el primer artículo de dos. Aquí verás qué es y cómo ponerlo en marcha. En MQTT II: a fondo entramos en el descubrimiento, los mensajes retenidos, la disponibilidad y la depuración.
Fuente: documentación oficial de la integración MQTT.
Cómo funciona
MQTT funciona como un tablón de anuncios. Los aparatos publican mensajes en un tema y quien esté suscrito a ese tema los recibe. En medio hay un programa, el broker, que recibe todos los mensajes y los reparte. Nadie habla con nadie directamente.
Cuatro palabras y ya lo tienes:
- Broker: el servidor que reparte los mensajes. En Home Assistant, casi siempre Mosquitto.
- Cliente: cualquiera que se conecta al broker. Home Assistant también es un cliente.
- Tema (topic): la «dirección» del mensaje, como
zigbee2mqtt/salon/sensor_puerta. - Mensaje (payload): el contenido. Puede ser un texto simple (
ON) o un JSON ({"temperatura": 21.5}).
Cómo se lee un tema
Los temas distinguen mayúsculas y minúsculas y no hace falta crearlos: existen en cuanto alguien publica en ellos. Los comodines + y # solo sirven para escuchar varios temas a la vez, nunca para publicar.
Ponerlo en marcha
- Instala el broker. En Ajustes → Aplicaciones, busca Mosquitto broker en la tienda, instálalo y arráncalo. La documentación oficial lo llama el método de instalación recomendado.
- Añade la integración MQTT. Normalmente aparece sola como descubierta en Ajustes → Dispositivos y servicios: pulsa Configurar. Home Assistant crea las credenciales que necesita.
- Conecta el aparato. En la configuración de Zigbee2MQTT, Tasmota o Shelly, escribe la IP de Home Assistant, el puerto 1883 y un usuario y contraseña. Crea en Home Assistant un usuario solo para esto (Ajustes → Personas → Usuarios) y no uses el tuyo.
- Listo. Con el descubrimiento activado (viene así de serie), los dispositivos aparecen en Ajustes → Dispositivos y servicios → MQTT.
Si usas Home Assistant Container, no hay apps: instala Mosquitto u otro broker compatible por tu cuenta y añade la integración a mano con su dirección, puerto y usuario.
Comprobar que llega
La integración trae una herramienta para ver los mensajes en directo: Ajustes → Dispositivos y servicios → MQTT → Configurar.
- En Escuchar un tema, escribe
#y pulsa Empezar a escuchar: verás todo lo que pasa por el broker. Para algo concreto, usazigbee2mqtt/#. - En Publicar un paquete puedes enviar un mensaje de prueba a cualquier tema.
Si escuchas # y no aparece nada, el aparato no está conectado al broker: revisa la IP, el puerto y el usuario.
¿MQTT o integración directa?
| Situación | Qué elegir |
|---|---|
| Zigbee con muchos dispositivos de marcas variadas | Zigbee2MQTT (usa MQTT) o ZHA (sin MQTT); los dos son buenas opciones |
| Enchufes con Tasmota, robots con Valetudo, Frigate | MQTT: es su forma natural de hablar |
| Shelly | La integración Shelly directa es lo más fácil; MQTT si ya lo usas para todo |
| ESPHome | Su integración nativa: MQTT es opcional |
| Un sensor hecho por ti con un ESP32 | MQTT, con descubrimiento (ver MQTT II) |
Siguiente paso
- Lee MQTT II: a fondo: descubrimiento, retenidos, disponibilidad, QoS y depuración.
- Tienes la ficha resumida en el Repositorio: MQTT.
- Para reaccionar a un mensaje en una automatización: el disparador MQTT.
Consulta siempre la fuente oficial: integración MQTT en home-assistant.io.
Infografías: NODARA, a partir de la documentación oficial de Home Assistant.