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ù plusieurs ESP32-S3 peuvent être connectés simultanément via Bluetooth. Chaque module ESP32-S3 surveille des GPIOs (boutons) et envoie instantanément les événements à une interface web HTML5.

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 d'un module ESP32-S3 supermini générique.

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, laisser ouvert pour HIGH) :

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

Table d'identification :

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

🚀 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

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

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

Monitorer le port série (optionnel) :

pio device monitor

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-S3 dans la liste Bluetooth
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

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

L'ESP32-S3 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-S3 (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-S3 et l'ordinateur (< 5 mètres)
• Assurez-vous que l'alimentation de l'ESP32-S3 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+)
• 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
• 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)
• 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.