DIYables ESP32 WebApps Biblioteca: Referencia de la API - Documentación completa
Visión general
La biblioteca ESP32 WebApps de DIYables proporciona una solución integral y modular para crear aplicaciones web basadas en WebSocket en ESP32. Incluye varias aplicaciones web preconstruidas y un marco flexible para crear aplicaciones personalizadas.
La biblioteca utiliza una arquitectura modular, en la que solo incluyes las aplicaciones web que necesitas, ahorrando memoria y mejorando el rendimiento.
Características
- Arquitectura modular: Añade solo las aplicaciones web que necesites para optimizar el uso de la memoria
- Uso eficiente de la memoria: Cada aplicación web puede habilitarse/deshabilitarse de forma independiente
- Más de 11 aplicaciones web listas para usar: Control completo del ESP32 sin conocimientos de programación web
- Framework de aplicaciones web personalizadas: Crea tus propias aplicaciones utilizando el sistema de clases base
- Comunicación en tiempo real: Basada en WebSocket para actualizaciones instantáneas
- Diseño responsivo: Funciona en ordenadores de escritorio, tabletas y dispositivos móviles
- Integración fácil: API simple basada en callbacks
- Soporte para múltiples aplicaciones: Permite añadir varias aplicaciones web de forma simultánea
Clases centrales
Servidor de Aplicación Web DIYables
La clase principal del servidor que gestiona las aplicaciones web, las solicitudes HTTP y la comunicación WebSocket.
Constructor
Crea una instancia de servidor de una aplicación web.
- httpPort: Puerto del servidor HTTP (predeterminado: 80)
- websocketPort: Puerto del servidor WebSocket (predeterminado: 81)
Métodos
Configuración y Conexión
Inicializa la conexión de red (para Ethernet o conexiones preconfiguradas) y inicia el servidor web.
- Devuelve: verdadero si tiene éxito, falso si falla
- Caso de uso: para soporte Ethernet en el futuro o cuando las credenciales de WiFi estén preconfiguradas
Inicializa la conexión WiFi y inicia el servidor web.
- ssid: nombre de la red WiFi
- password: contraseña de WiFi
- Devuelve: true si tiene éxito, false si falla
- Caso de uso: Conexión WiFi estándar con credenciales
Gestiona las solicitudes HTTP y la comunicación WebSocket. Debe ser llamado en el bucle principal.
Devuelve verdadero si el WiFi está conectado.
Devuelve la dirección IP del Arduino como una cadena.
Gestión de Aplicaciones
Agrega una aplicación web al servidor.
- app: puntero a una instancia de una aplicación web
Elimina una aplicación web por su ruta URL.
- ruta: ruta de la URL de la aplicación (p. ej., "/chat")
Obtiene una aplicación web por su ruta de URL.
- ruta: ruta URL de la aplicación
- Devuelve: puntero a la aplicación o nullptr si no se encuentra
Configura la página de error 404 (opcional).
- página: instancia de página 404
Acceso a Aplicaciones Especializadas
Obtiene la instancia de la página de pines digitales si se ha agregado.
- Devuelve: Puntero a la página de pines digitales o nullptr
Obtiene la instancia de la página del slider si se ha agregado.
- Devuelve: puntero a la página del control deslizante o nullptr
Obtiene la instancia de la página del joystick si se ha añadido.
- Devuelve: puntero a la página del joystick o nullptr
Clases base
Base de la página de la aplicación web DIYables
Clase base abstracta de la que heredan todas las aplicaciones web. Proporciona funcionalidades comunes para el manejo de HTTP, la comunicación por WebSocket y la gestión de páginas.
Constructor
Crea una instancia de página base con la ruta URL especificada.
- pagePath: ruta URL de la página (p. ej., "/web-joystick")
Métodos virtuales (Deben ser implementados por las clases derivadas)
Gestiona las solicitudes HTTP para esta página. Método virtual puro.
- cliente: Interfaz de cliente web para enviar la respuesta
Gestiona los mensajes de WebSocket para esta página. Método virtual puro.
- ws: Interfaz de conexión WebSocket
- message: Contenido del mensaje recibido
- length: Longitud del mensaje
Devuelve la cadena de identificación de la página utilizada en la visualización de la información de la conexión. Método virtual puro.
- Devuelve: Cadena de información de la página (p. ej., "🕹️ Joystick web: ")
Devuelve HTML para el botón de navegación de la página de inicio. Método virtual puro.
- Devuelve: cadena HTML para la tarjeta de navegación
Métodos virtuales (sobrescrituras opcionales)
Se llama cuando se establece una nueva conexión WebSocket.
- ws: Nueva conexión WebSocket
Llamado cuando se cierra una conexión WebSocket.
- ws: Conexión WebSocket cerrada
Métodos comunes
Obtiene la ruta de la URL de esta página.
- Devuelve: Cadena de la ruta de la página
Comprueba si la página está actualmente habilitada.
- Devuelve: verdadero si está habilitado, falso si está deshabilitado
Habilita o deshabilita la página.
- habilitar: verdadero para habilitar, falso para deshabilitar
Métodos utilitarios
Envía cabeceras HTTP estándar al cliente.
- cliente: Interfaz de cliente web
- tipo de contenido: tipo MIME (predeterminado: "text/html")
Envía un mensaje a un cliente WebSocket específico.
- ws: Conexión WebSocket de destino
- message: Mensaje a enviar
Transmite un mensaje a todos los clientes WebSocket conectados.
- mensaje: Mensaje para difundir
Envía contenido HTML grande utilizando la codificación de transferencia por trozos.
- cliente: Interfaz de cliente web
- html: Contenido HTML para enviar
Ejemplo de uso
Clases de aplicaciones web
Página de inicio de DIYables
Centro de navegación central que ofrece enlaces a todas las aplicaciones habilitadas.
Constructor
Ruta URL
- Ruta: / (raíz)
Página de chat web de DIYables
Interfaz de chat interactiva para la comunicación bidireccional con Arduino.
Constructor
Ruta URL
- Ruta: /webchat
Métodos
Establece la función de devolución de llamada para los mensajes de chat entrantes.
Envía un mensaje a la interfaz de chat web.
Página de monitoreo web de DIYables
Monitor serial basado en la web para salida en tiempo real y entrada de comandos.
Constructor
Ruta de la URL
- Ruta: /webmonitor
Métodos
Configura la función de devolución de llamada para los mensajes entrantes del monitor.
Envía un mensaje a la interfaz de monitoreo web.
DIYablesWebDigitalPinsPage
Controlar y monitorear los pines digitales del 0 al 13 a través de una interfaz web.
Constructor
Ruta de la URL
- Ruta: /webdigitalpins
Métodos
Habilita un PIN para el control web.
- pin: Número de pin (0-13)
- mode: WEB_PIN_OUTPUT o WEB_PIN_INPUT
Configura una función de devolución de llamada para las operaciones de escritura de pines (pines de salida).
Establece una función de devolución de llamada para las operaciones de lectura de pines (pines de entrada).
Establece una función de devolución de llamada para cambios en el modo del pin.
Actualiza el estado del pin en tiempo real para clientes web.
Página de deslizador web de DIYables
Control deslizante dual para aplicaciones analógicas y PWM.
Constructor
Ruta de la URL
- Ruta: /webslider
Métodos
Establece la función de devolución de llamada para los cambios en el valor del deslizador desde la web.
- Parámetros: slider1 (0-255), slider2 (0-255)
Configura una devolución de llamada para el cliente web que solicita valores actuales.
Envía los valores del deslizador a la interfaz web.
Página web del joystick de DIYables
Control de joystick 2D para robótica y aplicaciones de posicionamiento.
Constructor
- autoReturn: Si el joystick vuelve al centro automáticamente
- sensitivity: Porcentaje mínimo de movimiento para activar actualizaciones
Ruta de la URL
- Ruta: /webjoystick
Métodos
Establece la función de devolución de llamada para el movimiento del joystick desde la web.
- Parámetros: x (-100 a 100), y (-100 a 100)
Configura la función de devolución de llamada para el cliente web que solicita la posición actual.
Envía la posición del joystick a la interfaz web.
Establece el comportamiento de retorno automático.
Establece la sensibilidad de movimiento (porcentaje).
Página del Plotter Web de DIYables
Visualización de datos en tiempo real con soporte para múltiples series de datos.
Constructor
Ruta de la URL
- Ruta: /webplotter
Métodos
Establece el título del gráfico.
Establece las etiquetas de los ejes.
Activa o desactiva la escala automática del eje Y.
Establece el número máximo de puntos de datos que se mostrarán.
Añade un punto de datos a una serie.
Borra todos los datos del gráfico.
Página no encontrada de DIYables
Página de error 404 opcional para una mejor experiencia de usuario.
Constructor
Ejemplo de uso básico
Visión general de las aplicaciones web
Página de Inicio
- URL: http://[esp32-ip]/
- Propósito: Centro de navegación central
- Características: Enlaces a todas las aplicaciones habilitadas, estado de conexión
Aplicación de WebChat
- URL: http://[esp32-ip]/webchat
- Propósito: Interfaz de comunicación bidireccional
- Características: Mensajería en tiempo real, historial de mensajes, estado de WebSocket
Monitor web
- URL: http://[esp32-ip]/webmonitor
- Propósito: Reemplazo del monitor serial
- Características: Salida serial en tiempo real, entrada de comandos, tema oscuro
Control de pines digitales en la web
- URL: http://[esp32-ip]/webdigitalpins
- Propósito: Control de pines digitales 0-13
- Características: Control individual de pines, operaciones en lote, estado en tiempo real
Control deslizante web
- URL: http://[esp32-ip]/webslider
- Propósito: Control analógico/PWM dual
- Características: Dos deslizadores independientes (0-255), valores predefinidos, retroalimentación en tiempo real
Control de Joystick Web
- URL: http://[esp32-ip]/webjoystick
- Propósito: control de posición 2D para robots/vehículos
- Características: control táctil y de ratón, visualización de coordenadas, ajuste de sensibilidad
Trazador Web
- URL: http://[esp32-ip]/webplotter
- Propósito: Visualización de datos en tiempo real
- Características: Varias series de datos, autoescalado, títulos y ejes configurables
Comunicación WebSocket
Todas las aplicaciones utilizan WebSocket en el puerto 81 para la comunicación en tiempo real:
- URL de WebSocket: ws://[esp32-ip]:81
- Conexión: Reconexión automática ante la desconexión
- Protocolo: Formato de mensaje basado en texto
Formatos de mensajes
Mensajes de WebChat
- Desde la web: mensaje de texto directo
- A la web: mensaje de texto directo
Mensajes del Monitor Web
- Desde la Web: Mensaje de texto directo
- Para la Web: Mensaje de texto directo
Mensajes PIN Digital de la Web
- Desde la web: Formato JSON: {"pin": 13, "state": 1}
- A la web: Formato JSON: {"pin": 13, "state": 1}
Mensajes del control deslizante web
- Desde la Web: formato JSON: {"slider1": 128, "slider2": 255}
- A la Web: formato JSON: {"slider1": 128, "slider2": 255}
Mensajes del Joystick Web
- Desde la web: Formato JSON: {"x": 50, "y": -25}
- Para la web: Formato JSON: {"x": 50, "y": -25}
Mensajes del Plotter Web
- Desde la Web: No aplica (solo visualización)
- Para la Web: Formato JSON: {"series": "temp", "x": 10.5, "y": 23.4}
Manejo de errores
La biblioteca incluye manejo automático de errores para:
- Fallos de la conexión WiFi
- Desconexiones de WebSocket
- Formatos de mensajes no válidos
- Límites de conexión de clientes
Uso de memoria
Beneficios de la Arquitectura Modular: Incluya solo las aplicaciones web que necesite para optimizar el uso de la memoria.
Uso de memoria aproximado por componente:
- DIYablesWebAppServer: ~8KB de Flash, ~2KB de RAM
- DIYablesHomePage: ~3KB de Flash, ~1KB de RAM
- DIYablesWebChatPage: ~6KB de Flash, ~1.5KB de RAM
- DIYablesWebMonitorPage: ~5KB de Flash, ~1.5KB de RAM
- DIYablesWebDigitalPinsPage: ~8KB de Flash, ~2KB de RAM
- DIYablesWebSliderPage: ~6KB de Flash, ~1.5KB de RAM
- DIYablesWebJoystickPage: ~7KB de Flash, ~1.5KB de RAM
- DIYablesWebPlotterPage: ~10KB de Flash, ~2KB de RAM
- WebSocket Buffer: ~1KB de RAM por conexión
Total si se activan todas las apps: ~53KB Flash, ~12KB RAM
Configuración mínima (servidor + hogar + 1 aplicación): ~17KB de Flash, ~4.5KB de RAM
Notas de Seguridad
- No hay autenticación implementada (solo para redes locales)
- Utilícelo solo en redes de confianza
- Considere añadir autenticación para implementaciones públicas
Solución de problemas
Problemas comunes
- No se puede conectar a Wi-Fi
- Verificar el SSID y la contraseña
- Verificar que la red sea de 2,4 GHz (no 5 GHz)
- Comprobar la intensidad de la señal
- La conexión WebSocket falla
- Verifique que la dirección IP sea correcta
- Verificar la configuración del cortafuegos.
- Prueba con otro navegador
- Alto consumo de memoria
- Desactivar las aplicaciones no utilizadas
- Límite de conexiones simultáneas
- Reiniciar el ESP32 si se produce fragmentación de la memoria.
- Respuesta lenta
- Ver la intensidad de la señal WiFi
- Reducir la frecuencia de mensajes de WebSocket
- Usa funciones de devolución de llamada más cortas
Proyectos de ejemplo
Ejemplos de aplicaciones
La biblioteca ESP32 WebApps de DIYables incluye ejemplos completos diseñados para la plataforma educativa ESP32:
Ejemplos disponibles
- Ejemplo de chat: Interfaz de comunicación bidireccional
- Ejemplo de WebMonitor: Reemplazo del monitor serie con características mejoradas
- Ejemplo de WebDigitalPins: Controlar todos los pines digitales con retroalimentación visual
- Ejemplo de WebSlider: Control analógico/PWM dual con preajustes
- Ejemplo de WebJoystick: Control de posición 2D para proyectos de robótica
- Ejemplo de MultipleWebApps: Todas las aplicaciones funcionando simultáneamente
Consulte la carpeta examples/ para proyectos completos y la carpeta docs/ para instrucciones detalladas de configuración.
Interfaces de Abstracción de Plataforma
La biblioteca DIYables ESP32 WebApps utiliza una capa de abstracción de plataforma con interfaces que permiten soporte para múltiples plataformas de hardware. Estas interfaces separan la funcionalidad central de WebApp de las implementaciones específicas de la plataforma.
Interfaces principales
IWebClient
Interfaz para conexiones de cliente HTTP.
IWebSocket
Interfaz para conexiones WebSocket con soporte de comunicación bidireccional.
IWebServer
Interfaz para la funcionalidad del servidor HTTP.
IWebSocketServer
Interfaz para un servidor WebSocket con gestión de conexiones.
IProveedorDeRed
Interfaz para la gestión de la conectividad de red.
IServerFactory
Interfaz de fábrica para crear implementaciones específicas de la plataforma.
Ejemplo de implementación de la plataforma
Para ESP32, las interfaces están implementadas utilizando la biblioteca DIYables_ESP32_WebServer:
Añadiendo Soporte para Nuevas Plataformas
Para añadir soporte a una nueva plataforma (p. ej., ESP32):
- Implementa todas las interfaces para la plataforma objetivo
- Crea un ServerFactory que instancie tus implementaciones
- Gestiona la conectividad de red específica de la plataforma y los protocolos WebSocket
- Prueba con las clases WebApp existentes (no se requieren cambios)
Ejemplos de uso con diferentes plataformas:
Beneficios del diseño basado en interfaces
- Independencia de la plataforma: La lógica central de WebApp funciona en cualquier plataforma
- Extensibilidad: Es fácil añadir soporte para nuevo hardware
- Mantenibilidad: El código específico de la plataforma está aislado
- Testabilidad: Las interfaces pueden ser simuladas para pruebas unitarias
- Consistencia: La misma API en todas las plataformas compatibles
Soporte actual de la plataforma
- ✅ ESP32: Totalmente implementado y probado
- 🔄 ESP32: Disponible como extensión independiente - DIYables_WebApps_ESP32
- 🚀 Plataformas futuras: Se pueden añadir utilizando el mismo patrón de interfaz