Configurar MQTT en Home Assistant: broker, integración y discovery

MQTT es la forma en que Home Assistant habla con una enorme variedad de dispositivos: Zigbee2MQTT, Tasmota, ESPHome (opcionalmente), Shelly, Frigate, OpenMQTTGateway e innumerables sensores DIY. Configurarlo requiere tres piezas — un broker, la integración MQTT de Home Assistant e, idealmente, el MQTT discovery para que los dispositivos aparezcan automáticamente. Este tutorial cubre las tres y muestra cómo probar la configuración con un cliente MQTT.

Paso 1: elige un broker — complemento Mosquitto o externo

Home Assistant no incluye un broker MQTT propio; la integración es un cliente. Tienes dos opciones principales:

Opción A: el complemento Mosquitto broker

1. Ve a Ajustes → Complementos → Tienda de complementos, busca Mosquitto broker e instálalo.
2. Inícialo y activa Iniciar en el arranque y Watchdog.
3. Crea un usuario de Home Assistant dedicado para tus dispositivos (Ajustes → Personas → Usuarios, p. ej. mqtt-user). El complemento autentica contra los usuarios de Home Assistant, así que los dispositivos usan esas credenciales. No reutilices tu cuenta de administrador.
4. Home Assistant muestra ahora una integración MQTT descubierta en Ajustes → Dispositivos y servicios. Haz clic en Configurar y confirma.

Los dispositivos de tu red se conectan a tu host de Home Assistant en el puerto 1883 (y en el 8883 si configuras TLS en las opciones del complemento).

Opción B: un broker externo

En Home Assistant Container o Core no hay tienda de complementos, así que ejecuta Mosquitto a su lado — lo más fácil es Mosquitto en Docker, o una instalación por paquete como se describe en cómo instalar Mosquitto. Recuerda que Mosquitto 2.x necesita un listener explícito y autenticación antes de que otros hosts puedan conectarse; el generador de mosquitto.conf produce un archivo que funciona, y cómo proteger Mosquitto cubre usuarios y ACL.

Paso 2: configura la integración MQTT

Para un broker externo, añade la integración manualmente: Ajustes → Dispositivos y servicios → Añadir integración → MQTT. Introduce:

• Broker — nombre de host o IP (en una red Docker compartida, el nombre del contenedor, como mosquitto)
• Puerto — 1883, u 8883 para TLS (consulta los puertos MQTT)
• Usuario / Contraseña — un usuario del broker creado para Home Assistant

Las opciones avanzadas (actívalas con el Modo avanzado de tu perfil de usuario y luego Configurar → Volver a configurar MQTT) te permiten definir certificados TLS, el client ID, la versión del protocolo (3.1, 3.1.1 o 5), el prefijo de discovery y los mensajes de nacimiento (birth) y de última voluntad (will). Los datos de conexión al broker se configuran en la interfaz; ya no pueden definirse en configuration.yaml.

Paso 3: MQTT discovery

Con discovery, un dispositivo se anuncia publicando una configuración JSON en un topic conocido, y Home Assistant crea la entidad automáticamente — sin YAML. El formato del topic es:

<discovery_prefix>/<component>/[<node_id>/]<object_id>/config

• discovery_prefix — homeassistant por defecto
• component — el tipo de entidad: sensor, binary_sensor, switch, light, cover, climate, etc.
• node_id — agrupación opcional, normalmente el ID del dispositivo
• object_id — un ID para esta entidad (letras, dígitos, _ y -)

Aquí tienes un sensor de temperatura. Publícalo en homeassistant/sensor/garage_temp/config con el flag retain, para que Home Assistant lo vuelva a encontrar tras un reinicio:

{
  "name": "Garage temperature",
  "unique_id": "garage_env_temp",
  "state_topic": "garage/env/state",
  "value_template": "{{ value_json.temperature }}",
  "unit_of_measurement": "°C",
  "device_class": "temperature",
  "state_class": "measurement",
  "device": {
    "identifiers": ["garage_env_01"],
    "name": "Garage environment sensor",
    "manufacturer": "DIY",
    "model": "ESP32 + BME280"
  }
}

unique_id hace que la entidad sea editable desde la interfaz, y el bloque device agrupa las entidades bajo un mismo dispositivo. Después, el dispositivo publica sus lecturas en el topic de estado:

{ "temperature": 21.4, "humidity": 48 }

Los mensajes retenidos son esenciales aquí — lee mensajes retenidos de MQTT si el concepto es nuevo para ti. Los interruptores y las luces usan además un command_topic en el que Home Assistant publica cuando cambias la entidad.

Paso 4: pruébalo con un cliente MQTT

Puedes simular el dispositivo entero desde una terminal con los clientes de Mosquitto (referencia completa de opciones en la chuleta de mosquitto_pub/sub):

BROKER=homeassistant.local
AUTH="-u mqtt-user -P your-password"

mosquitto_pub -h $BROKER $AUTH -r -t 'homeassistant/sensor/garage_temp/config' -m '{
  "name": "Garage temperature",
  "unique_id": "garage_env_temp",
  "state_topic": "garage/env/state",
  "value_template": "{{ value_json.temperature }}",
  "unit_of_measurement": "°C",
  "device_class": "temperature",
  "device": { "identifiers": ["garage_env_01"], "name": "Garage environment sensor" }
}'

mosquitto_pub -h $BROKER $AUTH -t 'garage/env/state' -m '{"temperature": 21.4, "humidity": 48}'

La entidad aparece en Ajustes → Dispositivos y servicios → MQTT. Para ver todo lo que intercambian Home Assistant y tus dispositivos, suscríbete al prefijo de discovery:

mosquitto_sub -h homeassistant.local -u mqtt-user -P your-password -t 'homeassistant/#' -v

La página de la integración MQTT en Home Assistant también tiene herramientas integradas para escuchar un topic y publicar un paquete. Y para practicar el formato de discovery sin tocar el broker de tu casa, publica el JSON de arriba en un topic de prueba de un broker público desde el navegador:

Pruébalo en el cliente MQTT online

Problemas habituales

• La integración no puede conectarse — credenciales incorrectas, o el broker solo escucha en localhost. Revisa el log del broker y la guía de errores de conexión MQTT.
• La entidad desaparece tras un reinicio — la configuración no se publicó como retenida, o el dispositivo no vuelve a publicarla cuando homeassistant/status = online.
• La entidad muestra “desconocido” — el value_template no coincide con el payload, o todavía no se ha publicado nada en el topic de estado.
• Eliminar una entidad — publica un mensaje retenido vacío en su topic de configuración (-r -n).

Preguntas frecuentes