# 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/](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 :
```cpp
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** :
```bash
pio run -e esp32-s3-supermini
pio run -e esp32-s3-supermini --target upload
```
**Monitorer le port série** (optionnel) :
```bash
pio device monitor
```

### 3. Démarrer le serveur HTTPS

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

**Option A - Script automatique (Linux)** :
```bash
./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** :
```bash
python3 server.py
```

**Option C - Serveur Node.js** :
```bash
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 :
```json
{
  "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 :
```cpp
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) :
```cpp
#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)

```bash
# 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](https://developer.mozilla.org/en-US/docs/Web/API/Web_Bluetooth_API)
- [ESP32 BLE Arduino Documentation](https://github.com/espressif/arduino-esp32/tree/master/libraries/BLE)
- [PlatformIO Documentation](https://docs.platformio.org/)
- [ESP32 GPIO Reference](https://randomnerdtutorials.com/esp32-pinout-reference-gpios/)

## 📄 Licence

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