feat: Add scheduler to define force run

XavierBerger · web-flow · commit a1d6cda7551d · 2025-07-16T19:28:54.000+02:00
diff --git a/docs/en/firmware.md b/docs/en/firmware.md
@@ -10,7 +10,8 @@ Packages are :
 * **Engine** : design to determine how much of energy and when surplus of energy should be diverted to the load.
 * **Regulator** : design to channel the surplus of energy to a designated load.
 * **Energy counter** : design to report the amount of energy diverted to the load.
-* **Temperature limiter**: design to stop the system when a temperature limit is reached
+* **Temperature limiter**: design to stop the system when a temperature limit is reached.
+* **Scheduler** : design to schedule automatisation.
 
 ## Packages
 
diff --git a/docs/en/installation.md b/docs/en/installation.md
@@ -62,6 +62,11 @@ A **proxy** just need 1 **power meter** package
 * [Energy Counter Theorical](energy_counter_theorical.md)  
   Calculate energy savec base on energy diverted and load power.
 
+#### Step 2.5 : Add a Scheduler (*Optionnel*)
+
+* [Scheduler Forced Run](scheduler_forced_run.md)  
+  Stop solar routing and force load power between begin and end hour.
+
 ### Step 3: Configure your solar router
 
 Each package requires a configuration which is done in `vars` section of `packages`.  
diff --git a/docs/en/scheduler.md b/docs/en/scheduler.md
@@ -0,0 +1,7 @@
+# Scheduler
+
+A *scheduler* is designed to perform automation directly via EspHome, to be more robust in the event of loss of connection with HomeAssistant, for example.
+
+Each *scheduler* exposes controls to customize the automation to your needs from the HomeAssistant interface.
+
+The first example is to enable forced load operation during off-peak hours.
diff --git a/docs/en/scheduler_forced_run.md b/docs/en/scheduler_forced_run.md
@@ -0,0 +1,100 @@
+# Scheduler Forced Run
+
+The *scheduler forced run* is designed to automate solar router shutdown and forced run at a certain load power.
+
+Examples of use:
+
+- Enable forced run of load during off-peak hours (Router Level=100%)
+- Deactivate the router and switch off the load to make room for other uses (Router Level=0%).
+
+This *scheduler* exposes controls for customizing automation to your needs from the HomeAssistant interface.
+
+![HA](images/SchedulerForcedRunInHomeAssistant.png){ align=left }
+!!! note ""
+    **Controls**
+    
+    * ***Activate scheduler*** 
+        Controls whether the scheduler should be activated or not.
+        This allows you to deactivate the scheduler according to your own criteria (e.g. if your water heater has already had enough power during the day, there's no need to force it to run at night).
+    * ***Begin Hour*** 
+        From 0:00 to 23:00. Time at which forced operation starts.
+    * ***Begin Minute*** 
+        From 0 minutes to 55 minutes, in 5-minute steps.
+      If the start time is 1h and the minutes are 15 minutes, then forced operation starts at 1h15.
+    * ***Checking End Threshold*** 
+        From 0 minutes to 720 minutes, in 5-minute steps.
+        This option lets you define a safety margin to check every 5 minutes between the end of the schedule + X minutes that the router has returned to operation.
+        For example, if the end time is set to 2:00 and the verification threshold to 60 minutes, every 5 minutes between 2:00 and 3:00 (inclusive) the scheduler will restart the solar router if it is stopped.
+        This ensures that the schedule ends even if the ESP crashes at the end time.
+    * ***End Hour*** 
+        From 0:00 to 23:00. Time at which forced operation stops.
+    * ***End Minute*** 
+        From 0 minutes to 55 minutes, in 5-minute steps.
+        If the end time is 1h and the minutes are 15 minutes, then the forced walk schedule ends at 1h15.
+    * ***Router level*** 
+        From 0% to 100% in 1% steps.
+        Defines the target level at which the router will be set while the scheduler is running between the start and end times.
+
+
+## Simple Configuration
+
+To use more than one of these packages, add the following lines to your configuration file:
+
+```yaml linenums="1"
+packages:
+  scheduler_forced_run:
+    url: https://github.com/XavierBerger/Solar-Router-for-ESPHome/
+    files:
+      - path: solar_router/scheduler_forced_run.yaml
+```
+
+## Multiple Configuration
+
+If you want to use several instances of this package, for example to program one forced operation during the day and another at night, add the following lines to your configuration file:
+
+```yaml linenums="1"
+packages:
+  scheduler_forced_run:
+    url: https://github.com/XavierBerger/Solar-Router-for-ESPHome/
+    files:
+      - path: solar_router/scheduler_forced_run.yaml
+        vars:
+          scheduler_unique_id: "NightForced"
+      - path: solar_router/scheduler_forced_run.yaml
+        vars:
+          scheduler_unique_id: "DayForced"
+```
+
+It is necessary to define `scheduler_unique_id` in the `vars` section, as shown in the example above. This variable must not contain spaces or special characters, and must be unique for each *scheduler forced run*. It allows you to have as many instances as you need without any conflicts.
+
+## Advanced Configuration (script)
+
+
+This package provides the option of calling a custom script every 5 minutes during schedule execution.
+
+For example, to stop scheduling before the end time if a temperature sensor reaches a target value, add the following lines to your configuration file:
+
+```yaml linenums="1"
+packages:
+  scheduler_forced_run:
+    url: https://github.com/XavierBerger/Solar-Router-for-ESPHome/
+    files:
+      - path: solar_router/scheduler_forced_run.yaml
+        vars:
+          scheduler_unique_id: "NightForced"
+          custom_script: check_temperature_for_NightForcedScheduler
+          
+script:
+  # ...
+  - id: check_temperature_for_NightForcedScheduler
+    mode: single
+    then:
+        -if:
+            condition:
+                - lambda: return id(myTemperatureSensor).state >= 80;
+            then:
+                # Name of the switch is different for every scheduler, it depend of the scheduler_unique_id (default value: forced) : "${scheduler_unique_id}_scheduler_activate"
+                - switch.turn_off: NightForced_scheduler_activate
+```
+
+It is necessary to define `custom_script` in the `vars` section, as shown in the example above. This variable is used to pass the name of the script that will be called every 5 minutes when the scheduler is run.
diff --git a/docs/fr/firmware.md b/docs/fr/firmware.md
@@ -11,6 +11,7 @@ Les *packages* sont :
 * **Regulator** : conçu pour canaliser le surplus d'énergie vers une charge désignée.
 * **Energy counter** : conçu pour rapporter la quantité d'énergie détournée vers la charge.
 * **Temperature limiter** : conçu pour arrêter le système lorsqu'une limite de température est atteinte.
+* **Scheduler** : conçu pour planifier des automatisations.
 
 ## Packages
 
diff --git a/docs/fr/installation.md b/docs/fr/installation.md
@@ -60,6 +60,11 @@ Un **proxy** n'a besoin que d'un package **power meter**
 * [Compteur d'énergie théorique](energy_counter_theorical.md)  
   Calculer l'énergie économisée basée sur l'énergie détournée et la puissance de charge.
 
+#### Étape 2.5 : Ajouter un Planificateur (*Optionnel*)
+
+* [Planificateur de marche forcée](scheduler_forced_run.md)  
+  Stop le routeur solaire et force la puissance de charge entre une heure de début et de fin.
+
 ### Étape 3 : Configurer votre routeur solaire
 
 Chaque package nécessite une configuration qui se fait dans la section `substitution`.  
diff --git a/docs/fr/scheduler.md b/docs/fr/scheduler.md
@@ -0,0 +1,7 @@
+# Scheduler / Planificateur
+
+Un *scheduler / planificateur* est conçu pour effectuer une automatisation directement via EspHome afin d'être plus robuste en cas de perte de liason avec HomeAssistant par exemple.
+
+Chaque *scheduler / planificateur* expose des contrôles afin de personnaliser l'automatisation à vos besoins depuis l'interface HomeAssistant.
+
+Le premier exemple d'utilisation est de permettre une marche forcée de la charge pendant les heures creuses.
diff --git a/docs/fr/scheduler_forced_run.md b/docs/fr/scheduler_forced_run.md
@@ -0,0 +1,102 @@
+# Scheduler Forced Run / Planificateur marche forcée
+
+Le *scheduler forced run / planificateur marche forcée* est conçu pour automatiser l'arrêt du routeur solaire et la marche forcée à une certainne puissance de la charge.
+
+Exemples d'utilisation:
+
+- Permettre une marche forcée de la charge pendant les heures creuses. (Router Level=100%)
+- Désactiver le routeur et éteindre la charge afin de laisser la place à d'autres usages (Router Level=0%)
+
+Ce *scheduler / planificateur* expose des contrôles afin de personnaliser l'automatisation à vos besoins depuis l'interface HomeAssistant.
+
+![HA](images/SchedulerForcedRunInHomeAssistant.png){ align=left }
+!!! note ""
+    **Contrôles**
+    
+    * ***Activer le planificateur***  
+      Contrôle si le planificateur doit être activé ou non.
+      Ceci permet de désactiver la planification suivant vos propres critères (par exemple si votre chauffe-eau à eu déjà assez de puissance en journée, inutile de faire une marche forcée la nuit).
+    * ***Heure de début du planifacteur***   
+      De 0h à 23h. Heure à laquelle la marche forcée commence.
+    * ***Minute de début du planifacteur***  
+      De 0 minute à 55 minutes, avec un pas de 5 minutes.
+      Si l'heure de début est à 1h et les minutes à 15 minutes, alors la planification de marche forcée débute à 1h15.
+    * ***Seuil de vérification de l'arrêt du planificateur***  
+      De 0 minute à 720 minutes, avec un pas de 5 minutes.
+      Cette option permet de définir une marge de sécurité afin de vérifier toutes les 5 minutes entre la fin de la planification + X minutes que le routeur à bien été remis en fonctionnement.
+      Par exemple si l'heure de fin est définit à 2h00 et le seuil de vérification à 60 minutes, toutes les 5 minutes entre 2h et 3h (inclus) le planificateur relance le routeur solaire s'il est arrêté.
+      Ceci permet de s'assurer que la planification prend fin même s'il y a un plantage de l'ESP lors de l'heure de fin.
+    * ***Heure de fin du planifacteur***   
+      De 0h à 23h. Heure à laquelle la marche forcée s'arrête.
+    * ***Minute de fin du planifacteur***  
+      De 0 minute à 55 minutes, avec un pas de 5 minutes.
+      Si l'heure de fin est à 1h et les minutes à 15 minutes, alors la planification de marche forcée termine à 1h15.
+    * ***Niveau du routeur***  
+      De 0% à 100% avec un pas de 1%.
+      Définit le niveau cible où le routeur sera réglé pendant le fonctionnement du planificateur entre l'heure de début et de fin.
+
+
+
+## Configuration basique
+
+Pour utiliser plusieurs ce package, ajoutez les lignes suivantes à votre fichier de configuration :
+
+```yaml linenums="1"
+packages:
+  scheduler_forced_run:
+    url: https://github.com/XavierBerger/Solar-Router-for-ESPHome/
+    files:
+      - path: solar_router/scheduler_forced_run.yaml
+```
+
+## Configuration multiple
+
+Pour utiliser plusieurs instances de ce package, par exemple pour programée une marche forcée en journée et une autre la nuit, ajoutez les lignes suivantes à votre fichier de configuration :
+
+```yaml linenums="1"
+packages:
+  scheduler_forced_run:
+    url: https://github.com/XavierBerger/Solar-Router-for-ESPHome/
+    files:
+      - path: solar_router/scheduler_forced_run.yaml
+        vars:
+          scheduler_unique_id: "NightForced"
+      - path: solar_router/scheduler_forced_run.yaml
+        vars:
+          scheduler_unique_id: "DayForced"
+```
+
+Il est necessaire de définir `scheduler_unique_id` dans la section `vars` comme montré dans l'exemple ci-dessus. Cette variable ne doit pas contenir d'espace ou de caractères spéciaux, et doit être unique pour chaque *scheduler forced run / planificateur marche forcée*. Elle permet d'avoir autant d'instance que nécessaire sans aucun conflits.
+
+
+## Configuration avancée (script)
+
+Ce package fournit la possibilité d'appeler un script personnalisé toutes les 5 minutes lors de l'éxécution de la planification.
+
+Par exemple pour arrêter la planification avant l'heure de fin si un capteur de température atteint une valeur cible, ajoutez les lignes suivantes à votre fichier de configuration :
+
+```yaml linenums="1"
+packages:
+  scheduler_forced_run:
+    url: https://github.com/XavierBerger/Solar-Router-for-ESPHome/
+    files:
+      - path: solar_router/scheduler_forced_run.yaml
+        vars:
+          scheduler_unique_id: "NightForced"
+          custom_script: check_temperature_for_NightForcedScheduler
+          
+script:
+  # ...
+  - id: check_temperature_for_NightForcedScheduler
+    mode: single
+    then:
+        -if:
+            condition:
+                - lambda: return id(myTemperatureSensor).state >= 80;
+            then:
+                # Name of the switch is different for every scheduler, it depend of the scheduler_unique_id (default value: forced) : "${scheduler_unique_id}_scheduler_activate"
+                - switch.turn_off: NightForced_scheduler_activate
+```
+
+Il est necessaire de définir `custom_script` dans la section `vars` comme montré dans l'exemple ci-dessus. Cette variable permet de transmettre le nom du script qui sera appellé toutes les 5 minutes lors de l'éxécution du planificateur.
+
diff --git a/docs/images/SchedulerForcedRunInHomeAssistant.png b/docs/images/SchedulerForcedRunInHomeAssistant.png
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -36,6 +36,9 @@ nav:
       - Overview: temperature_limiter.md
       - Home Assistant: temperature_limiter_home_assistant.md
       - DS18B20: temperature_limiter_DS18B20.md
+  - Scheduler:
+      - Overview: scheduler.md
+      - Forced Run: scheduler_forced_run.md
   - Home Assistant:
       - Recorder configuration: recorder_configuration.md
   - About:
diff --git a/solar_router/scheduler_forced_run.yaml b/solar_router/scheduler_forced_run.yaml
