From 95e3cb5c3b1f114e62a7da85e9d3e2b1ef3dbed8 Mon Sep 17 00:00:00 2001 From: Julien Holtzer Date: Sun, 8 Feb 2026 12:11:17 +0100 Subject: [PATCH] =?UTF-8?q?v0.2.0=20-=20Sp=C3=A9cifications=20compl=C3=A9t?= =?UTF-8?q?=C3=A9es=20:=20architecture=202=20tiers,=20actions=20configurab?= =?UTF-8?q?les,=20passerelle,=20BOM,=20roadmap?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- SPECIFICATIONS.md | 362 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 362 insertions(+) diff --git a/SPECIFICATIONS.md b/SPECIFICATIONS.md index e69de29..5ede4c0 100644 --- a/SPECIFICATIONS.md +++ b/SPECIFICATIONS.md @@ -0,0 +1,362 @@ +# 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. \ No newline at end of file