Référence API de la bibliothèque WebApps de DIYables - Documentation complète
Vue d'ensemble
La bibliothèque WebApps de DIYables fournit une solution complète et modulaire pour créer des applications Web basées sur WebSocket sur les plateformes Arduino Uno R4 WiFi et DIYables STEM V4 IoT. Elle comprend plusieurs applications Web préconstruites et un cadre flexible pour créer des applications personnalisées. Spécialement optimisée pour la plateforme éducative DIYables STEM V4 IoT avec des capacités IoT améliorées et une intégration de capteurs intégrée.
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 indépendamment
- 11+ applications web prêtes à l'emploi: Contrôle Arduino complet sans connaissances en programmation web
- Cadre d'applications web personnalisées: Créez vos propres applications en utilisant le système de classes de base
- Communication en temps réel: Basé sur WebSocket pour des mises à jour instantanées
- Conception réactive: Fonctionne sur ordinateurs de bureau, tablettes 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
- Plateforme extensible: Actuellement implémenté pour Arduino Uno R4 WiFi, mais peut être étendu à d'autres plateformes matérielles. Voir DIYables_WebApps_ESP32
Classes centrales
DIYablesServeur d'application Web
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 l'opération réussit, faux sinon
- Cas d'utilisation: Pour une prise en charge Ethernet à venir ou lorsque les identifiants WiFi sont préconfigurés
Initialise la connexion Wi-Fi et démarre le serveur Web.
- ssid: nom du réseau WiFi
- password: mot de passe WiFi
- Returns: vrai si réussi, faux si échoué
- Use case: connexion WiFi standard avec identifiants
Gère les requêtes HTTP et la communication WebSocket. Doit être appelée dans la boucle principale.
Renvoie vrai si le WiFi est connecté.
Renvoie l'adresse IP de l'Arduino sous forme de chaîne.
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.
- chemin: chemin URL de l'application (par exemple, "/chat")
Récupère une application Web à partir de 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.
- Retour: Pointeur vers la page des broches numériques ou nullptr
Obtient l’instance de la page du slider si elle est ajoutée.
- Renvoie: Pointeur vers la page du curseur ou nullptr
Obtient l'instance de la page 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 de l'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 d'une 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 ex., "🕹️ Joystick Web: ")
Renvoie le HTML pour le bouton de navigation de la page d'accueil. Méthode virtuelle pure.
- Retour: chaîne HTML pour la carte de navigation
Méthodes virtuelles (redéfinitions 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
Obtient le chemin d'URL de cette page.
- Renvoie: chaîne représentant le chemin de la page
Vérifie si la page est actuellement activée.
- Retour: vrai si activé, faux si désactivé
Activer ou désactiver la page.
- activer: vrai pour activer, faux pour désactiver
Méthodes utilitaires
Envoie les en-têtes HTTP standards au client.
- client: Interface du client Web
- contentType: Type MIME (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 un grand contenu HTML en utilisant l'encodage 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 de chat Web de DIYables
Interface de chat interactive pour une communication bidirectionnelle avec Arduino.
Constructeur
Chemin d'URL
- Chemin: /webchat
Méthodes
Définit le rappel pour les messages de chat entrants.
Envoyer un message à l'interface de chat Web.
Page de surveillance du Web
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 des épingles numériques Web de DIYables
Contrôler et surveiller les broches numériques 0 à 13 via une interface Web.
Constructeur
Chemin d'URL
- Chemin: /webdigitalpins
Méthodes
Activer une broche 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 le rappel pour les opérations de lecture des broches (broches d'entrée).
Définit une fonction de rappel pour les changements de mode des broches.
Met à jour l'état du pin en temps réel pour les clients Web.
DIYablesWebSliderPage
Contrôle à double curseur 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 depuis le 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 Joystick Web DIYables
Contrôle par joystick 2D pour la robotique et les applications de positionnement.
Constructeur
- autoReturn: Si le joystick revient automatiquement au centre
- sensitivity: Pourcentage de déplacement minimum pour déclencher les mises à jour
Chemin d'URL
- Chemin: /webjoystick
Méthodes
Définit une fonction de rappel pour le mouvement 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.
Envoie la position du joystick à l'interface Web.
Définit le comportement de retour automatique.
Définit la sensibilité au mouvement (en pourcentage).
DIYablesWebPlotterPage
Visualisation de 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.
DIYablesPageIntrouvable
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://[arduino-ip]/
- Objectif : Centre de navigation central
- Fonctionnalités : Liens vers toutes les applications activées, État de connexion
Application WebChat
- URL: http://[arduino-ip]/webchat
- But: Interface de communication bidirectionnelle
- Fonctionnalités: Messagerie en temps réel, historique des messages, État du WebSocket
Moniteur Web
- URL: http://[arduino-ip]/webmonitor
- Objectif: Remplacement du moniteur série
- Fonctionnalités: Sortie série en temps réel, entrée de commande, thème sombre
Contrôle des broches numériques Web
- URL: http://[arduino-ip]/webdigitalpins
- But: Contrôler les broches numériques 0-13
- Caractéristiques: Contrôle individuel des broches, opérations par lots, état en temps réel
Contrôle de curseur Web
- URL: http://[arduino-ip]/webslider
- But: 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://[arduino-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 la sensibilité
Traceur Web
- URL: http://[arduino-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 du WebSocket: ws://[arduino-ip]:81
- Connexion: Reconnexion automatique en cas de déconnexion
- Protocole: Format de message basé sur du texte
Formats des messages
Messages 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 numériques épinglés sur le Web
- 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 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)
- Pour 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 mémoire Flash, ≈2 Ko RAM
- DIYablesHomePage: ≈3 Ko mémoire Flash, ≈1 Ko RAM
- DIYablesWebChatPage: ≈6 Ko mémoire Flash, ≈1,5 Ko RAM
- DIYablesWebMonitorPage: ≈5 Ko mémoire Flash, ≈1,5 Ko RAM
- DIYablesWebDigitalPinsPage: ≈8 Ko mémoire Flash, ≈2 Ko RAM
- DIYablesWebSliderPage: ≈6 Ko mémoire Flash, ≈1,5 Ko RAM
- DIYablesWebJoystickPage: ≈7 Ko mémoire Flash, ≈1,5 Ko RAM
- DIYablesWebPlotterPage: ≈10 Ko mémoire Flash, ≈2 Ko RAM
- Tampon WebSocket: ≈1 Ko RAM par connexion
Total si toutes les applications sont activées: ~53 Ko mémoire flash, ~12 Ko RAM
Configuration minimale (serveur + domicile + 1 application) : ~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 dans des réseaux de confiance
- Envisagez d'ajouter une authentification pour les déploiements publics
Dépannage
Problèmes courants
i. Impossible de se connecter au Wi-Fi
- Vérifier le SSID et le mot de passe
- Vérifier que le réseau est en 2,4 GHz (pas 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 navigateur différent
- Forte utilisation de la mémoire
- Désactiver les applications non utilisées
- Limiter les connexions simultanées
- Redémarrer l'Arduino en cas de fragmentation de mémoire.
- Réponse lente
- Vérifier la puissance 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 WebApps de DIYables comprend des exemples complets conçus pour la plateforme éducative Arduino Uno R4 WiFi et DIYables STEM V4 IoT:
Exemples disponibles
- Exemple de chat: Interface de communication bidirectionnelle
- Exemple de WebMonitor: Remplacement du moniteur série par des fonctionnalités améliorées
- Exemple de WebDigitalPins: Contrôlez toutes les broches numériques avec un retour visuel
- Exemple de WebSlider: Contrôle analogique/PWM double avec des préréglages
- Exemple de WebJoystick: Contrôle de position en 2D pour des projets robotiques
- Exemple de MultipleWebApps: Toutes les applications fonctionnent simultanément
Compatibilité matérielle
- Recommandé : DIYables STEM V4 IoT (fonctionnalités améliorées, capteurs intégrés)
- Compatible : Arduino Uno R4 WiFi
Ressources des tutoriels
Des tutoriels complets étape par étape disponibles sur :
- Newbiely.com/tutorials/arduino/arduino-uno-r4-wifi-web-apps
- Guides IoT spécifiques STEM V4 de DIYables et des exemples d'intégration de capteurs
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 plate-forme
La bibliothèque WebApps DIYables utilise une couche d'abstraction de plate-forme avec des interfaces qui permettent de prendre en charge plusieurs plate-formes matérielles. Ces interfaces séparent les fonctionnalités centrales des WebApps de leurs implémentations spécifiques à la plate-forme.
Interfaces centrales
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 un serveur WebSocket avec la gestion des connexions.
IFournisseurDeRéseau
Interface de gestion de la connectivité réseau.
IFabriqueServeur
Interface de fabrique pour la création d'implémentations spécifiques à la plateforme.
Exemple de mise en œuvre de la plateforme
Pour l'Arduino Uno R4 WiFi, les interfaces sont implémentées en utilisant la bibliothèque UnoR4WiFi_WebServer :
Ajout du support pour une nouvelle plateforme
Pour ajouter la prise en charge d'une nouvelle plateforme (par exemple, l'ESP32) :
- Implémentez toutes les interfaces pour la plate-forme cible
- Créez une ServerFactory qui instancie vos implémentations
- Gérez le réseau spécifique à la plate-forme 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 vis-à-vis de la plateforme: La logique Core 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
- ✅ Arduino Uno R4 WiFi: 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