wip: update doc

Author: Xavier Berger

docs/en/blueprint_priority_to_ev.md

@@ -1,6 +1,6 @@
 # Home Assistant blueprint — Priority to EV
 
-## 1 – What it does
+## What it does
 
 When an EV is plugged into a smart charger (MyEnergi Zappi, OpenEVSE,
 Wallbox Quasar, …) that already does its own surplus-following logic,
@@ -10,18 +10,18 @@ Router's water heater. This blueprint arbitrates between the two:
 - When the surplus is *large enough for long enough*, it turns the
   Solar Router **off** so the surplus is released to the grid, where
   the EV charger picks it up.
-- When the EV is unplugged, a cloud starts pulling from the grid, or
-  the EV stops taking the surplus (car full, paused, or tapering
-  finished), it turns the Solar Router back **on** so the water heater
-  catches whatever remains.
+- When the EV is unplugged, a cloud cuts PV production and the house
+  starts importing from the grid, or the EV stops taking the surplus
+  (car full, paused, or tapering finished), it turns the Solar Router
+  back **on** so the water heater catches whatever remains.
 
 The router firmware itself does **not** talk to the EV charger — the
 blueprint only toggles the router's `Activate Solar Routing` switch.
 Everything else stays in the charger's own hands.
 
-## 2 – Signals
+## Signals
 
-### 2a – Handoff (router ON → OFF)
+### Handoff (router ON → OFF)
 
 ```
 surplus = max(0, -grid_power) + max(0, diverted_power)
@@ -37,7 +37,7 @@ The router is turned OFF when `surplus > EV_Charging_Minimum_Surplus`
 holds continuously for `surplus_duration_trigger` seconds, provided
 the EV is plugged in and (if a SoC sensor is set) still below target.
 
-### 2b – Restore (router OFF → ON)
+### Restore (router OFF → ON)
 
 Once the router is OFF and the EV is drawing on solar, the surplus
 formula collapses to ~0: `diverted_power = 0` because the router is
@@ -61,9 +61,9 @@ turning the router back ON at that instant would fight the EV for the
 tail-end energy. The blueprint waits for `-grid_power >
 release_export_threshold` — i.e. the car has actually stopped drawing
 — to restore the router. The SoC target still gates new handoffs
-(see [3 – Behavior](#3--behavior)).
+(see [Behavior](#behavior)).
 
-## 3 – Behavior
+## Behavior
 
 ```text
 HANDOFF (router ON → OFF), when this stays true for surplus_duration_trigger s:
@@ -84,7 +84,7 @@ Crossing `ev_soc_target` freezes the handoff (no fresh router-OFF) but
 does not by itself restore the router — the export threshold handles
 that once the car actually stops drawing.
 
-## 4 – Inputs
+## Inputs
 
 | Input | Purpose | Default |
 | --- | --- | ---: |
@@ -99,7 +99,7 @@ that once the car actually stops drawing.
 | `release_export_threshold` | Export threshold for "EV done" detection in W | 200 |
 | `surplus_duration_trigger` | Debounce for all three level triggers in s | 60 |
 
-## 5 – Requirement: keep `Real Power` alive while the router is OFF
+## Requirement: keep `Real Power` alive while the router is OFF
 
 Before this version, turning the `Activate Solar Routing` switch OFF
 also stopped the meter polling and forced `Real Power` to `NaN`. The
@@ -110,11 +110,19 @@ keeps the native power meters polling continuously and no longer
 publishes `NaN` on shutdown. No user action is required if you flash
 the matching firmware version.
 
-## 6 – A day in the life
+## A day in the life
 
 Handoff threshold 1400 W, cloud & release thresholds 200 W each,
 debounce 60 s.
 
+![EV priority — typical day](images/priority_to_ev_day_en.png)
+
+*Top strip: numbered events (see caption below the figure). Middle
+panel: PV production (yellow), household baseline + water heater + EV
+stacked; the blue outline is the total consumption. Bottom panel:
+signed grid exchange (import above zero, export below) and the
+dashed blueprint surplus curve plotted on the export side.*
+
 | Time | Situation | grid_power | diverted | Router | Action |
 | :--- | :--- | ---: | ---: | :--- | :--- |
 | 06:00 | Night ending, no PV | +300 (import) | 0 | ON idle | — |
@@ -127,7 +135,7 @@ debounce 60 s.
 | 15:30 | EV self-stops on full, export stable > 60 s | **−1500** | 0 | **ON** | export release — router restored |
 | 20:00 | EV unplugged | −200 | 100 | ON | — |
 
-## 7 – Wiring an EV plug sensor (MyEnergi Zappi example)
+## Wiring an EV plug sensor (MyEnergi Zappi example)
 
 If your charger only exposes a text status, wrap it in a template
 binary sensor:
@@ -142,7 +150,7 @@ template:
              in ['EV Connected', 'Waiting for EV', 'Charging', 'Boosting', 'Complete'] }}
 ```
 
-## 8 – Installation
+## Installation
 
 Import the blueprint into Home Assistant:
 
@@ -153,7 +161,7 @@ Import the blueprint into Home Assistant:
 Create an automation from the imported blueprint and fill in the
 inputs.
 
-## 9 – Edge cases
+## Edge cases
 
 - **Brief cloud (< `surplus_duration_trigger` s)** — the router stays
   off; the debounce absorbs it.

docs/en/blueprint_use_cases.md

@@ -1,6 +1,6 @@
 # Blueprint Home Assistant — Priorité au VE
 
-## 1 – À quoi ça sert
+## À quoi ça sert
 
 Lorsqu'un véhicule électrique est branché sur un chargeur intelligent
 (MyEnergi Zappi, OpenEVSE, Wallbox Quasar, …) capable de suivre le
@@ -11,18 +11,19 @@ blueprint arbitre entre les deux :
 - Lorsqu'un surplus *suffisant* est disponible *assez longtemps*, il
   éteint le Solar Router pour que le surplus soit relâché vers le
   réseau, où le chargeur du VE le capte.
-- Lorsque le VE est débranché, qu'un nuage se met à tirer du courant
-  du réseau, ou que le VE cesse effectivement de prendre le surplus
-  (voiture pleine, en pause, fin de tapering), il rallume le Solar
-  Router pour que le chauffe-eau récupère ce qui reste.
+- Lorsque le VE est débranché, qu'un nuage coupe la production PV et
+  que la maison se met à importer, ou que le VE cesse effectivement de
+  prendre le surplus (voiture pleine, en pause, fin de tapering), il
+  rallume le Solar Router pour que le chauffe-eau récupère ce qui
+  reste.
 
 Le firmware du routeur ne communique **pas** avec le chargeur — le
 blueprint se contente de manipuler l'interrupteur `Activate Solar
 Routing`. Tout le reste reste à la charge du chargeur.
 
-## 2 – Signaux
+## Signaux
 
-### 2a – Bascule (routeur ON → OFF)
+### Bascule (routeur ON → OFF)
 
 ```
 surplus = max(0, -grid_power) + max(0, diverted_power)
@@ -39,7 +40,7 @@ reste vrai en continu pendant `surplus_duration_trigger` secondes, à
 condition que le VE soit branché et (si un capteur SoC est fourni)
 encore sous la cible.
 
-### 2b – Restauration (routeur OFF → ON)
+### Restauration (routeur OFF → ON)
 
 Une fois le routeur éteint et le VE en charge sur le solaire, la
 formule de surplus s'effondre à ~0 : `diverted_power = 0` (routeur
@@ -65,9 +66,9 @@ disputer avec le VE cette énergie de fin de charge. Le blueprint
 attend `-grid_power > release_export_threshold` — c'est-à-dire que la
 voiture a réellement cessé de consommer — pour restaurer le routeur.
 La cible SoC continue de verrouiller les nouvelles bascules
-(voir [3 – Comportement](#3--comportement)).
+(voir [Comportement](#comportement)).
 
-## 3 – Comportement
+## Comportement
 
 ```text
 BASCULE (routeur ON → OFF), quand ceci reste vrai pendant surplus_duration_trigger s :
@@ -89,7 +90,7 @@ fait pas bouger le routeur. Franchir `ev_soc_target` gèle la bascule
 seuil d'export s'en charge une fois que la voiture cesse réellement de
 consommer.
 
-## 4 – Entrées
+## Entrées
 
 | Entrée | Rôle | Défaut |
 | --- | --- | ---: |
@@ -104,7 +105,7 @@ consommer.
 | `release_export_threshold` | Seuil d'export pour la détection "VE plein", en W | 200 |
 | `surplus_duration_trigger` | Anti-rebond appliqué aux 3 triggers de niveau, en s | 60 |
 
-## 5 – Prérequis firmware : `Real Power` vivant même routeur éteint
+## Prérequis firmware : `Real Power` vivant même routeur éteint
 
 Avant cette version, éteindre `Activate Solar Routing` stoppait aussi
 le sondage du compteur et forçait `Real Power` à `NaN`. Le blueprint
@@ -115,11 +116,20 @@ le sondage des compteurs natifs en continu et n'écrit plus `NaN` à
 l'arrêt. Aucune action n'est requise côté utilisateur si le firmware
 assorti est flashé.
 
-## 6 – Une journée dans la vie
+## Une journée dans la vie
 
 Seuil de bascule 1400 W, seuils nuage & release 200 W chacun,
 anti-rebond 60 s.
 
+![Priorité VE — journée type](images/priority_to_ev_day_fr.png)
+
+*Bandeau du haut : événements numérotés (voir légende sous la figure).
+Panneau du milieu : production PV (jaune), talon + chauffe-eau + VE
+empilés ; le trait bleu est la consommation totale. Panneau du bas :
+échange réseau signé (import au-dessus de zéro, export en dessous) et
+la courbe de surplus vue par le blueprint (pointillé) tracée côté
+export.*
+
 | Heure | Situation | grid_power | diverted | Routeur | Action |
 | :--- | :--- | ---: | ---: | :--- | :--- |
 | 06:00 | Fin de nuit, pas de PV | +300 (import) | 0 | ON idle | — |
@@ -132,7 +142,7 @@ anti-rebond 60 s.
 | 15:30 | VE s'arrête réellement, export stable > 60 s | **−1500** | 0 | **ON** | export release — retour au routeur |
 | 20:00 | VE débranché | −200 | 100 | ON | — |
 
-## 7 – Détection de VE branché (exemple MyEnergi Zappi)
+## Détection de VE branché (exemple MyEnergi Zappi)
 
 Si votre chargeur n'expose qu'un statut texte, encapsulez-le dans un
 capteur binaire template :
@@ -147,7 +157,7 @@ template:
              in ['EV Connected', 'Waiting for EV', 'Charging', 'Boosting', 'Complete'] }}
 ```
 
-## 8 – Installation
+## Installation
 
 Importer le blueprint dans Home Assistant :
 
@@ -158,7 +168,7 @@ Importer le blueprint dans Home Assistant :
 Créer ensuite une automatisation depuis le blueprint importé et
 remplir les entrées.
 
-## 9 – Cas limites
+## Cas limites
 
 - **Nuage bref (< `surplus_duration_trigger` s)** — le routeur reste
   éteint ; l'anti-rebond absorbe.