Crear un instalador web para ESPHome

En esta entrada te enseño a crear un instalador web para ESPHome, la forma más profesional de compartir el firmware de tus dispositivos.

¿Qué es un instalador y para qué sirve?

Aunque no seas consciente de ello, estoy seguro de que alguna vez has utilizado un instalador web (como el de ESPHome o WLED). Básicamente, un instalador es una simple página web que te permite flashear placas ESP sólo con conectarlas y pulsar un botón.

No hace falta decir mucho más para que te imagines que crear un instalador web para ESPHome me parece la mejor forma de compartir tu código, especialmente si te gusta crear y compartir dispositivos con la comunidad (o te dedicas a ello).

Esta interfaz tan sencilla facilita muchísimo el trabajo de instalación, incluso para los usuarios que acaban de empezar, ya que no requiere tener ningún conocimiento de código.

¿Cómo puedo crear mi propio instalador?

Para poder crear un instalador web para ESPHome vamos a utilizar ESP Web Tools. Esta es una herramienta online que permite flashear placas ESP8266 y ESP32 directamente desde el navegador, sin necesidad de instalar programas adicionales. Funciona gracias a la API Web Serial que incluyen navegadores modernos (Chrome, Edge, etc.), y permite comunicarse directamente con el puerto serie de tu ordenador.

El proceso está detallado en la documentación oficial, pero a continuación te voy a indicar cuáles son los puntos clave para que funcione correctamente.

⚠️ Puedes añadir el instalador en cualquier parte de tu página web, pero también puedes pedirle a alguna IA que te cree una interfaz web dedicada (te recomiendo Claude). En todo caso debe estar alojado en una página accesible mediante HTTPS.

Carga el script de ESP Web Tools

Lo primero que tienes que hacer es incluir el script de ESP Web Tools en la página web donde quieras incluir el instalador.

Para ello sólo tienes que copiar el siguiente fragmento de código:

<script type="module" src="https://unpkg.com/esp-web-tools@10/dist/web/install-button.js?module"></script>

Incluye el botón de instalación

Tanto si quieres crear un instalador web para ESPHome en una página dedicada, como si lo vas a incluir entre tu contenido, siempre habrá un botón de instalación que inicie el proceso. Cuando el usuario pulse este botón, se abrirá el pop-up para que seleccione la placa que va a flashear.

Para incluir el botón correspondiente, copia el siguiente código donde quieras que aparezca:

<esp-web-install-button manifest="https://firmware.esphome.io/esp-web-tools/manifest.json"></esp-web-install-button>

Prepara el manifest.json

Si observas el código anterior, el botón llama a un fichero ‘manifest.json’ que contiene la información del firmware a flashear. Por tanto, tienes que crear un archivo con la siguiente estructura:

{
  "name": "Nombre del proyecto",
  "version": "1.0.0",
  "home_assistant_domain": "esphome",
  "funding_url": "https://esphome.io/guides/supporters.html",
  "new_install_prompt_erase": false,
  "builds": [
    {
      "chipFamily": "ESP32",
      "parts": [
        { "path": "merged-firmware.bin", "offset": 0 },
      ]
    },
    {
      "chipFamily": "ESP8266",
      "parts": [
        { "path": "esp8266.bin", "offset": 0 }
      ]
    }
  ]
}

Observa que tienes que indicar el nombre de tu proyecto y la versión del firmware (y, si quieres, una URL de donaciones). Además, en la parte de «builds» debes incluir el nombre del fichero ‘.bin’ correspondiente (para cada tipo de placa) al firmware que quieres instalar.

⚠️ Ojo! Cuando termines de editar el fichero y lo guardes (por ejemplo, 'https://www.aguacatec.es/mi_primer_manifest.json'), recuerda actualizar la URL HTTPS accesible de este fichero en el código del botón de instalación.

Prepara tus ficheros .bin

Como has visto en el paso anterior, tienes que crear el fichero ‘.bin’ con el firmware para la instalación. Si tienes ESPHome instalado como complemento de Home Assistant, simplemente sigue el proceso habitual de creación de un dispositivo. Pruébalo con tu placa y comprueba que funciona.

Hecho esto, asegúrate de añadir estas líneas en tu código, que sirven para que el usuario pueda configurar la red WiFi desde el instalador si es necesario:

improv_serial:

esp32_improv:
  authorizer: none 

Cuando tengas el código listo, pulsa en «Install», elige la opción «Manual download» y después la versión «Factory format». Esto te devolverá el fichero ‘.bin’ listo para incluirlo en tu instalador.

⚠️ Ojo! De nuevo, una vez generado tu fichero (por ejemplo, 'mi_primer_firmware.bin'), recuerda actualizar el nombre del fichero en el archivo "manifest" correspondiente, y guardar ambos en el mismo directorio.

Hecho esto, ya tendrías todo lo necesario para crear un instalador web para ESPHome.

Agradecimientos

La idea de escribir esta entrada surgió viendo este video de nuestro amigo Juan de Ardubrico, echa un ojo a su canal! 😄

♥️ ¿Eres YouTuber y quieres aparecer en nuestras entradas? Únete a nuestros canales amigos!