Home Assistant MQTT: guía completa de configuración

El soporte de MQTT en Home Assistant te permite incorporar a tu hogar inteligente cualquier dispositivo que hable MQTT: sensores ESP32 caseros, enchufes Tasmota, redes Zigbee2MQTT y gateways industriales por igual. En esta guía configurarás la integración MQTT de Home Assistant, crearás sensores e interruptores en YAML, lo probarás todo contra el broker público broker.connectmq.com y después pasarás a un broker privado de ConnectMQ con TLS.

Cómo usa MQTT Home Assistant

Home Assistant no es un broker MQTT. Su integración MQTT es un cliente que se conecta a un broker, se suscribe a topics de estado y publica en topics de órdenes. Los dispositivos son clientes del mismo broker. El broker se sitúa en el centro y enruta los mensajes, algo que se explica en detalle en qué hace un broker MQTT.

Eso te da dos opciones de alojamiento:

Opción	Dónde se ejecuta el broker	Ideal para	Contrapartidas
Complemento Mosquitto	En el equipo de Home Assistant	Una sola vivienda, todos los dispositivos en la LAN	Los dispositivos remotos necesitan redirección de puertos o VPN; tú mantienes las copias de seguridad
Broker en la nube	Alojado, accesible mediante TLS	Dispositivos en varias ubicaciones, sensores remotos, compartir datos con otras apps	Necesita internet; elige un proveedor de confianza
Ambos, con puente	Mosquitto local puenteado a un broker en la nube	Resiliencia local más acceso remoto	Más configuración

Este tutorial usa un broker en la nube porque funciona igual tanto si Home Assistant se ejecuta en una Raspberry Pi como en un NUC o una máquina virtual. Si quieres el razonamiento detallado y la opción con puente, lee cómo usar un broker MQTT externo con Home Assistant.

Paso 1: añadir la integración MQTT

Abre Ajustes > Dispositivos y servicios.
Haz clic en Añadir integración y busca MQTT.
Elige MQTT (no un complemento) e introduce los datos del broker:
- Broker: broker.connectmq.com
- Puerto: 1883
- Usuario y contraseña: déjalos vacíos para el broker público de pruebas
Envía el formulario. Home Assistant se conecta y crea la entrada de la integración MQTT.

Para configurar el client ID, TLS o la versión del protocolo, activa primero el Modo avanzado en tu perfil de usuario. El cuadro de diálogo de configuración de la integración muestra entonces campos adicionales como el client ID, el keep alive, la validación del certificado del broker, el transporte (TCP o WebSockets) y la versión del protocolo MQTT. Los necesitarás en el paso 6.

El broker público necesita un client ID no vacío. Home Assistant genera uno aleatorio automáticamente cuando el campo se deja vacío, lo cual sirve para hacer pruebas.

Paso 2: comprobar la conexión

Abre Ajustes > Dispositivos y servicios > MQTT > Configurar. Esta página tiene un formulario Publicar un paquete y otro Escuchar un topic.

En Escuchar un topic, introduce connectmq/demo/ha-x7m2/# y haz clic en Empezar a escuchar. Después, desde cualquier ordenador, publica un mensaje de prueba:

mosquitto_pub -h broker.connectmq.com -p 1883 -i ha-test-x7m2 \
  -t "connectmq/demo/ha-x7m2/test" -m "hello from the terminal"

El mensaje aparece en Home Assistant en menos de un segundo. Si no lo hace, comprueba que el equipo de Home Assistant puede salir hacia el puerto 1883; algunas redes lo bloquean, en cuyo caso usa el 8883 con TLS.

Paso 3: crear un sensor MQTT en YAML

Supongamos que un ESP32 publica la temperatura y la humedad como JSON en connectmq/demo/ha-x7m2/livingroom/climate:

{"temperature": 22.7, "humidity": 48.1, "battery": 87}

Añade esto a configuration.yaml (o a un archivo incluido desde él):

mqtt:
  sensor:
    - name: "Living Room Temperature"
      unique_id: livingroom_temperature_x7m2
      state_topic: "connectmq/demo/ha-x7m2/livingroom/climate"
      value_template: "{{ value_json.temperature }}"
      unit_of_measurement: "°C"
      device_class: temperature
      state_class: measurement
      expire_after: 600

    - name: "Living Room Humidity"
      unique_id: livingroom_humidity_x7m2
      state_topic: "connectmq/demo/ha-x7m2/livingroom/climate"
      value_template: "{{ value_json.humidity }}"
      unit_of_measurement: "%"
      device_class: humidity
      state_class: measurement
      expire_after: 600

unique_id te permite renombrar la entidad y asignarla a un área desde la interfaz. expire_after marca el sensor como no disponible si no llega ningún mensaje en diez minutos, que es como te das cuenta de que se ha agotado una batería. state_class: measurement hace que funcionen las estadísticas a largo plazo.

Recarga desde Herramientas para desarrolladores > YAML > Entidades MQTT configuradas manualmente y después simula el dispositivo:

mosquitto_pub -h broker.connectmq.com -p 1883 -i ha-test-x7m2 \
  -t "connectmq/demo/ha-x7m2/livingroom/climate" \
  -m '{"temperature": 22.7, "humidity": 48.1, "battery": 87}'

Paso 4: crear un interruptor MQTT

Un interruptor necesita un topic de órdenes en el que publica Home Assistant y un topic de estado en el que informa el dispositivo:

mqtt:
  switch:
    - name: "Desk Lamp"
      unique_id: desk_lamp_x7m2
      command_topic: "connectmq/demo/ha-x7m2/desk-lamp/set"
      state_topic: "connectmq/demo/ha-x7m2/desk-lamp/state"
      availability_topic: "connectmq/demo/ha-x7m2/desk-lamp/availability"
      payload_on: "ON"
      payload_off: "OFF"
      state_on: "ON"
      state_off: "OFF"
      qos: 1
      retain: false

Coloca los sensores y los interruptores bajo una única clave mqtt: en tu configuración; YAML no permite repetir la clave. Si todavía no tienes hardware, haz tú de dispositivo:

# actúa como el dispositivo: anuncia la disponibilidad e informa del estado
mosquitto_pub -h broker.connectmq.com -p 1883 -i ha-dev-x7m2 -r \
  -t "connectmq/demo/ha-x7m2/desk-lamp/availability" -m "online"
mosquitto_pub -h broker.connectmq.com -p 1883 -i ha-dev-x7m2 -r \
  -t "connectmq/demo/ha-x7m2/desk-lamp/state" -m "OFF"

# observa las órdenes que envía Home Assistant cuando accionas el interruptor
mosquitto_sub -h broker.connectmq.com -p 1883 -i ha-dev2-x7m2 \
  -t "connectmq/demo/ha-x7m2/desk-lamp/set" -v

Cuando cambias el interruptor en el panel, aparece ON en el terminal. Publica ON en el topic de estado para confirmarlo y el interruptor se queda encendido. Sin un topic de estado, Home Assistant ejecuta el interruptor en modo optimista y simplemente da por hecho que la orden ha funcionado.

Para luces con brillo, usa la plataforma light con schema: json; el formato del payload coincide con el del regulador de nuestro tutorial de iluminación inteligente con MQTT.

Paso 5: un dispositivo real

El dispositivo real más rápido es un ESP32 con un sketch corto, como en el tutorial de ESP32 con MQTT, que publique en el mismo topic de clima. Los dispositivos ESPHome y Tasmota también pueden publicar por MQTT; consulta ESPHome con MQTT. En lugar de escribir YAML para cada entidad, esos dispositivos pueden anunciarse automáticamente mediante el descubrimiento MQTT de Home Assistant.

Paso 6: pasar a un broker privado con TLS

El servidor MQTT público gratuito es perfecto para la primera hora, pero todo lo que circula por él puede leerlo cualquiera, y cualquiera puede publicar en el topic de órdenes de tu interruptor. Los datos de tu casa deben estar en un broker privado. También hay una razón práctica: el broker público permite 10 suscripciones por cliente, y Home Assistant se suscribe a un topic por entidad más los topics de descubrimiento, así que alcanzarás el límite enseguida.

Regístrate en el portal de ConnectMQ, crea un broker y copia el usuario, la contraseña y el client ID generados.
En Home Assistant, abre Ajustes > Dispositivos y servicios > MQTT, abre el menú de la entrada y elige Reconfigurar (o Configurar y después Volver a configurar MQTT, según tu versión).
Indica el puerto 8883, introduce el usuario y la contraseña, pon como client ID el valor emitido y establece la validación del certificado del broker en Automático para que el almacén de CA del sistema valide el certificado de Let's Encrypt.
Cambia tus topics de connectmq/demo/ha-x7m2/... a tu propia raíz, por ejemplo home/livingroom/climate, tanto en los dispositivos como en el YAML.

El client ID debe coincidir exactamente con el emitido, porque ConnectMQ vincula los client ID a las credenciales. Una discrepancia se manifiesta como líneas repetidas de "connection refused, not authorized" en el registro de Home Assistant.

Lista de comprobación para la resolución de problemas

La integración no se conecta. Prueba el mismo host, puerto y credenciales con mosquitto_sub desde otra máquina.
La entidad aparece como desconocida. El dispositivo no ha publicado desde que arrancó Home Assistant. Publica el estado con el indicador de retención.
La entidad aparece como no disponible. O bien ha transcurrido expire_after, o bien el topic de disponibilidad indica offline.
Errores de plantilla en el registro. El payload no es el JSON que esperas; escucha el topic y compáralo.
Dos brokers se disputan un dispositivo. Un dispositivo solo puede conectarse a un broker a la vez; elige uno o puentéalos.
Desconexiones cada pocos segundos. Dos clientes usan el mismo client ID y se expulsan mutuamente.

Ejecuta Home Assistant sobre ConnectMQ

Crea un broker Serverless gratuito en app.connectmq.com, sin tarjeta de crédito. Hasta 25 conexiones cubren una vivienda típica, y el explorador de topics en vivo de ConnectMQ te ayuda a depurar los payloads sin salir del navegador. Si te preguntas cómo se compara un broker MQTT gestionado con ejecutar Mosquitto por tu cuenta, la comparativa anterior y la guía de automatización IoT te ayudarán a decidir.

Preguntas frecuentes

¿Home Assistant incluye un broker MQTT?

No. La integración MQTT es un cliente. Puedes instalar el complemento Mosquitto o conectarte a un broker externo como ConnectMQ.

¿Puedo usar YAML y el descubrimiento a la vez?

Sí. Las entidades definidas en YAML y las descubiertas conviven en la misma integración, siempre que sus ID únicos sean distintos.

¿Qué puerto debe usar Home Assistant con un broker en la nube?

Usa el 8883 con TLS. El puerto 1883 envía las credenciales y los datos sin cifrar y solo debe usarse con datos públicos de prueba.

¿Por qué mi interruptor se vuelve a apagar solo?

El dispositivo publica OFF en el topic de estado, o se está reproduciendo un mensaje OFF retenido. Revisa el topic de estado con un suscriptor y elimina los mensajes retenidos obsoletos.

Integración MQTT de Home Assistant: guía completa de configuración