Provisioning Wi-Fi en ESP32: portal cautivo, BLE, Improv

Provisioning Wi-Fi del ESP32 comparado: contraseña en el código, portal cautivo, BLE y SoftAP de Espressif, Improv y ESP-Touch, por seguridad y facilidad.

Publicado
Tiempo de lectura
10 min
Categoría
Comparativas
Tres tarjetas con las etiquetas Portal, BLE e Improv apuntan con flechas discontinuas a una placa ESP32, mientras un chico rubio de pelo rizado y sudadera roja lo piensa.

En resumen

Para una placa que un desconocido configura desde el teléfono, el portal cautivo no necesita app pero envía la contraseña sin cifrar. La Security 1 o 2 de Espressif la cifra, e Improv sirve si la placa está en USB.

El provisioning Wi-Fi del ESP32 es la forma en que una placa aprende el nombre y la contraseña de tu red sin que estén compilados en su firmware. Los métodos habituales son las credenciales en el código, el portal cautivo, el provisioning BLE o SoftAP de Espressif, Improv y ESP-Touch. Para una placa que alguien configura desde el teléfono, yo elegiría el portal cautivo, salvo que la contraseña deba ir cifrada.

En este artículo los comparo por esfuerzo de configuración, seguridad, memoria y recuperación. La parte del portal sale del código de gizmo-common, que corre en cada dispositivo de OpenGizmo, y el resto de la documentación de Espressif, Improv y WiFiManager enlazada más abajo. No probé BLE, Improv ni ESP-Touch en hardware para este artículo, así que esas secciones describen documentos, no pruebas.

¿Qué es el provisioning Wi-Fi y por qué no poner la contraseña en el código?

Provisioning es hacer llegar las credenciales a una placa que no tiene ninguna. Ponerlas en el código es la versión sin esfuerzo: escribes WiFi.begin("name", "password") en el código fuente y haces el flasheo. Sirve para una placa que solo usarás tú, en una sola red, y deja de funcionar en cuanto cambia el router. Además deja tu contraseña en el archivo fuente y en el binario del firmware, así que no puedes publicar ni compartir ninguno de los dos tal cual.

Ese segundo punto es la razón por la que todo proyecto compartido necesita una respuesta mejor. El firmware precompilado, como las imágenes que instala el flasheador desde el navegador, tiene que ser idéntico para todos, así que las credenciales deben llegar después del flasheo.

Tabla de cinco métodos de provisioning con el canal que usa cada uno y lo que necesita el usuario, desde el flasheo por USB hasta una app del teléfono

¿Qué opciones hay para el provisioning Wi-Fi del ESP32?

MétodoCómo llegan las credencialesQué necesita el usuarioProtección en tránsito
En el códigoCompiladas en el firmwareCódigo fuente, toolchainNo se envían; quedan en el binario
Portal cautivoFormulario web servido por la placa desde su propio hotspotCualquier teléfono o laptop con navegadorNinguna si el hotspot es abierto; WPA2 si le pones contraseña al hotspot
Provisioning unificado de EspressifBLE (GATT) o SoftAP con un servidor HTTPLa app de ejemplo de Espressif, o una propiaSecurity 0: ninguna. Security 1: AES-256-CTR. Security 2: AES-256-GCM
Improv Serial o BLEPaquetes binarios por serial USB o Bluetooth LEChrome o Edge (no en iOS) para las demos web, o una appNo se describe en la especificación
ESP-Touch (SmartConfig)Una app del teléfono transmite las credenciales por broadcast y la placa escuchaApp del teléfono (Espressif publica una para Android)AES opcional en ESP-Touch v2

Esto es lo que hay detrás de cada fila.

Portal cautivo (y WiFiManager)

La placa abre su propio hotspot y sirve una página de configuración. WiFiManager hace lo mismo cuando la placa no logra unirse a una red guardada: pasa a modo punto de acceso y arranca un servidor DNS y un servidor web, y el repositorio llama al resultado portal cautivo. El README dice que la documentación está desactualizada, y cubre tanto ESP8266 como ESP32. gizmo-common es la versión de OpenGizmo de la misma idea, escrita para las aplicaciones web de nuestros proyectos. Cómo se abre la ventana emergente y por qué a veces no se abre está en ¿El portal cautivo del ESP32 no funciona? Arregla la ventana del Wi-Fi.

El provisioning unificado de Espressif

El Unified Provisioning de ESP-IDF es un framework, no una página: transporta las credenciales, y opcionalmente otros ajustes, por BLE (GATT) o por SoftAP más HTTP. Espressif lista apps de provisioning para Android y iOS con su código fuente, y una herramienta de Python, esp_prov, para depurar. La página actual de la documentación remite al componente network_provisioning para el código de la librería y los ejemplos. El transporte BLE ocupa unos 110 KB de RAM en ejecución, según la misma página, y buena parte se puede recuperar si después dejas de usar BLE. El core Arduino-ESP32 lo envuelve como WiFiProv, con un esquema SoftAP y otro BLE.

Improv

Improv Wi-Fi es un estándar abierto con dos transportes, Serial y Bluetooth LE, y afirma que ambos se pueden usar desde un navegador. La especificación serial define paquetes que empiezan por IMPROV y comandos como enviar los ajustes Wi-Fi y buscar redes. ESPHome lo incluye como el componente improv_serial, y ESP Web Tools figura en la lista de adoptantes de Improv. El SDK de C++ tiene licencia Apache-2.0, y su README pone la documentación del código entre las tareas pendientes.

ESP-Touch

ESP-Touch, también llamado SmartConfig, funciona al revés: la app del teléfono ya conoce la red y se la envía a la placa. En la librería para Android de Espressif, la app recibe el SSID, el BSSID y la contraseña del punto de acceso, y la tarea puede usar paquetes broadcast o multicast. ESP-Touch v2 no es compatible con el original. La página de SmartConfig de ESP-IDF dice que la v2 admite cifrado AES con una clave de 16 bytes. También dice que detengas la tarea después para liberar memoria.

¿Cuál es el método más sencillo para el usuario?

El más sencillo es el que no pide nada que el usuario no tenga ya. Un portal cautivo solo necesita el navegador del teléfono. Conectarse a un hotspot es algo que la gente conoce de hoteles y cafeterías, y en eso se apoya todo el método. Tiene un pero: es el teléfono quien decide si abre la página de acceso, y algunos no lo hacen.

El provisioning BLE es más fluido en un punto. Espressif señala que, tanto en Android como en iOS, la app puede encontrar la placa y conectarse sin salir de la app, mientras que con el provisioning SoftAP los usuarios de iOS acaban en los Ajustes del sistema para unirse a la red de la placa. El precio es la app: alguien tiene que crearla, publicarla y mantenerla, o el usuario instala la genérica de Espressif.

Improv Serial es el más cómodo cuando la placa ya está conectada a la computadora, porque una página como la de ESP Web Tools puede mostrar el dispositivo y enviar los ajustes Wi-Fi por el mismo cable. No sirve de nada para una placa olvidada en un cajón al otro lado de la casa. El sitio de Improv dice que sus demos web requieren Chrome o Edge y no funcionan en iOS.

ESP-Touch no necesita hotspot, pero el usuario sigue necesitando una app que aporte el nombre y la contraseña de la red. No encontré una fuente primaria sobre su comportamiento con redes de 5 GHz, así que no puedo decir cómo falla ahí.

Una lista para decidir: contraseña en el código para una sola red, BLE de Espressif con tu propia app, Improv Serial por USB, portal cautivo para cualquier teléfono

¿Qué tan seguro es cada método?

Aquí, seguridad significa una sola cosa: ¿puede alguien cerca de la placa leer o reemplazar las credenciales mientras viajan? La documentación de Espressif es la más explícita. Hay tres esquemas:

  • Security 0: "No security (No encryption)."
  • Security 1: intercambio de claves Curve25519 con cifrado AES-256-CTR. Tiene un modo autorizado que usa una cadena de prueba de posesión (PoP), un secreto por dispositivo que el usuario escribe en la app, y un modo sin ella.
  • Security 2: derivación de claves SRP6a con AES-256-GCM, basada en un nombre de usuario y una contraseña que tú le haces llegar a la app del teléfono de algún modo, por ejemplo con una etiqueta con código QR.

Para SoftAP, Espressif también sugiere WPA2 con una contraseña única por dispositivo. Un detalle que conviene revisar en el core de Arduino: la función beginProvision del header WiFiProv.h usa por defecto la prueba de posesión "abcd1234", así que define la tuya antes de distribuir la placa.

Improv es más escueto. En la especificación BLE, la contraseña viaja como bytes en claro en la characteristic de comandos RPC, y la página no describe emparejamiento ni cifrado, así que cualquier protección depende de tu stack BLE. Lo que añade es un paso de autorización opcional: un dispositivo puede esperar una interacción física antes de aceptar las credenciales, y la autorización caduca tras un tiempo que la especificación sugiere de un minuto. El checksum solo detecta errores accidentales.

Filas de seguridad: Espressif Security 0 y un portal cautivo abierto no tienen cifrado, la especificación de Improv BLE no dice nada, la Security 1 usa AES-256-CTR, la Security 2 AES-256-GCM

Un portal cautivo abierto no tiene ninguna protección, y prefiero decirlo a esconderlo. El hotspot de gizmo-common se inicia con WiFi.softAP(setupOptions.accessPointName), sin contraseña, así que las credenciales viajan por HTTP simple. Eso significa que cualquiera dentro del alcance de radio de la placa durante la configuración podría, en principio, leerlas. Lo deduje del código y no probé una captura de tráfico. Dos cosas limitan la exposición: el hotspot se abre solo mientras no hay una red que funcione (el firmware lo mantiene dos minutos después de que vuelve el Wi-Fi, para que el teléfono vea el resultado), y mientras está activo solo responden cuatro rutas de la API (/api/networks, /api/connect, /api/check-connection y /api/device), como muestra el código de guardRequest. Según WiFiManager, el punto de acceso se puede y se debe proteger con contraseña ("can and should"); con una contraseña conocida, el tráfico al menos va cifrado con WPA2 por el aire.

¿Cómo se guardan las credenciales y cómo se recupera uno de una contraseña incorrecta?

Guardar es la mitad fácil. La mitad difícil es un error de tecleo: si la placa sobrescribe una red que funcionaba con una contraseña incorrecta, queda sin conexión y no tiene forma de avisarlo.

gizmo-common lo resuelve en wifi_setup.cpp. Las credenciales nuevas se mantienen en RAM y se prueban primero. Se escriben en NVS (el almacén clave-valor de la flash del ESP32, namespace gizmo-wifi, claves ssid y password) solo cuando la conexión funciona. Si el intento falla a los 12,5 segundos, la placa las descarta, vuelve a la red guardada y abre el hotspot de nuevo. No encontré ningún cifrado de NVS en el código que leí, así que la contraseña guardada está en la flash como texto plano.

Para un reinicio a propósito, el usuario puede mantener pulsado el botón BOOT de la XIAO ESP32-S3 durante 10 segundos, o pulsar Forget network en la aplicación web, como describen el README de gizmo-common y la guía para arreglar el portal cautivo. Sea cual sea el método que elijas, hazle la misma pregunta: ¿qué pasa cuando la contraseña es incorrecta, y puede el usuario arreglarlo sin una computadora? Improv tiene en su especificación un error dedicado "unable to connect", y ESP-Touch se rinde tras un tiempo de espera que la página de SmartConfig sitúa entre 15 y 255 segundos.

¿Los 5 GHz rompen alguno de estos métodos?

El ESP32-S3 de la placa XIAO no tiene radio de 5 GHz, como se explica en la guía de compra de ESP32, donde solo el ESP32-C5 es de doble banda. Un método que escanea desde la placa, como el portal o el escaneo de Improv, lista solo lo que la placa puede oír. La página de Wi-Fi de la aplicación web tiene justo ese estado para un escaneo vacío: "No networks found yet", con un botón Scan again (mira docs/screenshot-wifi.png en el repositorio de Gizmo Ticker). Si tu router une las dos bandas bajo un mismo nombre, la placa normalmente puede conectarse igualmente por la de 2,4 GHz. Si las nombra por separado, elige el nombre de 2,4 GHz.

¿Qué método eligió OpenGizmo y por qué?

Los tres proyectos de OpenGizmo, el Gizmo Ticker, el Gizmo Reolink Switch y la Gizmo Camera, usan el portal cautivo. No encontré código de Improv, provisioning BLE ni ESP-Touch en los tres repositorios de firmware. Estas son las razones que puedo señalar en el código:

Un maker sostiene un teléfono que muestra la red Gizmo-Ticker mientras una placa XIAO con una pequeña antena envía ondas Wi-Fi hacia él

  • La aplicación web ya existe. Cada placa sirve su propia aplicación web, y la página de configuración /ap-setup forma parte de ella, así que el portal no cuesta un front end nuevo.
  • Ninguna app que publicar. Cualquier cosa con navegador puede hacer la configuración, en cualquier teléfono o laptop.
  • Reintentos seguros. Las credenciales se guardan solo después de conectarse, y un hotspot que se vuelve a abrir si falla es la vía de recuperación.
  • Reinicio a mano. El botón BOOT, o Forget network en la aplicación web, devuelve el portal.

Los costos son los de arriba: un hotspot abierto, HTTP simple y un teléfono que quizá no abra la ventana emergente. Los acepté porque el hotspot se abre solo mientras la placa no tiene red y lo único que se envía es la contraseña del Wi-Fi. Si yo distribuyera algo que maneja un secreto de más valor que la contraseña del Wi-Fi de casa, pasaría a la Security 2 de Espressif por BLE.

Entonces, ¿cuál debes usar?

Usa credenciales en el código para una placa de pruebas desechable. Usa un portal cautivo cuando cualquiera con un teléfono deba poder configurar la placa y un hotspot abierto sea aceptable. Usa el provisioning unificado de Espressif con Security 1 o 2 cuando controlas la app y quieres cifrado. Usa Improv Serial cuando la placa va conectada por USB de todos modos. ESP-Touch solo tiene sentido si ya distribuyes su app.

El límite de esta comparación es que leí las especificaciones y el código, y no medí el tiempo de configuración, el consumo de batería ni el tamaño en flash de ninguno de estos métodos. Si tu portal cautivo no se abre en un teléfono, ve a la guía para arreglar el portal cautivo, y si la placa está configurada pero su nombre .local no se resuelve, el siguiente problema es mDNS en Android. Para ver todo el flujo del dispositivo, lee la introducción a OpenGizmo.

Preguntas frecuentes

Encuentra respuestas rápidas a las preguntas más comunes sobre este tema.

El provisioning Wi-Fi es el paso en el que un ESP32 aprende el nombre y la contraseña de tu red Wi-Fi sin que estén escritos en su firmware. El usuario envía las credenciales desde un teléfono o una computadora, y la placa las guarda en la memoria flash y se conecta. Los métodos habituales son portal cautivo, Bluetooth LE, Improv y ESP-Touch.

Publicado

¿Listo para montar tu propio gizmo?

Elige un proyecto open source con ESP32 y sigue su guía paso a paso, desde la lista de componentes y el cableado hasta el firmware y el primer arranque.

Lee también

Explora las categorías