# etm-powersync-energy-etm

> Moteur HEMS pour l'expérience énergie de [nymea](https://nymea.io).
> Fork de `nymea-energy-plugin-nymea` (GPL-3.0), étendu d'un optimiseur EV vers un gestionnaire d'énergie complet : bornes, ECS, PAC, batterie, relais — pilotés sous une seule logique d'arbitrage, en local, sans dépendance cloud.

Ce plugin est un `EnergyPlugin` (il hérite de `libnymea-energy`, ce n'est **pas** un `IntegrationPlugin`). Il n'expose aucune `ThingClass` propre : il orchestre les Things créées par d'autres plugins, détectées **par interface** (`evcharger`, `electricvehicle`, `rootmeter`/`energymeter`, `energystorage`, et à terme `heatingelement`, `heatpump`, relais).

Produit : `libnymea_energypluginetm.so` → `/usr/lib/nymea/energy/`

---

## Statuts honnêtes

Chaque bloc affiche son état réel. On ne documente pas une promesse.

| Statut | Sens |
|---|---|
| **STABLE** | Hérité de l'amont, fonctionne en production |
| **EN COURS** | En industrialisation pour la beta |
| **ROADMAP** | Planifié, non implémenté |

---

## Modèle open-cœur

Deux couches, frontière nette. Le plugin de ce repo est **entièrement GPL-3.0**.

- **Couche A — ce repo (GPL-3.0).** Toute la mécanique HEMS : ingestion d'état, sécurité, arbitrage, stratégie par défaut basée sur règles, adaptateurs de charge. Tourne seul, sans aucun composant externe. C'est aussi le candidat à une contribution amont chez nymea.
- **Couche B — optimiseur externe (hors de ce repo).** Un processus séparé (propriétaire **Héos**, ou tiers communautaire) qui se branche par un socket local documenté. Il *propose* des décisions ; il ne peut jamais contourner la sécurité.

Principe directeur : **le plugin est agnostique à l'optimiseur.** Héos et un optimiseur tiers sont des backends interchangeables derrière le même contrat. Aucun code propriétaire ne vit dans ce repo — la séparation se fait par processus + protocole publié, pas par linkage.

Conséquence pratique, et invariant testé : **socket absent ou muet → repli automatique sur la stratégie de règles intégrée.** En mode Community, le plugin fonctionne intégralement sans optimiseur.

---

![Architecture ETM PowerSync](etm_powersync_energy.svg)

---

## Architecture — les blocs

### 1. Ingestion d'état — STABLE

Le plugin lit l'état du système via les interfaces nymea, jamais par `ThingClassId`.

| Interface | États lus | Actions émises |
|---|---|---|
| `evcharger` | `chargingEnabled`, `maxChargingCurrent`, `pluggedIn`, `charging`, `currentPhaseA/B/C`, `currentPowerPhaseA/B/C` | `setChargingEnabled`, `setMaxChargingCurrent` |
| `electricvehicle` | `batteryLevel`, `maxChargingCurrent`, `capacity`, `minChargingCurrent`, `phaseCount` | — |
| `rootmeter` / `energymeter` | `currentPowerPhaseA/B/C`, `currentPhaseA/B/C` | — |
| `energystorage` | `currentPower`, `batteryLevel` | — |
| `heatingelement`, `heatpump`, relais | à définir | à définir — ROADMAP |

Le `currentPower` du root meter est **négatif en cas de surplus** (export réseau). C'est la grandeur d'entrée centrale du moteur.

Deux déclencheurs distincts alimentent les deux boucles (voir §2) :
- `PowerBalanceEntryAdded` (`SampleRate1Min`) → le **cycle d'optimisation** `update()`, ~1×/min.
- `powerBalanceChanged` (temps réel, à chaque changement) → la **boucle de sécurité**, découplée du cycle.

### 2. Les deux boucles — STABLE

C'est la décision d'architecture la plus importante du moteur : **sécurité et optimisation sont deux boucles séparées, à cadences différentes, avec des priorités différentes.**

- **Boucle de sécurité** (`verifyOverloadProtection()`) tourne en temps réel sur `powerBalanceChanged`. Elle lit le courant par phase du root meter ; si une phase dépasse `phasePowerLimit × 230 W`, elle throttle immédiatement (issuer `OverloadProtection`). `verifyOverloadProtectionRecovery()` ré-active quand la marge revient.
- **Boucle d'optimisation** (`update()`) tourne ~1×/min sur le cycle lent. C'est elle, et elle seule, que l'optimiseur externe peut influencer.

L'optimiseur **ne touche jamais** la boucle de sécurité. Quoi qu'il propose, le plafond de puissance (overload, et à terme la contrainte réseau §14a) borne la sortie. C'est ce qui rend l'optimiseur débranchable, et autorise du code tiers non audité à se brancher sans risque pour l'installation.

### 3. Arbitrage central — EN COURS

L'amont calcule un budget de surplus pour les bornes EV uniquement, via le terme `addedPower` de `planSurplusCharging()` (« puissance déjà engagée dans ce cycle »). Le fork **généralise ce budget en allocation centrale** : un coordinateur unique tient le budget de surplus disponible, interroge chaque charge **par priorité décroissante**, et décrémente le budget à chaque engagement.

C'est la pièce qui évite le sur-engagement : sans budget central, un manager ECS, un manager batterie et le manager EV verraient chacun « 2 kW de surplus » et tireraient 6 kW. L'allocation reste **unique et centrale** ; les charges ne sont que des consommatrices du budget.

### 4. Adaptateurs de charge — EN COURS

L'application d'une décision à un appareil passe par un adaptateur par type de charge. L'amont a `executeChargingAction()` → `Thing::executeAction(setChargingEnabled, setMaxChargingCurrent)` pour l'EV. Le fork généralise : un `LoadAdapter` traduit une **allocation de puissance** en action device selon le type — ampères pour la borne, palier de relais pour l'ECS, décalage de consigne pour la PAC.

L'EV devient ainsi un type de charge parmi d'autres, et non plus le centre du moteur.

| Adaptateur | Statut |
|---|---|
| `evcharger` (hérité) | STABLE |
| ECS / relais | EN COURS (cible beta) |
| PAC / HVAC | ROADMAP |
| Batterie | ROADMAP |

### 5. Stratégie par défaut basée sur règles — EN COURS

La logique de décision locale (`planSurplusCharging()`, `planSpotMarketCharging()`) devient la **stratégie par défaut**, intégrée au plugin, GPL, sans aucune dépendance externe. C'est elle qui pilote en mode Community et qui prend le relais quand l'optimiseur est absent. Glouton par priorité statique avec décrément de budget — simple, déterministe, vérifiable.

### 6. Frontière A↔B — `requestOptimization()` — EN COURS

Point d'injection unique entre la couche GPL et l'optimiseur externe, **entre `prepareInformation()` et `adjustEvChargers()`** dans le cycle. Le plugin construit un contexte (`SurplusData`/`SurplusContext`) et appelle `PowerSyncClient::requestOptimization()` ; l'optimiseur retourne une allocation (`ChargingAction` aujourd'hui, `LoadAction` généralisé en cible) qui remplace ou complète les décisions locales.

Ce contrat sert trois usages d'un seul artefact : interface de stratégie interne, protocole du socket (Couche B), et spécification publiée pour la communauté.

---

## Comment ça fonctionne ensemble — le cycle `update()`

Exécuté à chaque entrée du bilan de puissance (~1 min). Pipeline hérité de l'amont, généralisé par le fork :

```
update(currentDateTime)
  │
  ├─ 1. updateManualSoCsWithoutMeter()   estime le SoC si pas de compteur sur le VE
  │
  ├─ 2. prepareInformation()             filtre les charges actives, calcule phases/SoC/temps restant,
  │                                       reset des actions par issuer
  │                              ┌───────────────────────────────────────────────┐
  │   ── FRONTIÈRE A↔B ──────────┤ requestOptimization(SurplusContext)            │
  │                              │   optimiseur vivant → LoadAction[]             │
  │                              │   absent / muet / abstain → stratégie défaut   │
  │                              └───────────────────────────────────────────────┘
  │
  ├─ 3. verifyOverloadProtection()       SÉCURITÉ — borne la sortie, quoi qu'ait proposé l'optimiseur
  ├─ 4. verifyOverloadProtectionRecovery()
  │
  ├─ 5. planSpotMarketCharging()         créneaux bon marché (SpotMarketManager) → schedules
  │
  ├─ 6. planSurplusCharging()            currentLoad = rootMeter.currentPower()
  │                                       + correction batteries + addedPower (budget)
  │                                       allowanceInAmpere = −currentLoad / 230
  │
  └─ 7. adjustEvChargers() / applyAllocation()
         décision finale par priorité :
           1. TimeRequirement   (deadline imminente)
           2. SurplusCharging   (courant surplus)
           3. SpotMarketCharging (créneau bon marché)
           4. fallback courant minimum (6 A)
           5. Idle (OFF)
              │
              ├─ executeChargingAction() → Thing::executeAction(...)
              ├─ emit chargingInfoChanged()       (ChargingState lu en JSON-RPC)
              └─ emit chargingSchedulesChanged()  (planning lu en JSON-RPC)
```

En parallèle, hors de ce cycle, la boucle de sécurité tourne en temps réel sur `powerBalanceChanged` et peut throttler à tout instant, indépendamment de l'optimiseur.

---

## Couche B — brancher un optimiseur sur le socket

L'optimiseur est un **serveur** ; le plugin est le **client**. L'optimiseur ouvre `/run/powersync/optimizer.sock`, le plugin s'y connecte.

Cycle de vie d'un backend (Héos ou tiers) :

1. **Handshake** — le backend annonce `{ protocolVersion, name }`. Le plugin vérifie la version ; incompatible → refus + repli règles.
2. **Boucle** — à chaque cycle le plugin pousse un `SurplusContext` (surplus disponible, charges avec type/puissance/min-max/priorité/état, batterie SoC, tarif, contrainte réseau) ; le backend renvoie un `LoadAction[]` (`{ loadId, action, targetPowerW, reason }`) ou `abstain`.
3. **Heartbeat** — la cadence des requêtes *est* le heartbeat. Pas de réponse dans le délai → `optimizerAlive=false` → repli règles, sans interruption du pilotage.

Le contrat est **générique-domaine**, pas spécifique à Héos : n'importe qui peut écrire un serveur (Python+ML, Rust, etc.) qui répond au même protocole. La spécification est publiée sous licence libre — voir `docs/OPTIMIZER_PROTOCOL.md` (ROADMAP).

> Sécurité : quelle que soit la sortie du backend, la boucle de sécurité et les bornes min/max par charge **plafonnent** l'allocation. Un optimiseur défaillant ne peut, au pire, que proposer une mauvaise répartition — bornée et clampée.

---

## Interface JSON-RPC

Namespace `NymeaEnergy` (hérité du fork ; migration vers un namespace EMS générique à l'étude pour l'amont). Transport WebSocket JSON-RPC 2.0, port nymea standard 4444. Voir [`INTERFACE.md`](INTERFACE.md) pour la référence complète (méthodes, types, notifications).

Surfaces principales : overload (`Get/SetPhasePowerLimit`), paramètres de charge (`acquisitionTolerance`, `batteryLevelConsideration`, `lockOnUnplug`), configuration EV (`Get/SetChargingInfo`), spot market.

---

## Configuration

Deux étages, à ne pas confondre :

**Tuning intégrateur — `EnergyManagerConfiguration`** (read-only, chargé une seule fois au démarrage ; un changement exige un redémarrage du daemon). Chemin : `$NYMEA_ENERGY_MANAGER_CONFIG`, sinon `/var/lib/nymea/energy-manager-configuration.json`, sinon les défauts (recommandé).

```json
{
  "chargingEnabledLockDuration": 300,
  "chargingCurrentLockDuration": 5,
  "minimumScheduleDuration": 15,
  "spotMarketChargePredictableEnergyPercentage": 0.5
}
```

| Paramètre | Défaut | Unité | Rôle |
|---|---|---|---|
| `chargingEnabledLockDuration` | 300 | s | Anti-flapping après ON/OFF |
| `chargingCurrentLockDuration` | 5 | s | Anti-flapping après changement de courant |
| `minimumScheduleDuration` | 15 | min | Durée minimale d'un créneau spot market |
| `spotMarketChargePredictableEnergyPercentage` | 0.5 | ratio | Fraction d'énergie spot considérée prédictible |

> Cette configuration sert à tester des comportements en environnement de test. Elle n'est pas destinée à être modifiée par l'utilisateur.

**Settings utilisateur** (runtime, via JSON-RPC, persistés dans `EnergySettings` / QSettings INI `energy.conf`) : `phasePowerLimit`, `acquisitionTolerance`, `batteryLevelConsideration`, les `ChargingInfo` par charger, l'état spot market. `lockOnUnplug` vit dans un QSettings séparé. Les seuils utilisateur ajoutés par le fork (seuil surplus par charge, priorités) suivent ce **chemin runtime**, jamais le JSON read-only.

---

## Conventions

- Timestamps : `QDateTime` ISO 8601 avec timezone.
- Puissances en **Watts**, courants en **Ampères**. `phasePowerLimit` est en **Ampères par phase**.
- `currentPower` root meter **négatif** = surplus (export).
- `phasePowerLimit = 0` → smart charging désactivé.
- `weighting` d'un `ScoreEntry` : 1.0 = créneau le moins cher, 0.0 = le plus cher.

---

## Build, tests, simulations

Build standard nymea (qmake6, cross-compilation arm64 supportée ; publication sur le canal APT `powersync-testing`).

Couverture de tests :

```sh
qmake CONFIG+=coverage
make -j$(nproc)
# tests dans tests/auto :
#   nymeaenergytestcharging
#   nymeaenergytestspotmarket
./build-coverage-report.sh -b builddir
```

Simulations (plots de vérification de la logique métier dans `results/`) :

```sh
./docker-simulation.sh   # docker requis
```

---

## Roadmap

- **Beta** : arbitrage central généralisé, adaptateur ECS/relais, frontière `requestOptimization` posée, stratégie règles par défaut. Mode `community` : tout fonctionne sans optimiseur.
- **Post-beta** : adaptateurs PAC/HVAC et batterie ; socket + protocole optimiseur documenté (GPL) ; backend propriétaire Héos ; contrainte réseau §14a EnWG comme source de plafond ; tarification FR (Linky TIC, Tempo) ; namespace EMS générique.
- **Amont** : une fois la beta opérationnelle, discussion avec l'équipe nymea sur une intégration possible dans l'arbre upstream.

---

## Licence

`etm-powersync-energy-etm` est sous **GNU General Public License v3.0 ou ultérieure**, comme l'amont dont il dérive. Tout le code de ce repo est GPL — il n'y a, et il n'y aura, aucun composant propriétaire ici. La valeur propriétaire (l'optimiseur **Héos**) vit dans un processus séparé, derrière le socket documenté, et n'est pas distribuée dans ce dépôt.

Une copie de la licence est incluse dans ce repo ; si elle manque : <https://www.gnu.org/licenses/gpl-3.0.html>.
