ESP32 no abre el portal cautivo: cómo arreglar el popup

Por qué el popup del portal cautivo del ESP32 no se abre en Android, iPhone o Windows: DNS, URL de prueba, redirecciones 302 y cómo arreglarlo.

Publicado
Tiempo de lectura
9 min
Un maker con gafas señala un teléfono que muestra una lista de Wi-Fi con la red Gizmo-Setup y un popup vacío, junto a una placa ESP32 sobre el escritorio.

En resumen

Un portal cautivo en el ESP32 necesita dos cosas: un DNS que responda a cualquier nombre con la IP de la placa y una redirección HTTP para la URL de prueba. Si el popup no se abre, revisa primero esas dos.

El portal cautivo del ESP32 no se abre cuando la comprobación de conectividad del teléfono recibe una respuesta de aspecto normal en lugar de una redirección. La placa necesita un servidor DNS que responda a cualquier nombre con su propia IP y un servidor web que redirija la petición de prueba a la página de configuración. Sin las dos cosas, Android, iOS y Windows creen que la red está bien y no muestran nada.

Esta guía sigue lo que de verdad hace la librería gizmo-common, porque todos los dispositivos de OpenGizmo (el Gizmo Ticker, el Gizmo Reolink Switch y la Gizmo Camera) abren así su primera configuración de Wi-Fi. He leído su código fuente y las fuentes de Android, Apple, Microsoft y Arduino-ESP32 enlazadas más abajo, y señalo lo que no pude verificar. ¿Tu placa se niega a mostrar el popup ahora mismo? Salta a la lista de comprobación más abajo y vuelve después para entender el porqué.

¿Cómo funciona un portal cautivo en el ESP32?

Un portal cautivo es una página web que el teléfono abre por sí solo cuando se une a una red Wi-Fi que no tiene Internet hasta que inicias sesión. Los hoteles lo hacen así. Un ESP32 puede hacer el mismo truco para su propia página de configuración, sin ninguna nube de por medio. La secuencia es corta:

  1. El ESP32 inicia un punto de acceso (un hotspot) y un servidor DNS en el puerto 53.
  2. El teléfono se une al hotspot y envía una prueba: una consulta DNS y después una petición HTTP a una dirección conocida.
  3. El servidor DNS responde con la IP del ESP32, sea cual sea el nombre consultado.
  4. El servidor web responde a la prueba con una redirección a la página de configuración.
  5. El teléfono ve que la respuesta no es la que espera y abre una ventana de inicio de sesión con la página de configuración.

Un teléfono y un ESP32 intercambiando una consulta DNS, una prueba HTTP y una redirección a /ap-setup, paso a paso

El popup es decisión del teléfono, no tuya. No puedes empujarle una página: solo puedes dar a la prueba una respuesta que haga que el teléfono diga "esto necesita iniciar sesión". Para otras formas de darle Wi-Fi a una placa, consulta Provisioning de Wi-Fi en ESP32: portal cautivo, BLE, Improv.

¿Qué URL piden Android, iPhone y Windows?

Cada sistema operativo tiene su propia prueba, y cada uno considera "online" una respuesta distinta. Todo lo demás es, para ellos, un portal cautivo.

SOPetición de prueba (por defecto)Respuesta que significa onlineFuente
Androidhttp://connectivitycheck.gstatic.com/generate_204HTTP 204Configuración de AOSP NetworkStack
Windows 10 1607 y posteriores, 11http://www.msftconnecttest.com/connecttest.txt200 con Microsoft Connect TestMicrosoft Learn, preguntas frecuentes de NCSI
iOS y macOShttp://captive.apple.com/hotspot-detect.htmlUna página con SuccessHost en la documentación de Apple, ruta y página según informes de la comunidad

Los valores por defecto de Android están en el archivo de recursos de AOSP NetworkStack: la prueba HTTP es http://connectivitycheck.gstatic.com/generate_204, con una HTTPS en https://www.google.com/generate_204 y dos de reserva. En el NetworkMonitor.java del mismo proyecto, una respuesta 200 con un cuerpo de 4 bytes o menos no se trata como portal a propósito, y una respuesta de portal sin cabecera Location hace que Android 12 y posteriores usen la URL de prueba como página de inicio de sesión (el código comprueba SdkLevel.isAtLeastS()). Los fabricantes de teléfonos pueden cambiar estas URL, así que toma la tabla como el comportamiento de serie.

Microsoft documenta su parte en las preguntas frecuentes de NCSI: desde Windows 10 build 14393 la prueba es www.msftconnecttest.com/connecttest.txt, y un 200 cuyo cuerpo no contiene el texto esperado, o un 302 o un 304, se interpreta como un hotspot que necesita iniciar sesión.

En el caso de Apple, la única fuente primaria que encontré es la lista de hosts de Apple Support para redes empresariales, que nombra captive.apple.com como usado para la "Internet connectivity validation for networks that use captive portals". La ruta /hotspot-detect.html y la página Success salen de artículos de la comunidad, así que trátalo como un dato muy repetido, no como una especificación de Apple. Un ingeniero de Apple también confirma, en una respuesta del foro de desarrolladores, que macOS mantiene una red cautiva fuera de la ruta por defecto hasta que cree que el portal ya está resuelto.

¿Qué responde gizmo-common?

La librería es lo bastante pequeña como para leerla. Cuando no hay ninguna red guardada, o un intento de conexión falla, inicia un hotspot abierto y un servidor DNS en startAccessPoint() de wifi_setup.cpp:

wifi_setup.cpp
wifi_setup.cpp
accessPointEnabled = WiFi.softAP(setupOptions.accessPointName);
// Answer every DNS name with the hotspot address, so phones open the setup page
dnsServer->start(DNS_PORT, "*", WiFi.softAPIP());
Lín. 3, col. 1UTF-8cpp

DNS_PORT es 53 y "*" significa "cualquier nombre". En el código de DNSServer de Arduino-ESP32, un dominio vacío o comodín coincide con todo, las consultas A y ANY reciben la IP, y otros tipos como AAAA reciben una respuesta vacía. Esa es la rama master actual: no revisé el core más antiguo que PlatformIO fija con espressif32 @ 8.0.0.

La mitad HTTP es handleCaptivePortalRequest(), que se llama primero en el manejador not-found del servidor web. Solo toca las peticiones GET y HEAD que llegan por el hotspot, nunca la página de configuración, /api/ ni los archivos propios de la aplicación web, y envía todo lo demás a la página de configuración:

wifi_setup.cpp
wifi_setup.cpp
// Send everything else to the setup page
request->redirect(setupOptions.setupPagePath);
Lín. 2, col. 1UTF-8cpp

La página de configuración es /ap-setup en los tres proyectos. En ESPAsyncWebServer 3.12.1, la versión que el ticker fija en su platformio.ini, redirect() usa por defecto el estado 302. Así que la prueba de la tabla de arriba recibe un 302 y una cabecera Location. Android ve un portal en lugar de un 204, Windows ve un 302 en lugar de su archivo de texto, y la comprobación de Apple no debería encontrar ninguna página Success. Ese es todo el truco: ninguna ruta especial /generate_204, un único catch-all.

Una tabla con las pruebas de Android, Apple y Windows, la respuesta que espera cada una y la única redirección 302 que el ESP32 envía a las tres

Dos detalles que ayudan más adelante. Las peticiones que llegan por la red Wi-Fi normal nunca se redirigen, porque la comprobación compara la IP local del cliente con la del hotspot. Y por el hotspot solo responden cuatro rutas de la API (/api/networks, /api/connect, /api/check-connection, /api/device): la configuración del Wi-Fi y los datos del dispositivo, nada más, porque cualquiera que esté cerca puede unirse al hotspot abierto. Para ver todo el flujo en un dispositivo terminado, mira cómo está construido el Reolink Switch y la visión general de OpenGizmo.

Lista de comprobación: el popup no aparece

Cambia una cosa a la vez y prueba después de cada paso.

Un maker sostiene un teléfono con la red Wi-Fi Gizmo-Ticker resaltada y señala una placa XIAO conectada a una matriz LED

1. ¿Existe el hotspot?

El hotspot solo se abre cuando no hay ninguna red guardada, o la guardada no logra conectar (el intento de conexión caduca a los 12,5 segundos, según WIFI_CONNECT_TIMEOUT). Mientras una red guardada funciona, no hay hotspot ni portal. Compila el entorno debug (pio run -e debug -t upload, y luego pio device monitor) y busca Access point ready on http://.... El firmware de release no escribe logs.

Si flasheaste la placa desde el navegador, ESP Web Tools: flashea un ESP32 desde el navegador explica las compilaciones de release.

2. ¿Se unió el teléfono de verdad al hotspot?

Muchos teléfonos prefieren los datos móviles cuando una red Wi-Fi no tiene Internet, y algunos preguntan si quieres seguir conectado. Sigue conectado, o apaga los datos móviles durante la prueba. En algunos teléfonos el aviso de inicio de sesión puede llegar como notificación en lugar de ventana, así que mira en el panel de notificaciones antes de suponer que no ha pasado nada. No encontré una fuente primaria sobre cómo lo redacta o dónde lo coloca cada fabricante.

3. Abre a mano una dirección http://

El README de gizmo-common da el mismo consejo: mientras estás conectado al hotspot, abre cualquier dirección http:// en el navegador y te redirigirá. Si esto funciona pero el popup no, el DNS y la redirección están bien y solo estorba la lógica de prueba del teléfono. Usa HTTP normal: el servidor web del firmware solo escucha en el puerto 80 (AsyncWebServer server(80) en cada proyecto), así que una dirección https:// no se puede redirigir.

4. Quita lo que se lleva la consulta DNS

Una VPN o una app que fuerza su propio resolvedor DNS, o el ajuste de DNS seguro de un navegador, pueden desviar la consulta del servidor DNS comodín, y el teléfono nunca llega a la placa. No encontré una fuente primaria sobre el modo DNS privado de Android, así que lo señalo como causa probable, no medida. Apaga la VPN y el DNS privado durante la configuración, y luego vuelve a encenderlos.

5. Comprueba el código de estado de la prueba

Desde una computadora conectada al hotspot, nslookup example.com debería devolver la IP del hotspot, y curl -i http://connectivitycheck.gstatic.com/generate_204 debería mostrar un 302 con Location: /ap-setup (lo deduje del código y no lo probé en hardware). Una IP equivocada apunta al lado del DNS. Un 204 significa que tu firmware, u otra cosa en el camino, responde a la prueba por su cuenta, y el teléfono pensará que está online.

6. Si escribes tu propio portal

Sigue la regla de antes: el DNS responde a cualquier nombre, y una ruta desconocida redirige a tu página. No envíes un 204 ni la página Success esperada desde tus propias rutas, o el teléfono pensará que está online y ocultará el popup.

¿Y la opción 114 de DHCP y la Captive Portal API?

La RFC 8910 define una forma de informar a los clientes sobre el portal, con la opción 114 de DHCPv4 y con una opción IPv6 de Router Advertisement (tipo 37), que llevan un URI. El URI apunta a una API descrita en la RFC 8908, que responde application/captive+json por HTTPS con un indicador captive y un user-portal-url opcional. El NetworkMonitor de Android ya contiene código para ese tipo de contenido, pero gizmo-common no envía la opción 114, así que los tres dispositivos de OpenGizmo dependen de la redirección de la prueba. No he probado esa opción en un ESP32.

¿Cuánto tiempo sigue encendido el hotspot y cómo lo recuperas?

Cuando la página de configuración consulta /api/check-connection y recibe el estado Connected, el firmware apaga el hotspot. Si la red guardada vuelve por sí sola, el hotspot sigue encendido 120 segundos (ACCESS_POINT_SHUTDOWN_DELAY) y luego se apaga. Las credenciales nuevas se prueban primero y solo se guardan cuando conectan, así que un error al teclear no puede reemplazar una red que funciona. La red guardada vive en NVS, el almacén clave-valor de la memoria flash del ESP32.

Para recuperar el portal, mantén presionado el botón BOOT de la XIAO ESP32-S3 durante 10 segundos mientras corre el firmware (esto también borra los ajustes propios del proyecto), o presiona Forget network en la aplicación web. La ESP32-CAM no tiene reinicio con BOOT: su GPIO0 es también el reloj de la cámara, así que usa la aplicación web. Si llegas a la placa por nombre después de unirte al Wi-Fi, el siguiente problema puede ser mDNS, que cubre ESP32 .local no funciona en Android.

Qué se verificó y los límites

El DNS comodín, la redirección 302, el timeout de 12,5 segundos y el retardo de 120 segundos del hotspot se leen directamente de gizmo-common v2.5.1 (fijada por el ticker y por el Reolink Switch; la cámara fija la v2.4.0, que no leí para esta guía) y de ESPAsyncWebServer 3.12.1; para esta guía no capturé paquetes de un teléfono real. Las pruebas de Android y Windows salen de la documentación de AOSP y de Microsoft, el host de Apple de Apple Support y su ruta solo de fuentes de la comunidad, y los fabricantes de teléfonos o las versiones del sistema pueden cambiar cualquiera de ellas. Si la lista de comprobación no arregló tu popup, prueba primero el paso 3: te dice si el fallo está en la placa o en el teléfono. Para una comparación con BLE e Improv, la guía de métodos de provisioning es la siguiente parada.

Preguntas frecuentes

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

El teléfono abre el inicio de sesión solo si su comprobación de conectividad recibe algo distinto de lo esperado. Si el DNS del ESP32 no responde a cada nombre con su IP, o el servidor web contesta a la URL de prueba con 204 o con la página equivocada, el teléfono da la red por buena y no muestra nada.

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