diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b6d7715 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,24 @@ +# CLAUDE.md — etm-powersync-energy-plugin-etm + +## Rôle +Energy manager nymea : rule-based surplus (Community) + load-management + connecteur vers l'optimiseur (Auto/Predict). + +## Source de vérité +[etm-powersync-docs / ARCHITECTURE.md](https://git.etm-powersync.fr/ETM-Schurig/etm-powersync-docs/src/branch/master/ARCHITECTURE.md). + +## Structure (héritée de l'amont) +`EnergyPluginNymea` est une coquille (`IID "io.nymea.EnergyPlugin"`, un `init()`). La logique vit dans des **managers** instanciés dans `init()` : `SmartChargingManager`, `spotmarket/`, `RootMeter`, `EvCharger`, `nymeaenergyjsonhandler` (API JSON-RPC). + +## Frontière de licence (impérative) +GPL-3. **Ne jamais coder ici** : MPC, prévision, Perez, masque d'ombrage, arbitrage. Ça appartient à `etm-powersync-optimizer`. + +## Travail attendu +- **Community** : ajuster le rule-based existant (surplus, hystérésis, priorités). Pas de réécriture from scratch — l'amont fournit la base. +- **OptimizerManager** (nouveau manager, à côté des autres) : collecte l'état (RootMeter + things) → `POST /optimize` → applique les `setpoints` via le chemin de contrôle existant (`EvCharger`). **Transport pur, zéro maths.** +- **Précédence** : optimiseur sain + planning frais → il pilote ; sinon → rule-based local. Le plugin fonctionne toujours seul. + +## Règle de sécurité (non négociable) +Le **load-management est prioritaire absolu** : toute consigne (y compris de l'optimiseur) qui ferait dépasser `ISOUSC` est **écrêtée localement après réception**. C'est une contrainte appliquée par le plugin, pas une suggestion envoyée à l'optimiseur. + +## Contrat +`OptimizerManager` implémente [interfaces/optimize.md](https://git.etm-powersync.fr/ETM-Schurig/etm-powersync-docs/src/branch/master/interfaces/optimize.md). diff --git a/README.md b/README.md index c398afc..1730aa1 100644 --- a/README.md +++ b/README.md @@ -1,74 +1,21 @@ +# etm-powersync-energy-plugin-etm -# nymea energy manager +Energy manager ETM-PowerSync pour nymea (energy experience). Fork de `nymea-energy-plugin-nymea` (nymea GmbH / chargebyte), étendu par ETM. -Repository for the energy plugin for the energy experience. +## Fonctions -This energy plugin adds smart charging, spotmarket charging and overload protection to the nymea energy experience. +- **Optimisation de surplus rule-based** (tier Community) — base héritée de l'amont (smart charging, spotmarket, overload protection), ajustée aux priorités ETM. +- **Load-management** — surveillance de la puissance souscrite (`ISOUSC`), protection fusible/disjoncteur. Contrainte de **sécurité, locale, prioritaire** sur toute consigne. +- **OptimizerManager** — connecteur vers `etm-powersync-optimizer` (tiers Auto/Predict). Transport pur ; repli automatique sur le rule-based si l'optimiseur est injoignable ou périmé. -## Energy manager configuration +## Build / tests -In order to tweak local energy manager setups a read only configuration file has been introduced. The file can be specified using the environment variable -`NYMEA_ENERGY_MANAGER_CONFIG`. If the environment path has not been specified, by default the energy manager will try to load the file from `/var/lib/nymea/energy-manager-configuration.json`. +Type `io.nymea.EnergyPlugin`. QMake (Qt5/Qt6). Simulations via `./docker-simulation.sh`, couverture via `./generate-coverage-report.sh` (cf. `tests/`). -If there is no such file, the defaults will be used, which is **recommended**. +## Licence -> Note: this configuration is desinged to test certain behaviors in certain test environments, it is not designed to be used by default or changed by the user. +GPL-3.0-or-later (`COPYING` → `LICENSE.GPL3`). Copyright amont nymea GmbH + chargebyte conservé. **Aucune logique propriétaire** ici. -The default configuration looks like this: +## Architecture d'ensemble -```json -{ - "chargingEnabledLockDuration": 300, - "chargingCurrentLockDuration": 5, - "minimumScheduleDuration": 15, - "spotMarketChargePredictableEnergyPercentage": 0.5 -} -``` - -* `chargingEnabledLockDuration`: defines in seconds how long a charger is locked when charging has been paused or resumed. Default is 5 minutes, which ensures a certain continuity for the car. Thsi prevents a constant charging start and stop. -* `chargingCurrentLockDuration`: defines in seconds how long a charger is locked when the charging current has been changed. According to the spec this can be changed every 10 seconds. For tests we can go under this spec limit. -* `minimumScheduleDuration`: duration in minutes. When spotmarket charging scheduled get calculated, there might be a situation where charging wpuld stop for an hour and the rest would be only one minute. In order to prevent such small schedules, this limit will be considered from the scheduler, the minimum is 15 minutes, everything underneeth will be appende or prepended to existing charging slots. -* `spotMarketChargePredictableEnergyPercentage`: if the spotmarket data are not availabe yet for the next day, this paramter specifies how much will be planed with the already known schedule. The rest will be planed once the schedules are available. - - -## Simulations - -In order to verify how the bussineslogic works and the target can be reached, a simulation environment has been set up producing plots of the simulation. - -For simplification and beeing able to play with the simulations, a docker tool can be used to run the simulations in a container. - -> Note: please install docker before running the script - - ./docker-simulation.sh - - -Once the simulation have finished successfully the plots can be found in the `results/` folder of the source directory. - -## Test coverage report - -In order to build a test coverage report from the energy manager, the source code bust be built with the coverage support enabled. - -Add the `qmake` configuration in order to enable it: - - qmake CONFIG+=coverage -on - make -j$(nproc) - - - # The tests can be found in tests/auto - nymeaenrgytestcharging - nymeaenrgytestspotmarket - - # Optionally you can also run the simulations to show coverage of the simulation code - nymea-energy-simulation - -Once all tests have run successfully, the report can be generated as follows: - - ./build-coverage-report.sh -b builddir - -The tool opens the generated report in the browser. - -## License - -nymea-energy-plugin-nymea is licensed under the GNU General Public License version 3.0 or (at your option) any later version. -A copy of the license should be included within this repository; if it is missing you can obtain it from . +Source de vérité : [etm-powersync-docs / ARCHITECTURE.md](https://git.etm-powersync.fr/ETM-Schurig/etm-powersync-docs/src/branch/master/ARCHITECTURE.md).