# `DAILY_BATTERY_STATE` : état de la batterie jour par jour - **Statut** : prototype en place (2026-10-12). Phase C : l'état seul, sans verdict. La phase B (niveaux gradués) viendra ensuite (D-018). - **Script** : `python3 src/energy/final.py [CSV ou dossiers]` (défaut : `data/VERMONT/`). Il écrit la page livrée, `out/_daily.html` + `.json`, dont cette analyse est le panneau du haut (D-021), et l'ouvre dans le navigateur. Elle est aussi le troisième panneau de `python3 src/energy/all_analyses.py` (comparaison, D-016). - **Code** : - `src/energy/battery_state.py` : calcul, bibliothèque standard uniquement (`run()`, `day_facts()`). Il reçoit les séries chargées par `common.stations.load_stations`, mais n'importe rien d'autre du projet : avec `src/energy/battery_trend.py`, il se livre seul à la plateforme (D-021) ; - `src/energy/final.py` : graphique plotly. ## Question posée Dans quel état la batterie a-t-elle passé chaque journée : remplie, chargée sans se remplir, ou en décharge visible ? - **Lien avec D-004** : une journée où l'apport remplit la batterie est soutenable ce jour-là. Une décharge visible signale un apport qui ne couvre pas la consommation. - **Ce que l'analyse ajoute aux deux `MOVING_AVERAGE_*`** : - pas d'inertie : l'état d'un jour ne dépend que de ce jour ; - aucun historique nécessaire, donc utilisable **dès le premier jour d'installation**, pour repérer une alimentation absente ou un apport insuffisant. - **Elle signale les journées incertaines** : sur le plateau LiFePO4, une charge partielle ne dit pas si la batterie a gagné ou perdu. C'est le moment d'indiquer au client que la situation énergétique est incertaine. ## Principe On lit chaque journée UTC avec des seuils physiques du matériel : la fin de charge du chargeur et le coude LiFePO4. Ces seuils valent dès le premier jour, sans comparaison au passé (D-018). Les tensions de référence sont dans `docs/energy/domaine/tensions-selon-l-etat-de-la-batterie.md`. Calcul exact, pour chaque jour UTC d (de 00:00 à 23:00) ayant au moins une ligne `BusVoltage` : 1. Heures mesurées : valeurs `BusVoltage` non vides et finies. Une valeur vide, `NaN` ou `inf` compte comme « pas de mesure ». Un horodatage hors de la grille horaire lève une erreur, comme dans `MOVING_AVERAGE_7_DAYS_DROP`. 2. `max_v` et `min_v` = maximum et minimum du jour. 3. `rise_v` = la plus grande montée du jour depuis un minimum antérieur : max sur h de (tension à h − minimum des heures ≤ h). 4. `night_end_v` = le minimum dont part cette montée (la fin de nuit, avant la charge du jour) ; sans montée, `min_v`. Le maximum du jour ne sert pas de repère : il peut être la queue de la soirée précédente, à 00:00. 5. `hours_full` = nombre d'heures ≥ `FULL_CHARGE_V`. 6. `coverage` = heures mesurées / 24. 7. L'état se lit dans cet ordre (la première condition vraie l'emporte) : | Ordre | Condition | `state` | Lecture | |---|---|---|---| | 1 | `hours_full` ≥ 1 | `FULL_CHARGE` | l'apport a rempli la batterie | | 2 | `min_v` < `PLATEAU_FLOOR_V` | `BELOW_PLATEAU` | décharge visible : la batterie a quitté le plateau | | 3 | `coverage` < `MIN_COVERAGE` | `None` (UNKNOWN) | trop de trous pour conclure à une absence | | 4 | `rise_v` < `MIN_RISE_V` | `NO_CHARGE` | décharge visible : aucun apport visible de la journée | | 5 | sinon | `PARTIAL_CHARGE` | **incertain** : charge sans pleine charge, bilan du jour illisible sur le plateau | - **Pourquoi les états 1 et 2 passent avant la couverture** : ils reposent sur une valeur mesurée, alors que les états 4 et 5 reposent sur l'absence de quelque chose. Un jour de coupure à moitié troué reste ainsi lisible s'il est passé sous le coude. - **Jour sans aucune heure mesurée** : `state` = `None`. Sortie (contrat commun) : un point par jour. - `t` = dernière heure du jour présente dans la série. - `value` = `max_v`, en V (`None` sans mesure). - `anomaly` = `None` pour tous les jours. **En phase C, `None` veut dire « pas de verdict »**, et non UNKNOWN comme dans le contrat ; l'UNKNOWN de l'état est porté par `state = None`. La phase B remplira `anomaly`. - `facts` = `{state, max_v, min_v, night_end_v, night_end_h, rise_v, hours_full, coverage}`. `night_end_h` est l'heure UTC (0 à 23) de la fin de nuit. **Causalité** : le jour d n'utilise que les heures de d. Pour le dernier jour d'un export, s'il est incomplet, l'état est provisoire : une heure ≥ 14,0 V ou un passage sous le coude peut encore survenir. ## Constantes et sources | Constante | Valeur | Source | |---|---|---| | `FULL_CHARGE_V` | 14,0 V | VERMONT, du 2026-04-09 au 2026-10-09 : sur 173 jours d'au moins 20 h mesurées, le maximum du jour est sous 13,55 V pour 35 jours et entre 14,02 et 14,33 V pour 135 jours. Seuls 3 jours tombent entre les deux (13,59, 13,68 et 13,96 V). Note de domaine : ≥ 14,0 V signale une charge complète (absorption ~14,2 V). | | `PLATEAU_FLOOR_V` | 12,8 V | Coude de la table OCV du collecteur (12,8 V = 30 %, `docs/aimsight/collecteur_system_info.py`). VERMONT : la pente de la baisse nocturne double sous 12,8 V (15 mV/h à 12,9 V, 29 mV/h à 12,8 V). | | `MIN_RISE_V` | 0,05 V | Au-dessus des variations d'une heure à l'autre sur le plateau (≤ 15 mV/h la nuit), et sous la plus faible vraie montée observée sur VERMONT (+0,079 V le 2026-05-05, jour nuageux ; ensuite +0,18 V le 2026-04-11). | | `MIN_COVERAGE` | 0,8 | Repris de `MOVING_AVERAGE_7_DAYS_DROP` : 20 heures mesurées sur 24. | ## Graphique - **Place** : troisième panneau d'analyse de la page commune, sous `MOVING_AVERAGE_7_DAYS_DROP` et `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP` (D-016). - **Contenu**, sur un seul axe en volts, avec un point par jour, placé à midi UTC de ce jour (au milieu de la journée, et non à son `t`, D-019) : - le maximum du jour et la fin de nuit, en deux courbes ; - les seuils de 14,0 V et 12,8 V en tirets. Ils sont tracés comme des courbes avec un point par jour, pour que le recalage au zoom (D-013) les garde visibles ; - l'état du jour, en marqueurs colorés sur la courbe du maximum, une couleur et une entrée de légende par état. - **Survol** : l'état et les faits du jour. ## Résultats sur VERMONT (jeu de travail) - **Répartition sur 184 jours** : 139 `FULL_CHARGE`, 31 `PARTIAL_CHARGE`, 14 `BELOW_PLATEAU`, 0 `NO_CHARGE`, 0 UNKNOWN. L'essai de conception lisait le 2026-05-05 `NO_CHARGE` ; avec la montée corrigée (voir « Historique »), il est `PARTIAL_CHARGE` (+0,079 V de 06:00 à 10:00). - **Rejeu causal** (chaque jour évalué à chaque heure) : dès qu'une mesure du jour passe sous 12,8 V, le jour est lu `BELOW_PLATEAU`. Le 2026-09-26, c'est le cas dès 04:00 UTC. - **`PARTIAL_CHARGE`** : - jours isolés en août (03/08, 15/08, 18/08) ; - puis du 29/08 au 01/09 ; - puis presque sans interruption à partir du 08/09 (seuls les 11, 18 et 19/09 sont `FULL_CHARGE`). C'est cohérent avec l'expert : charges complètes déjà rares depuis fin août, puis déficit vers le 20/09. - **`BELOW_PLATEAU`** du 2026-09-26 (fin de nuit à 12,71 V), un jour avant la première coupure (2026-09-27 01:00), jusqu'au 2026-10-09. Il couvre aussi les jours de coupure à moitié troués. - **Séries saines de jours consécutifs sans pleine charge** : 3 jours au plus (du 04 au 06/05). Ensuite, 4 jours (29/08–01/09), 6 jours (12–17/09) et 20 jours (20/09–09/10). ## Options écartées | Option | Pourquoi écartée | |---|---| | Comparer le jour au propre passé de la station (ex. maximum du jour face aux 30 derniers jours) | Aveugle à l'installation, faute d'historique, et sujette à l'accoutumance de `MOVING_AVERAGE_7_DAYS_DROP`. | | Hybride : seuils absolus les N premiers jours, puis comparaison au passé | Deux règles à calibrer et un changement de comportement au jour N, trop pour une première version. | | Un état par heure, ou un état horaire résumé par jour | La frontière entre charge et décharge sur le plateau est fragile à l'heure près. L'utilisateur a choisi un état par jour. | | États du collecteur (`BatteryState`, pente sur 60 s, ±2,5 mV/min) | Mis de côté par l'utilisateur. Ils demandent les données brutes à 1 Hz, et leur seuil (±150 mV/h) classe « stable » la charge et la décharge sur le plateau. | | Verdict gradué dès cette version (phase B) | Reporté : d'abord l'état seul (phase C), choix de l'utilisateur. | | Fin de nuit de la nuit qui suit le jour (matin de d+1) | Essayée le 2026-10-12, puis écartée par l'utilisateur, dans `DAILY_BATTERY_STATE` comme dans `DAILY_BATTERY_TREND` : `DAILY_BATTERY_STATE` reste sur les heures du jour lui-même (D-019). | | Nouveau champ du contrat pour « pas de verdict » | Toucherait les deux `MOVING_AVERAGE_*` ; `anomaly = None` documenté suffit en phase C. | ## Limites connues 1. **Jour UTC** : pour une station éloignée en longitude, la nuit serait coupée en deux par minuit UTC, et la « fin de nuit » serait faussée. Sur VERMONT, la fin de nuit tombe vers 04–06 h et le maximum entre 08 et 16 h UTC. 2. **Seuil de 14,0 V** : il suppose le même chargeur sur toutes les stations. Ce n'est pas confirmé, car ni le modèle ni les réglages du chargeur ne figurent dans la doc. 3. **Résolution horaire** : une absorption de moins d'une heure peut donner une moyenne sous 14,0 V, et le jour est alors lu `PARTIAL_CHARGE`. Exemple : le 2026-09-08, maximum 13,96 V. 4. **`PARTIAL_CHARGE` n'est pas une anomalie** : 31 jours sur 184, dont des jours sains nuageux. C'est la répétition qui comptera en phase B. 5. **Batterie de 7 Ah** : avec ~22 % de charge au matin (note de domaine), une station saine de 7 Ah à 5 W pourrait passer sous 12,8 V chaque nuit, et être lue `BELOW_PLATEAU` tous les jours. Ce n'est pas faux (la batterie quitte bien le plateau), mais c'est à vérifier sur une telle station. JUNGFRAU, station saine, a des nuits à 12,9 V : marge de 0,1 V. 6. **Secteur** : la tension reste vers 14,2–14,4 V, donc chaque jour est lu `FULL_CHARGE`. Après une perte secteur, le jour suivant devrait être lu `NO_CHARGE` ou `BELOW_PLATEAU`. Ce n'est pas vérifiable sur le jeu de travail, qui est solaire. 7. **Froid** : aucune donnée d'hiver. La charge LiFePO4 est en général bloquée sous 0 °C, d'où des jours `PARTIAL_CHARGE` ou `NO_CHARGE` possibles, même au soleil. 8. **Ambiguïté de `anomaly = None`** en phase C (voir « Principe »). ## Pistes - **Phase B, niveaux gradués** : à partir des séries d'états. Par exemple, une série de `PARTIAL_CHARGE` plus longue que la plus longue série saine (3 jours sur VERMONT), un `NO_CHARGE`, ou un `BELOW_PLATEAU`. - **Installation** : un `NO_CHARGE` dès le premier jour ensoleillé, ou aucune `FULL_CHARGE` les premiers jours, pour une alimentation absente ou un apport insuffisant. - **Jour solaire propre à la station** : couper les journées sur le cycle observé plutôt qu'à minuit UTC (limite 1). - **Consommation à l'installation** : `Power` révèle une veille profonde désactivée dès la première heure. C'est hors tension batterie, et laissé de côté pour l'instant. ## Historique - **2026-10-12** : conçue en brainstorming. L'utilisateur a choisi l'approche 1 (seuils physiques, jour UTC) et la phase C (état seul) avant la phase B. Elle ouvre le changement d'échelle de D-018. Spec écrite dans cette fiche (D-010). - **2026-10-12** : implémentée (`src/battery_state.py`, panneau dans `energy_plot.py`, point d'entrée `analyse_03.py`). Résultats conformes à l'essai de conception. - **2026-10-12** : corrigée après la relecture finale. La fin de nuit et la montée étaient calées sur le premier maximum du jour, qui peut être la tension de 00:00 (queue de la soirée précédente). Conséquences : le 2026-05-05 était lu `NO_CHARGE` malgré une montée de +0,079 V, la fin de nuit affichée du 2026-09-30 était fausse (12,68 V au lieu de 12,19 V), et le 2026-09-26, évalué en cours de journée, restait UNKNOWN de 04:00 à 11:00 malgré des mesures sous 12,8 V. Désormais, la montée part d'un minimum antérieur, et le coude se teste sur le minimum du jour (`min_v`). - **2026-10-12** : sur le graphique, chaque point est placé à midi UTC de son jour, et non plus à 23:00, comme les barres de l'analyse 04 (D-019). Le calcul ne change pas. - **2026-10-12** : titres, légendes et survols du graphique en anglais, pour le site de monitoring (D-023). Le calcul ne change pas. - **2026-10-12** : nouveau fait `night_end_h` (heure de la fin de nuit), pour placer la fin de nuit sur le graphique focus J−1 / J (D-024). Les autres faits ne changent pas (vérifié sur les 184 jours de VERMONT). - **2026-10-12** : fiche renommée d'après la règle (ex-`analyse_03.md`) et déplacée dans `docs/energy/analyses/` ; code dans `src/energy/` (D-026). Calcul inchangé.