esp_jardin/Fichier de Consignes - esp_jardin.md

# **CAHIER DES CHARGES & CONSIGNES DE DÉVELOPPEMENT : ESP\_JARDIN**

Ce document sert de prompt maître (Master Prompt) et de cahier des charges technique pour guider le développement de l'application embarquée esp\_jardin.

## **1\. Contexte, Vision & Objectifs**

L'objectif est de concevoir le firmware d'une station d'acquisition environnementale autonome basée sur un microcontrôleur **ESP32**, nommée **esp\_jardin**.  
Cet appareil doit acquérir les températures de trois sondes DS18B20, conserver un historique glissant de 24 heures en RAM, et proposer une double interface d'accès aux données :

1. Une **interface web locale moderne, responsive et en temps réel** (via WebSockets), accessible depuis les ordinateurs et smartphones.  
2. Une **API REST ultra-rapide** pour l'intégration automatique (ex: serveurs MCP, scripts d'automation, Home Assistant).

Le projet est développé sous **VS Code avec l'extension PlatformIO** en s'appuyant sur le **framework Arduino (C++)**, jugé optimal pour l'écosystème de librairies asynchrones requis.

tu debutera par une phase de recherche sur internet, suivi d’un brainstorming avec question sur les lib a utiliser ( avantage inconvenient) , les sondes a utiliser, le cablage, les evolution futures du projet). ensuite tu mettre a jours le dossier du projet en respectant l’architecture de plateformio, tu mettra a jours le parametrage de platformio pour la carte utilisée, ensuite tu creera le plan de deploiement. pense bien a faire l’analyse du design\_system. verifier la coherence de ce fichier de consigne avec les bonnes pratiques et mettre ajours si besoin.

## **2\. Phase 1 : Analyse Matérielle, GPIO & Évolutivité**

L'ESP32 possède des caractéristiques électriques et de boot strictes (Strapping Pins, Input-only pins, restrictions d'usage de l'ADC2 avec le WiFi). La sélection des GPIO pour les sondes actuelles et les extensions futures a été analysée de manière à préserver la stabilité du système.

### **Tableau d'allocation et de mapping des GPIO**

| GPIO Natif (ESP32) | Broche Standard (DevKit V1) | Broche alternative (Notation Arduino) | Fonction Actuelle | Type & Caractéristiques | Évolutivité / Usage Futur Prévu |
| :---- | :---- | :---- | :---- | :---- | :---- |
| **GPIO 4** | D4 | 4 | **Bus OneWire (DS18B20)** | Numérique I/O | Supporte l'ajout en parallèle d'autres sondes DS18B20. |
| **GPIO 21** | D21 | 21 | *Libre* | I/O (Bus I2C SDA) | Capteur de luminosité (BH1750) ou humidité/T° d'air (SHT31). |
| **GPIO 22** | D22 | 22 | *Libre* | I/O (Bus I2C SCL) | Horloge RTC externe ou capteurs I2C partagés. |
| **GPIO 32** | D32 | 32 | *Libre* | ADC1\_CH4 (Analogique) | Capteur d'humidité de sol (capacitif ou résistif). |
| **GPIO 33** | D33 | 33 | *Libre* | ADC1\_CH5 (Analogique) | Second capteur d'humidité ou entrée analogique. |
| **GPIO 25** | D25 | 25 | *Libre* | Numérique I/O / DAC | Commande d'actionneur / Relais (ex : Électrovanne arrosage). |
| **GPIO 26** | D26 | 26 | *Libre* | Numérique I/O / DAC | Commande d'actionneur 2 / Relais ou avertisseur sonore. |
| **GPIO 14** | D14 | 14 | *Libre* | Numérique (Interruption) | Capteur d'impulsions (ex: Pluviomètre à augets). |
| **GPIO 27** | D27 | 27 | *Libre* | Numérique (Interruption) | Bouton poussoir physique (ex: Reset paramètres ou forçage AP). |

*Note sur le bus OneWire : Une résistance de pull-up externe de 4.7kΩ est obligatoire entre le VCC (3.3V) et la broche de données (GPIO 4).*

## **3\. Architecture Logicielle & Arborescence PlatformIO**

L'architecture du projet doit être modulaire (fichiers .h et .cpp séparés) pour éviter de surcharger le point d'entrée principal.  
esp\_jardin/  
├── platformio.ini         \# Configuration PlatformIO et dépendances bibliothèques  
├── parametrage.md         \# Fichier source des configurations par défaut (SSID, Topics, Intervalles...)  
├── include/  
│   ├── config.h           \# Généré d'après parametrage.md (Structures, constantes globales)  
│   ├── network.h          \# Déclarations WiFi (AP/STA), mDNS, OTA, WebSockets  
│   ├── sensors.h          \# Déclarations OneWire, DallasTemperature et gestion d'historique RAM  
│   ├── web\_server.h       \# Déclarations serveur HTTP, API REST  
│   └── mqtt\_manager.h     \# Déclarations client MQTT, logique de publication  
├── src/  
│   ├── main.cpp           \# Initialisation, machine à états et loop non bloquante  
│   ├── network.cpp        \# Gestion WiFi hybride, OTA, WebSockets  
│   ├── sensors.cpp        \# Acquisition T°C, validation métrologique, tampon circulaire RAM  
│   ├── web\_server.cpp     \# Routage endpoints REST, parsing JSON, service des pages web  
│   └── mqtt\_manager.cpp   \# Routage des messages MQTT, asynchronisme  
├── data/                  \# Fichiers optionnels pour SPIFFS/LittleFS (ex: CSS, JS, images)  
│   └── index.html         \# Page web dynamique responsive principale  
└── design\_system/         \# Maquettes, styles CSS et frameworks JS fournis par le designer  
    └── ...

## **4\. Source de Vérité Unique : parametrage.md**

Toutes les configurations et constantes par défaut de l'application devront être implémentées d'après les valeurs suivantes, écrites dans parametrage.md à la racine :  
\# Paramétrage Initial \- esp\_jardin

\#\# Connexion WiFi  
\- Mode Station (STA) :  
  \- SSID: "Mon\_Reseau\_WiFi"  
  \- PASS: "Mon\_Mot\_De\_Passe\_Securise"  
\- Mode Access Point (AP de secours) :  
  \- AP\_SSID: "ESP\_CHEF\_JARDIN"  
  \- AP\_PASS: "Jardin2026"  
  \- Connection\_Timeout: 30000 ms (30 secondes)

\#\# Acquisition & Fréquences  
\- Fréquence de mesure (échantillonnage de base) : 10 secondes (10000 ms)  
\- Taille de l'historique en RAM : 288 points par sonde (correspond à 24h avec 1 mesure échantillonnée toutes les 5 min pour le graphique).

\#\# Broker MQTT  
\- IP Broker: "10.0.0.3"  
\- Port: 1883  
\- MQTT\_User: ""  
\- MQTT\_Pass: ""

\#\# Paramètres Spécifiques par Capteur (MQTT Custom)  
\- Sonde 1 (Index 0 \- ex : Température Exterieur) :  
  \- Nom : "T°C Ext"  
  \- Topic: "maison/jardin/ext/temperature"  
  \- Intervalle de publication : 60000 ms (1 minute)  
  \- Variation minimale requise (Deadband) : 0.2 °C  
\- Sonde 2 (Index 1 \- ex : Température Serre) :  
  \- Nom : "T°C Serre"  
  \- Topic: "maison/jardin/serre/temperature"  
  \- Intervalle de publication : 60000 ms (1 minute)  
  \- Variation minimale requise (Deadband) : 0.1 °C  
\- Sonde 3 (Index 1 \- ex : Température du Sol) :  
  \- Nom : "T°C Sol"  
  \- Topic: "maison/jardin/sol/temperature"  
  \- Intervalle de publication : 60000 ms (1 minute)  
  \- Variation minimale requise (Deadband) : 0.1 °C

## **5\. Spécifications Fonctionnelles Détaillées**

### **5.1. Gestion de la connectivité réseau**

1. **WiFi Hybride non-bloquant :** Au boot, l'ESP tente de se connecter en mode STA avec les identifiants fournis. S'il échoue après un temps d'attente spécifié, il initialise un point d'accès autonome (AP) nommé ESP\_CHEF\_JARDIN.  
2. **mDNS :** L'appareil s'enregistre sur le réseau local. L'interface d'administration et les API doivent être joignables à l'adresse DNS multicast http://esp\_jardin.local.  
3. **Mise à jour OTA :** Intégration de la bibliothèque ArduinoOTA avec mot de passe pour téléverser de nouveaux binaires à distance sans liaison physique USB.

### **5.2. Acquisition, Traitement RAM & Validation Métrologique**

1. **Précision numérique :** Les relevés de température doivent être formatés avec rigueur à **un seul chiffre après la virgule** (type float traité ou formaté via %.1f).  
2. **Tableau Circulaire en RAM (Historique 24h) :**  
   * L'historique des 24 heures glissantes doit utiliser un tableau circulaire (CircularBuffer ou logique d'indexation fixe dans un tableau de 288 structures par sonde) pour s'affranchir de l'usure de la mémoire Flash.  
   * *Validation mémoire :* Chaque élément stockant le timestamp (uint32\_t) \+ les deux températures (2x float) représente 12 octets. 288 mesures consomment \~3.45 Ko, ce qui est extrêmement sûr pour les 520 Ko de SRAM de l'ESP32 (impact \< 1%).  
3. **Robustesse matérielle :** Gestion des pannes de sondes Dallas (vérification des CRC et interception des codes d'erreur matériels types \-127.0 ou 85.0). Ces valeurs invalides ne doivent pas être écrites en RAM ni envoyées au broker MQTT.

### **5.3. Interface Web Interactive (Responsive & WebSocket)**

1. **WebSocket Temps Réel :** Dès qu'une nouvelle mesure est validée sur le bus OneWire, la valeur rafraîchie est sérialisée en JSON et poussée instantanément sur tous les clients connectés par WebSocket. Le polling HTTP est proscrit pour le temps réel.  
2. **Design System & Adaptabilité :**  
   * L'interface doit s'appuyer sur la charte et les classes CSS du dossier design\_system.  
   * L'application Web doit être fluide et ergonomique sur les écrans étroits (smartphones) comme sur les écrans larges (moniteurs / laptops).  
3. **Graphique Glissant :** Intégration d'un graphique (Chart.js ou équivalent via un CDN optimisé) représentant les 24h de mesures stockées en RAM. À l'ouverture, le graphique est initialisé avec l'historique complet (requête REST API), puis s'incrémente au fil de l'eau via les réceptions WebSocket.  
4. **Console d'Administration :** Intégration d'un formulaire pour ajuster dynamiquement l'intervalle d'échantillonnage et les configurations des serveurs MQTT.

### **5.4. API REST Standardisée**

Créer des endpoints de requêtes HTTP GET pour la lecture directe et l'intégration externe (scripts automatisés, serveurs de protocoles MCP) :

* **GET /api/status :** Renvoie l'état système (RSSI WiFi, Uptime, Mémoire RAM libre).  
* **GET /api/temperatures :** Renvoie l'état instantané au format standardisé :  
  {"sonde\_1": 19.3, "sonde\_2": 11.8, "unit": "C"}.  
* **GET /api/history :** Renvoie l'historique complet sous forme de tableau d'objets JSON pour reconstruire la courbe sur des serveurs tiers.

### **5.5. Publication MQTT Avancée**

Chaque capteur doit être géré de manière indépendante pour sa transmission :

1. **Cycles asynchrones :** La publication s'effectue à l'aide d'une tâche temporelle non bloquante (utilisation stricte de millis()).  
2. **Filtrage "Deadband" :** Si la différence absolue entre la température actuelle et la dernière valeur publiée est inférieure au seuil de variation (ex : 0.2°C pour la sonde 1), la publication est ignorée pour limiter la saturation de la bande passante, sauf si l'intervalle maximal de secours est dépassé.

## **6\. Plan de Déploiement, Validation & Tests (Livrables attendus)**

### **Étape A : Initialisation (Rapport d'analyse d'entrée)**

L'agent doit formaliser l'architecture du projet et les fichiers platformio.ini et parametrage.md initiaux.

### **Étape B : Production du Code Source Modulaire**

Production des fichiers de code .h et .cpp sans **aucun blocage** de type delay(). L'agent doit commenter le code en français de manière didactique.

### **Étape C : README de déploiement et d'utilisation**

Rédaction d'un fichier README.md complet intégrant :

1. Schéma électrique simplifié de connexion (rappel de la résistance pull-up 4.7kΩ).  
2. Directives de compilation et d'écriture de la configuration.  
3. Guide de première connexion au point d'accès de secours ESP\_CHEF\_JARDIN et configuration.  
4. Schémas de données pour l'API REST.

### **Étape D : Protocole de validation de robustesse**

Section expliquant comment tester :

1. La déconnexion sauvage du WiFi (le programme doit tenter une reconnexion automatique en boucle sans bloquer la boucle principale).  
2. La déconnexion d'une des sondes physiques (affichage d'un code erreur visuel sur l'interface au lieu d'une fausse température de \-127°C).  
3. L'indisponibilité temporaire du broker MQTT (mise en file d'attente ou rejet propre sans faire planter le microcontrôleur).