refactor: routing level refactorisation

cliff.toml

@@ -19,7 +19,7 @@ body = """
 {% else %}\
     ## [unreleased]
 {% endif %}\
-{% for group, commits in commits | group_by(attribute="group") %}
+{% for group, commits in commits | filter(attribute="merge_commit", value=true) | group_by(attribute="group") %}
     #### {{ group | striptags | trim | upper_first }}
     {% for commit in commits | unique(attribute="message") %}
         - {% if commit.scope %}*({{ commit.scope }})* {% endif %}\

docs/en/contributing.md

@@ -57,25 +57,32 @@ If this new power meter needs specific configuration, required parameters have t
 
 A documentation have to be added describing the power meter and how to configure it. See [update documentation](#update-documentation) chapter bellow.
 
-### Developping a **Regulator**
+### Developping **Regulator**
 
-A **Regulator** has to manage the percentage of energy sent to the load based on the `regulator_opening` sensor state. `regulator_opening` state can vary from 0 (where no energy is sent to the load) to 100 (where all the energy possible is sent to the load).
+A **Regulator** has to manage the percentage of energy sent to its load based on its regulator level sensor (e.g., `regulator_opening` for TRIAC/SSR). Each regulator's level can vary from 0 (where no energy is sent to the load) to 100 (where all possible energy is sent to the load).
 
-The following code represent an example (extracted from [regulator_triac.yaml](https://github.com/XavierBerger/Solar-Router-for-ESPHome/blob/main/solar_router/regulator_triac.yaml)) of usage based on `light` component using `brightness` to control the energy diverted:
+The system's overall state is managed by the `router_level` sensor, which controls all regulators. When `router_level` is 0, all regulators should be off, and when it's 100, all regulators should be at maximum. For systems with a single regulator, the regulator's level typically mirrors the `router_level`, but they remain separate as `router_level` is used for LED indicators and energy counting logic.
+
+Here's an example of a regulator implementation (extracted from [regulator_triac.yaml](https://github.com/XavierBerger/Solar-Router-for-ESPHome/blob/main/solar_router/regulator_triac.yaml)) using the `light` component's `brightness` to control energy diversion:
 
 ```yaml linenums="1"
 script:
   # Apply regulation on triac using light component
   - id: regulation_control
     mode: single
     then:
-      # Apply opening level on triac using light component
+      # Apply router_level to triac using light component
       - light.turn_on:
           id: dimmer_controller
           brightness: !lambda return id(regulator_opening).state/100.0;
 ```
 
-!!! tip "Tip: See already developped regulators for examples"
+!!! tip "Tip: See already developed regulators for examples"
+
+You can develop one or multiple regulators to work together in the same system. Each regulator should:
+- Have its own level sensor ranging from 0-100
+- Respond to changes in the system-wide `router_level`
+- Handle its specific hardware control logic
 
 If this new power meter needs specific configuration, required parameters have to be added into `substitution` section.
 

docs/en/engine.md

@@ -23,6 +23,18 @@ The green LED is reflecting the actual configuration of regulation:
 - ***ON*** : automatic regulation is active and is not diverting energy to the load.
 - ***blink*** : solar router is currently sending energy to the load.
 
+## Router Level vs Regulator Opening
+
+The solar router uses two distinct but related level controls:
+
+- **Router Level**: This is the main system-wide control (0-100%) that represents the overall routing state. It controls the LED indicators and energy counter logic. When automatic regulation is enabled, this level is dynamically adjusted based on power measurements.
+
+- **Regulator Opening**: This represents the actual opening level (0-100%) of the physical regulator. By default, it mirrors the router level since there is only one regulator. While it can be controlled independently, changes to regulator_opening alone won't affect the router_level or trigger LED state changes.
+
+The regulator opening entity is hidden from Home Assistant by default. To expose it, add this to your substitutions:
+
+Note: It's recommended to adjust the router_level rather than regulator_opening directly, as this ensures proper system feedback through LEDs and energy monitoring.
+
 ## Configuration
 
 To use this package, add the following lines to your configuration file:
@@ -43,4 +55,6 @@ substitutions:
   # Yellow LED is reflecting power meter status
   green_led_pin: GPIO19
   yellow_led_pin: GPIO18
+  # (Optional) Expose regulator opening to HA (hidden by default)
+  hide_regulators: "False"
 ```

docs/en/installation.md

@@ -52,7 +52,7 @@ A **proxy** just need 1 **power meter** package
 #### Step 2.3: Add an Engine
 
 * [Progressive Engine](engine.md)  
-  Read power exchange with the grid, determine and apply the percentage of regulator opening.
+  Read power exchange with the grid, determine and apply the percentage of router level.
 
 * [ON/OFF Engine](engine_on_off.md)  
   Read power exchange with the grid, and start to divert energy if a threshold is reached and stop if another threshold is reached.

docs/en/power_meter_home_assistant.md

@@ -11,7 +11,11 @@ packages:
     file: solar_router/power_meter_home_assistant.yaml
 ```
 
-This package needs to know the sensor to use to get the power consumption. It is expected for this sensor to be in Watt (W), to be positive (>0) when electricity is used from the grid and negative (<0) when electricity is sent to the grid. This sensor has to be defined by `main_power_sensor` into `subtsitutions` section of your configuration as in example ballow:
+This package needs to know which sensor to use to obtain the energy exchanged with the grid. It is expected that this sensor is in Watts (W), positive (>0) when electricity is consumed from the grid, and negative (<0) when electricity is sent to the grid.
+
+This power meter can also provide your solar router with the consumption used by your house. This may be necessary, for example, for calculating the theoretical diverted energy.
+
+The sensor for energy exchange with the grid should be defined by `main_power_sensor` and the consumption sensor by `consumption_sensor` in the `substitutions` section of your configuration, as shown in the example below.
 
 ```yaml linenums="1"
 substitutions:

docs/en/solar_router.md

@@ -13,8 +13,9 @@
     * ***Reactivity***  
       How fast will be the solar routing
       From 1 to 100. 1 is the slowest, 100 is the fastest.
-    * ***Regulator opening***  
-      What is the current percentage of gate opening to send energy to the load 
+    * ***Router Level***  
+      What is the current percentage of energy sent to the load by the overall router
+      From 0 to 100. 0 means no energy diverted, 100 means all energy diverted.
     * ***Target grid exchange***  
       What is the target of energy exchanged with the grid.  
       < 0 energy is sent to the grid  
@@ -30,8 +31,8 @@
 <br>  
 
 !!! note 
-    When solar routing is deactivated, regulator opening slider can be modified "by hand".  
-    If you modify the triac opening state while the solar routing is enabled, the routing algorithm will immediately modify the value to meet target grid exchange level.
+    When solar routing is deactivated, router level slider can be modified "by hand".  
+    If you modify the router level state while the solar routing is enabled, the routing algorithm will immediately modify the value to meet target grid exchange level.
 
 ## ON/OFF regulation
 
@@ -41,8 +42,9 @@
 
     * ***Activate Solar Routing***  
       Control if Solar routing should be activated or not
-    * ***Energy divertion***  
-      Ectivate energy divertion or not 
+    * ***Router Level***  
+      What is the current percentage of energy sent to the load by the overall router
+      Either 0 OR 100. 0 means no energy diverted, 100 means all energy diverted.
     * ***Start power level***  
       Define the level of energy when divertion has to start  
     * ***Start tempo***  
@@ -64,7 +66,6 @@
 <br>
 <br>
 
-
 !!! note 
-    When solar routing is deactivated, regulator opening slider can be modified "by hand".  
-    If you modify the triac opening state while the solar routing is enabled, the routing algorithm will immediately modify the value to meet target grid exchange level.
+    When solar routing is deactivated, router level slider can be modified "by hand".  
+    If you modify the router level state while the solar routing is enabled, the routing algorithm will immediately modify the value to meet target grid exchange level.

docs/fr/contributing.md

@@ -1,96 +1,103 @@
 # Contribuer au développement
 
-**Solar Router for [ESPHome](http://esphome.io)** est conçu pour être modulaire afin de faciliter la personnalisation pour divers compteurs d'énergie et régulateurs.  
-Vous souhaitez contribuer ? Vous êtes le bienvenu et vous trouverez ci-dessous quelques recommandations pour le faire.
+**Solar Router for [ESPHome](http://esphome.io)** est conçu de manière modulaire pour faciliter la personnalisation avec différents compteurs de puissance et différents régulateurs.  
+Vous souhaitez contribuer ? Vous êtes les bienvenus et vous trouverez ci-dessous quelques recommandations pour le faire.
 
-## Développer un **Matériel**
+## Développer un **Hardware**
 
-Vous pouvez proposer n'importe quel matériel basé sur vos besoins. Si ce nouveau matériel nécessite l'utilisation de GPIO, les broches utilisées par votre matériel doivent être configurées dans la section `substitution`.
+Vous pouvez proposer n'importe quel matériel selon vos besoins. Si ce nouveau matériel nécessite l'utilisation de GPIO, les broches utilisées par votre matériel doivent être configurées dans la section `substitution`.
 
-Une documentation doit être ajoutée décrivant ce nouveau matériel et ses contraintes (Ex : fonctionnalité disponibles sur les GPIO). Voir le chapitre [mettre à jour la documentation](#mise-a-jour-de-la-documentation) ci-dessous.
+Une documentation doit être ajoutée décrivant ce nouveau matériel et ses contraintes (Ex : capacités GPIO). Voir le chapitre [mettre à jour la documentation](#mettre-à-jour-la-documentation) ci-dessous.
 
-## Développer un **Package logiciel**
+## Développer un **Package Logiciel**
 
 ### Configurer l'environnement de développement
 
-Pour contribuer à **Solar Router for ESPHome**, développer une nouvelle fonctionnalité sur votre ordinateur et proposer une *Pull Request*, vous devez :
+Pour contribuer à **Solar Router for ESPHome**, développer une nouvelle fonctionnalité sur votre ordinateur et proposer une **pull request**, vous devez :
 
-- Forker le [dépôt **Solar Router for ESPHome**](https://github.com/XavierBerger/Solar-Router-for-ESPHome) sur Github.
-- Cloner votre dépôt forké sur votre PC.
-- Créer une branche de développement à partir de **main**.
-- [Créer et activer un environnement virtuel Python](https://docs.python.org/3/library/venv.html) :
-    ```
+- Forker le [dépôt **Solar Router for ESPHome**](https://github.com/XavierBerger/Solar-Router-for-ESPHome) sur Github
+- Cloner votre dépôt forké sur votre PC
+- Créer une branche de développement à partir de **main**
+- [Créer et activer un environnement virtuel Python](https://docs.python.org/3/library/venv.html)
+    ```shell
     python -m venv venv
     venv/bin/activate
     ```
-- Installer ESPHome CLI et autres dépendances du projet :
-    ```
+- Installer ESPHome CLI et autres dépendances :
+    ```shell
     pip install -r requirements.txt
-    ``` 
-- Installer et tester votre code sur votre appareil avec la commande `esphome` : 
     ```
-    esphome run ma_configuration.yaml
+- Installer et tester votre code sur votre appareil avec la commande `esphome` :
+    ```shell
+    esphome run my_configuration.yaml
     ```
-- Mettre à jour le code et pousser les mises à jour sur votre dépôt.
-- Proposer une *Pull Request* depuis votre fork vers le dépôt officiel.
+- Mettre à jour le code et pousser les modifications sur votre dépôt
+- Proposer une *pull request* depuis votre fork vers le dépôt officiel
 
 ### Développer un **Power Meter**
 
-Un **Power Meter** est un composant conçu pour fournir et mettre à jour un sensor nommé `real_power`.
+Un **Power Meter** est un composant conçu pour fournir et mettre à jour périodiquement un capteur nommé `real_power`.
 
 ```yaml linenums="1"
 sensor:
-  # Sensor showing the actual power consumption
+  # Capteur montrant la consommation de puissance actuelle
   - id: real_power
     platform: template
-    name: "Real Power"
+    name: "Puissance Réelle"
     device_class: "power"
     unit_of_measurement: "W"
     update_interval: 1s
 ```
 
-!!! tip "Astuce : Voir les Power Meter déjà développés pour des exemples"
+!!! tip "Astuce : Voir les compteurs de puissance déjà développés pour des exemples"
 
-Ce capteur est utilisé par les **Engine** pour obtenir la valeur de la puissance échangée avec le réseau.
+Ce capteur est utilisé par les **Moteurs** pour obtenir la valeur de la puissance échangée avec le réseau.
 
-Si ce nouveau Power Meter nécessite une configuration spécifique, les paramètres requis doivent être ajoutés dans la section `substitution`.
+Si ce nouveau compteur de puissance nécessite une configuration spécifique, les paramètres requis doivent être ajoutés dans la section `substitution`.
 
-Une documentation doit être ajoutée décrivant le Power Meter et comment le configurer. Voir le chapitre [mettre à jour la documentation](#mise-a-jour-de-la-documentation) ci-dessous.
+Une documentation doit être ajoutée décrivant le compteur de puissance et comment le configurer. Voir le chapitre [mettre à jour la documentation](#mettre-à-jour-la-documentation) ci-dessous.
 
-### Développer un **Régulateur**
+### Développer des **Regulators**
 
-Un **Régulateur** doit gérer le pourcentage d'énergie envoyé à la charge en fonction de l'état du capteur `regulator_opening`. L'état de `regulator_opening` peut varier de 0 (où aucune énergie n'est envoyée à la charge) à 100 (où toute l'énergie possible est envoyée à la charge).
+Un **Regulator** doit gérer le pourcentage d'énergie envoyé à sa charge en fonction de son capteur de niveau de régulation (par exemple, `regulator_opening` pour TRIAC/SSR). Le niveau de chaque régulateur peut varier de 0 (où aucune énergie n'est envoyée à la charge) à 100 (où toute l'énergie possible est envoyée à la charge).
 
-Le code suivant représente un exemple (extrait de [regulator_triac.yaml](https://github.com/XavierBerger/Solar-Router-for-ESPHome/blob/main/solar_router/regulator_triac.yaml)) d'utilisation basé sur le composant `light` utilisant `brightness` pour contrôler l'énergie dérivée :
+L'état global du système est géré par le capteur `router_level`, qui contrôle tous les régulateurs. Quand `router_level` est à 0, tous les régulateurs doivent être éteints, et quand il est à 100, tous les régulateurs doivent être au maximum. Pour les systèmes avec un seul régulateur, le niveau du régulateur reflète généralement le `router_level`, mais ils restent séparés car `router_level` est utilisé pour les indicateurs LED et la logique de comptage d'énergie.
+
+Voici un exemple d'implémentation d'un régulateur (extrait de [regulator_triac.yaml](https://github.com/XavierBerger/Solar-Router-for-ESPHome/blob/main/solar_router/regulator_triac.yaml)) utilisant le composant `light` et sa `brightness` pour contrôler la dérivation d'énergie :
 
 ```yaml linenums="1"
 script:
-  # Apply regulation on triac using light component
+  # Appliquer la régulation sur le triac en utilisant le composant light
   - id: regulation_control
     mode: single
     then:
-      # Apply opening level on triac using light component
+      # Appliquer router_level au triac en utilisant le composant light
       - light.turn_on:
           id: dimmer_controller
           brightness: !lambda return id(regulator_opening).state/100.0;
 ```
 
 !!! tip "Astuce : Voir les régulateurs déjà développés pour des exemples"
 
-Si ce nouveau compteur électrique nécessite une configuration spécifique, les paramètres requis doivent être ajoutés dans la section `substitution`.
+Vous pouvez développer un ou plusieurs régulateurs pour travailler ensemble dans le même système. Chaque régulateur doit :
+- Avoir son propre capteur de niveau allant de 0 à 100
+- Répondre aux changements du `router_level` global du système
+- Gérer sa logique de contrôle matériel spécifique
+
+Si ce nouveau compteur de puissance nécessite une configuration spécifique, les paramètres requis doivent être ajoutés dans la section `substitution`.
 
-Une documentation doit être ajoutée décrivant le compteur électrique et comment le configurer. Voir le chapitre [mise à jour de la documentation](#mise-a-jour-de-la-documentation) ci-dessous.
+Une documentation doit être ajoutée décrivant le compteur de puissance et comment le configurer. Voir le chapitre [mettre à jour la documentation](#mettre-à-jour-la-documentation) ci-dessous.
 
-## Mise à jour de la **Documentation**
+## Mettre à jour la **Documentation**
 
-La documentation est rédigée en utilisant [mkdocs](https://www.mkdocs.org/) et [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
+La documentation est écrite en utilisant [mkdocs](https://www.mkdocs.org/) et [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
 
 Pour installer `mkdocs`, vous devez installer [Python](https://python.org) puis :
 
-- Créer un environnement virtuel (voir [documentation Python](https://docs.python.org/3/library/venv.html)).
-- Installer le module requis avec la commande suivante `pip install -r requirements.txt`.
+- Créer un environnement virtuel (voir la [documentation Python](https://docs.python.org/3/library/venv.html)).
+- Installer les modules requis avec la commande suivante `pip install -r requirements.txt`.
 
-La documentation est stockée dans le répertoire `docs`. En anglais dans le répertoire `en` etn en français dans le répertoir `fr`. Pour voir vos modifications en temps réel dans votre navigateur, exécutez la commande `mkdocs serve` et naviguez sur [http://127.0.0.1:8000](http://127.0.0.1:8000)[6].
+La documentation est stockée dans le répertoire `docs`. Pour voir vos modifications en temps réel dans votre navigateur, exécutez la commande `mkdocs serve` et naviguez sur [http://127.0.0.1:8000](http://127.0.0.1:8000)
 
 !!! note "Mise à jour du Changelog"
     Le Changelog n'est disponible que dans la [documentation](https://xavierberger.github.io/Solar-Router-for-ESPHome/changelog/) officiellement publiée.  
@@ -100,6 +107,6 @@ La documentation est stockée dans le répertoire `docs`. En anglais dans le ré
     Les versions sont basées sur les tags.  
     Les lignes ajoutées dans le changelog sont basées sur les *messages de commit de fusion*.
 
-    Le script `tools\update_documentation.sh` est conçu pour mettre à jour `changelog.md`, générer et publier la documentation `mkdocs` sur [github pages](https://xavierberger.github.io/Solar-Router-for-ESPHome/).  
+    Le script `tools\update_documentation.sh` est conçu pour mettre à jour `changelog.md`, générer et publier la documentation `mkdocs` sur les [pages github](https://xavierberger.github.io/Solar-Router-for-ESPHome/).  
     **Le script de mise à jour de la documentation est destiné à être utilisé uniquement par le mainteneur du dépôt.**