Add the day color matrix, the energy diagnostic manual and the site figure

D-020: the delivered energy diagnostic keeps analyses 03 and 04 only,
combined by the state x trend matrix of cas-d-usage-03-04.drawio into
one color per day (green / orange / red, grey when unknown), coded in
src/day_color.py (standard library). docs/guide/diagnostic-energetique.md
explains it: part 1 for the client, part 2 for support.

D-021: energy_plot.daily_figure builds the figure for the monitoring
site (panel 03 above panel 04, shared time axis), written by
analyse_01.py as out/<STATION>_daily.html and .json. battery_state no
longer imports energy_check, so analyses 03 and 04 ship on their own.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
maximeandClaude Opus 5.5 committed 2026-10-12 16:23:21 +02:00
1 parent 129d4ff59b
commit fc74fec10f
9 files changed
+467 -8

No files matched your search

+177
View File
@@ -0,0 +1,177 @@
# 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.
**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.
- **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.