ESPHome MQTT: usa MQTT en lugar de la API nativa

Q: ¿ESPHome MQTT funciona sin Home Assistant?

Sí. Con discovery: false, el dispositivo simplemente publica estados y escucha comandos, y cualquier cliente MQTT puede usarlos.

El soporte MQTT de ESPHome permite que un ESP32 o ESP8266 configurado en YAML publique los estados de sus sensores y acepte comandos a través de cualquier broker estándar en lugar de la API nativa de Home Assistant. En este tutorial configurarás el componente mqtt:, entenderás los topics que genera ESPHome, añadirás TLS y credenciales para producción y reaccionarás a los mensajes entrantes directamente en el dispositivo.

API nativa o MQTT: cuándo cambiar

La API nativa de ESPHome es un enlace punto a punto, eficiente y cifrado, entre un dispositivo y Home Assistant. Es excelente cuando Home Assistant es lo único que habla con el dispositivo. Se queda corta en cuanto otro software necesita los mismos datos: un flujo de Node-RED, un registrador en Python, una canalización de Grafana a través de Telegraf o una segunda ubicación que no puede llegar a tu LAN.

MQTT lo resuelve poniendo un broker en medio. El dispositivo publica una vez y cualquier número de suscriptores recibe la lectura. No cambia nada en el dispositivo cuando añades un nuevo consumidor, y los dispositivos detrás de NAT pueden seguir llegando a un broker en internet. Si el modelo publicación/suscripción es nuevo para ti, la introducción a qué hace un broker MQTT es un buen punto de partida.

Aspecto	API nativa	ESPHome MQTT
Consumidores	Solo Home Assistant	Cualquier cliente MQTT
Ruta de red	HA debe llegar al dispositivo	El dispositivo llega al broker (funciona a través de NAT)
Discovery	Automático en HA	Mensajes de MQTT discovery (opcional)
Cifrado	Clave del protocolo Noise	TLS en la conexión con el broker
Infraestructura adicional	Ninguna	Un broker

Puedes usar ambos a la vez, pero si ya nada usa la API nativa, elimina el bloque api: para que el dispositivo no gaste memoria en ella.

Una configuración mínima de ESPHome MQTT

El siguiente ejemplo es una configuración completa para un ESP32 con un sensor DHT22 y un relé. Se conecta al servidor MQTT público gratuito, pensado para pruebas y prototipos, para que veas mensajes en pocos minutos. Sustituye a7k2q9 por tu propia cadena aleatoria para que tus topics no choquen con los de nadie.

esphome:
  name: greenhouse-node
  friendly_name: Greenhouse Node

esp32:
  board: esp32dev
  framework:
    type: esp-idf

logger:
  level: INFO

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

ota:
  - platform: esphome
    password: !secret ota_password

mqtt:
  broker: broker.connectmq.com
  port: 1883
  client_id: esphome-greenhouse-a7k2q9
  topic_prefix: connectmq/demo/a7k2q9/greenhouse
  discovery: false
  log_topic: null
  birth_message:
    topic: connectmq/demo/a7k2q9/greenhouse/status
    payload: online
    retain: true
  will_message:
    topic: connectmq/demo/a7k2q9/greenhouse/status
    payload: offline
    retain: true

sensor:
  - platform: dht
    pin: GPIO4
    model: DHT22
    update_interval: 30s
    temperature:
      name: "Air Temperature"
      id: air_temp
    humidity:
      name: "Air Humidity"
      id: air_hum

switch:
  - platform: gpio
    pin: GPIO26
    name: "Vent Fan"
    id: vent_fan

Flashéalo con esphome run greenhouse-node.yaml. Cuando el dispositivo esté en línea, suscríbete desde tu ordenador:

mosquitto_sub -h broker.connectmq.com -p 1883 -i sub-a7k2q9 \
  -t 'connectmq/demo/a7k2q9/greenhouse/#' -v

Deberías ver el estado online retenido y un mensaje de estado cada 30 segundos por cada sensor.

Ajustes que conviene entender

client_id: no puede estar vacío y debe ser único en el broker. Si dos dispositivos comparten un ID, el broker desconecta la sesión más antigua cada vez que se conecta la más nueva, y ambos dispositivos entran en un bucle de conexión y desconexión.
topic_prefix: por defecto es el nombre del nodo. Definirlo explícitamente te da una jerarquía predecible y mantiene ordenada el área pública de pruebas.
discovery: ponlo en false salvo que Home Assistant consuma este broker. Discovery publica mensajes de configuración retenidos bajo homeassistant/, que en un broker público compartido serían visibles para todo el mundo.
log_topic: ESPHome replica sus logs en <prefix>/debug por defecto. Ponerlo en null evita que un dispositivo muy hablador agote los límites de tasa.

Los topics que publica ESPHome

ESPHome construye los topics a partir del prefijo, el tipo de componente y un object ID derivado del nombre de la entidad (en minúsculas, con los espacios convertidos en guiones bajos).

Entidad	Topic de estado	Topic de comandos
Sensor Air Temperature	`<prefix>/sensor/air_temperature/state`	ninguno
Sensor Air Humidity	`<prefix>/sensor/air_humidity/state`	ninguno
Interruptor Vent Fan	`<prefix>/switch/vent_fan/state`	`<prefix>/switch/vent_fan/command`
Disponibilidad	`<prefix>/status`	ninguno

Los estados son cadenas simples: 23.4 para un sensor, ON u OFF para un interruptor. Para encender el ventilador desde la línea de comandos:

mosquitto_pub -h broker.connectmq.com -p 1883 -i pub-a7k2q9 \
  -t 'connectmq/demo/a7k2q9/greenhouse/switch/vent_fan/command' -m 'ON'

El dispositivo ejecuta el comando y después publica el nuevo estado en el topic state correspondiente, de modo que los dashboards siempre reflejan lo que realmente ocurrió y no lo que se pidió.

Si necesitas otra estructura de topics, cada componente acepta sobrescribir state_topic y command_topic. Es útil cuando ya tienes una estructura como la descrita en la guía de estructura de topics MQTT para el hogar inteligente.

sensor:
  - platform: dht
    pin: GPIO4
    model: DHT22
    temperature:
      name: "Air Temperature"
      state_topic: connectmq/demo/a7k2q9/site1/greenhouse/temperature

Reaccionar a mensajes MQTT en el dispositivo

El componente MQTT no es solo una salida. Puedes disparar automatizaciones desde cualquier topic con on_message u on_json_message, y publicar payloads arbitrarios con las acciones mqtt.publish y mqtt.publish_json.

mqtt:
  # ... ajustes de conexión de arriba ...
  on_message:
    - topic: connectmq/demo/a7k2q9/greenhouse/mode
      payload: "night"
      then:
        - switch.turn_off: vent_fan
  on_json_message:
    topic: connectmq/demo/a7k2q9/greenhouse/setpoint
    then:
      - lambda: |-
          if (x.containsKey("max_temp")) {
            id(max_temp) = x["max_temp"];
          }

globals:
  - id: max_temp
    type: float
    restore_value: true
    initial_value: '28.0'

interval:
  - interval: 60s
    then:
      - if:
          condition:
            lambda: 'return id(air_temp).state > id(max_temp);'
          then:
            - switch.turn_on: vent_fan
            - mqtt.publish_json:
                topic: connectmq/demo/a7k2q9/greenhouse/event
                payload: |-
                  root["event"] = "overheat";
                  root["temp"] = id(air_temp).state;

Así se mantiene una regla de seguridad sencilla en el propio dispositivo, de modo que el ventilador sigue funcionando aunque caiga la red, mientras que la consigna se puede cambiar a distancia publicando {"max_temp": 30}.

Configuración de producción: TLS y credenciales

El área pública de pruebas sirve para experimentar, pero cualquiera puede leer todos sus topics. Para una instalación real, crea un broker privado y usa las credenciales generadas. En ESP32 con el framework ESP-IDF, ESPHome admite TLS si le proporcionas el certificado de la CA que firmó el certificado del broker. ConnectMQ usa un certificado de Let's Encrypt, así que la CA es ISRG Root X1.

mqtt:
  broker: broker.connectmq.com
  port: 8883
  client_id: YOUR_CLIENT_ID
  username: YOUR_USERNAME
  password: !secret mqtt_password
  topic_prefix: site1/greenhouse
  discovery: false
  log_topic: null
  certificate_authority: |
    -----BEGIN CERTIFICATE-----
    (pega aquí el certificado ISRG Root X1)
    -----END CERTIFICATE-----
  birth_message:
    topic: site1/greenhouse/status
    payload: online
    retain: true
  will_message:
    topic: site1/greenhouse/status
    payload: offline
    retain: true

Guarda la contraseña en secrets.yaml y no en el archivo principal, para que no acabe en el control de versiones. Como en ConnectMQ el client ID está vinculado a las credenciales emitidas, cópialo exactamente desde el portal.

Las placas ESP8266 tienen mucha menos RAM y la validación completa de certificados les queda muy justa. Si necesitas TLS en un ESP8266, consulta la documentación actual de ESPHome para ver las opciones soportadas, o pasa el proyecto a un ESP32, que maneja TLS con holgura.

Alimentar Home Assistant y otras herramientas

Con el dispositivo en un broker, Home Assistant pasa a ser un consumidor más entre varios. Apunta su integración MQTT al mismo broker (la guía de broker MQTT externo para Home Assistant lo explica paso a paso) y pon discovery: true en el dispositivo para que las entidades aparezcan automáticamente. Los detalles de discovery, incluidos los payloads de configuración retenidos, se explican en Home Assistant MQTT discovery.

Al mismo tiempo, un flujo de Node-RED puede suscribirse a site1/+/sensor/+/state para registrar todos los sensores, y un script de Python puede archivar las lecturas en una base de datos. Ninguno necesita conocer la dirección IP del dispositivo.

Resolución de problemas de ESPHome MQTT

El dispositivo se conecta y se desconecta cada pocos segundos. Casi siempre es un client ID duplicado. Comprueba que ningún otro dispositivo ni un script de pruebas olvidado usa el mismo ID.
No aparece ningún mensaje. Confirma que la suscripción coincide exactamente con el prefijo, incluidas mayúsculas y minúsculas. Suscríbete a connectmq/demo/a7k2q9/# para ver todo lo que hay bajo tu rama.
Falla el handshake TLS. Verifica que el dispositivo tiene la hora correcta (TLS la necesita; ESPHome la sincroniza por SNTP), que pegaste el bloque PEM completo y que usas el puerto 8883.
Se descartan mensajes en el broker público. El área de pruebas permite 10 mensajes por segundo por cliente y 64 KB por mensaje. Los logs en el topic de depuración o los intervalos de actualización muy cortos pueden superarlo.
Se ignoran los comandos. Publica en el topic command, no en el state, y usa ON u OFF en mayúsculas para los interruptores.

Ver el árbol de topics en un explorador en vivo hace evidentes la mayoría de estos problemas en segundos, por eso merece la pena abrir el explorador de topics del portal o la aplicación ConnectMQ Desktop mientras flasheas.

Escalar más allá de unos pocos nodos

Una Raspberry Pi con un broker funciona hasta que deja de hacerlo: fallos de la tarjeta SD, cortes de luz y redirección de puertos para el acceso remoto pasan a ser problema tuyo. Pasar a un broker MQTT gestionado elimina ese mantenimiento y da a cada nodo ESPHome un endpoint TLS estable que funciona desde cualquier red. La visión general de cómo combinar dispositivos, brokers y lógica de automatización está en la guía de automatización IoT.

Conecta tus dispositivos ESPHome a ConnectMQ

ConnectMQ te da un broker privado con TLS en el puerto 8883, usuario, contraseña y client ID generados, y un explorador de topics en vivo para ver cómo reportan tus nodos ESPHome. Crea un broker Serverless gratuito en app.connectmq.com, sin tarjeta de crédito, pega las credenciales en secrets.yaml y flashea.

Preguntas frecuentes

¿Puedo usar ESPHome MQTT y la API nativa a la vez?

Sí. Ambos componentes pueden estar activos juntos, lo que resulta práctico durante una migración. Elimina api: cuando ya nada dependa de ella para ahorrar memoria.

¿ESPHome MQTT funciona sin Home Assistant?

Sí. Con discovery: false, el dispositivo simplemente publica estados y escucha comandos, y cualquier cliente MQTT puede usarlos.

¿Por qué mi dispositivo ESPHome se reconecta continuamente al broker?

La causa más habitual es que dos clientes usan el mismo client ID. Da a cada dispositivo un client_id único, o usa exactamente el ID emitido con las credenciales de tu broker.

¿Qué QoS usa ESPHome?

Los mensajes de estado usan QoS 0 por defecto. Puedes definir qos por componente o en birth_message y will_message si necesitas garantías de entrega, como se explica en la guía de niveles de QoS en MQTT.

ESPHome MQTT: usar MQTT en lugar de la API nativa