Referencia de la API de la Biblioteca WebApps de DIYables - Documentación completa
Visión general
La biblioteca WebApps de DIYables ofrece una solución completa y modular para crear aplicaciones web basadas en WebSocket en Arduino Uno R4 WiFi y DIYables STEM V4 IoT. Incluye varias aplicaciones web preconstruidas y un marco flexible para crear aplicaciones personalizadas. Especialmente optimizada para la plataforma educativa DIYables STEM V4 IoT con capacidades IoT mejoradas y una integración de sensores incorporada.
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
- Memoria eficiente: Cada aplicación web puede habilitarse/deshabilitarse de forma independiente
- 11+ Aplicaciones web listas para usar: Control total de Arduino sin conocimientos de programación web
- Framework de aplicaciones web personalizado: Crea tus propias aplicaciones utilizando el sistema de clases base
- Comunicación en tiempo real: Basado en WebSocket para actualizaciones instantáneas
- Diseño responsivo: Funciona en computadoras de escritorio, tabletas y dispositivos móviles
- Fácil integración: API basada en callbacks sencilla
- Soporte para múltiples aplicaciones: Soporte para añadir varias aplicaciones web de forma simultánea
- Plataforma extensible: Actualmente implementado para Arduino Uno R4 WiFi, pero puede ampliarse para otras plataformas de hardware. Ver DIYables_WebApps_ESP32
Clases principales
DIYablesWebAppServer
La clase principal del servidor que gestiona aplicaciones web, solicitudes HTTP y comunicación WebSocket.
Constructor
Crea una instancia de servidor de aplicaciones 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 compatibilidad futura con Ethernet 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: verdadero si tiene éxito, falso si falla
- Caso de uso: Conexión WiFi estándar con credenciales
Maneja las solicitudes HTTP y la comunicación WebSocket. Debe llamarse en el bucle principal.
Devuelve verdadero si WiFi está conectado.
Devuelve la dirección IP del Arduino como una cadena.
Gestión de Aplicaciones
Añade una aplicación web al servidor.
- aplicación: Puntero a una instancia de una aplicación web
Elimina una aplicación web por su ruta de la URL.
- ruta: ruta de la URL de la aplicación (p. ej., "/chat")
Obtiene una aplicación web por la ruta de su URL.
- ruta: ruta URL de la aplicación
- Devuelve: Puntero a la aplicación o nullptr si no se encuentra
Configura la página 404 No encontrada (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 añadido.
- Devuelve: Puntero a la página de pines digitales o nullptr
Obtiene la instancia de la página deslizante 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
DIYablesWebAppPageBase
Clase base abstracta de la que heredan todas las aplicaciones web. Proporciona funcionalidad común para el manejo de HTTP, la comunicación 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 clases derivadas)
Gestiona las peticiones HTTP para esta página. Método puramente virtual.
- cliente: Interfaz de cliente web para enviar una 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., "🕹️ Web Joystick: ")
Devuelve HTML para el botón de navegación de la página de inicio. Método virtual puro.
- Devoluciones: 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
Se llama cuando se cierra la 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.
- client: Interfaz de cliente web
- contentType: 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
Difunde un mensaje a todos los clientes WebSocket conectados.
- mensaje: Mensaje para difundir
Envía contenido HTML grande utilizando la codificación de transferencia en 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 proporciona enlaces a todas las aplicaciones habilitadas.
Constructor
Ruta URL
- Ruta: / (raíz)
DIYablesWebChatPage
Interfaz de chat interactiva para la comunicación bidireccional con Arduino
Constructor
Ruta de la URL
- Ruta: /webchat
Métodos
Configura la función de devolución de llamada para mensajes de chat entrantes.
Envía un mensaje a la interfaz de chat web.
Página de Monitoreo Web de DIYables
Monitor serie basado en la web para salida en tiempo real y entrada de comandos.
Constructor
Ruta de la URL
- Ruta: /webmonitor
Métodos
Establece la función de devolución de llamada para los mensajes entrantes del monitor.
Envía un mensaje a la interfaz del monitor web.
Página de Pines Digitales de DIYables Web
Controlar y monitorizar 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
Establece una función de devolución de llamada para 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).
Configura una devolución de llamada para cambios en el modo del pin.
Actualiza el estado del pin en tiempo real para los clientes web.
DIYablesWebSliderPage
Control deslizante dual para aplicaciones analógicas y PWM.
Constructor
Ruta de la URL
- Ruta: /webslider
Métodos
Establece la devolución de llamada para los cambios de valor del control deslizante desde la web.
- Parámetros: slider1 (0-255), slider2 (0-255)
Configura una función de devolución de llamada para el cliente web que solicita valores actuales.
Envía los valores de los deslizadores 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 regresa al centro automáticamente
- sensitivity: Porcentaje mínimo de movimiento para activar actualizaciones
Ruta de la URL
- Ruta: /webjoystick
Métodos
Establece una 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)
Establece una 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.
Ajusta 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.
Configura las etiquetas de los ejes.
Activa o desactiva el escalado automático del eje Y.
Establece el número máximo de puntos de datos que se muestran.
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://[arduino-ip]/
- Propósito: Centro de navegación central
- Características: Enlaces a todas las aplicaciones habilitadas, estado de la conexión
Aplicación WebChat
- URL: http://[arduino-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://[arduino-ip]/webmonitor
- Propósito: Reemplazo del monitor serie
- Características: Salida serie en tiempo real, entrada de comandos, tema oscuro
Control de Pines Digitales Web
- URL: http://[arduino-ip]/webdigitalpins
- Propósito: Controlar pines digitales 0-13
- Características: Control individual de pines, operaciones en bloque, estado en tiempo real
Control deslizante web
- URL: http://[arduino-ip]/webslider
- Propósito: Control analógico/PWM dual
- Características: Dos deslizadores independientes (0-255), valores preestablecidos, retroalimentación en tiempo real
Control de Joystick Web
- URL: http://[arduino-ip]/webjoystick
- Propósito: control de posición en 2D para robots/vehículos
- Características: control táctil/ratón, visualización de coordenadas, ajuste de sensibilidad
Plotter web
- URL: http://[arduino-ip]/webplotter
- Propósito: Visualización de datos en tiempo real
- Características: Múltiples series de datos, escalado automático, 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://[arduino-ip]:81
- Conexión: Reconexión automática al desconectarse
- Protocolo: Formato de mensajes 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
- A la web: Mensaje de texto directo
Mensajes de pines digitales en la web
- Desde la Web: formato JSON: {"pin": 13, "state": 1}
- A la Web: formato JSON: {"pin": 13, "state": 1}
Mensajes del deslizador web
- Desde la Web: formato JSON: {"slider1": 128, "slider2": 255}
- Para la Web: formato JSON: {"slider1": 128, "slider2": 255}
Mensajes del Joystick Web
- Desde la Web: Formato JSON: {"x": 50, "y": -25}
- A la Web: Formato JSON: {"x": 50, "y": -25}
Mensajes del plotter web
- Desde la Web: No aplica (solo para visualización)
- A la Web: Formato JSON: {"series": "temp", "x": 10.5, "y": 23.4}
Gestión de Errores
La biblioteca incluye el manejo automático de errores para:
- Fallos de conexión WiFi
- Desconexiones de WebSocket
- Formatos de mensajes inválidos
- Límites de conexiones 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 habilitan todas las aplicaciones: ~53KB de memoria Flash, ~12KB de memoria RAM
Configuración mínima (servidor + hogar + 1 aplicación): ~17 KB de memoria Flash, ~4.5 KB de RAM
Notas de Seguridad
- Sin autenticación implementada (solo para redes locales)
- Usar solo en redes de confianza
- Considera añadir autenticación para despliegues públicos
Solución de problemas
Problemas comunes
- No se puede conectar a Wi-Fi
- Verificar el SSID y la contraseña
- Verifica que la red sea de 2.4 GHz (no 5 GHz)
- Verificar la intensidad de la señal
- La conexión WebSocket falla
- Verificar que la dirección IP sea correcta
- Verifica la configuración del cortafuegos
- Prueba un navegador diferente
- Alto consumo de memoria
- Desactivar las aplicaciones no utilizadas
- Limitar conexiones concurrentes
- Reiniciar Arduino si se produce fragmentación de memoria
- Respuesta lenta
- Verificar la intensidad de la señal WiFi
- Reducir la frecuencia de los mensajes de WebSocket
- Usa funciones de devolución de llamada más cortas.
Proyectos de ejemplo
Ejemplos de aplicaciones
La biblioteca WebApps de DIYables incluye ejemplos integrales diseñados para Arduino Uno R4 WiFi y la plataforma educativa DIYables STEM V4 IoT:
Ejemplos disponibles
- Ejemplo de Chat: interfaz de comunicación bidireccional
- Ejemplo de WebMonitor: reemplazo del monitor serie con funciones mejoradas
- Ejemplo de WebDigitalPins: Controlar todos los pines digitales con retroalimentación visual
- Ejemplo de WebSlider: Control dual analógico/PWM con preajustes
- Ejemplo de WebJoystick: Control de posición en 2D para proyectos de robótica
- Ejemplo de MultipleWebApps: Todas las aplicaciones ejecutándose simultáneamente
Compatibilidad de hardware
- Recomendado: DIYables STEM V4 IoT (características mejoradas, sensores integrados)
- Compatible: Arduino Uno R4 WiFi
Recursos de Tutoriales
Tutoriales completos paso a paso disponibles en:
- Newbiely.com/tutorials/arduino/arduino-uno-r4-wifi-web-apps
- Guías específicas de IoT para STEM V4 de DIYables y ejemplos de integración de sensores
Consulta la carpeta examples/ para proyectos completos y la carpeta docs/ para instrucciones detalladas de configuración.
Interfaces de abstracción de la plataforma
La biblioteca DIYables WebApps utiliza una capa de abstracción de plataforma con interfaces que permiten dar soporte a múltiples plataformas de hardware. Estas interfaces separan la funcionalidad central de WebApp de las implementaciones específicas de la plataforma.
Interfaces centrales
IWebClient
Interfaz para conexiones de cliente HTTP.
IWebSocket
Interfaz para conexiones WebSocket con soporte de comunicación bidireccional
IServidorWeb
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 plataforma
Para Arduino Uno R4 WiFi, las interfaces se implementan utilizando la biblioteca UnoR4WiFi_WebServer:
Añadir soporte para nuevas plataformas
Para añadir soporte para una nueva plataforma (p. ej., ESP32):
- Implementar todas las interfaces para la plataforma objetivo
- Crear un ServerFactory que instancie tus implementaciones
- Manejar las redes específicas de la plataforma y los protocolos WebSocket
- Probar 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: Fácil de añadir soporte para hardware nuevo
- 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 soportadas
Soporte de la plataforma actual
- ✅ Arduino Uno R4 WiFi: Totalmente implementado y probado
- 🔄 ESP32: Disponible como extensión independiente - DIYables_WebApps_ESP32
- 🚀 Futuras plataformas: Pueden añadirse utilizando el mismo patrón de interfaz