EVCS/docs/MANUEL_COMPLET.md

# Manuel Utilisateur - Système EVCS Solaire

> Document généré le 17/07/2026
> Projet: n8n / Home Assistant / EVCS Solaire sans injection réseau

---

## 1. Architecture Globale

```
┌─────────────────────────────────────────────────────────────────┐
│                         DGX Spark (10.10.10.8)                  │
│  ┌─────────────────┐    ┌─────────────────┐                     │
│  │  Qwen3.6-35B    │    │  Qwen3-VL       │                     │
│  │  (texte, code)  │    │  (vision)       │                     │
│  └────────┬────────┘    └────────┬────────┘                     │
└───────────┼──────────────────────┼──────────────────────────────┘
            │                      │
            ▼                      ▼
┌───────────────────────────────────────────────────────────────────┐
│                     opencode (minimax-m2.5)                       │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │ Skills: n8n-code-javascript, n8n-expression-syntax,         │ │
│  │         n8n-mcp-tools-expert, n8n-node-configuration,       │ │
│  │         n8n-validation-expert                               │ │
│  └─────────────────────────────────────────────────────────────┘ │
└───────────┬──────────────────────┬───────────────────────────────┘
            │                      │
            ▼                      ▼
┌──────────────────────┐    ┌──────────────────────────────────────┐
│   n8n (cloud)        │    │   Home Assistant (10.10.10.17:8123)  │
│   https://n8n.airtria.pro    │    ┌──────────────────────────────────┐ │
│  ┌────────────────┐ │    │ │ Dashboards YAML (17 fichiers)      │ │
│  │ 40 workflows   │ │    │ │ - evcs_master.yaml                 │ │
│  │ 13 actifs      │ │    │ │ - evcs_mobile.yaml                 │ │
│  └────────┬───────┘ │    │ │ - victron_master.yaml              │ │
│           │         │    │ │ - etc.                              │ │
│           ▼         │    │ └──────────────────────────────────┘ │
│  ┌────────────────┐ │    └──────────────────────────────────────┘
│  │ MCP Servers    │ │
│  │ (6 outils)     │ │
│  └────────┬───────┘ │
└───────────┼─────────┘
            │
            ▼
┌───────────────────────────────────────────────────────────────────┐
│                     Équipements physiques                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐               │
│  │ EVCS HQ229  │  │ Victron ESS │  │ MultiPlus   │               │
│  │ (borne VE)  │  │ (batterie)  │  │ (onduleur)  │               │
│  └─────────────┘  └─────────────┘  └─────────────┘               │
└───────────────────────────────────────────────────────────────────┘
```

---

## 2. Workflows n8n Actifs

### 2.1 Gestion Énergie (EVCS + Grid)

| ID | Nom | Fréquence | Fonction |
|---|---|---|---|
| `ATswvGfG4KJUls0K` | HA Snapshot EVCS Surplus Controller V2.6 | 30s | Pilotage borne EVCS, décision charge solaire/réseau |
| `7iIlu7LLTW7TZA8o` | Victron - Battery / Grid Hysteresis Fix V1 | 1 min | Hystérésis réseau EDF (ON ≤20%, OFF ≥30%) |
| `cTeeHy4ePiVeELLh` | Victron - Auto Charge Manager V1.2 | 30s | Limites DVCC batterie (MaxChargeCurrent/Voltage) |

### 2.2 Gestion Charges

| ID | Nom | Fréquence | Fonction |
|---|---|---|---|
| `2NhrfxuGm4pTUNs9` | SDB Climate & Surplus Manager V2.2 | 1 min | Pilotage chauffage SDB selon surplus |
| `FtPVF7byhtu4o6Oh` | Victron - Garage Thermal Surplus Manager V2.2 | 1 min | Gestion garage thermique |
| `A11aOb50cGtpJmvn` | Water Heater Advisor V2.3 | 10 min | Advisor ballon ECS |
| `yX2j8m04e3pxaoQq` | Water Heater Advisor ECS 6 Nodes + Build + Execute | 10 min | Pilotage ballon ECS |
| `YjiNCpEoVhPT8JMw` | Victron - Flexible Load Advisor V1 | 5 min | Charge flexible |

### 2.3 Advisor / Monitoring

| ID | Nom | Fréquence | Fonction |
|---|---|---|---|
| `U0nRmdS9Pa0qzpWm` | Victron - PV Surplus Advisor V1 | 15 min | Advisor surplus PV |

### 2.4 MCP (Machine Communication Protocol)

| ID | Nom | Fonction |
|---|---|---|
| `76hHlVYIgt1lEHyR` | MCP - ha.get_state | Lecture états HA |
| `eeDmEICJ3ArjwpCt` | MCP - ha.set_helper | Écriture helpers HA |
| `uGZAOJjKegRuRNyb` | MCP - grid-set-state | Pilotage ON/OFF réseau EDF |
| `a92quWH4pokpIqdn` | MCP - victron-set-charge-limits | Limites courant/tension batterie |
| `RVTMdsvR4i8wSc18` | MCP - pv.get_forecast | Prévisions Forecast.Solar |

---

## 3. Skills opencode

| Skill | Chemin | Fonction |
|---|---|---|
| n8n-code-javascript | `.opencode/skills/n8n-code-javascript/SKILL.md` | Analyse/patch code JS dans nodes n8n |
| n8n-expression-syntax | `.opencode/skills/n8n-expression-syntax/SKILL.md` | Validation syntaxe {{ }} |
| n8n-mcp-tools-expert | `.opencode/skills/n8n-mcp-tools-expert/SKILL.md` | Utilisation outils MCP |
| n8n-node-configuration | `.opencode/skills/n8n-node-configuration/SKILL.md` | Configuration nœuds n8n |
| n8n-validation-expert | `.opencode/skills/n8n-validation-expert/SKILL.md` | Interprétation erreurs validation |

---

## 4. MCP - Outils disponibles

### 4.1 Lecture

- **ha-get-state** : Lire un état Home Assistant
  - Input: `entity_id` (ex: `sensor.victron_battery_soc`)
  - Output: état + attributs

- **pv-get-forecast** : Prévisions solaires
  - Input: aucun
  - Output: `today_remaining_kwh`, `tomorrow_kwh`, `tomorrow_peak_time`

### 4.2 Écriture

- **ha-set-helper** : Écrire un helper HA
  - Input: `entity_id`, `value`

- **grid-set-state** : Piloter le réseau EDF
  - Input: `state` ('on' ou 'off')

- **victron-set-charge-limits** : Limites de charge
  - Input: `max_charge_current_a`, `max_charge_voltage_v`

### 4.3 Workflows n8n

- **n8n-mcp** : CRUD workflows
  - List workflows, get workflow, update workflow, activate/deactivate

---

## 5. Dashboards Home Assistant

### 5.1 Principaux

| Fichier | Titre | Description |
|---|---|---|
| `evcs_master.yaml` | EVCS Master | Dashboard principal borne VE |
| `evcs_mobile.yaml` | EVCS Mobile | Version mobile |
| `victron_master.yaml` | Victron Master | Dashboard principal système Victron |
| `victron_mobile.yaml` | Victron Mobile | Version mobile |

### 5.2 Debug

| Fichier | Titre | Description |
|---|---|---|
| `big_victron_debug.yaml` | Victron Debug (complet) | Debug étendu |
| `victron_debug.yaml` | Victron Debug | Debug standard |
| `EVCS_SOLAR.yaml` | EVCS Solar | Vue solaire EVCS |

### 5.3 Pilotage

| Fichier | Titre | Description |
|---|---|---|
| `ECS_PILOTAGE.yaml` | ECS Pilotage | Pilotage ECS |
| `ECS_PILOTAGE_PREMIUM.yaml` | ECS Pilotage Premium | Pilotage ECS avancé |
| `GARAGE_PREMIUM_PILOTAGE.yaml` | Garage Premium Pilotage | Pilotage garage |
| `SDB_PREMIUM_PILOTAGE.yaml` | SDB Premium Pilotage | Pilotage SDB |

### 5.4 Debug Premium

| Fichier | Titre | Description |
|---|---|---|
| `ECS_DEBUG_REGLAGES.yaml` | ECS Debug Réglages | Debug ECS |
| `ECS_DEBUG_REGLAGES_PREMIUM.yaml` | ECS Debug Réglages Premium | Debug ECS avancé |
| `GARAGE_DEBUG_PREMIUM.yaml` | Garage Debug Premium | Debug garage |
| `SDB_DEBUG_PREMIUM.yaml` | SDB Debug Premium | Debug SDB |

---

## 6. Helpers Home Assistant (principaux)

### 6.1 Configuration EVCS

| Entity ID | Type | Description |
|---|---|---|
| `input_select.victron_evcs_strategy` | select | Stratégie (auto_solar_plus, force_grid_now, etc.) |
| `input_number.victron_evcs_required_energy_kwh` | number | Énergie demandée (kWh) |
| `input_boolean.victron_evcs_departure_priority_enabled` | boolean | Priorité départ |
| `input_datetime.victron_evcs_departure_time` | datetime | Heure de départ |
| `input_boolean.victron_evcs_allow_grid_hc_night` | boolean | Réseau HC nuit |
| `input_boolean.victron_evcs_allow_grid_hc_midday` | boolean | Réseau HC midi |
| `input_boolean.victron_evcs_surplus_auto_enabled` | boolean | Contrôleur surplus actif |

### 6.2 État système

| Entity ID | Type | Description |
|---|---|---|
| `input_text.victron_evcs_operating_mode` | text | Profil actif |
| `input_text.victron_evcs_surplus_state` | text | État interne |
| `input_text.victron_evcs_surplus_current_decision` | text | Décision logique |
| `input_text.victron_evcs_source_mode` | text | Source autorisée (Solaire/Réseau) |
| `input_text.victron_evcs_surplus_reason` | text | Raison courte |
| `input_text.victron_evcs_last_block_reason` | text | Dernier blocage |

### 6.3 Paramètres seuils

| Entity ID | Type | Description | Valeur actuelle |
|---|---|---|---|
| `input_number.victron_evcs_soc_start_min` | number | Seuil SOC démarrage | 80% |
| `input_number.victron_evcs_soc_stop_min` | number | Seuil SOC arrêt | 70% |
| `input_number.victron_evcs_midday_soc_min` | number | Seuil SOC midi | 75% |
| `input_number.victron_evcs_night_target_soc` | number | Cible SOC nuit | 70% |
| `input_number.evcs_plafond_courant_edf_on` | number | Plafond EDF ON | 20A |
| `input_number.victron_evcs_current_max_auto_a` | number | Plafond modes auto | 22A |

### 6.4 Hystérésis réseau

| Entity ID | Type | Description |
|---|---|---|
| `input_boolean.victron_grid_hysteresis_latch` | boolean | Latch hystérésis |
| `input_boolean.victron_evcs_night_session_active` | boolean | Session nuit active |
| `input_boolean.victron_evcs_night_grid_takeover_needed` | boolean | Takeover réseau nuit |

---

## 7. Capteurs clés (lecture seule)

| Entity ID | Description |
|---|---|
| `sensor.victron_battery_soc` | SOC batterie (%) |
| `sensor.victron_battery_current` | Courant batterie (A) |
| `sensor.victron_pv_power_system` | Puissance PV totale (W) |
| `sensor.victron_consumption_power_l1` | Consommation maison (W) |
| `sensor.victron_grid_power_l1` | Puissance réseau (W) |
| `sensor.victron_evcs_current` | Courant EVCS réel (A) |
| `sensor.victron_evcs_set_current` | Consigne lue borne (A) |
| `sensor.victron_evcs_ac_power` | Puissance EVCS (W) |
| `sensor.victron_evcs_charging_time` | Durée de charge |
| `sensor.victron_evcs_statut_fr` | Statut FR borne |
| `sensor.victron_evcs_mode_fr` | Mode FR borne |
| `switch.edf_general_ok_switch` | Interrupteur réseau EDF |
| `binary_sensor.victron_evcs_vehicle_connected` | Véhicule connecté |
| `binary_sensor.victron_evcs_device_connected` | Borne détectée |

---

## 8. Scripts HA

| Script | Fonction |
|---|---|
| `script.evcs_boost_edf` | BOOST EDF 28A (plafonds 28A + force_grid_now) |
| `script.evcs_boost_off` | Retour normal (plafonds 20/22 + auto_solar_plus) |
| `script.edf_urgence_off` | EDF Urgence OFF (hystérésis OFF + latch OFF + stratégie stop) |
| `script.edf_force_on` | EDF forcé ON |
| `script.edf_rendre_la_main` | Rendre la main au système auto |

---

## 9. Stratégies de charge

| Stratégie | Description | SourceMode | Conditions |
|---|---|---|---|---|
| `auto_solar_plus` | Solaire uniquement + assistance batterie haute | solar_only / solar_potential | SOC ≥ 90% + dette nuageuse faible |
| `auto_solar` | Solaire classique | solar_only | - |
| `force_grid_now` | Préservation batterie (remonter à seuil) | grid_forced / grid_hc_allowed | Si SOC < 22% → remonter à 35% été / 50% mi-saison / 75% hiver |
| `force_charge_now` | Charge immédiate (solution de secours manuelle) | solar_only si possible, grid_forced si SOC < 35% | À la discrétion du conducteur qui doit prendre sa voiture |
| `stop` | Arrêt complet | - | - |

---

## 10. Profils temporels

| Profil | Horaire | Description |
|---|---|---|
| `morning_solar` | 07:30 - 11:00 | Fenêtre solaire matin |
| `midday_hc_or_solar` | 12:24 - 14:24 | HC midi ou solaire |
| `evening_high_soc` | 17:00 - 20:30 | Soir haute priorité SOC |
| `night_hc` | 01:24 - 07:24 | Heures creuses nuit |
| `outside_window` | Autres | Hors fenêtres → Mode probe (sonde) pour relancer le PV si besoin |

---

## 11. Logique de décision (DECISION_ENGINEV2)

### 11.1 Garde-fous (Safety)

- **commonSafetyStartOk** : Vérifications sécurité au démarrage
- **commonSafetyHoldOk** : Vérifications sécurité au maintien
- **mustStopHard** : Arrêt d'urgence (batterie basse, surcharge)

### 11.2 Conditions de démarrage

| Condition | Seuil | Description |
|---|---|---|
| `solarStartOk` | SOC ≥ profil + PV ≥ 1000W | Démarrage solaire |
| `gridStartOk` | SOC ≤ 35% + réseau dispo | Démarrage réseau |
| `batteryAssistSolarStartOk` | SOC ≥ 90% + dette nuageuse faible | Assistance batterie solaire |
| `probeStartOk` | Mode probe actif | Sonde PV |

### 11.3 Step-up / Step-down

- **Step-up** : Augmente le courant si PV suffisant ou batterie en charge
- **Step-down** : Diminue si batterie décharge trop ou dette nuageuse

### 11.4 Cloud Debt (Dette Nuageuse) & Probe

#### Problème
Quand les batteries sont pleines (SOC > 90%) et que la maison consomme peu (< 1200W), le MPPT de l'onduleur Victron se bride à la consommation maison uniquement. Le PV visible reste bas tant que l'EVCS ne démarre pas.

#### Dette Nuageuse
- **Définition** : La batterie se décharge pour alimenter la maison + VE sans production PV suffisante
- **Seuil max** : 1.5 kWh
- **Durée max** : 30 min
- Cette dette doit être "remboursée" par du surplus PV ultérieur

#### Mode Probe (Sonde)
- **Principe** : Lancer la borne à 10A pour "provoquer" une production PV qui va s'adapter en quelques secondes
- **Courant probe** : 10A (augmenté de 6A à 10A)
- **Durée probe** : 3 minutes
- **Retry** : 45 minutes si échec
- **Activation** : En dehors des fenêtres définies (`outside_window`) ou lors de passages nuageux

#### Bypass outside_window
En mode `auto_solar_plus` ou `force_charge_now`, le profil `outside_window` ne bloque plus la charge solaire locale si :
- SOC batterie ≥ 90%
- Forecast solaire fort
- Maison consommation faible

### 11.5 Logique Heure de départ (Night EVCS)

#### Objectif
S'assurer que le véhicule est chargé avant l'heure de départ prévue.

#### Comportement

| Scénario | Action |
|---|---|
| Heure départ proche + batteries suffisantes | Charge solaire prioritaire |
| Heure départ proche + batteries insuffisantes | grid_forced (HC) si disponible |
| Heure départ proche + pas de HC | grid_forced (plein tarif) |

#### Paramètres
- **batteryHardFloorPct** : Plancher dur batterie (ex: 22%)
- **batteryMorningTargetPct** : Objectif SOC matin selon forecast
  - Forecast fort (> 15 kWh) : 40%
  - Forecast moyen (8-15 kWh) : 50%
  - Forecast faible (< 8 kWh) : 75%
- **gridTakeoverTriggerPct** : Seuil de basculement réseau
- **batteryRecoveryUrgent** : Si temps restant < temps de charge nécessaire

### 11.6 Cycle nuit HC complet — GRAFCET (P7 + P8 + fixes 08/08/2026)

Deux automates coordonnés via les helpers HA (`night_grid_takeover_needed`,
`victron_evcs_surplus_state`) :
- **G1** = contrôleur EVCS V2.6 (boucle 30 s)
- **G2** = hystérésis EDF (« Victron - Battery / Grid Hysteresis Fix V1 », 1 min)

```
G1 — SESSION NUIT EVCS
──────────────────────
X0  JOUR / attente (profils solaires)
 │   t1: fenêtre HC (01:24) ET véhicule branché
X1  SESSION NUIT ACTIVE — capture startSOC/startAt (une seule fois, Fix B)
 │   t2: toggle "Réseau HC nuit" ON → nightGridHcPreferred (P7)
X2  TAKEOVER: helper ON → G2 force EDF ON ; ACM tient la batterie (~2 A)
 │   t3: EDF ON confirmé (gridAvailable)
X3  CHARGE VE: start 6 A → step-up (plafond 20 A / boost 28 A)
 │   t4: fin de charge = VDF no-demand OU statut EVCS brut 3 "charged" (Fix D)
X4  CHARGE TERMINÉE (collant): vehicleChargeCompleted, sourceMode='blocked'
 │
 ├─ t5a: SOC < cible matin
 │   X5a RECOVERY BATTERIE: takeover ON (EDF ON), ACM recharge → cible
 │    │   t6: SOC ≥ cible
 │    ▼
 └─ t5b: SOC ≥ cible matin
     X5b RECOVERY DONE (collant, Fix A): état 'night_recovery_done_idle'
      │   takeover OFF définitif → G2 coupe EDF (turn_off_recovered)
      │   ré-engagement UNIQUEMENT si SOC ≤ cible − 2 (bande anti-rebond)
      │   t7: débranchement OU fin de fenêtre (07:24)
     X6  CLÔTURE: clear session → retour X0 (profil jour)

G2 — HYSTÉRÉSIS EDF (seuils ON ≤ 20 % | OFF ≥ 30 % | min_on 25 | cooldown 15)
──────────────────────────────────────────────────────────────────────────────
Y0  EDF OFF (observe_only)
 │   u1: override EVCS (takeover/force_grid/grid_forced) sans no-demand
 │   u2: SOC ≤ seuil ON (bypass cooldown)
Y1  EDF ON + latch
 │   v1: override disparu ET min_on écoulé ET SOC ≥ seuil OFF → turn_off_recovered
 │   v2: force_grid + voiture pleine → coupure immédiate
 │   v3: véhicule débranché + SOC ≥ seuil OFF → coupure immédiate
 │       (turn_off_vehicle_unplugged, bypass min_on — Fix C 08/08/2026)
 └─▶ retour Y0 (cooldown 15 min)
```

États surplus « fin de nuit » (aucun ne doit matcher les patterns no-demand
de G2 — full_or_paused / not_requesting_power / charge_complete / no_demand) :
- `night_session_done_idle` : charge finie, recovery batterie possible (EDF
  maintenu si SOC < cible)
- `night_recovery_done_idle` : charge finie ET batterie à la cible → EDF
  relâché définitivement (anti-rebond)

#### Incident de référence (nuit 07-08/08/2026)
SOC bloqué pile à la cible (35 %) = point dégénéré (engage `soc ≤ 35`,
release `soc > 35`) → rebond EDF ON/OFF période ~10 min + flapping ACM 2-4 s,
et EDF maintenu 25 min après débranchement. Corrigé par Fix A (flag collant +
bande 2 pts), Fix B (snapshot relit startSOC/startAt), Fix C (coupure au
débranchement), Fix D (statut charged = fin de charge immédiate).

---

## 12. Configuration opencode.json

```json
{
  "provider": {
    "openrama": {
      "models": {
        "minimax-m2.5": { "name": "minimax-m2.5" }
      }
    },
    "qwen-dgx-vl": {
      "models": {
        "qwen3-vl": { "attachment": true, "modalities": {"input": ["text","image"]} },
        "qwen3.6-35b": { "options": { "temperature": 0.15, "reasoningEffort": "none" } }
      }
    }
  },
  "mcp": {
    "n8n-mcp": { "type": "local", "command": ["npx", "-y", "n8n-mcp-server"] },
    "ha-get-state": { "type": "remote", "url": "https://n8n.airtria.pro/mcp/..." },
    "ha-set-helper": { "type": "remote", "url": "https://n8n.airtria.pro/mcp/..." },
    "grid-set-state": { "type": "remote", "url": "https://n8n.airtria.pro/mcp/grid-set-state/sse" },
    "victron-set-charge-limits": { "type": "remote", "url": "https://n8n.airtria.pro/mcp/..." },
    "pv-get-forecast": { "type": "remote", "url": "https://n8n.airtria.pro/mcp/..." }
  },
  "permission": {
    "bash": { "curl *": "deny", "wget *": "deny", "*": "ask" }
  }
}
```

---

## 13. Méthode de travail

### 13.1 Lecture d'un workflow n8n

1. Utiliser `n8n-mcp_get_workflow` avec l'ID
2. Le fichier est écrit dans `~/.local/share/opencode/tool-output/tool_*`
3. **Attention** : Le fichier commence par "Retrieved workflow: <nom>" AVANT le JSON
4. Extraction par nœud :
   ```bash
   grep -n '"name": "NOM_DU_NOEUD"' <fichier>
   sed -n 'DEBUT,FINp' <fichier>
   ```

### 13.2 Modification

1. **TOUJOURS** backup avant modification
2. Une seule modification à la fois
3. Vérifier avec dry-run
4. Valider en production

### 13.3 Interdiction

- **JAMAIS** de curl/wget direct vers HA/n8n/Victron
- **JAMAIS** d'IP/URL/token inventés
- Utiliser les MCP uniquement

---

## 14. À compléter par l'utilisateur

- [ ] Tableau détaillé des fonctionnalités (entrées/sorties/conditions)
- [ ] Documentation EDF Urgence (créé par FABLE)
- [ ] Liste des incidents récurrents
- [ ] Procédures de dépannage
- [ ] Glossaire des termes techniques

---

*Document généré automatiquement le 17/07/2026*