lisael-box/docs/superpowers/specs/2026-06-14-lisael-box-wifi-provisioning-design.md

Lisael Box — Provisioning WiFi par SoftAP (captif) — design

Date: 2026-06-14 Statut: validé (brainstorming), prêt pour le plan. Projet: firmware Lisael Box (ESP32-S3-BOX-3), ESP-IDF v5.4.

But

Permettre de configurer le WiFi de la box sans reflasher : quand la box ne se connecte à aucun réseau connu, elle devient un point d'accès Lisael-Box et sert un portail captif où l'on choisit son réseau WiFi et saisit le mot de passe ; la box enregistre en NVS et se reconnecte. Débloque aussi le debug (le Mac rejoint l'AP → même sous-réseau → logs UDP).

Décisions (validées)

• Portail captif : DNS catch-all → la page s'ouvre automatiquement en rejoignant l'AP.
• AP ouvert (sans mot de passe), SSID Lisael-Box.
• Construit maintenant.

Comportement

1. Au boot, net_task tente le STA avec les creds NVS/menuconfig (existant).
2. Si non connecté après ~20 s (ou aucune cred enregistrée) → bascule en APSTA : SoftAP Lisael-Box (ouvert, IP 192.168.4.1) + démarre le portail. Le STA reste actif (tentatives de reconnexion en tâche de fond).
3. La box affiche un écran WiFi : « Connecte-toi au réseau Lisael-Box — la page de configuration s'ouvre toute seule (sinon va sur 192.168.4.1) ».
4. L'utilisateur rejoint Lisael-Box. Le portail captif redirige tout → la page de config : liste des réseaux scannés (boutons) + champ mot de passe.
5. À la validation → la box enregistre les creds (NVS) via lisael_wifi_save_credentials(), applique la config STA et reconnecte.
6. Dès connexion STA réussie → la box arrête l'AP + le portail, quitte l'écran WiFi (retour Accueil), poursuit SNTP/météo/etc.

Composants

• main/net/wifi.c / .h (modif) : ajouter
  • esp_err_t lisael_wifi_start_ap(void) — passe en WIFI_MODE_APSTA, crée le netif AP (esp_netif_create_default_wifi_ap), configure SoftAP Lisael-Box (WIFI_AUTH_OPEN, max_connection=4, canal 1), esp_wifi_start (idempotent si déjà démarré → juste set_mode + AP config).
  • esp_err_t lisael_wifi_stop_ap(void) — repasse en WIFI_MODE_STA.
  • esp_err_t lisael_wifi_apply_sta(const char *ssid, const char *pass) — esp_wifi_set_config(STA) + esp_wifi_connect() (réutilisé par le portail).
  • int lisael_wifi_scan(wifi_ap_record_t *out, int max) — scan bloquant court, renvoie le nb de réseaux (dédupliqués par SSID).
  • exposer lisael_wifi_is_connected() (existe déjà).
• main/net/wifi_portal.c / .h (neuf) :
  • void lisael_wifi_portal_start(void) — démarre esp_http_server (port 80)
    • un serveur DNS captif (tâche : socket UDP 53, répond à toute requête A par 192.168.4.1).
  • void lisael_wifi_portal_stop(void) — arrête HTTP + DNS.
  • Routes HTTP : GET / → page HTML (form : <select>/liste des SSID scannés + <input password> + submit) ; GET /scan → JSON [{ssid,rssi}] ; POST /save (form-urlencoded ssid,pass) → lisael_wifi_save_credentials
    • lisael_wifi_apply_sta → page « Connexion en cours… » ; catch-all (404 handler) → redirection 302 vers http://192.168.4.1/ (déclenche le portail captif des OS, ex. /generate_204, /hotspot-detect.html).
• main/app_main.c (modif net_task) : après lisael_wifi_wait_connected(20s) échoué → lisael_wifi_start_ap() + lisael_wifi_portal_start() + afficher l'écran WiFi ; lancer une petite tâche qui attend lisael_wifi_is_connected() puis lisael_wifi_portal_stop() + lisael_wifi_stop_ap() + retour Accueil + SNTP/météo.
• main/modes/wifi_setup.c (neuf) + déclaration dans ui.h : lv_obj_t *lisael_screen_wifi_setup(void) — écran plein : titre « Réglage WiFi », texte « Connecte-toi au réseau Lisael-Box sur ton téléphone, la page s'ouvre toute seule (sinon : 192.168.4.1) ». Affiché via un nouveau mode/loader dédié (pas une tuile pour l'instant). Mis à jour « Connexion… » puis disparaît.
• main/CMakeLists.txt : ajouter net/wifi_portal.c, modes/wifi_setup.c ; REQUIRES += esp_http_server.
• sdkconfig : esp_http_server (composant, pas de Kconfig spécifique) ; SoftAP ne demande rien de spécial. CONFIG_LWIP_MAX_SOCKETS suffisant (DNS+HTTP).

Gestion d'erreurs / robustesse

• RAM tendue : le portail (HTTP + DNS) ne tourne que en mode AP (sinon arrêté). Scan bref. Buffers HTTP modestes.
• Si esp_wifi_init a échoué (offline total, déjà géré) → pas d'AP non plus (log).
• Mauvais mot de passe → la reconnexion échoue → on re-bascule en AP/portail (la page indique « échec, réessaie »). Boucle jusqu'à succès.
• Le portail capte aussi les URL de détection OS (302 → /).

Hors-scope (v2)

• Tuile « Réglages WiFi » à l'accueil pour relancer le provisioning à la demande.
• Mot de passe sur l'AP, page stylée, multi-langue, mémorisation de plusieurs réseaux.

Tests (acceptation, sur carte)

1. Effacer/!connecter le STA → au boot la box montre l'écran « Lisael-Box ».
2. Le Mac/téléphone voit le réseau Lisael-Box, le rejoint → la page de config s'ouvre toute seule (portail captif).
3. La page liste les réseaux WiFi proches ; on choisit, on saisit le mot de passe, on valide.
4. La box se connecte, arrête l'AP, revient à l'Accueil ; date/météo repartent.
5. (debug) Pendant que le Mac est sur Lisael-Box, les logs UDP de la box arrivent (écouteur 9999) → permet de diagnostiquer le bug des pochettes.
6. Mauvais mot de passe → retour au portail avec message d'échec.