# 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/](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 :
```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 = 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 !

### 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** :
```bash
pio run -e esp32-s3-supermini --target upload
```

**Monitorer le port série** (voir code PIN 123456) :
```bash
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)** :
```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
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 :
```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

### 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)

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