Saltar al contenido principal

Integración domótica ESPHome, gratuita y de código abierto

Integración ESPHome para Gladys Assistant

Controle sus dispositivos ESPHome (ESP32/ESP8266) en local, mediante la API nativa.

Ver en GitHubTodas las integraciones

Esta integración permite controlar sus dispositivos ESPHome (ESP32, ESP8266) desde Gladys Assistant, directamente en su red local, mediante la API nativa de ESPHome. Sin nube, sin broker MQTT y sin necesidad de Home Assistant.

Gladys, la integración y sus nodos ESPHome: los nodos envían sus estados por sí mismos, los comandos salen de Gladys y la búsqueda pasa por el mDNS que captura Gladys

Funcionalidades​

A diferencia de un aparato comercial, un nodo ESPHome expone exactamente lo que usted ha declarado en su archivo YAML. Por eso la integración se adapta a lo que anuncia cada nodo:

Componente ESPHomeLo que obtiene en Gladys
sensorSensor numérico (temperatura, humedad, potencia, batería…)
binary_sensorSensor binario (movimiento, apertura, presencia, fuga, humo…)
text_sensorSensor de texto (solo lectura)
textTexto editable: enviar un mensaje al nodo (pantalla)
switchInterruptor (encendido/apagado)
lightLámpara: encendido/apagado, brillo, color, temperatura de color
coverPersiana o cortina: abrir, cerrar, detener, posición
fanVentilador: encendido/apagado y velocidad
lockCerradura: bloquear / desbloquear
sirenSirena: encendida / apagada
valveVálvula: abierta / cerrada
buttonPulsador
numberAjuste numérico editable (control deslizante)
climateTermostato: consigna (una sola) y temperatura medida
eventNinguna funcionalidad: el disparador de escena «Evento de ESPHome»

Los tipos que no tienen equivalente en Gladys (media_player, camera, select, date…) simplemente se omiten en la búsqueda. Un sensor energy (en kWh o Wh) es un índice acumulado: Gladys calcula a partir de él el consumo y su coste.

Los estados llegan en tiempo real​

ESPHome envía sus cambios de estado por sí mismo: la integración mantiene una conexión abierta con cada nodo, y Gladys recibe el nuevo valor en el instante en que cambia. No hay ningún intervalo de consulta que ajustar. Un dispositivo que usted añade recibe de inmediato los valores que su nodo ya ha comunicado, y una lectura que no cambia no se vuelve a enviar (se actualiza una vez por hora).

Requisitos​

  • Gladys 5.1.0 o posterior.

  • Uno o varios dispositivos con ESPHome 2025.10 o posterior.

  • La API nativa activada en su YAML (lo está por defecto):

    api:
      encryption:
        key: 'su_clave_base64'

  • Gladys y sus nodos ESPHome deben estar en la misma red local.

Configuración​

1. La clave de cifrado​

Abra la pantalla de configuración de la integración y pegue en Clave de cifrado la clave declarada en api: encryption: key: de su YAML.

Si todos sus nodos comparten la misma clave (el caso más habitual cuando se usa un !secret común), es lo único que hay que rellenar.

Si sus nodos no tienen ningún cifrado (api: sin bloque encryption), deje este campo vacío.

2. Los nodos con una clave distinta​

Si algunos nodos tienen su propia clave, rellene Claves por nodo, un nodo por línea:

salon|kBv1s2f3G4h5J6k7L8m9N0p1Q2r3S4t5U6v7W8x9Y0=
cocina|9xQm4Zt6R8s0T2u4V6w8X0y2Z4a6B8c0D2e4F6g8H0=

El nombre del nodo es el declarado en esphome: name:. Estas claves tienen prioridad sobre la clave por defecto.

3. Descubra sus dispositivos​

Vaya a la pantalla Descubrir e inicie una búsqueda. Los nodos ESPHome presentes en su red aparecen allí con todas sus entidades. Añada los que quiera: sin ninguna dirección IP que escribir.

La búsqueda utiliza mDNS (el protocolo con el que ESPHome se anuncia en la red). Es Gladys quien realiza la captura, porque la integración se ejecuta en un contenedor que nunca recibe ese tipo de tráfico.

4. Si no se encuentra un nodo​

Algunas redes bloquean el mDNS (VLAN separadas, Wi-Fi con aislamiento de clientes, router que filtra el multicast). En ese caso, declare el nodo a mano en Nodos añadidos a mano, una dirección por línea:

salon.local
192.168.1.42
192.168.1.43:6054

La integración combina tres fuentes: los dispositivos ya conocidos, la búsqueda mDNS y los nodos añadidos a mano; al conectarse, el nodo da su nombre real, que se convierte en su identificador

El puerto es opcional (6053 por defecto). Una vez conectado, el nodo anuncia él mismo su nombre real: un nodo añadido por su dirección IP aparecerá con su nombre ESPHome, y seguirá funcionando aunque su dirección IP cambie después.

Si ese nodo tiene una clave de cifrado propia, indíquela en Claves por nodo usando la misma dirección que ha escrito aquí, y no su nombre ESPHome:

192.168.1.42|kBv1s2f3G4h5J6k7L8m9N0p1Q2r3S4t5U6v7W8x9Y0=

El motivo es sencillo: su nombre solo se conoce una vez establecida la conexión, y la conexión necesita precisamente la clave. Esto no afecta a los nodos encontrados por la búsqueda ni a los que usan la clave por defecto.

Acciones disponibles​

  • Probar la conexión: vuelve a lanzar una búsqueda completa y le indica cuántos nodos han respondido y cuántas funcionalidades están disponibles.
  • Reconectar los nodos: cierra todas las conexiones y las vuelve a abrir. Útil tras reprogramar un nodo o cambiar una clave.

Escenas​

Disparadores​

  • Evento de ESPHome: una entidad event de un nodo se ha activado: un botón pulsado una o dos veces o mantenido, un timbre, un código de mando recibido. Filtros: el nodo (esphome: name:), la entidad (su name:) y el tipo de evento (uno de sus event_types); deje un filtro vacío para aceptarlo todo. Variables: node, entity, entity_id, event_type.
  • Nodo ESPHome desconectado: un nodo ha permanecido desconectado durante un minuto. Un reinicio o una actualización OTA que terminan en ese minuto no activan nada. Variables: node, address.
  • Nodo ESPHome conectado de nuevo: un nodo notificado como desconectado vuelve a estar conectado. Variables: node, address, offline_minutes.

Una entidad de evento, activada por un botón que distingue los clics simples y dobles:

event:
  - platform: template
    name: 'Button'
    id: button_event
    event_types: [single, double]

binary_sensor:
  - platform: gpio
    pin: GPIO0
    on_multi_click:
      - timing:
          [ON for at most 0.5s, OFF for at most 0.3s, ON for at most 0.5s, OFF for at least 0.2s]
        then:
          - event.trigger: { id: button_event, event_type: double }
      - timing: [ON for at most 0.5s, OFF for at least 0.4s]
        then:
          - event.trigger: { id: button_event, event_type: single }

Acción «Ejecutar una acción de ESPHome»​

Ejecuta una acción declarada en api: actions: en el YAML de un nodo: reproducir una melodía, mostrar un mensaje, lanzar un script.

api:
  actions:
    - action: play_rtttl
      variables:
        song_str: string
      then:
        - rtttl.play:
            rtttl: !lambda 'return song_str;'
  • Nodo: el nombre ESPHome del nodo, o el nombre de su dispositivo en Gladys.
  • Acción: play_rtttl.
  • Argumentos: un objeto JSON con una entrada por variable, por ejemplo {"song_str": "two_short:d=4,o=5,b=100:16e6,16e6"}. Se aceptan variables de escena. Déjelo vacío para una acción sin variables.

Un argumento ausente, desconocido o de tipo incorrecto hace fallar la acción con un mensaje claro, al igual que un nombre de acción que el nodo no declara (el mensaje enumera las que sí declara). Las salidas node y action están disponibles para las acciones siguientes de la escena. Durante los dos segundos posteriores a esta acción, los eventos de ese nodo no inician ninguna escena: una acción que activa un evento no puede entrar en bucle con la escena que la llamó.

Entender los sensores: la importancia de device_class​

Gladys necesita saber qué mide un sensor para mostrarlo correctamente (icono, unidad, gráfico). ESPHome transmite esa información mediante device_class.

Una entidad YAML se convierte en una o varias funcionalidades de Gladys: por su device_class, por la forma de su declaración o como medida genérica

Con un device_class, su sensor llega tipado:

sensor:
  - platform: dht
    temperature:
      name: 'Temperatura salón'
      device_class: temperature # -> sensor de temperatura en Gladys
    humidity:
      name: 'Humedad salón'
      device_class: humidity # -> sensor de humedad en Gladys

Sin device_class, el sensor aparece igualmente, pero en la categoría genérica «Desconocido». Funciona y se guarda su historial, pero no tendrá ni icono ni categoría específica. Si uno de sus sensores aparece así, añada el device_class correspondiente en su YAML y vuelva a lanzar una búsqueda.

Dos familias de sensores escapan a esta regla, porque ESPHome nunca les asigna un device_class: el vocabulario de Home Assistant no tiene palabra para lo que miden. La integración las reconoce por la forma de su declaración:

Declaración ESPHomeCategoría Gladys
unit_of_measurement: "°"Ángulo
ninguna unidad y accuracy_decimals: 0Contador

Es el caso típico de los sensores mmWave (ld2410, ld2450…): sus contadores de objetivos (Moving / Still / Presence Target Count) llegan como Contador, y sus ángulos de objetivo (Target-1 Angle) como Ángulo. Un firmware que declara explícitamente state_class: measurement_angle, total o total_increasing se clasifica prioritariamente según esa declaración.

Entre los device_class reconocidos están: temperature, humidity, pressure, illuminance, battery, signal_strength, carbon_dioxide, pm25, pm10, power, energy, voltage, current, distance, moisture, speed, duration y, para los sensores binarios: motion, occupancy, door, window, smoke, gas, moisture, vibration, tamper, battery, lock.

Solución de problemas​

La búsqueda no encuentra ningún nodo Compruebe que sus nodos estén encendidos y conectados al Wi-Fi. Si su red bloquea el mDNS, añádalos a mano (ver más arriba).

Se encuentra un nodo, pero no aparece en la lista Casi siempre se trata de una clave de cifrado que no coincide. El nodo es visible en la red, pero rechaza la conexión. Compruebe la clave en su YAML y utilice Claves por nodo si difiere de la clave por defecto.

Un nodo desaparece y vuelve a aparecer Es normal tras un reinicio del nodo (actualización OTA, corte de corriente). La integración se reconecta automáticamente, con un retardo creciente para no saturar la red.

Un dispositivo aparece como «inaccesible» La conexión con ese nodo se ha perdido: nodo apagado, fuera del alcance del Wi-Fi o reiniciándose. La integración lo reintenta automáticamente. Tenga en cuenta también que un nodo ESPHome solo acepta un número limitado de clientes API simultáneos: si el mismo nodo ya está conectado a un Home Assistant o a una consola de registros de ESPHome abierta, puede rechazar una conexión más. Cierre los clientes innecesarios y utilice la acción Reconectar los nodos.

Un termostato solo muestra la temperatura medida, sin consigna Es un termostato de dos consignas (heat_cool, una baja y una alta). Gladys gestiona una sola consigna por termostato: en lugar de mostrar un control deslizante que se quedaría en 0 y no controlaría nada, la integración solo publica la temperatura medida.

La acción «Ejecutar una acción de ESPHome» falla El nodo debe estar conectado, el nombre de la acción debe ser el que figura tras action: en el YAML, y los argumentos deben corresponder a sus variables: (nombres y tipos). El mensaje de error de la escena indica cuál es incorrecto.

Una entidad no aparece en absoluto Su tipo no tiene equivalente en Gladys (ver la tabla de funcionalidades), o está marcada como internal: true en su YAML; en ese caso, ESPHome no la expone en su API.

Parámetros de configuración​

Estos son los parámetros que ESPHome te pide en su pantalla de configuración en Gladys.

ParámetroTipoObligatorioDescripción
Primeros pasossectionNoEsta integración se comunica con sus nodos ESPHome en su red local, a través de su API nativa (puerto 6053). Pegue su clave de cifrado a continuación y luego vaya a la pantalla Descubrir e inicie una búsqueda: los nodos encontrados en su red aparecen allí con todas sus entidades, listos para añadirse. Sin ninguna dirección IP que escribir.
Clave de cifradosecretNoLa clave base64 declarada en api: encryption: key: de su YAML de ESPHome. Se usa para todos los nodos que no tengan una clave específica más abajo. Déjela vacía solo si sus nodos no tienen cifrado.
Nodos con una clave distintasectionNoRellene los dos campos siguientes solo si algunos nodos no comparten la clave anterior, o si la búsqueda en la red no encuentra un nodo (otra VLAN, mDNS filtrado por su router).
Claves por nodosecretNoUn nodo por línea, con el formato nodo|clave. El nombre del nodo es el de su YAML de ESPHome (esphome: name:), o su dirección. Estas claves tienen prioridad sobre la clave anterior.
Nodos añadidos a manostringNoUna dirección por línea (salon.local, 192.168.1.42 o 192.168.1.42:6053), para los nodos que la búsqueda en la red no encuentra. Los nodos encontrados por la búsqueda no necesitan nada aquí.
Duración de la búsqueda (s)numberNoTiempo durante el cual la búsqueda mDNS escucha los nodos ESPHome en la red.
Tiempo de espera de conexión (s)numberNoTiempo de espera de la respuesta de un nodo antes de abandonarlo.

Cómo instalar ESPHome en Gladys​

  1. En Gladys, abre Integraciones: ESPHome aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
  2. Haz clic en Instalar. Gladys descarga la imagen Docker (ghcr.io/william-de71/gladys-esphome:1.2.1), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración).
  3. Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
  4. También puedes instalarla directamente desde la URL de su repositorio: https://github.com/William-De71/gladys-esphome.

ESPHome requiere Gladys >=5.1.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.

¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.

Sobre las integraciones externas​

ESPHome es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene William-De71, no el equipo principal de Gladys.

Suscríbete a la newsletter de Gladys Assistant

Unos pocos correos al mes sobre nuevas versiones y novedades del proyecto. Enviados por Pierre-Gilles Leymarie, fundador del proyecto. Puedes darte de baja cuando quieras 🙂
Última actualización en