Référence de l’API de la bibliothèque DIYables ESP32 WebApps - Documentation complète
Vue d'ensemble
La bibliothèque DIYables ESP32 WebApps fournit une solution complète et modulaire pour créer des applications Web basées sur WebSocket sur l'ESP32. Elle comprend plusieurs applications Web préconstruites et un cadre flexible pour la création d'applications personnalisées.
La bibliothèque utilise une architecture modulaire où vous n'incluez que les applications web dont vous avez besoin, ce qui permet d'économiser de la mémoire et d'améliorer les performances.
Fonctionnalités
- Architecture modulaire: Ajoutez uniquement les applications web dont vous avez besoin pour optimiser l'utilisation de la mémoire
- Économe en mémoire: Chaque application web peut être activée/désactivée de manière indépendante
- 11+ Applications web prêtes à l'emploi: Contrôle complet de l'ESP32 sans connaissances en programmation web
- Cadre d'applications web personnalisé: Créez vos propres applications en utilisant le système de classes de base
- Communication en temps réel: Basée sur WebSocket pour des mises à jour instantanées
- Conception réactive: Fonctionne sur ordinateur de bureau, tablette et appareils mobiles
- Intégration facile: API simple basée sur des callbacks
- Support de plusieurs applications: Prise en charge de l'ajout de plusieurs applications web simultanément
Classes fondamentales
Serveur d'applications Web DIYables
La classe principale du serveur qui gère les applications web, les requêtes HTTP et la communication WebSocket.
Constructeur
Crée une instance de serveur d'applications web.
- httpPort: port du serveur HTTP (par défaut : 80)
- websocketPort: port du serveur WebSocket (par défaut : 81)
Méthodes
Configuration et connexion
Initialise la connexion réseau (pour Ethernet ou des connexions préconfigurées) et démarre le serveur web.
- Retour: vrai si réussi, faux si échoué
- Cas d'utilisation: Pour un support Ethernet futur ou lorsque les identifiants Wi-Fi sont préconfigurés
Initialise la connexion WiFi et démarre le serveur web.
- ssid: nom du réseau WiFi
- password: Mot de passe du réseau WiFi
- Renvoie: vrai si réussi, faux sinon
- Cas d'utilisation: Connexion WiFi standard avec des identifiants
Gère les requêtes HTTP et la communication WebSocket. Doit être appelé dans la boucle principale.
Renvoie vrai si le Wi‑Fi est connecté.
Renvoie l'adresse IP de l'Arduino sous forme de chaîne de caractères.
Gestion des applications
Ajoute une application web au serveur.
- app: Pointeur vers une instance d'une application Web
Supprime une application web par son chemin d'URL.
- path: chemin d'URL de l'application (par exemple, "/chat")
Récupère une application Web par son chemin d'URL.
- Chemin: chemin URL de l'application
- Retour: Pointeur vers l'application ou nullptr si non trouvé
Définit la page 404 Non trouvée (facultatif).
- page: instance de page 404
Accès à des applications spécialisées
Obtient l'instance de la page des broches numériques si elle est ajoutée.
- Renvoie: pointeur vers la page des broches numériques ou nullptr
Récupère l'instance de la page du curseur si elle est ajoutée.
Renvoie: pointeur vers la page du curseur ou nullptr
Obtient l'instance de la page du joystick si elle est ajoutée.
- Retour: Pointeur vers la page du joystick ou nullptr
Classes de base
DIYablesWebAppPageBase
Classe de base abstraite dont toutes les applications Web héritent. Fournit des fonctionnalités communes pour la gestion HTTP, la communication WebSocket et la gestion des pages.
Constructeur
Crée une instance de page de base avec le chemin d'URL spécifié.
- pagePath: chemin d'URL de la page (par exemple, "/web-joystick")
Méthodes virtuelles (Doivent être implémentées par les classes dérivées)
Gère les requêtes HTTP pour cette page. Méthode virtuelle pure.
- client: Interface client Web pour l'envoi de la réponse
Gère les messages WebSocket pour cette page. Méthode virtuelle pure.
- ws: interface de connexion WebSocket
- message: contenu du message reçu
- length: longueur du message
Renvoie la chaîne d'identification de la page utilisée dans l'affichage des informations de connexion. Méthode virtuelle pure.
- Retour: chaîne d'informations de la page (par exemple, "🕹️ Joystick Web: ")
Renvoie le HTML du bouton de navigation de la page d'accueil. Méthode virtuelle pure.
- Retour: chaîne HTML pour la carte de navigation
Méthodes virtuelles (réécritures optionnelles)
Appelé lorsqu'une nouvelle connexion WebSocket est établie.
- ws: nouvelle connexion WebSocket
Appelé lorsque la connexion WebSocket est fermée.
- ws: connexion WebSocket fermée
Méthodes courantes
Récupère le chemin URL de cette page.
- Retour: Chaîne représentant le chemin de la page
Vérifie si la page est actuellement activée.
- Renvoie: vrai si activé, faux si désactivé
Activer ou désactiver la page.
- activer: true pour activer, false pour désactiver
Méthodes utilitaires
Envoie les en-têtes HTTP standard au client.
- client: Interface du client Web
- contentType: type MIME (valeur par défaut : "text/html")
Envoie un message à un client WebSocket spécifique.
- ws: Connexion WebSocket cible
- message: Message à envoyer
Diffuse un message à tous les clients WebSocket connectés.
- message: Message à diffuser
Envoie du contenu HTML volumineux en utilisant le transfert par morceaux.
- client: interface du client Web
- html: contenu HTML à envoyer
Exemple d'utilisation
Classes d'applications Web
Page d'accueil de DIYables
Centre de navigation central fournissant des liens vers toutes les applications activées.
Constructeur
Chemin d'URL
- Chemin: / (racine)
Page Web du chat DIYables
Interface de chat interactive pour une communication bidirectionnelle avec Arduino.
Constructeur
Chemin de l'URL
- Chemin: /webchat
Méthodes
Définit la fonction de rappel pour les messages de chat entrants.
Envoie un message à l'interface du chat Web.
Page de surveillance Web de DIYables
Moniteur série basé sur le Web pour la sortie en temps réel et l'entrée de commandes.
Constructeur
Chemin d'URL
- Chemin: /webmonitor
Méthodes
Définit la fonction de rappel pour les messages entrants du moniteur.
Envoie un message à l'interface du moniteur Web.
Page Web des Épingles Numériques DIYables
Contrôlez et surveillez les broches numériques 0 à 13 via l'interface Web.
Constructeur
Chemin de l'URL
- Chemin: /webdigitalpins
Méthodes
Active un PIN pour le contrôle Web.
- pin: Numéro de broche (0-13)
- mode: WEB_PIN_OUTPUT ou WEB_PIN_INPUT
Définit la fonction de rappel pour les opérations d’écriture sur les broches (broches de sortie).
Définit la fonction de rappel pour les opérations de lecture des broches (broches d'entrée).
Définit la fonction de rappel pour les changements de mode des broches.
Actualise l'état du pin en temps réel pour les clients web.
DIYablesWebSliderPage
Contrôle à deux curseurs pour les applications analogiques et PWM.
Constructeur
Chemin d'URL
- Chemin: /webslider
Méthodes
Définit la fonction de rappel pour les changements de valeur du curseur à partir du Web.
- Paramètres: slider1 (0-255), slider2 (0-255)
Définit la fonction de rappel pour le client Web qui demande les valeurs actuelles.
Envoie les valeurs des curseurs à l'interface web.
Page Web du Joystick DIYables
Contrôle par joystick 2D pour la robotique et les applications de positionnement.
Constructeur
- autoReturn: Retour automatique du joystick au centre
- sensitivity: Pourcentage minimum de déplacement pour déclencher les mises à jour
Chemin d'URL
- Chemin: /webjoystick
Méthodes
Définit la fonction de rappel pour le déplacement du joystick depuis le Web.
- Paramètres : x (-100 à 100), y (-100 à 100)
Définit la fonction de rappel pour le client web qui demande la position actuelle.
Transmet la position du joystick à l'interface Web.
Définit le comportement de retour automatique.
Définit la sensibilité du déplacement (pourcentage).
Page du traceur Web de DIYables
Visualisation des données en temps réel avec prise en charge de plusieurs séries de données.
Constructeur
Chemin d'URL
- Chemin: /webplotter
Méthodes
Définit le titre du graphique.
Définit les étiquettes des axes.
Activation ou désactivation de la mise à l'échelle automatique de l'axe des ordonnées.
Définit le nombre maximum de points de données à afficher.
Ajoute un point de données à une série.
Efface toutes les données du graphique.
Page non trouvée de DIYables
Page d'erreur 404 optionnelle pour une meilleure expérience utilisateur.
Constructeur
Exemple d'utilisation de base
Aperçu des applications web
Page d'accueil
- URL: http://[esp32-ip]/
- But: Centre de navigation central
- Fonctionnalités: Liens vers toutes les applications activées, état de connexion
Application WebChat
- URL: http://[esp32-ip]/webchat
- Objectif: Interface de communication bidirectionnelle
- Fonctionnalités: Messagerie en temps réel, historique des messages, statut du WebSocket
Moniteur Web
- URL: http://[esp32-ip]/webmonitor
- Objectif: remplacement du moniteur série
- Caractéristiques: Sortie série en temps réel, saisie de commandes, thème sombre
Contrôle des broches numériques via le Web
- URL: http://[esp32-ip]/webdigitalpins
- But: Contrôle des broches numériques 0-13
- Caractéristiques: Contrôle individuel des broches, opérations en bloc, état en temps réel
Contrôle de curseur Web
- URL: http://[esp32-ip]/webslider
- Objectif: Contrôle analogique et PWM double
- Caractéristiques: Deux curseurs indépendants (0-255), valeurs prédéfinies, retour en temps réel
Contrôle du joystick Web
- URL: http://[esp32-ip]/webjoystick
- Objectif: Contrôle de position 2D pour les robots/véhicules
- Fonctionnalités: Contrôle tactile/souris, affichage des coordonnées, réglage de sensibilité
Traceur Web
- URL: http://[esp32-ip]/webplotter
- Objectif: Visualisation des données en temps réel
- Fonctionnalités: Plusieurs séries de données, mise à l'échelle automatique, titres et axes configurables
Communication WebSocket
Toutes les applications utilisent WebSocket sur le port 81 pour la communication en temps réel :
- URL WebSocket: ws://[esp32-ip]:81
- Connexion: Reconnexion automatique en cas de déconnexion
- Protocole: format de message textuel
Formats de messages
Messages de WebChat
- Depuis le Web: Message texte direct
- Vers le Web: Message texte direct
Messages du Moniteur Web
- Depuis le Web: message texte direct
- Vers le Web: message texte direct
Messages épinglés du Web numérique
- Depuis le Web : format JSON : {"pin": 13, "state": 1}
- Vers le Web : format JSON : {"pin": 13, "state": 1}
Messages du curseur Web
- Depuis le Web : format JSON : {"slider1": 128, "slider2": 255}
- Vers le Web : format JSON : {"slider1": 128, "slider2": 255}
Messages du joystick sur le Web
- Depuis le Web: Format JSON : {"x": 50, "y": -25}
- Vers le Web: Format JSON : {"x": 50, "y": -25}
Messages du traceur Web
- Depuis le Web: Non applicable (affichage uniquement)
- Vers le Web: Format JSON : {"series": "temp", "x": 10.5, "y": 23.4}
Gestion des erreurs
La bibliothèque comprend une gestion automatique des erreurs pour :
- Pannes de connexion Wi-Fi
- Déconnexions WebSocket
- Formats de messages invalides
- Limites de connexion des clients
Utilisation de la mémoire
Avantages de l'architecture modulaire: Incluez uniquement les applications web dont vous avez besoin pour optimiser l'utilisation de la mémoire.
Utilisation approximative de la mémoire par composant :
- DIYablesWebAppServer: ~8 Ko de mémoire Flash, ~2 Ko de RAM
- DIYablesHomePage: ~3 Ko de mémoire Flash, ~1 Ko de RAM
- DIYablesWebChatPage: ~6 Ko de mémoire Flash, ~1,5 Ko de RAM
- DIYablesWebMonitorPage: ~5 Ko de mémoire Flash, ~1,5 Ko de RAM
- DIYablesWebDigitalPinsPage: ~8 Ko de mémoire Flash, ~2 Ko de RAM
- DIYablesWebSliderPage: ~6 Ko de mémoire Flash, ~1,5 Ko de RAM
- DIYablesWebJoystickPage: ~7 Ko de mémoire Flash, ~1,5 Ko de RAM
- DIYablesWebPlotterPage: ~10 Ko de mémoire Flash, ~2 Ko de RAM
- WebSocket Buffer: ~1 Ko de RAM par connexion
Total si toutes les applications sont activées : ~53 Ko de mémoire flash, ~12 Ko de RAM
Configuration minimale (serveur + domicile + 1 appli) : ~17 Ko de mémoire flash, ~4,5 Ko de RAM
Notes de sécurité
- Aucune authentification n'est mise en œuvre (réseaux locaux uniquement)
- Utiliser uniquement sur des réseaux de confiance
- Envisagez d'ajouter une authentification pour les déploiements publics
Dépannage
Problèmes courants
- Impossible de se connecter au Wi-Fi
- Vérifier le SSID et le mot de passe
- Vérifiez que le réseau est en 2,4 GHz (et non en 5 GHz)
- Vérifier la force du signal
- La connexion WebSocket échoue
- Vérifiez que l'adresse IP est correcte
- Vérifier les paramètres du pare-feu.
- Essayez un autre navigateur
- Utilisation élevée de la mémoire
- Désactiver les applications inutilisées
- Limiter les connexions simultanées
- Redémarrer l'ESP32 si une fragmentation de la mémoire se produit
- Réponse lente
- Vérifier la force du signal Wi-Fi
- Réduire la fréquence des messages WebSocket
- Utilisez des fonctions de rappel plus courtes
Exemples de projets
Exemples d'applications
La bibliothèque ESP32 WebApps de DIYables comprend des exemples complets conçus pour la plateforme éducative ESP32 :
Exemples disponibles
- Exemple de chat: Interface de communication bidirectionnelle
- Exemple WebMonitor: Remplacement du moniteur série par des fonctionnalités améliorées
- Exemple WebDigitalPins: Contrôle de toutes les broches numériques avec rétroaction visuelle
- Exemple WebSlider: Contrôle double analogique/PWM avec des préréglages
- Exemple WebJoystick: Contrôle de position en 2D pour des projets robotiques
- Exemple MultipleWebApps: Toutes les applications fonctionnent simultanément
Consultez le dossier examples/ pour des projets complets et le dossier docs/ pour des instructions d'installation détaillées.
Interfaces d'abstraction de la plateforme
La bibliothèque ESP32 WebApps de DIYables utilise une couche d’abstraction de plateforme avec des interfaces qui permettent la prise en charge de plusieurs plates-formes matérielles. Ces interfaces séparent la fonctionnalité centrale des WebApps de leurs implémentations spécifiques à la plateforme.
Interfaces de base
IWebClient
Interface pour les connexions du client HTTP.
IWebSocket
Interface pour les connexions WebSocket avec prise en charge de la communication bidirectionnelle.
IWebServer
Interface pour la fonctionnalité du serveur HTTP.
IWebSocketServer
Interface pour le serveur WebSocket avec gestion des connexions.
INetworkProvider
Interface de gestion de la connectivité réseau.
IFabriqueServeur
Interface de fabrique pour la création d'implémentations spécifiques à la plateforme.
Exemple d'implémentation de la plateforme
Pour l'ESP32, les interfaces sont implémentées en utilisant la bibliothèque DIYables_ESP32_WebServer :
Ajout du support pour une nouvelle plateforme
Pour ajouter la prise en charge d'une nouvelle plateforme (par exemple ESP32) :
- Implémentez toutes les interfaces pour la plateforme cible
- Créez une ServerFactory qui instancie vos implémentations
- Gérez le réseau spécifique à la plateforme et les protocoles WebSocket
- Testez avec les classes WebApp existantes (aucun changement nécessaire)
Exemple d’utilisation avec différentes plateformes :
Avantages de la conception basée sur les interfaces
- Indépendance de la plateforme: La logique centrale de WebApp fonctionne sur n'importe quelle plateforme
- Extensibilité: Facile d'ajouter la prise en charge de nouveaux matériels
- Maintenabilité: Le code spécifique à la plateforme est isolé
- Testabilité: Les interfaces peuvent être simulées pour les tests unitaires
- Cohérence: La même API sur toutes les plateformes prises en charge
Support de la plateforme actuelle
- ✅ ESP32: Entièrement implémenté et testé
- 🔄 ESP32: Disponible en tant qu’extension séparée - DIYables_WebApps_ESP32
- 🚀 Plateformes futures: Peuvent être ajoutées en utilisant le même modèle d’interface