Files
Support-Agent/docs/guide/diagnostic-energetique.md
T

179 lines
14 KiB
Markdown
Raw Normal View History

# Manuel : lire le diagnostic énergétique d'une station AIMsight
- **Statut** : brouillon, 2026-10-12. La couleur du jour (partie 1) est calculée par `src/day_color.py`, selon la matrice de `cas-d-usage-03-04.drawio` (D-020), mais aucun graphique ne l'affiche encore (D-021).
- **Lecteurs** : la partie 1 s'adresse au client final ; la partie 2 à l'ingénieur support AIMsight.
---
# Partie 1 : lecture rapide
## 1. Ce que surveille le diagnostic
Une station AIMsight fonctionne sur batterie. La batterie est rechargée par un panneau solaire ou par le secteur.
Chaque jour, pour chaque station, le diagnostic répond à une question : **l'énergie reçue ce jour-là couvre-t-elle la consommation de la station ?**
La réponse est une **couleur par jour**, accompagnée d'une **flèche** qui compare le jour à la veille.
Une station peut avoir une batterie encore bien chargée et déjà être en difficulté : si elle ne reçoit plus d'énergie, elle s'arrêtera tôt ou tard. Le diagnostic regarde donc si l'énergie arrive, pas seulement si la batterie est pleine.
## 2. Les trois couleurs, et ce qu'il faut faire
| Couleur | Ce que ça veut dire | Que faire |
|---|---|---|
| 🟢 **Vert** | La station a reçu assez d'énergie ce jour-là. | Rien. |
| 🟠 **Orange** | Incertain : la batterie s'est rechargée, mais pas complètement. Le bilan de la journée ne peut pas être établi. | Rien si l'orange est isolé : un jour nuageux suffit à le produire. **Prévenir le support si l'orange dure plus de 3 jours d'affilée.** |
| 🔴 **Rouge** | La station ne reçoit pas assez d'énergie. Des coupures, la nuit surtout, sont possibles ou déjà en cours. | **Contacter le support.** |
| ⚪ **Gris** | Inconnu : pas assez de mesures ce jour-là pour conclure, ou premier jour suivi (pas de veille à comparer). | Regarder les jours voisins. |
- **Pourquoi 3 jours** : sur la station de référence (VERMONT), en période saine, la plus longue série de jours sans recharge complète est de 3 jours (du 04 au 06/05/2026). Ce seuil reste à confirmer sur d'autres stations.
- **La couleur du jour peut encore changer** tant que la journée n'est pas terminée (minuit UTC).
## 3. La flèche : comparaison avec la veille
| Flèche | Ce que ça veut dire |
|---|---|
| ↗ | mieux que la veille |
| → | comme la veille |
| ↘ | moins bien que la veille |
La flèche nuance la couleur :
- **un orange ↘** inquiète plus qu'un orange → ;
- **un vert ↗** après un orange : la station a récupéré.
Une seule flèche ↘ n'est pas une alerte : un jour nuageux en donne une, suivie d'un ↗ le lendemain. **C'est la répétition qui compte.**
## 4. Trois exemples réels (station VERMONT, solaire, 2026)
### Une période saine
Du 05 au 14/08 : 🟢 → tous les jours. La batterie se recharge complètement chaque jour et se retrouve au même niveau chaque matin.
### Des oranges isolés : rien à faire
| Jour | 03/08 | 04/08 | … | 15/08 | 16/08 | 17/08 | 18/08 | 19/08 |
|---|---|---|---|---|---|---|---|---|
| Couleur | 🟠 ↘ | 🟢 ↗ | | 🟠 ↘ | 🟢 ↗ | 🟢 → | 🟠 ↘ | 🟢 ↗ |
Chaque orange est un jour nuageux, et la station revient au vert dès le lendemain.
### Une station qui s'épuise : prévenir le support, puis contacter le support
| Période | Couleurs | Ce qui se passe |
|---|---|---|
| 29/08 – 01/09 | 🟠 🟠 🟠 🟠 | **4 jours d'orange d'affilée** : c'est plus que tout ce qu'on voit en période saine. **Le 01/09, il faut prévenir le support**, 26 jours avant la première coupure. |
| 02/09 – 25/09 | surtout 🟠 ; 🟢 seulement les 02–05, 07, 11, 18 et 19/09 | Les recharges complètes deviennent rares. Deux séries de 6 jours d'orange (12–17/09 et 20–25/09). |
| 26/09 | 🔴 ↘ | La batterie est descendue sous ~30 % de charge. **Il faut contacter le support.** |
| 27/09, 01:00 UTC | 🔴 | Première coupure de la station, la nuit. |
| jusqu'au 09/10 | 🔴 | Coupures nocturnes répétées. |
Diagnostic de l'expert : interruptions nocturnes dues à un déficit d'énergie. Remède indiqué : réactiver le mode veille profonde entre les mesures, pour réduire la consommation.
---
# Partie 2 : annexe technique (support)
La couleur du jour combine deux analyses de la tension batterie (`BusVoltage`, moyennes horaires) :
- l'**état** du jour (analyse 03, `DAILY_BATTERY_STATE`) ;
- la **tendance** face à la veille (analyse 04, `DAILY_BATTERY_TREND`).
Le détail de chaque analyse (calcul exact, sources, résultats, options écartées) est dans sa fiche : `docs/analyses/analyse_03.md` et `docs/analyses/analyse_04.md`.
Une couleur reste une preuve imparfaite : elle conclut au plus `consistent with`. Elle signale une journée à regarder, elle ne remplace pas le diagnostic.
## 5. L'état du jour (analyse 03)
Chaque journée UTC (00:00 à 23:00) est lue avec deux seuils du matériel, valables dès le premier jour d'installation, sans historique (D-018) :
- **14,0 V** : fin de charge du chargeur. Une heure à 14,0 V ou plus signale une recharge complète.
- **12,8 V** : coude de la batterie LiFePO4 (~30 % de charge). Au-dessus, la tension de nuit reste presque plate (le « plateau ») ; en dessous, elle chute de plus en plus vite.
L'état se lit dans cet ordre ; la première condition vraie l'emporte :
| Ordre | Condition | État | Lecture |
|---|---|---|---|
| 1 | au moins une heure ≥ 14,0 V | ● `FULL_CHARGE` | l'apport a rempli la batterie |
| 2 | une heure < 12,8 V | ▼ `BELOW_PLATEAU` | décharge visible : la batterie a quitté le plateau |
| 3 | montée du jour < 0,05 V | ✕ `NO_CHARGE` | aucun apport visible de la journée |
| 4 | sinon | ◆ `PARTIAL_CHARGE` | **incertain** : charge sans recharge complète ; sur le plateau, on ne sait pas si la batterie a gagné ou perdu |
- **Montée du jour** : la plus grande hausse de tension depuis un minimum antérieur du même jour.
- **Fin de nuit** : le minimum dont part cette montée, juste avant la charge du jour. C'est le meilleur repère du niveau de la batterie.
- **Sources des seuils** :
- 14,0 V : sur VERMONT, le maximum du jour est soit sous 13,55 V, soit entre 14,02 et 14,33 V (170 jours sur 173) ;
- 12,8 V : table OCV du collecteur ;
- 0,05 V : au-dessus du bruit d'une heure sur le plateau, sous la plus faible vraie recharge observée (+0,079 V un jour nuageux).
## 6. La tendance (analyse 04)
On compare le jour J à la veille J−1 :
1. **Si l'état a changé, l'état décide.** Rang : `FULL_CHARGE` > `PARTIAL_CHARGE` > `NO_CHARGE` > `BELOW_PLATEAU`. Un état plus haut donne `BETTER` (↗), un état plus bas donne `WORSE` (↘).
2. **Sinon, la fin de nuit décide** : écart = fin de nuit de J − fin de nuit de J−1.
- écart > +0,05 V : `BETTER` (↗) ;
- écart < −0,05 V : `WORSE` (↘) ;
- sinon : `STABLE` (→).
**Source de la zone morte de ±0,05 V** : sur VERMONT, entre deux jours `FULL_CHARGE` consécutifs, l'écart va de −0,026 à +0,043 V (5e et 95e centiles). Les jours de déficit de septembre baissent de −0,07 à −0,12 V.
**À savoir en lisant les barres** : la fin de nuit de J est celle du matin de J. Son écart résume donc la recharge de J−1, alors que l'état est celui de J. Quand l'état change, la barre peut le contredire. Exemple : le 12/04, l'état passe de `PARTIAL_CHARGE` à `FULL_CHARGE` (↗), avec une barre à −0,187 V, héritée du 11/04 nuageux.
## 7. La matrice : de l'état et de la tendance à la couleur
| Tendance \ État | ● `FULL_CHARGE` | ◆ `PARTIAL_CHARGE` | ✕ `NO_CHARGE` | ▼ `BELOW_PLATEAU` |
|---|---|---|---|---|
| ↗ `BETTER` | 🟢 | 🟢 | 🟠 | 🔴 |
| → `STABLE` | 🟢 | 🟠 | 🔴 | 🔴 |
| ↘ `WORSE` | 🟢 | 🟠 | 🔴 | 🔴 |
Lecture de chaque case, avec le nombre de jours observés sur VERMONT (184 jours, du 09/04 au 09/10/2026) :
| État | Tendance | Couleur | Situation | Lecture | VERMONT |
|---|---|---|---|---|---|
| `FULL_CHARGE` | ↗ | 🟢 | retour à la recharge complète, ou fin de nuit plus haute | récupération après un jour faible | 17 j |
| `FULL_CHARGE` | → | 🟢 | recharge complète, fin de nuit à ±0,05 V | cas sain : `consistent with` un régime soutenable | 120 j |
| `FULL_CHARGE` | ↘ | 🟢 | recharge complète, fin de nuit plus basse | rare ; à vérifier | 1 j (24/07 : artefact de trou, le 23/07 n'a que 16 h mesurées) |
| `PARTIAL_CHARGE` | ↗ | 🟢 | reprise depuis `NO_CHARGE` ou `BELOW_PLATEAU`, ou fin de nuit plus haute | l'apport reprend | 0 j |
| `PARTIAL_CHARGE` | → | 🟠 | charge partielle, fin de nuit à ±0,05 V | incertain ; une dérive lente (< 0,05 V/jour) reste « stable » | 10 j, dont 22–24/09 alors que la station s'épuise |
| `PARTIAL_CHARGE` | ↘ | 🟠 | après une recharge complète, ou fin de nuit plus basse | jour nuageux ou début de déficit : à surveiller s'il se répète | 21 j |
| `NO_CHARGE` | ↗ | 🟠 | depuis `BELOW_PLATEAU`, ou fin de nuit plus haute sans apport | peu plausible physiquement : vérifier les données (trou, redémarrage) | 0 j |
| `NO_CHARGE` | → | 🔴 | 2e jour sans apport ou plus, batterie restée sur le plateau | `consistent with` une alimentation absente, même batterie pleine (D-004) | 0 j |
| `NO_CHARGE` | ↘ | 🔴 | perte de l'apport, ou fin de nuit qui baisse sans apport | `consistent with` une perte d'alimentation | 0 j |
| `BELOW_PLATEAU` | ↗ | 🔴 | fin de nuit plus haute, toujours sous le plateau | **souvent un faux « mieux »** : un jour de coupure, la fin de nuit est la tension de redémarrage | 3 j (01/10, 03/10, 08/10), tous faux |
| `BELOW_PLATEAU` | → | 🔴 | sous le plateau, fin de nuit à ±0,05 V | `consistent with` un régime non soutenable qui dure | 7 j |
| `BELOW_PLATEAU` | ↘ | 🔴 | entrée sous le plateau, ou fin de nuit qui baisse encore | `consistent with` un régime non soutenable ; coupures nocturnes possibles | 4 j (26/09 entrée, 27/09, 02/10, 09/10) |
- **Total VERMONT** : 138 jours 🟢, 31 🟠, 14 🔴 et 1 jour gris (09/04, premier jour : sans veille, pas de tendance).
- **Jour gris** : l'état ou la tendance est inconnu (moins de 20 h mesurées sans recharge complète ni passage sous le plateau, ou pas de veille). La matrice ne traite pas encore ces cas (D-020, D-021).
- **Pourquoi `NO_CHARGE` → est rouge et non orange** : en orange, une coupure d'alimentation passerait du rouge (1er jour, ↘) à l'orange (2e jour, →) alors qu'elle continue. Une batterie assez grande pour rester sur le plateau ne change rien : sans apport, la station tombera (D-004).
## 8. Lire les pages HTML
Commande : `python3 src/analyse_03.py`. Elle écrit deux pages dans `out/` et les ouvre dans le navigateur.
- `<STATION>_daily.html` : le graphique destiné au site de monitoring (D-021), soit les panneaux `DAILY_BATTERY_STATE` et `DAILY_BATTERY_TREND` décrits ci-dessous, sur le même axe du temps. Sa figure Plotly est aussi écrite en JSON (`<STATION>_daily.json`), pour `Plotly.newPlot`.
- `<STATION>_energy.html` : la page de toutes les analyses, avec ces deux panneaux, et une courbe par mesure dessous.
- `<STATION>_focus_<AAAA-MM-JJ>.html` : le focus sur un jour et sa veille (D-024), pour comprendre une couleur. Commande : `python3 src/focus_jour.py 27.09`. Le terminal affiche les faits qui ont produit la couleur ; le graphique montre les 48 h de `BusVoltage`, avec les heures sans mesure en gris, les seuils de 14,0 et 12,8 V, le maximum et la fin de nuit de chaque jour, et une flèche de la fin de nuit de la veille à celle du jour (bleue ↗, grise →, rouge ↘).
**Attention aux couleurs** : celles des panneaux ne sont pas celles de la matrice. Elles distinguent les états et les tendances ; elles ne disent pas le niveau de préoccupation. Par exemple, `BELOW_PLATEAU` y est en bleu.
- **Langue** : les titres, légendes et survols des panneaux 03 et 04 sont en anglais, comme le site (D-023). Par exemple, le maximum du jour est `daily maximum`, la fin de nuit `night end`, et les tendances `better`, `stable` et `worse`.
- **Les panneaux 01 et 02** (moyennes sur 7 jours), en haut de la page, ne font pas partie de ce diagnostic : les ignorer.
- **Panneau `DAILY_BATTERY_STATE`** (analyse 03), un point par jour, placé à midi UTC :
- courbe foncée : le maximum du jour ; courbe claire : la fin de nuit ;
- tirets : les seuils de 14,0 V (vert) et de 12,8 V (bleu) ;
- marqueurs sur le maximum, selon l'état : ● vert `FULL_CHARGE`, ◆ jaune orangé `PARTIAL_CHARGE`, ▼ bleu `BELOW_PLATEAU`, ✕ violet `NO_CHARGE`.
- **Panneau `DAILY_BATTERY_TREND`** (analyse 04), une barre par jour :
- hauteur : l'écart de fin de nuit face à la veille, en V ;
- couleur : bleu ↗, gris →, rouge ↘ ;
- tirets : la zone morte de ±0,05 V ;
- quand l'état décide, la couleur suit la tendance, même si la barre est petite ou de signe contraire (voir § 6).
- **Survol** : chaque point et chaque barre affichent les faits calculés du jour (état, tensions, écarts, ce qui a décidé la tendance).
- **Dessous** : une courbe par mesure. Sur `BusVoltage`, les bandes grises marquent les heures sans mesure, et les bandes colorées les zones de tension (décharge, en charge, pleine charge).
- **Zoom** : dans le temps seulement, au rectangle ou à la molette ; double-clic pour revenir à la vue complète.
## 9. Limites à connaître
1. **Jour UTC** : la journée est coupée à minuit UTC. Pour une station éloignée en longitude, la nuit serait coupée en deux, et la fin de nuit faussée.
2. **Seuil de 14,0 V** : il suppose le même chargeur sur toutes les stations, ce qui n'est pas confirmé. Une recharge complète de moins d'une heure peut aussi être lue `PARTIAL_CHARGE` (08/09 : maximum à 13,96 V).
3. **Jours de coupure** : faux ↗ sous le plateau (voir § 7). La couleur reste rouge.
4. **Dérive lente** : une baisse de moins de 0,05 V par jour est lue → (VERMONT, 22–24/09, alors que la station s'épuise). La série d'oranges, elle, la signale.
5. **Froid** : aucune donnée d'hiver. Sous 0 °C, la charge d'une batterie LiFePO4 est en général bloquée : des jours orange ou rouges sont possibles même au soleil.