BleQuiz

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

📋 Description

BleQuiz permet de créer un système de quiz interactif en temps réel où plusieurs ESP32 peuvent être connectés simultanément via Bluetooth. Chaque module ESP32 surveille des GPIOs (boutons) et envoie instantanément les événements à une interface web HTML5.

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

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

🔧 Configuration

ESP32 (src/main.cpp)

Par défaut, le code surveille 4 GPIOs : 2, 4, 5, 6 (compatibles ESP32 Wrover et ESP32-C3)

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

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

Pour changer le nom du module (important pour différencier plusieurs ESP32) :

String moduleName = "ESP32-Module-1"; // Changer pour chaque ESP32

GPIOs avec Pull-up

Les GPIOs sont configurés en INPUT_PULLUP, ce qui signifie :

• État normal (non connecté) : HIGH (3.3V)
• État actif (connecté à GND) : LOW (0V)

Le système envoie une notification à la page HTML quand un GPIO passe à l'état BAS.

🚀 Installation et utilisation

1. Prérequis

• PlatformIO installé (via VS Code ou CLI)
• Python 3 (pour le serveur HTTPS)
• Navigateur compatible : Chrome, Edge ou Opera (Firefox et Safari ne supportent pas Web Bluetooth)

2. Configuration des ESP32

Le projet supporte deux environnements (voir platformio.ini) :

• esp32dev : ESP32 Wrover standard
• esp32-c3-supermini : Seeed XIAO ESP32-C3 (ou module générique ESP32-C3)

Compiler et téléverser pour ESP32 Wrover :

pio run -e esp32dev
pio run -e esp32dev --target upload

Compiler et téléverser pour ESP32-C3 :

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

Monitorer le port série (optionnel) :

pio device monitor

⚠️ Important : Si vous utilisez plusieurs modules, modifiez le nom de chaque module dans src/main.cpp :

String moduleName = "ESP32-Module-1"; // Changer pour Module-2, Module-3, etc.

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. Lancer le quiz : Naviguez entre les questions, les modules répondent en appuyant sur leurs boutons
4. Répétez pour connecter plusieurs modules simultanément

🌐 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

Changer le nom du module ESP32

Dans src/main.cpp, modifiez :

String moduleName = "ESP32-Module-1"; // Changer pour chaque ESP32 (Module-2, Module-3, etc.)

Modifier les GPIOs surveillés

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

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

GPIOs recommandés :

• ESP32 Wrover : 2, 4, 5, 12, 13, 14, 15, 16, 17, 18, 19, 21, 22, 23
• ESP32-C3 : 2, 3, 4, 5, 6, 7, 8, 9, 10

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"

Modifier le délai de lecture

Dans src/main.cpp, dernière ligne de loop() :

delay(100); // Modifier selon vos besoins (en millisecondes)

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

L'ESP32 n'apparaît pas dans la liste Bluetooth

• Vérifiez que le module est alimenté correctement (USB ou externe 5V)
• Consultez le moniteur série : pio device monitor pour voir les messages de démarrage
• Assurez-vous que le Bluetooth est activé sur votre ordinateur
• Sur Linux, vérifiez que BlueZ est à jour : bluetoothctl --version
• Redémarrez l'ESP32 (bouton RESET ou débrancher/rebrancher)

Pas de données reçues dans l'interface web

• Vérifiez que les UUID correspondent dans src/main.cpp et index.html
• Consultez la console JavaScript (F12) pour voir les erreurs
• Testez en connectant un GPIO à GND avec un simple fil
• Vérifiez que le module est bien connecté (voyant dans l'interface)

Déconnexions fréquentes

• Réduisez la distance entre l'ESP32 et l'ordinateur (< 5 mètres)
• Assurez-vous que l'alimentation de l'ESP32 est stable (câble USB de qualité)
• Évitez les interférences (WiFi 2.4GHz, micro-ondes)
• Augmentez le délai dans la boucle principale si trop de données sont envoyées

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

• Vérifiez que vous accédez bien à https://localhost:8443 (pas http://)
• Utilisez Chrome, Edge ou Opera (pas Firefox ni Safari)
• 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+)
• Compatibilité ESP32 : ESP32 Wrover, ESP32-C3 (Seeed XIAO)
• GPIOs configurables : 4 par défaut (extensible)
• Connexions simultanées : Jusqu'à 10 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

🎯 Notes d'utilisation

• Modules multiples : Chaque module doit avoir un nom unique configuré dans src/main.cpp
• Sécurité BLE : Le code utilise un mode sans bonding (pas de mémorisation d'appairage)
• 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)

🚀 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 !

🔐 Sécurité

Le projet est conçu pour un usage éducatif et de démonstration. Pour un usage en production :

• Authentification BLE : Implémenter un système de pairing sécurisé
• Chiffrement des données : Activer le chiffrement des caractéristiques BLE
• Certificat SSL valide : Remplacer le certificat auto-signé par un certificat CA
• Validation côté serveur : Ajouter une validation des réponses côté serveur
• Limitation de connexions : Implémenter une limite et un contrôle d'accès
• Logs d'audit : Enregistrer les actions pour le suivi et la sécurité

📚 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.

👥 Contribution

Les contributions sont les bienvenues ! N'hésitez pas à :

• Signaler des bugs
• Proposer de nouvelles fonctionnalités
• Améliorer la documentation
• Soumettre des pull requests

---

Créé avec ❤️ pour l'éducation et l'apprentissage interactif