feat: Add engine dimmer with bypass

BREAKING CHANGE

Engine names have been reviewed as in list below:  
- engine.yaml => engine_1dimmer.yaml  
- engine_on_off.yaml => engine_1switch.yaml

Author: XavierBerger

.github/workflows/esphome_compilation.yml

@@ -31,9 +31,9 @@ jobs:
         echo "hotspot_password: \"myHotspotPassword\"" >> secrets.yaml
         echo "proxy_api_encryption_key: \"8q4u9dNBGMcsPemx+Q+WzLTU+mLXHAgPsrTpGjyV1hs=\"" >> secrets.yaml
         
-    - name: Compile esp32-proxy-client.yaml
+    - name: Compile esp8266-proxy-client.yaml
       continue-on-error: true
-      run: tools/convert_to_local_source_for_ci.sh esp32-proxy-client.yaml && esphome compile work_in_progress.yaml
+      run: tools/convert_to_local_source_for_ci.sh esp8266-proxy-client.yaml && esphome compile work_in_progress.yaml
       id: conf1
 
     - name: Compile wt32-eth01-solar-water-heater.yaml

docs/en/compile_coverage.md

@@ -4,7 +4,7 @@
 * common.yaml
 * power_meter_fronius.yaml
 * regulator_triac.yaml
-* engine.yaml
+* engine_1dimmer.yaml
 * energy_counter_theorical.yaml
 * temperature_limiter_DS18B20.yaml
 
@@ -13,11 +13,11 @@
 
 ## esp8266-standalone_on_off
 * power_meter_home_assistant.yaml
-* engine_on_off.yaml
+* engine_1switch.yaml
 * regulator_mecanical_relay.yaml
 * temperature_limiter_home_assistant.yaml
 
-## esp32-proxy-client
+## esp8266-proxy-client
 * power_meter_proxy_client.yaml
-* engine.yaml
+* engine_1dimmer_1bypass.yaml
 * regulator_solid_state_relay.yaml

docs/en/engine.md

@@ -1,13 +1,15 @@
+# Solar router engines
 
-# Progressive Engine
+An engine is designed to define how many and when energy has to be diverted.
 
-This package is implementing the engine of the solar router which determines when and how many energy has to be diverted to the load.
+Different kind of engine exists whach can progressively divert energy to a load and manage an ON/OFF switch. See details into engine's dedicated pages.
 
-**Progressive engine** calls every second the power meter to get the actual energy exchanged with the grid. If energy produce is greater than energy consummed and exceed the define echange target, the engine will determine the **percentage of the regulator "opening"** and adjusts it dynamically to reach the target.
+!!! note "Engine naming"
+    The name of engine is reflecting how energy divertion is performed:  
+    **Example** : `engine_1dimmer_1bypass` will manage 1 dimmer managing a progressive regulation associated with a bypass relay. 
 
-Engine's automatic regulation can be activated or deactivated with the activation switch.
 
-## User feedback LEDS
+### User feedback LEDS
 
 The yellow LED is reflecting the network connection:
 
@@ -16,37 +18,13 @@ The yellow LED is reflecting the network connection:
 - ***blink*** : solar router is not connected to the network and is trying to reconnect.
 - ***fast blink*** : An error occurs during the reading of energy exchanged with the grid.
 
-
 The green LED is reflecting the actual configuration of regulation:
 
 - ***OFF*** : automatic regulation is deactivated.
 - ***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:
-
-```yaml linenums="1"
-packages:
-  engine:
-    url: https://github.com/XavierBerger/Solar-Router-for-ESPHome/
-    file: solar_router/engine.yaml
-```
-
-When this package is used it is required to define the following paramater is `substitution` section as show in the example bellow:
+The configuration of LED are performed on `substitution` section as show in the example bellow:
 
 ```yaml linenums="1"
 substitutions:
@@ -55,6 +33,4 @@ 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/engine_1dimmer.md

@@ -0,0 +1,32 @@
+
+# engine_1dimmer
+
+This package is implementing the engine of the solar router which determines when and how many energy has to be diverted to the load.
+
+**engine_1dimmer** calls every second the power meter to get the actual energy exchanged with the grid. If energy produce is greater than energy consummed and exceed the define echange target, the engine will determine the **percentage of the regulator "opening"** and adjusts it dynamically to reach the target.
+
+Engine's automatic regulation can be activated or deactivated with the activation switch.
+
+## 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:
+
+```yaml linenums="1"
+packages:
+  engine:
+    url: https://github.com/XavierBerger/Solar-Router-for-ESPHome/
+    file: solar_router/engine_1dimmer.yaml
+```
+

docs/en/engine_1dimmer_1bypass.md

@@ -0,0 +1,43 @@
+# engine_1dimmer_1bypass
+
+This package implements the engine of the solar router which determines when and how much energy has to be diverted to the load, with a bypass function for maximum efficiency.
+
+When the regulator is intensively used for an extended period, the regulator will tends to overheat. This engine is designed to avoid this issue by activating a bypass relay and turning off the regulator when the regulator is opened at 100% for an extended period. To avoid flickering, the bypass relay is activated only when the regulator is opened at 100% for a number of consecutive regulation.
+
+**engine_1dimmer_1bypass** calls every second the power meter to get the actual energy exchanged with the grid. If energy produced is greater than energy consumed and exceeds the defined exchange target, the engine will determine the **percentage of regulator opening** and adjusts it dynamically to reach the target. When the regulator reaches 100% for an extended period, the bypass relay is activated for maximum efficiency.
+
+Engine's automatic regulation can be activated or deactivated with the activation switch.
+
+## How to wire the bypass relay
+
+- Live on the Bypass Relay Common (COM) and on the Relay to the Live Input of the Regulator
+- Normally Closed (NC) floating
+- Normally Open (NO) of the Relay to the Load Output of the Regulator (or directly to the Load)
+
+!!! Danger "Follow the wiring instructions"
+    Do not plug the Regulator Live Input to the Normally Closed (NC) of the relay ! Your load would be de-energized while switching the relay, potentially creating arcs inside the relay.
+    More info in this [discussion](https://github.com/XavierBerger/Solar-Router-for-ESPHome/pull/51#issuecomment-2625724543).
+
+## Router Level vs Regulator Opening
+
+The solar router uses three 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.
+
+- **Bypass Relay**: This represents the actual state (ON/OFF) of the physical bypass relay. When the Regulation is enabled, this relay automatically turns on after the duration `Bypass tempo` defined in Home Assistant. When the Regulation is disabled, you can manually trigger this relay to fully energized your load, LEDs and Energy Counter (if enabled) will not be triggered. You can also set the *Router Level* to 100, this will enable the relay, fully energized your load, trigger LEDs and Energy Counter.
+
+## Configuration
+
+To use this package, add the following lines to your configuration file:
+
+```yaml linenums="1"
+packages:
+  engine_regulator_1bypass:
+    url: https://github.com/XavierBerger/Solar-Router-for-ESPHome/
+    file: solar_router/engine_regulator_1bypass.yaml
+```
+
+!!! tip "Adjusting Bypass Tempo"
+    The `Bypass Tempo` determines how many consecutive regulations at 100% are needed before activating the bypass relay. A lower value will make the bypass more reactive but might cause more frequent switching (flickering). Because there's roughly 1 regulation per second, `Bypass Tempo` can be approximated as the time in second with the regulator at 100% before which the the bypass relay is activated.

docs/en/engine_on_off.md docs/en/engine_1switch.mddocs/en/engine_on_off.md renamed to docs/en/engine_1switch.md

@@ -1,15 +1,15 @@
 
-# ON/OFF Engine
+# engine_1switch
 
 This package is implementing the engine of the solar router which determines energy can be diverted to a local load or not.
 
-**ON/OFF engine** calls every second the power meter to get the actual power consumed. If energy sent to the grid is greater than the divertion start level (in W) during start tempo (in s), the relay is closed to use the energy locally. When the energy sent to the grid reach the level (in W) defined to stop the divertion during stop tempo (in s), the relay is openned and local consomption is stopped.
+**engine_1switch** calls every second the power meter to get the actual power consumed. If energy sent to the grid is greater than the divertion start level (in W) during start tempo (in s), the relay is closed to use the energy locally. When the energy sent to the grid reach the level (in W) defined to stop the divertion during stop tempo (in s), the relay is openned and local consomption is stopped.
 
-ON/OFF engine's automatic regulation can be activated or deactivated with the activation switch.
+engine_1switch's automatic regulation can be activated or deactivated with the activation switch.
 
 The following schema is representing the consumption with this engine activated:
 
-![engine_on_off](images/engine_on_off.png)
+![engine_1switch](images/engine_1switch.png)
 
 **Legend:**
 
@@ -28,22 +28,6 @@ The following schema is representing the consumption with this engine activated:
 !!! tips "finely adjust start and stop tempo"
     The start and stop tempo determine the responsiveness of the regulation. These delays must be finely adjusted to avoid oscillations. For example, if you have an electric stove, pay attention to the heating delays.
 
-## User feedback LEDS
-
-The yellow LED is reflecting the network connection:
-
-- ***OFF*** : solar router is not connected to power supply.
-- ***ON*** : solar router is connected to the network.
-- ***blink*** : solar router is not connected to the network and is trying to reconnect.
-- ***fast blink*** : An error occurs during the reading of energy exchanged with the grid.
-
-
-The green LED is reflecting the actual configuration of regulation:
-
-- ***OFF*** : automatic regulation is deactivated.
-- ***ON*** : automatic regulation is active and is not diverting energy to the load.
-- ***blink*** : solar router is currently sending energy to the load.
-
 ## Configuration
 
 To use this package, add the following lines to your configuration file:
@@ -52,7 +36,7 @@ To use this package, add the following lines to your configuration file:
 packages:
   engine:
     url: https://github.com/XavierBerger/Solar-Router-for-ESPHome/
-    file: solar_router/engine_on_off.yaml
+    file: solar_router/engine_1switch.yaml
 ```
 
 When this package is used it is required to define the following paramater is `substitution` section as show in the example bellow:

docs/en/example_proxy.md

@@ -6,10 +6,10 @@ The configuration of the **Proxy client** is only using a [Home Assistant power
 --8<-- "esp8285-power-meter-proxy.yaml"
 ```
 
-This configuration the **Solar Router** is using [Proxy client power meter](power_meter_proxy_client.md), [Triac regulator](regulator_triac.md) and [Solar router engine](engine.md).
+This configuration the **Solar Router** is using [Proxy client power meter](power_meter_proxy_client.md), [Triac regulator](regulator_triac.md) and [Solar router engine](engine_1dimmer.md).
 
 GPIO pins have been defined to match hardware configuration described [here](hardware.md)
 
 ```yaml linenums="1"
---8<-- "esp32-proxy-client.yaml"
+--8<-- "esp8266-proxy-client.yaml"
 ```

docs/en/example_standalone.md

@@ -1,6 +1,6 @@
 # Standalone Solar Router
 
-This configuration implements a **Solar Router** with a progressive regulation. It uses [Fronuis power meter](power_meter_fronius.md), [Triac regulator](regulator_triac.md), [Progressive engine](engine.md).
+This configuration implements a **Solar Router** with a progressive regulation. It uses [Fronuis power meter](power_meter_fronius.md), [Triac regulator](regulator_triac.md), [Progressive engine](engine_1dimmer.md).
 
 GPIO pins have been defined to match hardware configuration described [here](hardware.md)
 

docs/en/hardware.md

@@ -45,5 +45,5 @@ Bill of material:
 * 1 x ESP8266 (or equivalent)
 
 !!! Note "This router has some limitation"
-    * It has to be used with ON/OFF regulation (engine_on_off.yaml) and is not compatible with variable engine
+    * It has to be used with ON/OFF regulation (engine_1switch.yaml) and is not compatible with variable engine
     * Due to the small space of memory, it doesn't support OTA update

docs/en/installation.md

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