Ejemplo de WebApp personalizada para ESP32 - Tutorial de interfaz web simple para principiantes
Visión general
Este ejemplo proporciona una plantilla completa para crear tus propias aplicaciones web personalizadas que se integran a la perfección con la Biblioteca WebApps ESP32 de DIYables.

La plantilla CustomWebApp es perfecta para principiantes que desean añadir su propia interfaz web al ecosistema de DIYables ESP32 WebApps. Este tutorial te muestra cómo construir una página web simple con intercambio de datos bidireccional en tiempo real entre el navegador y el ESP32 a través de WebSocket que puede:
- Enviar mensajes de texto desde un navegador web al ESP32 al instante mediante WebSocket
- Recibir mensajes desde el ESP32 y mostrarlos en tiempo real en la página web
- Mantener una conexión WebSocket persistente para una comunicación continua
- Reconexión automática cuando se pierde la conexión WebSocket
- Trabajar en dispositivos móviles con diseño responsive
Diseñado para ESP32 - esta plantilla se integra perfectamente con las aplicaciones web existentes de DIYables y proporciona la base para construir tus propias interfaces de IoT personalizadas!
Esta plantilla proporciona código mínimo para empezar. Los usuarios pueden desarrollar sus propias aplicaciones web sofisticadas modificando esta plantilla. Se recomienda tener conocimientos básicos de programación web (HTML, CSS, JavaScript) para personalizar la interfaz web y añadir características avanzadas.
Lo que aprenderás
- Cómo crear una aplicación web personalizada que se integre con la Biblioteca DIYables ESP32 WebApps
- Cómo añadir tu página personalizada al ecosistema de aplicaciones web de DIYables
- Cómo enviar mensajes de texto desde el navegador web al ESP32
- Cómo enviar datos desde el ESP32 al navegador web
- Cómo manejar las conexiones WebSocket y la reconexión automática
- Cómo hacer interfaces web que se adapten a dispositivos móviles
- Cómo usar el sistema de plantillas DIYables ESP32 WebApps para desarrollo rápido
Características
- Integración de DIYables ESP32 WebApps: Se integra sin problemas con el ecosistema de la biblioteca DIYables ESP32 WebApps.
- Código de plantilla mínimo: Proporciona una base básica que puedes ampliar y personalizar.
- Desarrollo basado en plantillas: Un punto de partida completo que puedes modificar para crear aplicaciones sofisticadas.
- Mensajería de texto simple: Envía mensajes entre el navegador web y Arduino.
- Reconexión automática: Se reconecta automáticamente cuando se pierde la conexión.
- Diseño móvil adaptable: Funciona perfectamente en teléfonos, tabletas y computadoras.
- Amigable para principiantes: Código limpio y sencillo que es fácil de entender.
- Framework extensible: Se requieren conocimientos básicos de programación web (HTML/CSS/JavaScript) para una personalización avanzada.
Hardware Requerido
Or you can buy the following kits:
| 1 | × | DIYables ESP32 Starter Kit (ESP32 included) | |
| 1 | × | DIYables Sensor Kit (30 sensors/displays) | |
| 1 | × | DIYables Sensor Kit (18 sensors/displays) |
Cómo empezar
Puede comenzar a construir su aplicación web personalizada para la placa ESP32 siguiendo los siguientes pasos principales:
- Ejecutar la plantilla de aplicación personalizada predeterminada en tu placa ESP32
- Probar y verificar que la aplicación web personalizada predeterminada funciona correctamente
- Comprender el protocolo de comunicación y cómo funciona en segundo plano
- Modificar la plantilla para adaptar tu aplicación
- Gestión de múltiples aplicaciones web personalizadas - Guía esencial para prevenir conflictos
Empecemos uno por uno.
Ejecuta la Plantilla de Aplicación Personalizada Predeterminada en tu placa ESP32
Pasos R\u00e1pidos
- Si es la primera vez que usas el ESP32, consulta el tutorial sobre configurar el entorno para ESP32 en el IDE de Arduino
- Conecta la placa ESP32 a tu computadora mediante un cable USB
- Inicia el IDE de Arduino en tu computadora
- Selecciona la placa ESP32 adecuada (p. ej. ESP32 Dev Module) y el puerto COM
- Navega hasta el icono Bibliotecas en la barra izquierda del IDE de Arduino
- Busca "DIYables ESP32 WebApps", luego localiza la biblioteca DIYables ESP32 WebApps de DIYables
- Haz clic en el botón Instalar para instalar la biblioteca

- Se le pedirá instalar algunas dependencias de la biblioteca
- Haga clic en el botón Instalar todo para instalar todas las dependencias de la biblioteca

- En el IDE de Arduino, ve a Archivo > Ejemplos > DIYables ESP32 WebApps > CustomWebApp
- Verás 4 archivos que componen la plantilla completa de la aplicación web personalizada:
- CustomWebApp.ino - Código principal de ESP32 (¡aquí es donde puedes añadir tu lógica personalizada!)
- CustomWebApp.h - Archivo de encabezado (que define la interfaz para la biblioteca WebApps ESP32 de DIYables)
- CustomWebApp.cpp - Archivo de implementación (maneja la integración con el marco de la biblioteca)
- custom_page_html.h - diseño de página web (¡personaliza tu interfaz web aquí!)
- Configura la red WiFi cambiando estas líneas en CustomWebApp.ino:
Paso 5: Subir y Probar
- Haz clic en el botón Subir en el IDE de Arduino para subir código al ESP32
- Abre el Monitor Serial para ver el estado de la conexión
- Toma nota de la dirección IP que se muestra en el Monitor Serial
- Abre el Monitor Serial
- Consulta el resultado en el Monitor Serial. Se muestra a continuación
- Si no ves nada, reinicia la placa ESP32.
- Toma nota de la dirección IP que se muestre y escribe esta dirección en la barra de direcciones de un navegador web en tu smartphone o PC.
- Ejemplo: http://192.168.0.2
- Verás la página de inicio tal como se muestra en la imagen a continuación:

- Haz clic en el enlace Web Custom, verás la interfaz de usuario de la aplicación Web Custom como se muestra a continuación:

- O también puedes acceder a la página directamente mediante la dirección IP, seguida de /custom. Por ejemplo: http://[IP_ADDRESS]/custom
Probar y Verificar que la Aplicación Web Personalizada Predeterminada Funcione Correctamente
Al ejecutar la plantilla predeterminada de CustomWebApp, esto es lo que deberías ver:
En la interfaz web:
- Estado de la conexión: Muestra "Conectado" en azul cuando WebSocket está activo
- Campo de entrada de mensajes: Campo de texto para escribir mensajes para Arduino
- Botón Enviar: Haz clic para enviar tu mensaje (o pulsa Enter)
- Pantalla de mensajes de Arduino: Muestra mensajes recibidos desde ESP32 en texto azul
Comportamiento del ESP32:
- Respuesta de Eco: Cuando envíes "Hello" desde la web, el ESP32 responde con "Echo: Hello"
- Actualizaciones periódicas: ESP32 envía mensajes de tiempo de actividad cada 5 segundos: "Tiempo de actividad de Arduino: X segundos"
- Monitor serie: Todos los mensajes recibidos se registran para depuración
Prueba la comunicación:
- Escribe un mensaje en la caja de entrada (p. ej., "mensaje de prueba")
- Haz clic en Enviar o pulsa Enter
- Ver el Monitor Serial - deberías ver: "Recibido desde la web: mensaje de prueba"
- Ver la página web - deberías ver: "Eco: mensaje de prueba"
- Espera unos segundos - verás mensajes de tiempo de actividad periódicos actualizados cada 3 segundos (p. ej., "Tiempo de actividad de Arduino: 15 segundos", "Tiempo de actividad de Arduino: 18 segundos", etc.)
Comprender el protocolo de comunicación y cómo funciona en segundo plano
Entender los mecanismos internos te ayuda a personalizar la plantilla de manera efectiva.
Sistema de identificadores de aplicaciones
La plantilla CustomWebApp utiliza etiquetas de mensaje únicas (llamadas "Identificadores de Aplicación") que ayudan al código ESP32 y a los clientes web a filtrar los mensajes que les pertenecen. Esto es esencial porque su aplicación puede incluir varias aplicaciones web, y cada aplicación necesita procesar solo sus propios mensajes mientras ignora los demás:
Lado del ESP32 (CustomWebApp.h y CustomWebApp.cpp)
Lado de JavaScript (custom_page_html.h)
Beneficios de este diseño:
- Fuente única de verdad: Cambiar el identificador en un solo lugar por idioma
- Sin cadenas mágicas: Elimina las cadenas codificadas 'CUSTOM:' en todo el código
- Seguridad de tipos: El uso de constantes previene errores tipográficos
- Extensible: Fácil crear varias aplicaciones personalizadas con identificadores diferentes
- Evitar conflictos de datos entre varias aplicaciones: Cada aplicación utiliza un identificador único para evitar interferencias de mensajes
- Profesional: Sigue principios de diseño orientado a objetos
Notas importantes:
- Puedes mantener el identificador actual "CUSTOM:" al modificar esta plantilla de aplicación web personalizada para adaptarla a tu proyecto. Sin embargo, cuando crees más de una aplicación personalizada, asegúrate de cambiarlo para evitar conflictos.
- Si cambias el identificador, asegúrate de que el valor en JavaScript (.h file) y en el código ESP32 (.cpp file) sean los mismos (p. ej., que ambos usen "TEMP:" o que ambos usen "SENSOR:").
- Identificadores prereservados por aplicaciones integradas: Los siguientes identificadores ya están en uso por las aplicaciones integradas de WebApps de DIYables ESP32 y deben evitarse:
- Identificadores principales de la aplicación: "CHAT:", "MONITOR:", "PLOTTER:", "DIGITAL_PINS:", "JOYSTICK:", "SLIDER:", "TABLE:", "RTC:", "ROTATOR:", "GAUGE:"
- Identificadores de subprotocolo: "TIME:", "DATETIME:", "JOYSTICK_CONFIG:", "PLOTTER_DATA:", "PLOTTER_CONFIG:", "SLIDER_VALUES:", "TABLE_CONFIG:", "TABLE_DATA:", "VALUE_UPDATE:", "PIN_CONFIG:", "PIN_STATES:", "PIN_UPDATE:"
Flujo de Comunicación
De la página web al ESP32:
Cuando escribes un mensaje en la interfaz web y haces clic en el botón Enviar, por ejemplo: Hello, ocurre el siguiente flujo:
- JavaScript agrega identificador: JavaScript agrega automáticamente el identificador de la aplicación (que es "CUSTOM:" en esta plantilla) utilizando la constante APP_IDENTIFIER, luego envía un mensaje al ESP32 vía WebSocket. El mensaje real enviado es: CUSTOM:Hello
- La biblioteca DIYables ESP32 WebApps recibe: La biblioteca DIYables ESP32 WebApps recibe el mensaje CUSTOM:Hello y lo pasa a tu método CustomWebAppPage::handleWebSocketMessage
- La clase CustomWebAppPage elimina el identificador: En handleWebSocketMessage, la clase CustomWebAppPage verifica si el mensaje comienza con su APP_IDENTIFIER, elimina el identificador usando .substring(APP_IDENTIFIER.length()), y luego pasa el mensaje restante Hello invocando la función de callback implementada en tu archivo .ino
- Tu aplicación maneja: Tu aplicación en el archivo .ino recibe únicamente Hello y puede manejar el mensaje según tu lógica personalizada. La plantilla actual solo lo imprime y envía una respuesta
De ESP32 a la página web:
Cuando tu ESP32 quiere enviar datos a la interfaz web, por ejemplo: Temperature: 25°C, se produce el siguiente flujo:
- Tu aplicación llama a sendToWeb(): En tu archivo .ino, llamas a customPage.sendToWeb("Temperature: 25°C") para enviar datos al navegador web
- La clase CustomWebAppPage añade identificador y transmite: La clase CustomWebAppPage añade automáticamente el identificador de la aplicación usando su constante APP_IDENTIFIER a tu mensaje y transmite CUSTOM:Temperature: 25°C a todos los clientes web conectados vía WebSocket
- JavaScript recibe y filtra el mensaje: El navegador web recibe CUSTOM:Temperature: 25°C a través del manejador de eventos ws.onmessage, pero JavaScript solo procesa mensajes que empiezan con APP_IDENTIFIER y elimina el identificador usando .substring(APP_IDENTIFIER.length())
- La página web muestra el mensaje limpio: La plantilla actual muestra el mensaje limpio Temperature: 25°C (sin identificador) en la sección "Mensaje de Arduino". Puedes personalizar el JavaScript para analizar y mostrar los datos de distintas maneras según las necesidades de tu aplicación
Visión general de la arquitectura
El ejemplo de CustomWebApp consta de cuatro archivos principales:
- CustomWebApp.ino - Sketch principal de ESP32 con la lógica de tu aplicación
- CustomWebApp.h - Archivo de cabecera que define la clase de la página personalizada (interfaz de la biblioteca)
- CustomWebApp.cpp - Implementación con la lógica de comunicación (código de la biblioteca)
- custom_page_html.h - Interfaz HTML separada para facilitar la personalización
Modifica la plantilla para adaptar tu aplicación
La plantilla está diseñada para ser fácilmente personalizable para tus necesidades específicas. Así es como puedes adaptarla:
1. Integración de hardware
Añadir inicialización de hardware
En la función setup() de CustomWebApp.ino:
Gestión de comandos personalizados
Extienda la función de devolución de llamada para manejar sus comandos personalizados:
Enviar datos de sensores en tiempo real
2. Personalización de la interfaz web
Modificar el diseño de HTML
Edita el HTML en custom_page_html.h para cambiar la interfaz:
Personalizar el procesamiento de JavaScript
Actualiza la función ws.onmessage para manejar tipos de datos específicos:
Añadir Estilo
Personaliza el CSS para tu aplicación:
Otra personalización
Más allá de modificar la interfaz web y la integración de hardware, también puedes personalizar cómo aparece tu aplicación en el ecosistema de DIYables ESP32 WebApps:
1. Personalizar la ruta de la aplicación
Puede cambiar la ruta de la URL desde la que su aplicación web personalizada es accesible modificando el constructor en su archivo de encabezado:
Ruta predeterminada:
Ejemplos de rutas personalizadas:
Notas importantes:
- La ruta debe empezar con "/": Siempre comience su ruta con una barra diagonal
- Utilice nombres descriptivos: Elija rutas que describan claramente la función de su aplicación
- Evite conflictos: No utilice rutas ya tomadas por aplicaciones integradas como /chat, /monitor, /plotter, etc.
- Utilice minúsculas y guiones: Siga las convenciones de URL web para una mejor compatibilidad
2. Personalizar la tarjeta de la aplicación en la página de inicio
Puedes personalizar cómo aparece tu aplicación en la página de inicio de DIYables ESP32 WebApps modificando el método getNavigationInfo() en tu archivo de implementación:
Tarjeta de la aplicación básica:
Tarjeta de aplicación avanzada con CSS en línea:
Administrar múltiples aplicaciones web personalizadas - Guía esencial para la prevención de conflictos
Al desarrollar varias aplicaciones web personalizadas, es crucial evitar conflictos entre diferentes aplicaciones. Supongamos que queremos agregar tres aplicaciones personalizadas llamadas "Temperature Monitor", "Motor Controller" y "Sensor Dashboard" a nuestro proyecto ESP32. Así es como puedes asegurarte de que funcionen juntas de forma armoniosa:
1. Usar identificadores únicos de la aplicación
Cada aplicación web personalizada debe tener un identificador único para evitar conflictos de mensajes:
Ejemplo: Aplicación de Monitoreo de Temperatura
Ejemplo: Aplicación de Controlador de Motor
Ejemplo: Aplicación de panel de sensores
2. Utiliza rutas de página únicas
Cada aplicación web necesita una ruta URL única:
3. Usa nombres de clase únicos
Evita conflictos de nombres usando nombres de clase descriptivos:
4. Organizar varias aplicaciones en un solo proyecto
Así es como estructurar un proyecto con varias aplicaciones personalizadas:
5. Mejores Prácticas para Múltiples Aplicaciones
Organización de archivos
Navegación entre aplicaciones
Actualiza el método getNavigationInfo() en cada aplicación para facilitar la navegación:
6. Pruebas de varias aplicaciones
Al probar varias aplicaciones:
- Prueba cada aplicación de forma individual primero
- Verifica el Monitor Serial para conflictos de mensajes
- Verifica que los identificadores únicos funcionen correctamente
- Prueba la navegación entre diferentes aplicaciones
- Monitorea el uso de memoria con varias aplicaciones cargadas
Siguiendo estas pautas, puedes crear múltiples aplicaciones web personalizadas que funcionen juntas sin interferir entre sí ni con otras aplicaciones web ESP32 de DIYables.