Saltar al contenido

MQTT II: a fondo

Descubrimiento MQTT por dispositivo, mensajes retenidos, nacimiento y última voluntad, disponibilidad, QoS, YAML, seguridad y depuración en Home Assistant.

  • Publicado el
  • mqtt
  • integraciones
  • avanzado
Sello MQTT II junto al titular «MQTT II: a fondo»

En MQTT I: lo esencial vimos qué es un broker y cómo poner MQTT en marcha. Aquí entramos en lo que pasa por dentro: cómo aparecen solos los dispositivos, por qué a veces quedan entidades fantasma, cómo sabe Home Assistant que algo está desconectado y cómo depurar cuando no llega nada.

Fuente: documentación oficial de la integración MQTT.

1. Descubrimiento

El descubrimiento MQTT es lo que hace que un dispositivo de Zigbee2MQTT o Tasmota aparezca solo. El aparato publica una ficha de configuración en un tema especial y Home Assistant la convierte en un dispositivo con sus entidades.

El tema homeassistant/device/garaje_esp32/config dividido en prefijo, tipo, id del objeto y config, y una carga JSON con dev, o, state_topic y cmps que se convierte en el dispositivo Sensor del garaje
Un mensaje retenido, un dispositivo completo.

El tema siempre sigue este formato:

<prefijo>/<tipo>/[<node_id>/]<object_id>/config

Descubrimiento por dispositivo

Es el formato recomendado hoy: un mensaje describe el dispositivo y todas sus entidades. Por ejemplo, un ESP32 en el garaje que publica temperatura y humedad en JSON en casa/garaje/clima. Su ficha, en el tema homeassistant/device/garaje_esp32/config:

{
  "dev": { "ids": "garaje_esp32", "name": "Sensor del garaje", "mf": "Casero", "mdl": "ESP32" },
  "o": { "name": "mi-firmware", "sw": "1.0" },
  "state_topic": "casa/garaje/clima",
  "availability_topic": "casa/garaje/estado",
  "cmps": {
    "temp": {
      "p": "sensor",
      "unique_id": "garaje_temperatura",
      "name": "Temperatura",
      "device_class": "temperature",
      "unit_of_measurement": "°C",
      "value_template": "{{ value_json.temperatura }}"
    },
    "hum": {
      "p": "sensor",
      "unique_id": "garaje_humedad",
      "name": "Humedad",
      "device_class": "humidity",
      "unit_of_measurement": "%",
      "value_template": "{{ value_json.humedad }}"
    }
  }
}

Puedes probarlo sin programar nada: en Ajustes → Dispositivos y servicios → MQTT → Configurar → Publicar un paquete, pega el tema y el JSON, marca Retener y publica. El dispositivo aparece al momento.

Borrar lo descubierto (y las entidades fantasma)

Para eliminar un dispositivo descubierto, publica un mensaje vacío y retenido en su tema de configuración. Si solo quieres quitar una entidad de un dispositivo, publica la ficha con ese componente reducido a su p y, después, otra ficha sin él.

Las entidades fantasma son casi siempre fichas retenidas de aparatos que ya no existen: el broker se las sigue entregando a Home Assistant en cada arranque. Escucha homeassistant/# para encontrarlas y bórralas con el mensaje vacío.

¿Tienes un aparato con descubrimiento por entidad? La documentación oficial explica cómo migrar al formato por dispositivo sin perder el historial, con el mensaje {"migrate_discovery": true }.

2. Retenidos, nacimiento y última voluntad

Tres columnas: retenido, el broker guarda el último mensaje del tema; nacimiento, Home Assistant publica online en homeassistant/status al arrancar; última voluntad, el aparato deja dicho al broker que publique offline si se cae
Así se entera Home Assistant de lo que pasó mientras no miraba.

Disponibilidad

Con la disponibilidad, una entidad pasa a No disponible cuando su aparato se cae, en vez de quedarse con el último valor como si nada:

3. Calidad de servicio (QoS)

Tres niveles de QoS: 0, como mucho una vez, para lecturas frecuentes; 1, al menos una vez, la opción habitual para órdenes y estados; 2, exactamente una vez, para cuando un duplicado molesta
Más QoS, más garantías y más tráfico.

En casa, QoS 0 basta para sensores que publican cada pocos segundos y QoS 1 es la opción sensata para órdenes. QoS 2 casi nunca hace falta en una red local.

4. Entidades a mano, en YAML

Si un aparato publica por MQTT pero no tiene descubrimiento, defines tú la entidad en configuration.yaml. El formato recomendado es una lista con un elemento por entidad:

mqtt:
  - sensor:
      name: "Temperatura del trastero"
      unique_id: trastero_temperatura
      state_topic: "casa/trastero/clima"
      value_template: "{{ value_json.temperatura }}"
      unit_of_measurement: "°C"
      device_class: temperature
      state_class: measurement
      availability_topic: "casa/trastero/estado"
  - switch:
      name: "Ventilador del trastero"
      unique_id: trastero_ventilador
      state_topic: "casa/trastero/ventilador"
      command_topic: "casa/trastero/ventilador/set"
      payload_on: "ON"
      payload_off: "OFF"

5. Publicar desde una automatización

La acción mqtt.publish envía cualquier mensaje. Por ejemplo, avisar a una pantalla casera de que alguien ha llamado:

actions:
  - action: mqtt.publish
    data:
      topic: "casa/pantalla/aviso"
      payload: "Han llamado a la puerta"
      qos: 1
      retain: false

Para lo contrario, reaccionar a un mensaje, usa el disparador MQTT.

6. Seguridad

7. Depurar

  1. Escucha # en Configurar → Escuchar un tema. Si el mensaje no aparece, el problema está en el aparato o en el broker, no en Home Assistant.
  2. Comprueba el JSON: si el mensaje llega pero la entidad no cambia, revisa el value_template. Pruébalo en Herramientas para desarrolladores → Plantilla.
  3. Activa el registro detallado un rato y mira Ajustes → Sistema → Registros:
logger:
  default: warning
  logs:
    homeassistant.components.mqtt: debug
  1. mqtt.dump guarda en un fichero todos los mensajes de un tema durante unos segundos: útil para enviarlo en un informe de error.

Consulta siempre la fuente oficial: integración MQTT en home-assistant.io. La ficha resumida está en el Repositorio: MQTT.

Infografías: NODARA, a partir de la documentación oficial de Home Assistant.

Volver a Artículos