Récupération de configuration Wi-Fi par AP et essais de recette
Un parcours de configuration Wi-Fi est prêt pour un produit lorsque l’utilisateur peut se remettre d’identifiants erronés, d’un routeur absent, d’une interruption ou d’une coupure d’alimentation sans reflasher le firmware. Concevez-le comme une machine à états bornée, avec résultat visible, identifiants protégés et retour volontaire à la configuration. Une soumission HTTP réussie vers l’appareil n’en constitue qu’une étape.
Cet article traite d’un point d’accès de configuration hébergé par l’appareil, suivi d’une connexion au routeur du client. Il concerne les produits Linux et MCU ; les API dépendent du pilote et du SDK choisis. Tous les délais et essais sont des propositions de conception, pas des performances mesurées.
Définir le succès avant de concevoir l’écran
Distinguez quatre jalons : le téléphone a envoyé une configuration candidate ; l’appareil s’est associé et authentifié ; il a obtenu une configuration IP utilisable ; le service applicatif requis a été joint. Pour un contrôleur local, le dernier critère peut être la découverte sur le réseau. Pour un produit cloud, il peut s’agir d’un enregistrement authentifié ou d’un échange de contrôle. Précisez quel jalon valide définitivement les nouveaux réglages.
Une panne cloud ne prouve pas que le mot de passe Wi-Fi est faux. Si Wi-Fi et DHCP ont réussi mais que le backend est indisponible, conservez l’état distinct « réseau configuré, service indisponible ». La politique produit doit décider si cet état permet de terminer l’installation, plutôt que de renvoyer continuellement l’utilisateur au formulaire de mot de passe.
Spécifiez bandes radio, modes de sécurité, encodage et longueur du SSID, réseaux masqués et exigences des réseaux d’entreprise. Réessayer ne permet pas à un module limité à 2,4 GHz de joindre un réseau exclusivement 5 GHz. WPA-Enterprise, portails captifs en amont et réseaux d’entreprise administrés exigent une prise en charge explicite ou une exclusion claire.
Rendre les changements de configuration transactionnels
Conservez la dernière configuration fonctionnelle séparément de la candidate en cours d’essai. Attribuez un identifiant à chaque tentative. Une nouvelle soumission du même identifiant doit retourner l’état de la même tentative, sans lancer plusieurs connexions simultanées. Une nouvelle tentative doit annuler ou remplacer l’ancienne de façon contrôlée.
Lorsque la plateforme le permet, testez les identifiants candidats sans remplacer immédiatement l’enregistrement durable connu comme fonctionnel. Après le critère de succès convenu, validez atomiquement un enregistrement versionné. Conservez intégrité et version de schéma, et définissez le comportement au démarrage si l’alimentation disparaît pendant l’écriture. Le chiffrement au repos nécessite une gestion appropriée des clés et ne remplace pas une configuration authentifiée.
Certains gestionnaires SDK enregistrent les identifiants avant la fin de la validation applicative. ESP-IDF 5.2.6 documente par exemple la vérification des identifiants stockés et les comportements d’échec/redémarrage dans son guide de provisionnement Wi-Fi. Il s’agit d’une contrainte d’intégration propre à la version. Vérifiez les API de réinitialisation/reconfiguration et construisez le modèle produit autour d’elles ; « identifiants présents » ne signifie pas « installation réussie ».
Conserver un accès volontaire à la récupération
Définissez ce qui rouvre la configuration : commande authentifiée, séquence de bouton physique ou outil d’installation. Précisez durée d’appui, indication LED et effet d’un appui court accidentel. Une réinitialisation réseau doit normalement préserver étalonnage, identité de l’appareil et réglages applicatifs indépendants. Le retour usine est une opération distincte et clairement signalée.
Une politique proposée pourrait ouvrir une fenêtre de dix minutes, borner une tentative de connexion par un délai configurable, puis permettre un nouvel essai ou restaurer les anciens réglages. Ces valeurs doivent correspondre aux routeurs et au parcours d’installation supportés. Ne laissez pas un réseau de configuration sans restriction ouvert en permanence simplement parce que le premier essai a échoué.
Si la configuration se ferme automatiquement, le téléphone doit pouvoir connaître le résultat sans ambiguïté : interrogation d’état tant que le lien reste disponible, preuve de succès affichée avant transition, état LED ou redécouverte sur le réseau cible. Une connexion TCP rompue ne distingue pas réussite et plantage.
Prévoir la perte du chemin de communication du téléphone
Les téléphones peuvent privilégier les données mobiles, quitter un Wi-Fi sans Internet ou afficher un navigateur de portail captif limité. Testez les versions Android/iOS supportées avec les données mobiles activées et désactivées. Fournissez une URL locale ou un parcours applicatif documenté qui fonctionne sans détection automatique du portail. Une page utilisable hors ligne ne doit pas dépendre de scripts ou polices hébergés sur Internet.
La coexistence AP/station présente des limites propres à la radio. Sur ESP32, la documentation indique un canal de fonctionnement commun avec priorité à la station ; rejoindre un routeur sur un autre canal peut donc affecter la connexion de configuration. Consultez le guide du pilote Wi-Fi, puis vérifiez la version réelle du SDK et du module. Les chipsets Linux nécessitent aussi des combinaisons d’interfaces prises en charge par le pilote ; des démonstrations AP et STA séparées ne prouvent pas leur coexistence.
Rendez l’interface d’état résistante aux reconnexions. Stockez le dernier résultat indépendamment de la connexion HTTP, avec identifiant de tentative, phase et code de raison sans information sensible. Un ancien onglet ne doit pas écraser une tentative plus récente déjà réussie.
Protéger le transfert des identifiants et les diagnostics
Utilisez un secret d’enrôlement par appareil ou une autre méthode authentifiée adaptée au produit. Un AP ouvert avec formulaire de mot de passe non authentifié expose un chemin sensible. Étudiez ensemble la sécurité du transport et la vérification d’identité de l’appareil ; un certificat autosigné arbitraire sans mécanisme de confiance et de découverte risque seulement d’habituer les installateurs à ignorer les avertissements.
Ne recopiez pas les exemples de journalisation qui affichent le mot de passe Wi-Fi. Journalisez phase, durée, raison de déconnexion SDK, nombre d’essais, version du firmware et identifiant réseau anonymisé. Restreignez l’export diagnostique et effacez les identifiants candidats temporaires devenus inutiles. Limitez tentatives et sessions simultanées, et définissez qui contrôle la configuration lorsque deux téléphones interviennent.
Des raisons différentes nécessitent des actions différentes. Un refus d’authentification invite à vérifier identifiants ou sécurité. L’absence d’AP correspondant invite à vérifier bande, portée, SSID masqué et politique de recherche. Un délai DHCP dépassé pointe vers le service d’adressage ou le réseau local. Les erreurs TLS et d’enregistrement appartiennent au chemin applicatif et peuvent concerner horloge, certificats ou politique de compte.
Prouver la récupération dans la matrice de recette
| Essai | Récupération attendue | Preuves à conserver |
|---|---|---|
| Mot de passe incorrect, puis corrigé | Nouvelle tentative acceptée sans reflash ni effacement d’identité | Identifiants de tentative, raison et état final |
| Routeur disparu pendant la connexion | Délai borné ; ancienne configuration ou entrée de configuration récupérable | Chronologie des phases et compteurs de tentatives/ressources |
| Association réussie, DHCP bloqué | Erreur d’adresse distincte de l’authentification | Événements Wi-Fi et capture DHCP |
| Réseau opérationnel, cloud indisponible | Erreur de service identifiée ; Wi-Fi valide conservé selon politique | États IP, DNS et applicatif sans identifiants secrets |
| Coupure pendant réception, essai et validation | Démarrage sur ancienne/nouvelle configuration valide ou mode de récupération explicite | Journal de démarrage, version et contrôle d’intégrité |
| Le téléphone quitte l’AP ; un second rejoint | Contrôle de la tentative préservé ; dernier résultat récupérable | État visible côté client et requêtes concurrentes |
| Expiration de configuration et reset réseau physique | Fermeture au délai prévu ; réouverture autorisée sans perte d’étalonnage | Scan radio, bouton/LED et comparaison des réglages |
Répétez les pannes autour des transitions d’état plutôt qu’à des instants arbitraires uniquement. Incluez changements de canal, faible signal et charge radio/applicative simultanée. Comptez les récupérations réussies sur toutes les tentatives, consignez chaque échec et mesurez le délai jusqu’à l’état utilisable. Ne rapportez pas seulement la moyenne : quelques essais sans fin peuvent concentrer le coût du support.
Exposer un contrat diagnostique compact
Le document d’état suivant illustre un contrat applicatif, pas une API SDK. Le vocabulaire des phases et raisons doit être versionné avec l’application mobile :
{
"schema": 1,
"attempt_id": "setup-0042",
"phase": "waiting_for_ip",
"result": "pending",
"elapsed_ms": 12400,
"reason": null,
"can_retry": false
}Utilisez une horloge monotone pour les délais afin qu’une correction d’heure ne prolonge ou ne raccourcisse pas un essai. Le watchdog doit détecter un worker bloqué sans redémarrer un appareil sain au seul motif que le routeur externe manque. Suivez mémoire et sockets sur des échecs répétés pour détecter les fuites invisibles dans une démonstration unique.
Convenir d’un livrable complet de mise en service
Le service de connectivité des équipements d’Obeita aide à cadrer l’intégration appareil, téléphone et routeur. Le projet livré de passerelle ESP32 Wi-Fi et Bluetooth décrit des travaux AP/STA ; son rôle Mesh distinct ne prouve pas que ce parcours soit déjà implémenté ou qualifié.
Fournissez versions du module et SDK, liste des téléphones, routeurs et modes de sécurité supportés, journaux actuels et parcours installateur requis. La livraison doit comprendre états, erreurs visibles, traitement des identifiants, sémantique des resets et essais de panne reproductibles, en plus de l’écran de configuration du cas nominal.
