BleQuiz

Application HTML5 de quiz temps réel pour plusieurs modules ESP32-S3 via Bluetooth Low Energy (BLE)

📋 Description

BleQuiz permet de créer un système de quiz interactif en temps réel où jusqu'à 8 modules ESP32-S3 peuvent être connectés simultanément via Bluetooth. Chaque module surveille 4 boutons (GPIOs) et envoie instantanément les événements à une interface web HTML5 avec feedback visuel LED.

Cas d'usage : Quiz en classe, jeux de rapidité, systèmes de vote, buzzers interactifs multi-joueurs.

Adresse de test : https://blequiz.apps.christophe-scaya.fr/ (serveur de démonstration, utiliser le fichier quiz_exemple.txt)

✨ Fonctionnalités principales

• 🎮 Identification automatique : 8 modules nommés automatiquement via jumpers (BleQuiz-1 à BleQuiz-8)
• 🔐 Appairage sécurisé : Code PIN 123456, mémorisation pour reconnexion automatique
• 💡 LED RGB intégrée : Feedback visuel couleur selon la réponse (Rouge/Vert/Bleu/Jaune)
• 📱 Multi-plateforme : Compatible Android, iOS, Linux, Windows (Chrome/Edge)
• 🌐 Interface web moderne : Support des formules chimiques (indices/exposants)
• ⚡ Temps réel : Détection instantanée du premier à répondre

🔧 Configuration

ESP32-S3 (src/main.cpp)

Par défaut, le code surveille 4 GPIOs : 2, 4, 5, 6 (compatibles ESP32-S3 Supermini)

Pour modifier les GPIOs surveillés, éditez cette ligne :

const int GPIO_PINS[] = {2, 4, 5, 6}; // GPIOs à surveiller (A, B, C, D)

LED WS2812 (ESP32-S3)

Le projet supporte une LED WS2812 sur le GPIO 48 (ESP32-S3) pour indiquer l'état du module :

États de la LED :

• ⚪ Blanc clignotant (500ms) → Déconnecté de la page web
• ⚪ Blanc fixe → Connecté, en attente de réponse ou affichage des scores
• 🔴 Rouge → Bouton GPIO 2 pressé (réponse A)
• 🟢 Vert → Bouton GPIO 4 pressé (réponse B)
• 🔵 Bleu → Bouton GPIO 5 pressé (réponse C)
• 🟡 Jaune → Bouton GPIO 6 pressé (réponse D)

Comportement selon les phases du quiz :

1. Connexion initiale → ⚪ Blanc fixe (GPIO actifs)
2. Question affichée → ⚪ Blanc fixe (attente de réponse)
3. Bouton pressé → 🔴🟢🔵🟡 Couleur correspondante
4. Résultats affichés → LED garde sa couleur (GPIO désactivés)
5. Question suivante → ⚪ Blanc fixe (GPIO réactivés)
6. Scores finaux → ⚪ Blanc fixe (GPIO désactivés)
7. Déconnexion → ⚪ Blanc clignotant

Configuration : La bibliothèque Adafruit NeoPixel est automatiquement installée via PlatformIO.

Identification automatique des modules (GPIO 8, 9, 10)

Chaque module ESP32-S3 peut être identifié automatiquement via 3 GPIOs configurés en INPUT_PULLUP :

Configuration des jumpers (connecter à GND pour LOW = 1, laisser ouvert pour HIGH = 0) :

• GPIO 8 = bit 0
• GPIO 9 = bit 1
• GPIO 10 = bit 2

Table d'identification (logique inverse) :

GPIO 10	GPIO 9	GPIO 8	Binaire	Nom du module
HIGH	HIGH	HIGH	000	BleQuiz-1
HIGH	HIGH	LOW	001	BleQuiz-2
HIGH	LOW	HIGH	010	BleQuiz-3
HIGH	LOW	LOW	011	BleQuiz-4
LOW	HIGH	HIGH	100	BleQuiz-5
LOW	HIGH	LOW	101	BleQuiz-6
LOW	LOW	HIGH	110	BleQuiz-7
LOW	LOW	LOW	111	BleQuiz-8

Avantage : Plus besoin de modifier le code pour chaque module, il suffit de configurer les jumpers !

Mise à jour OTA (Over-The-Air)

Le module supporte la mise à jour distante via WiFi sans câble USB !

Activation du mode OTA :

1. Appuyez simultanément sur les 4 boutons (A, B, C, D) pendant 5 secondes
2. 🔵 La LED clignotera rapidement en bleu → Mode OTA actif
3. Le module crée un Point d'accès WiFi avec :
   • SSID : Nom du module (ex: BleQuiz-5)
   • Mot de passe : 12345678
   • IP : 192.168.4.1

Effectuer la mise à jour :

# Sur votre ordinateur, connectez-vous au WiFi du module, puis dans le répertoire tools, exécutez l'outil espota :
python3 espota.py -i 192.168.4.1 -p 3232 -f [CHEMIN_DU_FIRMWARE]/firmware.bin

Mise à jour OTA via PlatformIO

Vous pouvez également effectuer la mise à jour OTA directement depuis PlatformIO :

1. Connectez le module à son réseau WiFi OTA (voir instructions ci-dessus).
2. Modifiez le fichier platformio.ini en décommantant la configuration OTA :

upload_protocol = espota
upload_port = 192.168.4.1

3. Lancez la commande suivante pour téléverser le firmware :

pio run -e esp32-s3-supermini --target upload

PlatformIO utilisera automatiquement le protocole OTA pour envoyer le firmware au module via le réseau WiFi.

Remarque : Assurez-vous que votre ordinateur est connecté au même réseau que le module ESP32-S3.

Timeout de sécurité :

• Si aucune mise à jour n'est reçue après 60 secondes, le module redémarre automatiquement
• Cela évite que le module reste bloqué en mode OTA

Indicateurs LED en mode OTA :

• 🔵 Bleu clignotant rapide → En attente de mise à jour
• 🟢 Vert fixe → Mise à jour réussie (avant redémarrage)
• 🔴 Rouge fixe → Erreur lors de la mise à jour

Appairage Bluetooth sécurisé

Le système utilise un appairage sécurisé avec code PIN pour une meilleure compatibilité :

• Code PIN fixe : 123456 (affiché au démarrage dans le moniteur série)
• Premier appairage : Entrez 123456 sur votre appareil
• Appairages suivants : Reconnexion automatique sans code
• Compatibilité : ✅ Android | ✅ iOS | ✅ Linux | ✅ Windows

🚀 Installation et utilisation

1. Prérequis

• PlatformIO (VS Code ou CLI)
• ESP32-S3 (Seeed XIAO ESP32-S3 ou compatible)
• Python 3 (serveur HTTPS)
• Navigateur : Chrome, Edge ou Opera

2. Compilation et téléversement

Compiler et téléverser :

pio run -e esp32-s3-supermini --target upload

Monitorer le port série (voir code PIN 123456) :

pio device monitor

⚠️ Important : Notez le code PIN 123456 affiché au démarrage pour le premier appairage.

3. Démarrer le serveur HTTPS

⚠️ Important : Web Bluetooth nécessite HTTPS (ou localhost en HTTP)

Option A - Script automatique (Linux) :

./start.sh

Ce script :

• Démarre automatiquement le serveur Python HTTPS
• Lance Chrome avec les flags Web Bluetooth appropriés
• Ouvre directement l'application à https://localhost:8443

Option B - Serveur Python manuel :

python3 server.py

Option C - Serveur Node.js :

node server.js

Les serveurs Python et Node.js :

• Génèrent automatiquement un certificat SSL auto-signé
• Démarrent sur https://localhost:8443
• Servent la page HTML avec support Bluetooth

4. Ouvrir dans le navigateur

Ouvrez Chrome, Edge ou Opera et accédez à :

https://localhost:8443

Note :

• Vous verrez un avertissement de sécurité (certificat auto-signé) → Cliquez sur "Avancé" puis "Continuer vers localhost"
• Firefox et Safari ne supportent pas encore Web Bluetooth
• Sur Linux, utilisez le script start.sh pour lancer Chrome avec les bons paramètres

5. Utiliser l'application

1. Charger un fichier de questions : Cliquez sur "Choisir un fichier" et sélectionnez votre fichier de quiz (voir quiz_exemple.txt)
2. Connecter les modules : Cliquez sur "Connecter un module" et sélectionnez votre ESP32
3. Premier appairage : Entrez le code 123456 quand demandé (Android/iOS)
4. Appairages suivants : La connexion se fait automatiquement sans code
5. Lancer le quiz : Naviguez entre les questions, les modules répondent en appuyant sur leurs boutons
6. Répétez pour connecter plusieurs modules simultanément

Note sur l'appairage :

• Première connexion : Le système demande un code PIN (123456)
• Connexions suivantes : L'appairage est mémorisé, reconnexion automatique
• Android/iOS : L'appairage sécurisé améliore grandement la compatibilité
• Ubuntu/Linux : Fonctionne avec ou sans appairage

🌐 Pourquoi HTTPS est nécessaire ?

Web Bluetooth API nécessite un contexte sécurisé pour des raisons de sécurité :

• ✅ https:// (avec certificat SSL)
• ✅ http://localhost ou http://127.0.0.1
• ❌ file:// (ouverture directe du fichier HTML)

Les serveurs fournis (server.py et server.js) génèrent automatiquement un certificat SSL auto-signé.

🔌 Branchement des GPIOs

Pour tester, connectez vos boutons/switches entre les GPIOs et la masse (GND) :

ESP32          Bouton/Switch
GPIO 2   ----  [Bouton A] ---- GND
GPIO 4   ----  [Bouton B] ---- GND
GPIO 5   ----  [Bouton C] ---- GND
GPIO 6   ----  [Bouton D] ---- GND

Configuration : Les GPIOs utilisent des résistances de pull-up internes, donc :

• État normal (bouton non pressé) : HIGH (3.3V)
• État actif (bouton pressé) : LOW (0V / GND)

📁 Structure du projet

BleQuiz/
├── index.html          # Interface web du quiz
├── platformio.ini      # Configuration PlatformIO (esp32dev, esp32-c3)
├── server.py           # Serveur HTTPS Python
├── server.js           # Serveur HTTPS Node.js
├── start.sh            # Script de lancement automatique (Linux)
├── quiz_exemple.txt    # Exemple de fichier de questions
├── src/
│   └── main.cpp        # Code ESP32 (BLE + GPIO)
└── include/
    └── README

📊 Format des données BLE

Les données sont envoyées en JSON via Bluetooth Low Energy :

{
  "module": "ESP32-Module-1",
  "gpios": [
    {"pin": 2, "state": "0"},
    {"pin": 4, "state": "1"},
    {"pin": 5, "state": "0"},
    {"pin": 6, "state": "0"}
  ]
}

• state: "0" = GPIO HIGH (bouton non pressé)
• state: "1" = GPIO LOW (bouton pressé)

🎨 Fonctionnalités de l'interface

L'application web offre :

• Chargement de quiz : Support de fichiers texte avec questions et réponses
• Connexion multi-modules : Connectez jusqu'à 10 ESP32 simultanément
• Affichage en temps réel : État des boutons de chaque module avec code couleur
• Système de scoring : Points automatiques pour les bonnes réponses
• Mode de jeu : Détection du premier à répondre avec verrouillage
• Animations visuelles : Feedback instantané lors des appuis
• Historique : Suivi des réponses et du temps de réaction

⚙️ Personnalisation

Modifier les GPIOs surveillés

Dans src/main.cpp, adaptez selon votre matériel :

const int GPIO_PINS[] = {2, 4, 5, 6}; // GPIOs à surveiller

Changer les UUID Bluetooth

Dans src/main.cpp et index.html, modifiez (doit être identique des deux côtés) :

#define SERVICE_UUID        "4fafc201-1fb5-459e-8fcc-c5c9c331914b"
#define CHARACTERISTIC_UUID "beb5483e-36e1-4688-b7f5-ea07361b26a8"
#define COMMAND_UUID      "beb5483e-36e1-4688-b7f5-ea07361b26a9"

Format du fichier de quiz

Créez un fichier texte avec ce format (voir quiz_exemple.txt) :

* Quelle est la formule de l'ion fer(III) ?
- Fe^(2+)
+ Fe^(3+)
- Fe_(2)^(3-)
- Fe_(3)^(2+)

* Question suivante ?
- Mauvaise réponse
- Autre mauvaise réponse
+ Bonne réponse
- Encore une mauvaise réponse

Format :

• * = Question
• - = Mauvaise réponse
• + = Bonne réponse

Syntaxe pour indices et exposants :

• ^(texte) = exposant → Fe^(3+) s'affiche comme Fe³⁺
• _(texte) = indice → H_(2)O s'affiche comme H₂O
• Combinaison possible : Fe_(2)O_(3) → Fe₂O₃

🐛 Dépannage

Problèmes d'appairage Bluetooth

Android ne veut pas appairer :

• Assurez-vous d'entrer le code PIN 123456 quand demandé
• Effacez les appairages Bluetooth précédents dans les paramètres Android
• Réinitialisez l'ESP32 et réessayez

iOS ne voit pas le module :

• Vérifiez que le Bluetooth est activé dans les réglages iOS
• Le module doit être alimenté et le moniteur série doit afficher "Advertising BLE démarré"
• iOS peut mettre quelques secondes avant de découvrir les périphériques BLE
• Entrez le code 123456 lors du premier appairage

Le module n'apparaît pas dans la liste Bluetooth :

• Vérifiez l'alimentation USB (5V stable)
• Consultez pio device monitor pour voir "Code d'appairage : 123456"
• Redémarrez l'ESP32 (bouton RESET)
• Sur Linux, vérifiez BlueZ : bluetoothctl --version

Erreur "HTTPS required" ou "Bluetooth API not available"

• Accédez à https://localhost:8443 (pas http://)
• Navigateurs supportés : Chrome, Edge, Opera uniquement
• Sur Linux, utilisez le script ./start.sh pour les bons paramètres Chrome

Erreur de compilation PlatformIO

• Vérifiez votre environnement dans platformio.ini
• Mettez à jour PlatformIO : pio upgrade
• Nettoyez le projet : pio run --target clean
• Réinstallez les dépendances : pio pkg update

📝 Caractéristiques techniques

• Protocole : Bluetooth Low Energy (BLE 4.0+)
• LED WS2812 : Indicateur visuel d'état sur GPIO 48
• Identification automatique : Via GPIOs 8, 9, 10 (BleQuiz-1 à BleQuiz-8)
• GPIOs boutons : 4 par défaut (2, 4, 5, 6)
• Connexions simultanées : Jusqu'à 8+ modules ESP32
• Fréquence de mise à jour : 100ms par défaut
• Portée Bluetooth : ~10 mètres en intérieur
• Navigateurs supportés : Chrome 56+, Edge 79+, Opera 43+
• Serveurs fournis : Python 3 (SSL auto-signé) et Node.js
• Bibliothèques : Adafruit NeoPixel (pour LED WS2812)

🎯 Notes d'utilisation

• Identification automatique : Les modules se nomment automatiquement BleQuiz-1 à BleQuiz-8 selon les GPIOs 8, 9, 10
• Appairage BLE : Code PIN fixe 123456 pour le premier appairage, puis reconnexion automatique
• Compatibilité : Appairage sécurisé (bonding) pour Android/iOS, fonctionne aussi sur Ubuntu/Linux
• Web Bluetooth : La page HTML doit obligatoirement être servie en HTTPS ou via localhost
• Détection de changement : Les événements GPIO sont envoyés instantanément lors des transitions HIGH→LOW
• Mode Pull-up : Les boutons doivent connecter le GPIO à GND (pas à VCC)
• LED WS2812 : Feedback visuel automatique sur ESP32-S3, la LED indique l'état de connexion et les réponses
• Commandes BLE :
  • START : Active la détection GPIO (blanc fixe)
  • RESET : Fige la LED, désactive les GPIO (affichage résultats)
  • SCORES : Blanc fixe, GPIO désactivés (scores finaux)

🚀 Démarrage rapide (Linux)

# 1. Compiler et téléverser le code ESP32
pio run -e esp32dev --target upload

# 2. Lancer l'application (serveur + navigateur)
./start.sh

# 3. Dans l'interface web :
#    - Charger un fichier de quiz
#    - Connecter les modules ESP32
#    - Commencer le quiz !

📚 Ressources

• Web Bluetooth API Documentation
• ESP32 BLE Arduino Documentation
• PlatformIO Documentation
• ESP32 GPIO Reference

📄 Licence

Ce projet est open source. Libre d'utilisation, modification et distribution.