12 KiB

Raw Blame History Unescape Escape

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

Charger un fichier de questions : Cliquez sur "Choisir un fichier" et sélectionnez votre fichier de quiz (voir quiz_exemple.txt)
Connecter les modules : Cliquez sur "Connecter un module" et sélectionnez votre ESP32
Lancer le quiz : Naviguez entre les questions, les modules répondent en appuyant sur leurs boutons
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

📄 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

12 KiB Raw Blame History Unescape Escape