# Spécifications — Companion Cube Interactif

> **Version :** 0.2.0  
> **Date :** 2026-02-08  
> **Statut :** Brouillon — en cours de validation  

---

## Sommaire

- [Partie 1 — Spécifications Fonctionnelles](#partie-1--spécifications-fonctionnelles)
- [Partie 2 — Spécifications Techniques (v1.0 — ESP32-S3)](#partie-2--spécifications-techniques-v10--esp32-s3)
- [Partie 3 — Passerelle (Gateway/Dock)](#partie-3--passerelle-gatewaydock)
- [Partie 4 — Feuille de Route](#partie-4--feuille-de-route)

---

# Partie 1 — Spécifications Fonctionnelles

## 1. Vision Produit

Un cube interactif de ~12 cm inspiré du **Weighted Companion Cube** (Aperture Science), repositionné dans un contexte **opérationnel** (IT/DevOps, Défense, Coordination d'équipes).

Le cube est un **terminal physique configurable** : chaque face est un bouton lumineux dont le rôle, les animations et les actions sont définis depuis le serveur **ops-devices**. Il communique localement (ESP-NOW / BLE) avec une **passerelle** (dock) qui assure la connectivité réseau (WiFi / 4G) vers le serveur MQTT.

### Contraintes de Design
* **Esthétique :** Coque grise mate, coins renforcés, centre de chaque face marqué d'un symbole configurable servant de bouton tactile. Le reste de la face est lumineux (LEDs RGB diffuses).
* **Diffusion Lumineuse :** Aucun "point chaud" visible. La lumière doit être diffuse, organique, et sembler émaner de la face.
* **Étanchéité Visuelle :** Aucun connecteur ni bouton visible de l'extérieur (charge par induction Qi, interaction par tactile et NFC).
* **Taille :** ~12 cm d'arête.
* **Environnement :** Bureau / QG intérieur (pas de contrainte IP spécifique pour la v1).

---

## 2. Architecture Globale (2 Tiers)

```
┌─────────────┐     ESP-NOW / BLE      ┌──────────────────┐     WiFi / 4G     ┌─────────────┐
│   CUBE(s)   │ ◄─────────────────────► │   PASSERELLE     │ ◄───────────────► │  SERVEUR    │
│  ESP32-S3   │    Communication locale │   (Dock/Gateway)  │       MQTT        │ ops-devices │
│  Simple     │                         │   ESP32-S3 + WiFi │                   │  Mosquitto  │
└─────────────┘                         │   Charge Qi TX    │                   └─────────────┘
                                        └──────────────────┘
```

* **Cube** : Terminal autonome, pas de WiFi activé. Communication locale uniquement.
* **Passerelle** : Dock physique qui charge le cube (Qi) et fait le pont entre la communication locale et le réseau (WiFi/4G → MQTT).
* **Serveur** : ops-devices existant avec Mosquitto (MQTT), backend API, et interface web de configuration.

---

## 3. Disposition des Faces

| Face | Position | Rôle Matériel | Rôle Logiciel |
|------|----------|---------------|---------------|
| **1** | Dessus | NFC (PN532) + Tactile + LEDs | Configurable (NFC + action) |
| **2** | Face avant | Tactile + LEDs | Configurable (action + statut) |
| **3** | Face droite | Tactile + LEDs | Configurable (action + statut) |
| **4** | Face arrière | Tactile + LEDs | Configurable (action + statut) |
| **5** | Face gauche | Tactile + LEDs | Configurable (action + statut) |
| **6** | Dessous | Récepteur Qi + LEDs (indicateur charge) | Statut batterie / charge |

> **Les rôles logiciels des faces 1 à 5 sont entièrement configurables depuis le serveur.** L'utilisateur définit pour chaque face : l'action déclenchée, et l'animation associée à chaque état.

---

## 4. Système d'Actions Configurable

Chaque face (1-5) est un **slot d'action** configurable avec les propriétés suivantes :

### 4.1 Définition d'une Action

| Propriété | Description | Exemple |
|-----------|-------------|---------|
| `label` | Nom affiché dans l'interface | "Redémarrer Nginx" |
| `icon` | Symbole sur la face physique (optionnel, gravé/imprimé) | 🔄 |
| `trigger` | Type d'interaction physique | `tap`, `long_press`, `double_tap` |
| `mqtt_topic` | Topic MQTT publié lors du déclenchement | `ops/cube/{id}/action/face2` |
| `mqtt_payload` | Payload JSON envoyé | `{"action": "restart", "target": "nginx"}` |
| `confirm` | Nécessite une confirmation (double tap) | `true` / `false` |

### 4.2 États Visuels d'une Action

Chaque action possède des **états visuels** animés sur les LEDs de la face :

| État | Description | Animation par défaut |
|------|-------------|---------------------|
| `idle` | En veille, aucune activité | Pulsation lente (couleur configurable) |
| `listening` | En écoute / surveillance active | Respiration douce (bleu) |
| `triggered` | Action déclenchée par l'utilisateur | Flash blanc → onde de couleur |
| `success` | Action exécutée avec succès | Vert fixe 3s → retour idle |
| `error` | Échec de l'action | Rouge clignotant 5s → retour idle |
| `alert` | Alerte reçue du serveur | Animation insistante (rouge pulsé) |
| `warning` | Avertissement reçu | Orange pulsé |
| `info` | Information reçue | Bleu flash unique |

### 4.3 Cas d'Usage Prioritaires

#### IT/DevOps — Monitoring & Actions Serveurs
* Face = un service (Nginx, Postgres, API, etc.)
* LED verte = service UP, rouge = DOWN
* Tap = voir le statut détaillé (clignotement code)
* Double Tap = redémarrer le service
* Alerte push = notification serveur DOWN

#### Défense — C2 (Command & Control)
* Face = un canal ou une zone d'opération
* LED = statut de la zone (vert = RAS, orange = vigilance, rouge = alerte)
* Tap = acquitter l'alerte
* Long Press = envoyer un signal prédéfini (point de ralliement, repli, etc.)
* NFC = identification opérateur / changement de profil

#### Coordination d'Équipes
* Face = une équipe ou un membre
* LED = disponibilité (vert = dispo, orange = occupé, rouge = indisponible)
* Tap = envoyer un "ping" à l'équipe
* Double Tap = demande de contact urgent
* Long Press = déclencher un timer partagé (briefing, pause)

---

## 5. Modes de Fonctionnement

### A. Mode Veille (Idle)
* Pulsation lente ("respiration") sur les 6 faces, couleur selon l'état de chaque action configurée.
* **Économie :** Luminosité réduite à 10% après 5 minutes sans interaction.
* **Deep Sleep :** Après 30 minutes sans interaction ni message MQTT, le cube entre en deep sleep. Réveil par toucher ou message ESP-NOW.

### B. Mode Interaction Tactile
* **Tap :** La face réagit par un flash blanc + exécute l'action `tap` configurée.
* **Long Press (> 2s) :** Exécute l'action `long_press` configurée.
* **Double Tap :** Exécute l'action `double_tap` configurée (avec confirmation si activée).

### C. Mode NFC (Face du dessus uniquement)
* **Tag d'identification :** Change le profil utilisateur du cube (jeu d'actions différent).
* **Tag d'action :** Déclenche une action spécifique associée au tag.
* **Smartphone :** Le cube peut envoyer une URL (NDEF) ou recevoir des données de configuration.
* **Cube-à-Cube :** Approcher deux cubes = transfert du profil de configuration (WiFi, serveur, actions).

### D. Mode Alerte (Push depuis le serveur)
* Le serveur envoie un message MQTT → la passerelle le relaie au cube en ESP-NOW/BLE.
* La face concernée passe en animation d'alerte.
* L'utilisateur acquitte en touchant la face → le cube envoie un ACK au serveur.

---

## 6. Gestion de l'Énergie et Alertes

* **Autonomie cible :** 12-24h en usage actif (LEDs à luminosité moyenne, communication ESP-NOW active).
* **Charge Qi (sur la passerelle) :** Quand posé sur le dock, les faces passent en orange pulsé → vert fixe à 100%.
* **Charge USB-C :** Accessible en ouvrant une face (maintenance uniquement).
* **Alerte Batterie Faible :** La face du dessous clignote en rouge sous 15%. Sous 5%, toutes les faces clignotent rouge.
* **Sécurité Thermique :** Si >45°C, le cube coupe les LEDs et émet un flash rouge toutes les 10s.

---

## 7. Configuration et Administration

### Via l'interface web ops-devices
* Associer un cube (pairing BLE via la passerelle).
* Configurer les actions de chaque face (drag & drop).
* Créer des profils d'actions (IT, C2, Coordination) interchangeables via NFC.
* Voir l'état temps réel de chaque cube (batterie, température, dernière interaction).
* Mettre à jour le firmware (OTA via la passerelle).

### Via la passerelle
* Appairage automatique des cubes à proximité.
* Relais transparent MQTT ↔ ESP-NOW.
* File d'attente des messages si le cube est en deep sleep.
* Logs locaux des interactions.

---

# Partie 2 — Spécifications Techniques (v1.0 — ESP32-S3)

## 1. Architecture Matérielle du Cube

* **MCU :** ESP32-S3 (WiFi désactivé pour économie d'énergie, BLE + ESP-NOW actifs).
* **Touch :** 6 pads capacitifs natifs (pins TOUCH de l'ESP32-S3).
* **NFC :** 1x PN532 (face du dessus) — Communication I2C.
* **LEDs :** 6 lignes Data indépendantes (1 par face), LEDs WS2812B.
* **Batterie :** LiPo > 2000mAh (volume disponible dans un cube de 12cm).
* **Charge :** Qi 5V (face du dessous) + USB-C (maintenance).
* **Jauge batterie :** CW2015 (I2C).
* **Thermique :** NTC 10kΩ sur batterie, reliée à l'ESP32 et au TP4056.
* **Charge controller :** TP4056 avec protection.

---

## 2. Design des Faces ("Sandwich" à 2 étages)

### Étage A : PCB "Bouchon" (Capteur)
* **Face du dessus :** PN532 (NFC) + pad capacitif central.
* **Faces 2-5 :** Pad capacitif central uniquement.
* **Fixation :** Plaque contre la membrane de 1.0mm, enfiché dans l'étage B via connecteurs 2.54mm.

### Étage B : PCB "Anneau" (LEDs & Structure)
* **LEDs :** 12x WS2812B disposées en cercle, orientées vers l'extérieur.
* **Connectivité :** Reçoit le PCB Bouchon (femelle 2.54) et renvoie les signaux au PCB central (JST).
* **Flux d'air :** Large ouverture centrale (~30mm) pour la dissipation thermique.

---

## 3. Gestion de l'Énergie & Thermique

### Alimentation & Charge
* **Batterie :** LiPo 3.7V — capacité cible 2000-3000mAh (le volume d'un cube de 12cm le permet).
* **Charge Qi :** Récepteur Qi 5V sur la face du dessous.
* **Charge USB-C :** Résistances 5.1kΩ, accès maintenance.
* **Contrôleur :** TP4056 avec protection (CHRG/STDBY).

### Monitoring (I2C & Analogique)
* **Jauge :** CW2015 — suivi précis de la capacité via I2C.
* **Thermique :** NTC 10kΩ sur batterie, reliée à l'ESP32-S3 (ADC) et au TP4056 (coupure auto >45°C).

### Estimation d'Autonomie
| Mode | Consommation estimée | Autonomie (2500mAh) |
|------|---------------------|---------------------|
| Deep Sleep | ~10µA | ~28 000h (3+ ans) |
| Veille (LEDs 10%) | ~50mA | ~50h |
| Actif (LEDs 50% + ESP-NOW) | ~150mA | ~16h |
| Actif max (LEDs 100% + BLE) | ~250mA | ~10h |

---

## 4. Mapping des Pins (ESP32-S3)

| Fonction | Pin GPIO | Détails |
| :--- | :--- | :--- |
| **LEDs Face 1 (dessus)** | GPIO 1 | Data WS2812B |
| **LEDs Face 2 (avant)** | GPIO 2 | Data WS2812B |
| **LEDs Face 3 (droite)** | GPIO 4 | Data WS2812B |
| **LEDs Face 4 (arrière)** | GPIO 5 | Data WS2812B |
| **LEDs Face 5 (gauche)** | GPIO 6 | Data WS2812B |
| **LEDs Face 6 (dessous)** | GPIO 7 | Data WS2812B (indicateur charge) |
| **I2C SDA** | GPIO 8 | Bus commun (PN532 + CW2015) |
| **I2C SCL** | GPIO 9 | Bus commun |
| **Touch Face 1** | GPIO 10 | Capacitif natif ESP32-S3 |
| **Touch Face 2** | GPIO 11 | Capacitif natif |
| **Touch Face 3** | GPIO 12 | Capacitif natif |
| **Touch Face 4** | GPIO 13 | Capacitif natif |
| **Touch Face 5** | GPIO 14 | Capacitif natif |
| **Touch Face 6** | GPIO 21 | Capacitif natif (optionnel) |
| **TP4056 CHRG** | GPIO 15 | État de charge |
| **TP4056 STDBY** | GPIO 16 | Charge terminée |
| **NTC (Temp)** | GPIO 17 (ADC) | Surveillance thermique |
| **USB D-** | GPIO 19 | Programmation & Debug natif |
| **USB D+** | GPIO 20 | Programmation & Debug natif |

---

## 5. Structure Mécanique (OpenSCAD)

* **Dimensions :** Cube de ~12 cm d'arête.
* **Chambre de Diffusion :** "Ring Shroud" de 6mm entre les LEDs et la paroi extérieure.
* **Membranes Tactiles :** Épaisseur réduite à 1.0mm au centre de chaque face.
* **Système de Clips :** Ergots type baïonnette pour verrouiller le PCB Anneau.
* **Circulation d'air :** Effet cheminée par les centres évidés des faces.
* **Matériau :** Impression 3D (PLA/PETG) pour la petite série (5-10 unités).
* **Finition :** Peinture grise mate + vernis de protection.

---

## 6. Stack Logicielle (PlatformIO / Arduino Framework)

| Composant | Librairie / Technologie | Rôle |
|-----------|------------------------|------|
| **Animations LEDs** | FastLED | Gestion des 6 sorties WS2812B |
| **NFC** | Adafruit PN532 | Lecture/écriture tags NFC (I2C) |
| **Communication locale** | ESP-NOW (natif) | Liaison cube ↔ passerelle |
| **BLE** | NimBLE-Arduino | Configuration initiale, pairing |
| **OTA** | Via passerelle (ESP-NOW) | Mise à jour firmware sans fil |
| **Jauge batterie** | CW2015 driver | Monitoring SOC (I2C) |
| **Sécurité thermique** | Custom | Priorité aux alertes NTC + SOC |
| **Persistance config** | Preferences (NVS) | Stockage local des actions/profils |

### Structure MQTT (Topics)

```
ops/cube/{cube_id}/status          → Statut général (batterie, temp, uptime)
ops/cube/{cube_id}/face/{n}/state  → État visuel de la face n
ops/cube/{cube_id}/face/{n}/action → Action déclenchée par l'utilisateur
ops/cube/{cube_id}/config          → Configuration des actions (serveur → cube)
ops/cube/{cube_id}/config/ack      → Acquittement de configuration
ops/cube/{cube_id}/alert           → Alertes push (serveur → cube)
ops/cube/{cube_id}/alert/ack       → Acquittement d'alerte
ops/cube/{cube_id}/ota             → Commande de mise à jour OTA
ops/cube/{cube_id}/ota/status      → Statut de la mise à jour
```

---

# Partie 3 — Passerelle (Gateway/Dock)

## 1. Rôle

La passerelle est le pont entre les cubes (communication locale) et le serveur (réseau IP). Elle sert également de station de charge Qi.

## 2. Matériel

* **MCU :** ESP32-S3 (WiFi activé) ou ESP32-C6 (WiFi + Thread).
* **Communication locale :** ESP-NOW (cube ↔ passerelle).
* **Communication réseau :** WiFi → MQTT vers le serveur ops-devices.
* **Charge :** Émetteur Qi 5V intégré dans le dock.
* **Connectivité optionnelle :** Module 4G (SIM7600) pour les déploiements sans WiFi.
* **Alimentation :** USB-C 5V (branchée en permanence).

## 3. Fonctionnalités Logicielles

* **Relais MQTT ↔ ESP-NOW :** Traduction transparente des messages.
* **File d'attente :** Stockage des messages si un cube est en deep sleep, livraison au réveil.
* **Multi-cube :** Gestion de 1 à N cubes simultanément.
* **OTA Proxy :** Télécharge le firmware depuis le serveur, le transmet au cube en ESP-NOW.
* **Watchdog :** Détection de perte de connexion (cube ou serveur) avec alertes.
* **Logs :** Historique local des interactions (SPIFFS/LittleFS).

---

# Partie 4 — Feuille de Route

## v1.0 — MVP (ESP32-S3)
* Cube fonctionnel avec 6 faces LED + tactile + 1 NFC.
* Passerelle ESP-NOW → WiFi → MQTT.
* Configuration des actions via l'interface web ops-devices.
* Charge Qi + USB-C.
* Firmware OTA via passerelle.
* **Cible :** 5-10 unités, budget 50-100€/cube (hors passerelle).

## v1.1 — Améliorations
* Synthèse vocale (petit haut-parleur, annonce des actions/alertes).
* Synchronisation multi-cubes (actions coordonnées via ESP-NOW).
* Profils NFC (changement de jeu d'actions par tag).

## v2.0 — Version Souveraine (STM32WB)
* Remplacement ESP32-S3 par STM32WB (STMicroelectronics, français).
* Communication Thread/Matter native.
* Touch via contrôleur externe (AT42QT1070).
* OTA via BLE (STM32 OTA DFU).
* Certification et durcissement pour usage Défense.
* Aucune technologie non-européenne dans la chaîne.

---

## BOM Estimatif (v1.0 — par cube)

| Composant | Référence | Qté | Prix unitaire | Total |
|-----------|-----------|-----|---------------|-------|
| ESP32-S3-WROOM-1 | Espressif | 1 | ~4€ | 4€ |
| WS2812B (LEDs) | — | 72 (12/face) | ~0.05€ | 4€ |
| PN532 (NFC) | NXP | 1 | ~3€ | 3€ |
| TP4056 (Charge) | — | 1 | ~0.50€ | 1€ |
| CW2015 (Jauge) | CellWise | 1 | ~1€ | 1€ |
| NTC 10kΩ | — | 1 | ~0.10€ | 0€ |
| Batterie LiPo 2500mAh | — | 1 | ~8€ | 8€ |
| Récepteur Qi | — | 1 | ~3€ | 3€ |
| PCBs (6 anneaux + 6 bouchons + central) | JLCPCB | 13 | ~1€ | 13€ |
| Connecteurs JST + 2.54mm | — | lot | ~3€ | 3€ |
| Boîtier impression 3D | PLA/PETG | 1 | ~5€ | 5€ |
| USB-C + passifs | — | lot | ~2€ | 2€ |
| **TOTAL** | | | | **~47€** |

> Budget restant (~3-53€) disponible pour la finition, les imprévus, et l'outillage.