Documentation rework

README-fr.md

@@ -7,7 +7,7 @@
 [En](README.md)|[Fr](README-fr.md)
 ![Tip](images/icon.png)
 
-> ![Tip](images/tips.png) Cette intégration de thermostat vise à simplifier considérablement vos automatisations autour de la gestion du chauffage. Parce que tous les événements autour du chauffage classiques sont gérés nativement par le thermostat (personne à la maison ?, activité détectée dans une pièce ?, fenêtre ouverte ?, délestage de courant ?), vous n'avez pas à vous encombrer de scripts et d'automatismes compliqués pour gérer vos thermostats. ;-).
+> ![Tip](images/tips.png) Cette intégration de thermostat vise à simplifier considérablement vos automatisations autour de la gestion du chauffage. Parce que tous les événements autour du chauffage classiques sont gérés nativement par le thermostat (personne à la maison ?, activité détectée dans une pièce ?, fenêtre ouverte ?, délestage de puissance ?), vous n'avez pas à vous encombrer de scripts et d'automatismes compliqués pour gérer vos thermostats. ;-).
 
 Ce composant personnalisé pour Home Assistant est une mise à niveau et une réécriture complète du composant "Awesome thermostat" (voir [Github](https://github.com/dadge/awesome_thermostat)) avec l'ajout de fonctionnalités.
 

documentation/en/additions.md

@@ -0,0 +1,211 @@
+# Some Essential Add-Ons
+
+- [Some Essential Add-Ons](#some-essential-add-ons)
+  - [the Versatile Thermostat UI Card](#the-versatile-thermostat-ui-card)
+  - [the Scheduler Component!](#the-scheduler-component)
+  - [Regulation curves with Plotly to Fine-Tune Your Thermostat](#regulation-curves-with-plotly-to-fine-tune-your-thermostat)
+  - [Event notification with the AppDaemon NOTIFIER](#event-notification-with-the-appdaemon-notifier)
+
+## the Versatile Thermostat UI Card
+A dedicated card for the Versatile Thermostat has been developed (based on Better Thermostat). It is available here: [Versatile Thermostat UI Card](https://github.com/jmcollin78/versatile-thermostat-ui-card) and offers a modern view of all the VTherm statuses:
+
+![image](https://github.com/jmcollin78/versatile-thermostat-ui-card/blob/master/assets/1.png?raw=true)
+
+## the Scheduler Component!
+
+To make the most out of the Versatile Thermostat, I recommend using it with the [Scheduler Component](https://github.com/nielsfaber/scheduler-component). The scheduler component provides climate scheduling based on predefined modes. While this feature is somewhat limited with the generic thermostat, it becomes very powerful when paired with the Versatile Thermostat.
+
+Assuming you have installed both the Versatile Thermostat and the Scheduler Component, here’s an example:
+
+In Scheduler, add a schedule:
+
+![image](https://user-images.githubusercontent.com/1717155/119146454-ee1a9d80-ba4a-11eb-80ae-3074c3511830.png)
+
+Choose the "Climate" group, select one (or more) entity, pick "MAKE SCHEME," and click next:
+(You can also choose "SET PRESET," but I prefer "MAKE SCHEME.")
+
+![image](https://user-images.githubusercontent.com/1717155/119147210-aa746380-ba4b-11eb-8def-479a741c0ba7.png)
+
+Define your mode scheme and save:
+
+![image](https://user-images.githubusercontent.com/1717155/119147784-2f5f7d00-ba4c-11eb-9de4-5e62ff5e71a8.png)
+
+In this example, I set ECO mode during the night and when no one is home during the day, BOOST in the morning, and COMFORT in the evening.
+
+I hope this example helps; feel free to share your feedback!
+
+## Regulation curves with Plotly to Fine-Tune Your Thermostat
+You can obtain a curve similar to the one shown in [some results](#some-results) using a Plotly graph configuration by leveraging the thermostat's custom attributes described [here](#custom-attributes):
+
+Replace the values between `[[ ]]` with your own.
+<details>
+
+```yaml
+- type: custom:plotly-graph
+  entities:
+    - entity: '[[climate]]'
+      attribute: temperature
+      yaxis: y1
+      name: Consigne
+    - entity: '[[climate]]'
+      attribute: current_temperature
+      yaxis: y1
+      name: T°
+    - entity: '[[climate]]'
+      attribute: ema_temp
+      yaxis: y1
+      name: Ema
+    - entity: '[[climate]]'
+      attribute: on_percent
+      yaxis: y2
+      name: Power percent
+      fill: tozeroy
+      fillcolor: rgba(200, 10, 10, 0.3)
+      line:
+        color: rgba(200, 10, 10, 0.9)
+    - entity: '[[slope]]'
+      name: Slope
+      fill: tozeroy
+      yaxis: y9
+      fillcolor: rgba(100, 100, 100, 0.3)
+      line:
+        color: rgba(100, 100, 100, 0.9)
+  hours_to_show: 4
+  refresh_interval: 10
+  height: 800
+  config:
+    scrollZoom: true
+  layout:
+    margin:
+      r: 50
+    legend:
+      x: 0
+      'y': 1.2
+      groupclick: togglegroup
+      title:
+        side: top right
+    yaxis:
+      visible: true
+      position: 0
+    yaxis2:
+      visible: true
+      position: 0
+      fixedrange: true
+      range:
+        - 0
+        - 1
+    yaxis9:
+      visible: true
+      fixedrange: false
+      range:
+        - -2
+        - 2
+      position: 1
+    xaxis:
+      rangeselector:
+        'y': 1.1
+        x: 0.7
+        buttons:
+          - count: 1
+            step: hour
+          - count: 12
+            step: hour
+          - count: 1
+            step: day
+          - count: 7
+            step: day
+```
+</details>
+
+Example of curves obtained with Plotly:
+
+![image](images/plotly-curves.png)
+
+## Event notification with the AppDaemon NOTIFIER
+This automation leverages the excellent AppDaemon app named NOTIFIER, developed by Horizon Domotique, demonstrated [here](https://www.youtube.com/watch?v=chJylIK0ASo&ab_channel=HorizonDomotique), and the code is available [here](https://github.com/jlpouffier/home-assistant-config/blob/master/appdaemon/apps/notifier.py). It allows users to be notified of security-related events occurring on any Versatile Thermostat.
+
+This is a great example of using the notifications described here: [notification](#notifications).
+<details>
+
+```yaml
+alias: Surveillance Mode Sécurité chauffage
+description: Envoi une notification si un thermostat passe en mode sécurité ou power
+trigger:
+  - platform: event
+    event_type: versatile_thermostat_security_event
+    id: versatile_thermostat_security_event
+  - platform: event
+    event_type: versatile_thermostat_power_event
+    id: versatile_thermostat_power_event
+  - platform: event
+    event_type: versatile_thermostat_temperature_event
+    id: versatile_thermostat_temperature_event
+condition: []
+action:
+  - choose:
+      - conditions:
+          - condition: trigger
+            id: versatile_thermostat_security_event
+        sequence:
+          - event: NOTIFIER
+            event_data:
+              action: send_to_jmc
+              title: >-
+                Radiateur {{ trigger.event.data.name }} - {{
+                trigger.event.data.type }} Sécurité
+              message: >-
+                Le radiateur {{ trigger.event.data.name }} est passé en {{
+                trigger.event.data.type }} sécurité car le thermomètre ne répond
+                plus.\n{{ trigger.event.data }}
+              callback:
+                - title: Stopper chauffage
+                  event: stopper_chauffage
+              image_url: /media/local/alerte-securite.jpg
+              click_url: /lovelace-chauffage/4
+              icon: mdi:radiator-off
+              tag: radiateur_security_alerte
+              persistent: true
+      - conditions:
+          - condition: trigger
+            id: versatile_thermostat_power_event
+        sequence:
+          - event: NOTIFIER
+            event_data:
+              action: send_to_jmc
+              title: >-
+                Radiateur {{ trigger.event.data.name }} - {{
+                trigger.event.data.type }} Délestage
+              message: >-
+                Le radiateur {{ trigger.event.data.name }} est passé en {{
+                trigger.event.data.type }} délestage car la puissance max est
+                dépassée.\n{{ trigger.event.data }}
+              callback:
+                - title: Stopper chauffage
+                  event: stopper_chauffage
+              image_url: /media/local/alerte-delestage.jpg
+              click_url: /lovelace-chauffage/4
+              icon: mdi:radiator-off
+              tag: radiateur_power_alerte
+              persistent: true
+      - conditions:
+          - condition: trigger
+            id: versatile_thermostat_temperature_event
+        sequence:
+          - event: NOTIFIER
+            event_data:
+              action: send_to_jmc
+              title: >-
+                Le thermomètre du radiateur {{ trigger.event.data.name }} ne
+                répond plus
+              message: >-
+                Le thermomètre du radiateur {{ trigger.event.data.name }} ne
+                répond plus depuis longtemps.\n{{ trigger.event.data }}
+              image_url: /media/local/thermometre-alerte.jpg
+              click_url: /lovelace-chauffage/4
+              icon: mdi:radiator-disabled
+              tag: radiateur_thermometre_alerte
+              persistent: true
+mode: queued
+max: 30
+```
+</details>

documentation/en/algorithms.md

@@ -0,0 +1,67 @@
+# The Different Algorithms Used
+
+- [The Different Algorithms Used](#the-different-algorithms-used)
+  - [The TPI Algorithm](#the-tpi-algorithm)
+    - [Configuring the TPI Algorithm Coefficients](#configuring-the-tpi-algorithm-coefficients)
+    - [Principle](#principle)
+  - [The Self-Regulation Algorithm (Without Valve Control)](#the-self-regulation-algorithm-without-valve-control)
+  - [The Auto-Start/Stop Function Algorithm](#the-auto-startstop-function-algorithm)
+
+## The TPI Algorithm
+
+### Configuring the TPI Algorithm Coefficients
+
+If you have selected a thermostat of type `over_switch`, `over_valve`, or `over_climate` with self-regulation in `Direct Valve Control` mode and choose the "TPI" option in the menu, you will land on this page:
+
+![image](images/config-tpi.png)
+
+You need to provide:
+1. the coefficient `coef_int` for the TPI algorithm,
+2. the coefficient `coef_ext` for the TPI algorithm.
+
+### Principle
+
+The TPI algorithm calculates the On vs Off percentage for the radiator at each cycle, using the target temperature, the current room temperature, and the current outdoor temperature. This algorithm is only applicable for Versatile Thermostats operating in `over_switch` and `over_valve` modes.
+
+The percentage is calculated using this formula:
+
+    on_percent = coef_int * (target_temperature - current_temperature) + coef_ext * (target_temperature - outdoor_temperature)
+    Then, the algorithm ensures that 0 <= on_percent <= 1.
+
+The default values for `coef_int` and `coef_ext` are `0.6` and `0.01`, respectively. These default values are suitable for a standard well-insulated room.
+
+When adjusting these coefficients, keep the following in mind:
+1. **If the target temperature is not reached** after stabilization, increase `coef_ext` (the `on_percent` is too low),
+2. **If the target temperature is exceeded** after stabilization, decrease `coef_ext` (the `on_percent` is too high),
+3. **If reaching the target temperature is too slow**, increase `coef_int` to provide more power to the heater,
+4. **If reaching the target temperature is too fast and oscillations occur** around the target, decrease `coef_int` to provide less power to the radiator.
+
+In `over_valve` mode, the `on_percent` value is converted to a percentage (0 to 100%) and directly controls the valve's opening level.
+
+## The Self-Regulation Algorithm (Without Valve Control)
+
+The self-regulation algorithm can be summarized as follows:
+
+1. Initialize the target temperature as the VTherm setpoint,
+2. If self-regulation is enabled:
+   1. Calculate the regulated temperature (valid for a VTherm),
+   2. Use this temperature as the target,
+3. For each underlying device of the VTherm:
+     1. If "Use Internal Temperature" is checked:
+          1. Calculate the compensation (`trv_internal_temp - room_temp`),
+     2. Add the offset to the target temperature,
+     3. Send the target temperature (= regulated_temp + (internal_temp - room_temp)) to the underlying device.
+
+## The Auto-Start/Stop Function Algorithm
+
+The algorithm used in the auto-start/stop function operates as follows:
+1. If "Enable Auto-Start/Stop" is off, stop here.
+2. If VTherm is on and in Heating mode, when `error_accumulated` < `-error_threshold` -> turn off and save HVAC mode.
+3. If VTherm is on and in Cooling mode, when `error_accumulated` > `error_threshold` -> turn off and save HVAC mode.
+4. If VTherm is off and the saved HVAC mode is Heating, and `current_temperature + slope * dt <= target_temperature`, turn on and set the HVAC mode to the saved mode.
+5. If VTherm is off and the saved HVAC mode is Cooling, and `current_temperature + slope * dt >= target_temperature`, turn on and set the HVAC mode to the saved mode.
+6. `error_threshold` is set to `10 (° * min)` for slow detection, `5` for medium, and `2` for fast.
+
+`dt` is set to `30 min` for slow, `15 min` for medium, and `7 min` for fast detection levels.
+
+The function is detailed [here](https://github.com/jmcollin78/versatile_thermostat/issues/585).

documentation/en/base-attributes.md

@@ -0,0 +1,45 @@
+- [Choosing Basic Attributes](#choosing-basic-attributes)
+- [Choosing the features to Use](#choosing-the-features-to-use)
+
+# Choosing Basic Attributes
+
+Select the "Main Attributes" menu.
+
+![image](images/config-main.png)
+
+Provide the mandatory main attributes. These attributes are common to all VTherms:
+1. A name (this will be both the integration's name and the `climate` entity name),
+2. An entity ID of a temperature sensor that provides the room temperature where the radiator is installed,
+3. An optional sensor entity providing the last seen date and time of the sensor (`last_seen`). If available, specify it here. It helps prevent safety shutdowns when the temperature is stable, and the sensor stops reporting for a long time (see [here](troubleshooting.md#why-does-my-versatile-thermostat-go-into-safety-mode)),
+4. A cycle duration in minutes. At each cycle:
+   1. For `over_switch`: VTherm will turn the radiator on/off, modulating the proportion of time it is on,
+   2. For `over_valve`: VTherm will calculate a new valve opening level and send it if it has changed,
+   3. For `over_climate`: The cycle performs basic controls and recalculates the self-regulation coefficients. The cycle may result in a new setpoint sent to underlying devices or a valve opening adjustment in the case of a controllable TRV.
+5. The equipment's power, which will activate power and energy consumption sensors for the device. If multiple devices are linked to the same VTherm, specify the total maximum power of all devices here,
+6. The option to use additional parameters from centralized configuration:
+   1. Outdoor temperature sensor,
+   2. Minimum/maximum temperature and temperature step size,
+7. The option to control the thermostat centrally. See [centralized control](#centralized-control),
+8. A checkbox if this VTherm is used to trigger a central boiler.
+
+> ![Tip](images/tips.png) _*Notes*_
+>  1. With the `over_switch` and `over_valve` types, calculations are performed at each cycle. In case of changing conditions, you will need to wait for the next cycle to see a change. For this reason, the cycle should not be too long. **5 minutes is a good value**, but it should be adjusted to your heating type. The greater the inertia, the longer the cycle should be. See [Tuning examples](tuning-examples.md).
+>  2. If the cycle is too short, the radiator may never reach the target temperature. For example, with a storage heater, it will be unnecessarily activated.
+
+# Choosing the features to Use
+
+Select the "Features" menu.
+
+![image](images/config-features.png)
+
+Choose the features you want to use for this VTherm:
+1. **Opening detection** (doors, windows) stops heating when an opening is detected. (see [managing openings](feature-window.md)),
+2. **Motion detection**: VTherm can adjust the target temperature when motion is detected in the room. (see [motion detection](feature-motion.md)),
+3. **Power management**: VTherm can stop a device if the power consumption in your home exceeds a threshold. (see [load-shedding management](feature-power.md)),
+4. **Presence detection**: If you have a sensor indicating presence or absence in your home, you can use it to change the target temperature. See [presence management](feature-presence.md). Note the difference between this function and motion detection: presence is typically used at the home level, while motion detection is more room-specific.
+5. **Automatic start/stop**: For `over_climate` VTherms only. This function stops a device when VTherm detects it will not be needed for a while. It uses the temperature curve to predict when the device will be needed again and turns it back on at that time. See [automatic start/stop management](feature-auto-start-stop.md).
+
+> ![Tip](images/tips.png) _*Notes*_
+> 1. The list of available functions adapts to your VTherm type.
+> 2. When you enable a function, a new menu entry is added to configure it.
+> 3. You cannot validate the creation of a VTherm if all parameters for all enabled functions have not been configured.

documentation/en/creation.md

@@ -0,0 +1,71 @@
+# Choosing a VTherm
+
+- [Choosing a VTherm](#choosing-a-vtherm)
+  - [Creating a New Versatile Thermostat](#creating-a-new-versatile-thermostat)
+- [Choosing a VTherm Type](#choosing-a-vtherm-type)
+  - [Centralized configuration](#centralized-configuration)
+  - [VTherm over a switch](#vtherm-over-a-switch)
+  - [VTherm over another thermostat](#vtherm-over-another-thermostat)
+  - [VTherm over a valve](#vtherm-over-a-valve)
+- [Making the right choice](#making-the-right-choice)
+- [Reference Article](#reference-article)
+
+> ![Tip](images/tips.png) _*Notes*_
+>
+> There are three ways to work with VTherms:
+> 1. Each Versatile Thermostat is fully configured independently. Choose this option if you do not want any centralized configuration or management.
+> 2. Some aspects are configured centrally. For example, you can define the minimum/maximum temperatures, open window detection parameters, etc., at a single central instance. For each VTherm you configure, you can then choose to use the central configuration or override it with custom parameters.
+> 3. In addition to centralized configuration, all VTherms can be controlled by a single `select` entity called `central_mode`. This feature allows you to stop/start/set frost protection/etc. for all VTherms at once. For each VTherm, you can specify if it is affected by this `central_mode`.
+
+## Creating a New Versatile Thermostat
+
+Click on "Add Integration" on the integration page (or click 'Add device' in the integration page)
+
+![image](images/add-an-integration.png)
+
+then:
+
+![image](images/config-main0.png)
+
+The configuration can be modified via the same interface. Simply select the thermostat to modify, press "Configure," and you will be able to change some parameters or settings.
+
+Follow the configuration steps by selecting the menu option to configure.
+
+# Choosing a VTherm Type
+
+## Centralized configuration
+This option allows you to configure certain repetitive aspects for all VTherms at once, such as:
+1. Parameters for different algorithms (TPI, open window detection, motion detection, power sensors for your home, presence detection). These parameters apply across all VTherms. You only need to enter them once in `Centralized Configuration`. This configuration does not create a VTherm itself but centralizes parameters that would be tedious to re-enter for each VTherm. Note that you can override these parameters on individual VTherms to specialize them if needed.
+2. Configuration for controlling a central heating system,
+3. Certain advanced parameters, such as safety settings.
+
+## VTherm over a switch
+This VTherm type controls a switch that turns a radiator on or off. The switch can be a physical switch directly controlling a radiator (often electric) or a virtual switch that can perform any action when turned on or off. The latter type can, for example, control pilot wire switches or DIY pilot wire solutions with diodes. VTherm modulates the proportion of time the radiator is on (`on_percent`) to achieve the desired temperature. If it is cold, it turns on more frequently (up to 100%); if it is warm, it reduces the on time.
+
+The underlying entities for this type are `switches` or `input_booleans`.
+
+## VTherm over another thermostat
+When your device is controlled by a `climate` entity in Home Assistant and you only have access to this, you should use this VTherm type. In this case, VTherm simply adjusts the target temperature of the underlying `climate` entity.
+
+This type also includes advanced self-regulation features to adjust the setpoint sent to the underlying device, helping to achieve the target temperature faster and mitigating poor internal regulation. For example, if the device's internal thermometer is too close to the heating element, it may incorrectly assume the room is warm while the setpoint is far from being achieved in other areas.
+
+Since version 6.8, this VTherm type can also regulate directly by controlling the valve. Ideal for controllable TRVs, this type is recommended if you have such devices.
+
+The underlying entities for this VTherm type are exclusively `climate`.
+
+## VTherm over a valve
+If the only entity available to regulate your radiator's temperature is a `number` entity, you should use the `over_valve` type. VTherm adjusts the valve opening based on the difference between the target temperature and the actual room temperature (and the outdoor temperature, if available).
+
+This type can be used for TRVs without an associated `climate` entity or other DIY solutions exposing a `number` entity.
+
+# Making the right choice
+> ![Tip](images/tips.png) _*How to Choose the Type*_
+> Choosing the correct type is crucial. It cannot be changed later via the configuration interface. To make the right choice, consider the following questions:
+> 1. **What type of equipment will I control?** Follow this order of preference:
+>    1. If you have a controllable thermostatic valve (TRV) in Home Assistant through a `number` entity (e.g., a Shelly TRV), choose the `over_valve` type. This is the most direct type and ensures the best regulation.
+>    2. If you have an electric radiator (with or without a pilot wire) controlled by a `switch` entity to turn it on/off, then the `over_switch` type is preferable. Regulation will be managed by the Versatile Thermostat based on the temperature measured by your thermometer at its placement location.
+>    3. In all other cases, use the `over_climate` mode. You retain your original `climate` entity, and the Versatile Thermostat "only" controls the on/off state and target temperature of your original thermostat. Regulation is handled by your original thermostat in this case. This mode is particularly suited for all-in-one reversible air conditioning systems exposed as a `climate` entity in Home Assistant. Advanced self-regulation can achieve the setpoint faster by forcing the setpoint or directly controlling the valve when possible.
+> 2. **What type of regulation do I want?** If the controlled equipment has its own built-in regulation mechanism (e.g., HVAC systems, certain TRVs) and it works well, choose `over_climate`. For TRVs with a controllable valve in Home Assistant, the `over_climate` type with `Direct Valve Control` self-regulation is the best choice.
+
+# Reference Article
+For more information on these concepts, refer to this article (in French): https://www.hacf.fr/optimisation-versatile-thermostat/#optimiser-vos-vtherm

documentation/en/feature-advanced.md

@@ -0,0 +1,53 @@
+# Advanced Configuration
+
+- [Advanced Configuration](#advanced-configuration)
+  - [Advanced Settings](#advanced-settings)
+    - [Minimum Activation Delay](#minimum-activation-delay)
+    - [Safety Mode](#safety-mode)
+
+These settings refine the thermostat's operation, particularly the safety mechanism for a _VTherm_. Missing temperature sensors (room or outdoor) can pose a risk to your home. For instance, if the temperature sensor gets stuck at 10°C, the `over_climate` or `over_valve` _VTherm_ types will command maximum heating of the underlying devices, which could lead to room overheating or even property damage, at worst resulting in a fire hazard.
+
+To prevent this, _VTherm_ ensures that thermometers report values regularly. If they don't, the _VTherm_ switches to a special mode called Safety Mode. This mode ensures minimal heating to prevent the opposite risk: a completely unheated home in the middle of winter, for example.
+
+The challenge lies in that some thermometers—especially battery-operated ones—only send temperature updates when the value changes. It is entirely possible to receive no temperature updates for hours without the thermometer failing. The parameters below allow fine-tuning of the thresholds for activating Safety Mode.
+
+If your thermometer has a `last seen` attribute indicating the last contact time, you can specify it in the _VTherm_'s main attributes to greatly reduce false Safety Mode activations. See [configuration](base-attributes.md#choosing-base-attributes) and [troubleshooting](troubleshooting.md#why-does-my-versatile-thermostat-switch-to-safety-mode).
+
+For `over_climate` _VTherms_, which self-regulate, Safety Mode is disabled. In this case, there is no danger, only the risk of an incorrect temperature.
+
+## Advanced Settings
+
+The advanced configuration form looks like this:
+
+![image](images/config-advanced.png)
+
+### Minimum Activation Delay
+
+The first delay (`minimal_activation_delay_sec`) in seconds is the minimum acceptable delay to turn on the heating. If the calculated activation time is shorter than this value, the heating remains off. This parameter only applies to _VTherm_ with cyclic triggering `over_switch`. If the activation time is too short, rapid switching will not allow the device to heat up properly.
+
+### Safety Mode
+
+The second delay (`security_delay_min`) is the maximum time between two temperature measurements before the _VTherm_ switches to Safety Mode.
+
+The third parameter (`security_min_on_percent`) is the minimum `on_percent` below which Safety Mode will not be activated. This setting prevents activating Safety Mode if the controlled radiator does not heat sufficiently. In this case, there is no physical risk to the home, only the risk of overheating or underheating.
+Setting this parameter to `0.00` will trigger Safety Mode regardless of the last heating setting, whereas `1.00` will never trigger Safety Mode (effectively disabling the feature). This can be useful to adapt the safety mechanism to your specific needs.
+
+The fourth parameter (`security_default_on_percent`) defines the `on_percent` used when the thermostat switches to `security` mode. Setting it to `0` will turn off the thermostat in Safety Mode, while setting it to a value like `0.2` (20%) ensures some heating remains, avoiding a completely frozen home in case of a thermometer failure.
+
+It is possible to disable Safety Mode triggered by missing data from the outdoor thermometer. Since the outdoor thermometer usually has a minor impact on regulation (depending on your configuration), it might not be critical if it's unavailable. To do this, add the following lines to your `configuration.yaml`:
+
+```yaml
+versatile_thermostat:
+...
+    safety_mode:
+        check_outdoor_sensor: false
+```
+
+By default, the outdoor thermometer can trigger Safety Mode if it stops sending data. Remember that Home Assistant must be restarted for these changes to take effect. This setting applies to all _VTherms_ sharing the outdoor thermometer.
+
+> ![Tip](images/tips.png) _*Notes*_
+> 1. When the temperature sensor resumes reporting, the preset will be restored to its previous value.
+> 2. Two temperature sources are required: the indoor and outdoor temperatures. Both must report values, or the thermostat will switch to "security" preset.
+> 3. An action is available to adjust the three safety parameters. This can help adapt Safety Mode to your needs.
+> 4. For normal use, `security_default_on_percent` should be lower than `security_min_on_percent`.
+> 5. If you use the Versatile Thermostat UI card (see [here](additions.md#better-with-the-versatile-thermostat-ui-card)), a _VTherm_ in Safety Mode is indicated by a gray overlay showing the faulty thermometer and the time since its last value update: ![safety mode](images/safety-mode-icon.png).

documentation/en/feature-auto-start-stop.md

@@ -0,0 +1,39 @@
+# Auto-start / Auto-stop
+
+- [Auto-start / Auto-stop](#auto-start--auto-stop)
+  - [Configure Auto-start/stop](#configure-auto-startstop)
+  - [Usage](#usage)
+
+This feature allows _VTherm_ to stop an appliance that doesn't need to be on and restart it when conditions require it. This function includes three settings that control how quickly the appliance is stopped and restarted.
+Exclusively reserved for _VTherm_ of type `over_climate`, it applies to the following use case:
+1. Your appliance is permanently powered on and consumes electricity even when heating (or cooling) is not needed. This is often the case with heat pumps (_PAC_) that consume power even in standby mode.
+2. The temperature conditions are such that heating (or cooling) is not needed for a long period: the setpoint is higher (or lower) than the room temperature.
+3. The temperature rises (or falls), remains stable, or falls (or rises) slowly.
+
+In such cases, it is preferable to ask the appliance to turn off to avoid unnecessary power consumption in standby mode.
+
+## Configure Auto-start/stop
+
+To use this feature, you need to:
+1. Add the `With auto-start and stop` function in the 'Functions' menu.
+2. Set the detection level in the 'Auto-start/stop' option that appears when the function is activated. Choose the detection level between 'Slow', 'Medium', and 'Fast'. With the 'Fast' setting, stops and restarts will occur more frequently.
+
+![image](images/config-auto-start-stop.png)
+
+The 'Slow' setting allows about 30 minutes between a stop and a restart,
+The 'Medium' setting sets the threshold to about 15 minutes, and the 'Fast' setting puts it at 7 minutes.
+
+Note that these are not absolute settings since the algorithm takes into account the slope of the room temperature curve to respond accordingly. It is still possible that a restart occurs shortly after a stop if the temperature drops significantly.
+
+## Usage
+
+Once the function is configured, you will now have a new `switch` type entity that allows you to enable or disable auto-start/stop without modifying the configuration. This entity is available on the _VTherm_ device and is named `switch.<name>_enable_auto_start_stop`.
+
+![image](images/enable-auto-start-stop-entity.png)
+
+Check the box to allow auto-start and auto-stop, and leave it unchecked to disable the feature.
+
+> ![Tip](images/tips.png) _*Notes*_
+> 1. The detection algorithm is described [here](algorithms.md#auto-startstop-algorithm).
+> 2. Some appliances (boilers, underfloor heating, _PAC_, etc.) may not like being started/stopped too frequently. If that's the case, it might be better to disable the function when you know the appliance will be used. For example, I disable this feature during the day when presence is detected because I know my _PAC_ will turn on often. I enable auto-start/stop at night or when no one is home, as the setpoint is lowered and it rarely triggers.
+> 3. If you use the Versatile Thermostat UI card (see [here](additions.md#better-with-the-versatile-thermostat-ui-card)), a checkbox is directly visible on the card to disable auto-start/stop, and a _VTherm_ stopped by auto-start/stop is indicated by the icon: ![auto-start/stop icon](images/auto-start-stop-icon.png).

documentation/en/feature-central-boiler.md

@@ -0,0 +1,123 @@
+# Le contrôle d'une chaudière centrale# Controlling a Central Boiler
+
+- [Le contrôle d'une chaudière centrale# Controlling a Central Boiler](#le-contrôle-dune-chaudière-centrale-controlling-a-central-boiler)
+  - [Principle](#principle)
+  - [Configuration](#configuration)
+    - [How to Find the Right Action?](#how-to-find-the-right-action)
+  - [Events](#events)
+  - [Warning](#warning)
+
+You can control a centralized boiler. As long as it's possible to trigger or stop the boiler from Home Assistant, Versatile Thermostat will be able to control it directly.
+
+## Principle
+The basic principle is as follows:
+1. A new entity of type `binary_sensor`, named by default `binary_sensor.central_boiler`, is added.
+2. In the configuration of the _VTherms_, you specify whether the _VTherm_ should control the boiler. In a heterogeneous installation, some _VTherms_ should control the boiler, and others should not. Therefore, you need to indicate in each _VTherm_ configuration whether it controls the boiler.
+3. The `binary_sensor.central_boiler` listens for state changes in the equipment of the _VTherms_ marked as controlling the boiler.
+4. When the number of devices controlled by the _VTherm_ requesting heating (i.e., when its `hvac_action` changes to `Heating`) exceeds a configurable threshold, the `binary_sensor.central_boiler` turns `on`, and **if an activation service has been configured, that service is called**.
+5. If the number of devices requesting heating drops below the threshold, the `binary_sensor.central_boiler` turns `off`, and **if a deactivation service has been configured, that service is called**.
+6. You have access to two entities:
+   - A `number` type entity, named by default `number.boiler_activation_threshold`, which gives the activation threshold. This threshold is the number of devices (radiators) requesting heating.
+   - A `sensor` type entity, named by default `sensor.nb_device_active_for_boiler`, which shows the number of devices requesting heating. For example, a _VTherm_ with 4 valves, 3 of which request heating, will make this sensor show 3. Only the devices from _VTherms_ marked to control the central boiler are counted.
+
+You therefore always have the information to manage and adjust the triggering of the boiler.
+
+All these entities are linked to the central configuration service:
+
+![Boiler Control Entities](images/entitites-central-boiler.png)
+
+## Configuration
+To configure this feature, you need a centralized configuration (see [Configuration](#configuration)) and check the 'Add Central Boiler' box:
+
+![Add a Central Boiler](images/config-central-boiler-1.png)
+
+On the next page, you can provide the configuration for the actions (e.g., services) to be called when the boiler is turned on/off:
+
+![Add a Central Boiler](images/config-central-boiler-2.png)
+
+The actions (e.g., services) are configured as described on the page:
+1. The general format is `entity_id/service_id[/attribute:value]` (where `/attribute:value` is optional).
+2. `entity_id` is the name of the entity controlling the boiler in the form `domain.entity_name`. For example: `switch.chaudiere` for a boiler controlled by a switch, or `climate.chaudière` for a boiler controlled by a thermostat, or any other entity that allows boiler control (there is no limitation). You can also toggle inputs (`helpers`) such as `input_boolean` or `input_number`.
+3. `service_id` is the name of the service to be called in the form `domain.service_name`. For example: `switch.turn_on`, `switch.turn_off`, `climate.set_temperature`, `climate.set_hvac_mode` are valid examples.
+4. Some services require a parameter. This could be the 'HVAC Mode' for `climate.set_hvac_mode` or the target temperature for `climate.set_temperature`. This parameter should be configured in the format `attribute:value` at the end of the string.
+
+Examples (to adjust to your case):
+- `climate.chaudiere/climate.set_hvac_mode/hvac_mode:heat`: to turn the boiler thermostat on in heating mode.
+- `climate.chaudiere/climate.set_hvac_mode/hvac_mode:off`: to turn off the boiler thermostat.
+- `switch.pompe_chaudiere/switch.turn_on`: to turn on the switch powering the boiler pump.
+- `switch.pompe_chaudiere/switch.turn_off`: to turn off the switch powering the boiler pump.
+- ...
+
+### How to Find the Right Action?
+To find the correct action to use, it's best to go to "Developer Tools / Services", search for the action to call, the entity to control, and any required parameters.
+Click 'Call Service'. If your boiler turns on, you have the correct configuration. Then switch to YAML mode and copy the parameters.
+
+Example:
+
+In "Developer Tools / Actions":
+
+![Service Configuration](images/dev-tools-turnon-boiler-1.png)
+
+In YAML mode:
+
+![Service Configuration](images/dev-tools-turnon-boiler-2.png)
+
+The service to configure will then be: `climate.sonoff/climate.set_hvac_mode/hvac_mode:heat` (note the removal of spaces in `hvac_mode:heat`).
+
+Do the same for the off service, and you’re ready to go.
+
+## Events
+
+Each successful boiler activation or deactivation sends an event from Versatile Thermostat. This can be captured by an automation, for example, to notify you of the change.
+The events look like this:
+
+An activation event:
+```yaml
+event_type: versatile_thermostat_central_boiler_event
+data:
+  central_boiler: true
+  entity_id: binary_sensor.central_boiler
+  name: Central boiler
+  state_attributes: null
+origin: LOCAL
+time_fired: "2024-01-14T11:33:52.342026+00:00"
+context:
+  id: 01HM3VZRJP3WYYWPNSDAFARW1T
+  parent_id: null
+  user_id: null
+```yaml
+event_type: versatile_thermostat_central_boiler_event
+data:
+  central_boiler: true
+  entity_id: binary_sensor.central_boiler
+  name: Central boiler
+  state_attributes: null
+origin: LOCAL
+time_fired: "2024-01-14T11:33:52.342026+00:00"
+context:
+  id: 01HM3VZRJP3WYYWPNSDAFARW1T
+  parent_id: null
+  user_id: null
+```
+
+Un évènement d'extinction :
+```yaml
+event_type: versatile_thermostat_central_boiler_event
+data:
+  central_boiler: false
+  entity_id: binary_sensor.central_boiler
+  name: Central boiler
+  state_attributes: null
+origin: LOCAL
+time_fired: "2024-01-14T11:43:52.342026+00:00"
+context:
+  id: 01HM3VZRJP3WYYWPNSDAFBRW1T
+  parent_id: null
+  user_id: null
+```
+
+## Warning
+
+> ![Astuce](images/tips.png) _*Notes*_
+>
+> Software or home automation control of a central boiler may pose risks to its proper operation. Before using these functions, ensure that your boiler has proper safety features and that they are functioning correctly. For example, turning on a boiler with all valves closed can create excessive pressure.

documentation/en/feature-central-mode.md

@@ -0,0 +1,31 @@
+# Centralized Control
+
+- [Centralized Control](#centralized-control)
+  - [Configuration of Centralized Control](#configuration-of-centralized-control)
+  - [Usage](#usage)
+
+This feature allows you to control all your _VTherms_ from a single control point.
+A typical use case is when you leave for an extended period and want to set all your _VTherms_ to frost protection, and when you return, you want to set them back to their initial state.
+
+Centralized control is done from a special _VTherm_ called centralized configuration. See [here](creation.md#centralized-configuration) for more information.
+
+## Configuration of Centralized Control
+
+If you have set up a centralized configuration, you will have a new entity named `select.central_mode` that allows you to control all _VTherms_ with a single action.
+
+![central_mode](images/central-mode.png)
+
+This entity appears as a list of choices containing the following options:
+1. `Auto`: the 'normal' mode where each _VTherm_ operates autonomously,
+2. `Stopped`: all _VTherms_ are turned off (`hvac_off`),
+3. `Heat only`: all _VTherms_ are set to heating mode if supported, otherwise they are stopped,
+4. `Cool only`: all _VTherms_ are set to cooling mode if supported, otherwise they are stopped,
+5. `Frost protection`: all _VTherms_ are set to frost protection mode if supported, otherwise they are stopped.
+
+## Usage
+
+For a _VTherm_ to be controllable centrally, its configuration attribute named `use_central_mode` must be true. This attribute is available in the configuration page `Main Attributes`.
+
+![central_mode](images/use-central-mode.png)
+
+This means you can control all _VTherms_ (those explicitly designated) with a single control.

documentation/en/feature-motion.md

@@ -0,0 +1,40 @@
+# Motion or Activity Detection
+
+- [Motion or Activity Detection](#motion-or-activity-detection)
+  - [Configure Activity Mode or Motion Detection](#configure-activity-mode-or-motion-detection)
+  - [Usage](#usage)
+
+This feature allows you to change presets when motion is detected in a room. If you don't want to heat your office when the room is occupied and only when the room is occupied, you need a motion (or presence) sensor in the room and configure this feature.
+
+This function is often confused with the presence feature. They are complementary but not interchangeable. The 'motion' function is local to a room equipped with a motion sensor, while the 'presence' function is designed to be global to the entire home.
+
+## Configure Activity Mode or Motion Detection
+
+If you have chosen the `With motion detection` feature:
+
+![image](images/config-motion.png)
+
+What we need:
+- a **motion sensor**. Entity ID of a motion sensor. The states of the motion sensor must be "on" (motion detected) or "off" (no motion detected),
+- a **detection delay** (in seconds) defining how long we wait for confirmation of the motion before considering the motion. This parameter can be **greater than your motion sensor's delay**, otherwise, the detection will happen with every motion detected by the sensor,
+- an **inactivity delay** (in seconds) defining how long we wait for confirmation of no motion before no longer considering the motion,
+- a **"motion" preset**. We will use the temperature of this preset when activity is detected,
+- a **"no motion" preset**. We will use the temperature of this second preset when no activity is detected.
+
+## Usage
+
+To tell a _VTherm_ that it should listen to the motion sensor, you must set it to the special 'Activity' preset. If you have installed the Versatile Thermostat UI card (see [here](additions.md#much-better-with-the-versatile-thermostat-ui-card)), this preset is displayed as follows: ![activity preset](images/activity-preset-icon.png).
+
+You can then, upon request, set a _VTherm_ to motion detection mode.
+
+The behavior will be as follows:
+- we have a room with a thermostat set to activity mode, the "motion" mode chosen is comfort (21.5°C), the "no motion" mode chosen is Eco (18.5°C), and the motion delay is 30 seconds on detection and 5 minutes on the end of detection.
+- the room has been empty for a while (no activity detected), the setpoint temperature in this room is 18.5°.
+- someone enters the room, and activity is detected if the motion is present for at least 30 seconds. The temperature then goes up to 21.5°.
+- if the motion is present for less than 30 seconds (quick passage), the temperature stays at 18.5°.
+- imagine the temperature has gone up to 21.5°, when the person leaves the room, after 5 minutes the temperature is returned to 18.5°.
+- if the person returns before the 5 minutes, the temperature stays at 21.5°.
+
+> ![Tip](images/tips.png) _*Notes*_
+> 1. As with other presets, `Activity` will only be offered if it is correctly configured. In other words, all 4 configuration keys must be set.
+> 2. If you are using the Versatile Thermostat UI card (see [here](additions.md#much-better-with-the-versatile-thermostat-ui-card)), motion detection is represented as follows: ![motion](images/motion-detection-icon.png).

documentation/en/feature-power.md

@@ -0,0 +1,46 @@
+# Power Management - Load Shedding
+
+- [Power Management - Load Shedding](#power-management---load-shedding)
+  - [Configure Power Management](#configure-power-management)
+
+This feature allows you to regulate the electricity consumption of your heaters. Known as load shedding, this feature enables you to limit the electrical consumption of your heating device if overcapacity conditions are detected.
+You will need a **sensor for the total instantaneous power consumption** of your home, as well as a **sensor for the maximum allowed power**.
+
+The behavior of this feature is basic:
+1. when the _VTherm_ is about to turn on a device,
+2. it compares the last known value of the power consumption sensor with the last value of the maximum allowed power. If there is a remaining margin greater than or equal to the declared power of the _VTherm_'s devices, then the _VTherm_ and its devices will be turned on. Otherwise, they will remain off until the next cycle.
+
+WARNING: This very basic operation **is not a safety function** but more of an optimization feature to manage consumption at the cost of heating performance. Overloads may occur depending on the frequency of updates from your consumption sensors, and the actual power used by your devices. Therefore, you must always maintain a safety margin.
+
+Typical use case:
+1. you have an electricity meter limited to 11 kW,
+2. you occasionally charge an electric vehicle at 5 kW,
+3. that leaves 6 kW for everything else, including heating,
+4. you have 1 kW of other equipment running,
+5. you have declared a sensor (`input_number`) for the maximum allowed power at 9 kW (= 11 kW - the reserve for other devices - margin)
+
+If the vehicle is charging, the total power consumed is 6 kW (5+1), and a _VTherm_ will only turn on if its declared power is 3 kW max (9 kW - 6 kW).
+If the vehicle is charging and another _VTherm_ of 2 kW is running, the total power consumed is 8 kW (5+1+2), and a _VTherm_ will only turn on if its declared power is 1 kW max (9 kW - 8 kW). Otherwise, it will wait until the next cycle.
+
+If the vehicle is not charging, the total power consumed is 1 kW, and a _VTherm_ will only turn on if its declared power is 8 kW max (9 kW - 1 kW).
+
+## Configure Power Management
+
+If you have chosen the `With power detection` feature, configure it as follows:
+
+![image](images/config-power.png)
+
+1. the entity ID of the **instantaneous power consumption sensor** for your home,
+2. the entity ID of the **maximum allowed power sensor**,
+3. the temperature to apply if load shedding is activated.
+
+Note that all power values must have the same units (kW or W, for example).
+Having a **maximum allowed power sensor** allows you to adjust the maximum power over time using a scheduler or automation.
+
+> ![Tip](images/tips.png) _*Notes*_
+>
+> 1. In case of load shedding, the radiator is set to the preset named `power`. This is a hidden preset, and you cannot select it manually.
+> 2. Always keep a margin, as the maximum power may briefly be exceeded while waiting for the next cycle calculation, or due to unregulated equipment.
+> 3. If you don't want to use this feature, uncheck it in the 'Functions' menu.
+> 4. If a _VTherm_ controls multiple devices, the **electrical consumption of your heating** must match the sum of the powers.
+> 5. If you are using the Versatile Thermostat UI card (see [here](additions.md#much-better-with-the-versatile-thermostat-ui-card)), load shedding is represented as follows: ![load shedding](images/power-exceeded-icon.png).

documentation/en/feature-presence.md

@@ -0,0 +1,24 @@
+# Presence / Absence Management
+
+- [Presence / Absence Management](#presence--absence-management)
+  - [Configure Presence (or Absence)](#configure-presence-or-absence)
+
+## Configure Presence (or Absence)
+
+If this feature is selected, it allows you to dynamically adjust the preset temperatures of the thermostat when presence (or absence) is detected. To do this, you need to configure the temperature to be used for each preset when presence is disabled. When the presence sensor turns off, these temperatures will be applied. When it turns back on, the "normal" temperature configured for the preset will be used. See [preset management](feature-presets.md).
+
+To configure presence, fill out this form:
+
+![image](images/config-presence.png)
+
+For this, you simply need to configure an **occupancy sensor** whose state must be 'on' or 'home' if someone is present, or 'off' or 'not_home' otherwise.
+
+Temperatures are configured in the entities of the device corresponding to your _VTherm_ (Settings/Integration/Versatile Thermostat/the vtherm).
+
+WARNING: People groups do not work as a presence sensor. They are not recognized as a presence sensor. You need to use a template as described here [Using a People Group as a Presence Sensor](troubleshooting.md#using-a-people-group-as-a-presence-sensor).
+
+> ![Tip](images/tips.png) _*Notes*_
+>
+> 1. The temperature change is immediate and is reflected on the front panel. The calculation will consider the new target temperature at the next cycle calculation.
+> 2. You can use the direct person.xxxx sensor or a Home Assistant sensor group. The presence sensor handles the states `on` or `home` as present and `off` or `not_home` as absent.
+> 3. To pre-heat your home when everyone is absent, you can add an `input_boolean` entity to your people group. If you set this `input_boolean` to 'On', the presence sensor will be forced to 'On' and the presets with presence will be used. You can also set this `input_boolean` to 'On' via an automation, for example, when you leave a zone to start preheating your home.

documentation/en/feature-presets.md

@@ -0,0 +1,30 @@
+# Presets (Pre-configured Settings)
+
+- [Presets (Pre-configured Settings)](#presets-pre-configured-settings)
+  - [Configure Pre-configured Temperatures](#configure-pre-configured-temperatures)
+
+## Configure Pre-configured Temperatures
+
+The preset mode allows you to pre-configure the target temperature. Used in conjunction with Scheduler (see [scheduler](additions#the-scheduler-component)), you'll have a powerful and simple way to optimize the temperature relative to the electricity consumption in your home. The managed presets are as follows:
+ - **Eco**: the device is in energy-saving mode
+ - **Comfort**: the device is in comfort mode
+ - **Boost**: the device fully opens all valves
+
+If the AC mode is used, you can also configure temperatures when the equipment is in air conditioning mode.
+
+**None** is always added to the list of modes, as it is a way to not use presets but instead set a **manual temperature**.
+
+The presets are configured directly from the _VTherm_ entities or the central configuration if you're using centralized control. Upon creating the _VTherm_, you will have different entities that will allow you to set the temperatures for each preset:
+
+![presets](images/config-preset-temp.png).
+
+The list of entities varies depending on your feature choices:
+1. If the 'presence detection' function is activated, you will have the presets with an "absence" version prefixed with _abs_.
+2. If you have selected the _AC_ option, you will also have presets for 'air conditioning' prefixed with _clim_.
+
+> ![Tip](images/tips.png) _*Notes*_
+>
+> 1. When you manually change the target temperature, the preset switches to None (no preset).
+> 2. The standard preset `Away` is a hidden preset that cannot be directly selected. Versatile Thermostat uses presence management or motion detection to automatically and dynamically adjust the target temperature based on presence in the home or activity in the room. See [presence management](feature-presence.md).
+> 3. If you're using load shedding management, you will see a hidden preset named `power`. The heating element's preset is set to "power" when overload conditions are met and load shedding is active for that heating element. See [power management](feature-power.md).
+> 4. If you're using advanced configuration, you will see the preset set to `safety` if the temperature could not be retrieved after a certain delay. See [Safety Mode](feature-advanced.md#safety-mode).

documentation/en/feature-window.md

@@ -0,0 +1,64 @@
+# Door/Window Open Detection
+
+- [Door/Window Open Detection](#doorwindow-open-detection)
+  - [Sensor Mode](#sensor-mode)
+  - [Auto Mode](#auto-mode)
+
+You must have selected the `With Open Detection` feature on the first page to reach this page.
+Open detection can be done in two ways:
+1. By using a sensor placed on the opening (sensor mode),
+2. By detecting a sudden temperature drop (auto mode)
+
+## Sensor Mode
+To switch to sensor mode, you need to provide an entity of type `binary_sensor` or `input_boolean`.
+In this mode, you need to fill in the following information:
+
+![mode window sensor](images/config-window-sensor.png)
+
+1. A **delay in seconds** before any change. This allows you to open a window quickly without stopping the heating.
+2. The action to take when the opening is detected as open. The possible actions are:
+   1. _Turn off_: the _VTherm_ will be turned off.
+   2. _Fan only_: heating or cooling will be turned off, but the equipment will continue to ventilate (for compatible equipment).
+   3. _Frost protection_: the "Frost Protection" preset temperature will be selected on the _VTherm_ without changing the current preset (see notes below).
+   4. _Eco_: the "Eco" preset temperature will be applied to the _VTherm_ without changing the current preset (see notes below).
+
+When the detector switches to open:
+1. _VTherm_ waits for the specified delay.
+2. If the window is still open after the delay, the _VTherm_ state (Heating / Cooling / ..., current preset, current target temperature) is saved and the action is performed.
+
+Similarly, when the detector switches to closed:
+1. _VTherm_ waits for the specified delay.
+2. If the window is still closed after the delay, the state before the window opening is restored.
+
+## Auto Mode
+In auto mode, the configuration is as follows:
+
+![image](images/config-window-auto.png)
+
+1. A **delay in seconds** before any change. This allows you to open a window quickly without stopping the heating.
+2. A detection threshold in degrees per hour. When the temperature drops beyond this threshold, the thermostat will turn off. The lower this value, the faster the detection (with a higher risk of false positives).
+3. A threshold for ending detection in degrees per hour. When the temperature drop exceeds this value, the thermostat will return to the previous mode (mode and preset).
+4. A maximum detection duration. Beyond this duration, the thermostat will return to its previous mode and preset even if the temperature continues to drop.
+5. The action to take when the opening is detected as open. The actions are the same as in sensor mode described above.
+
+To adjust the thresholds, it is recommended to start with the reference values and adjust the detection thresholds. Some tests gave me the following values (for an office):
+- Detection threshold: 3°C/hour
+- No detection threshold: 0°C/hour
+- Max duration: 30 min.
+
+A new sensor called "slope" has been added for all thermostats. It provides the slope of the temperature curve in °C/hour (or °K/hour). This slope is smoothed and filtered to avoid aberrant thermometer values that could interfere with the measurement.
+
+![image](images/temperature-slope.png)
+
+To adjust it properly, it is recommended to display both the temperature curve and the slope of the curve ("slope") on the same historical graph:
+
+![image](images/window-auto-tuning.png)
+
+> ![Tip](images/tips.png) _*Notes*_
+>
+> 1. If you want to use **multiple door/window sensors** to automate your thermostat, simply create a group with the usual behavior (https://www.home-assistant.io/integrations/binary_sensor.group/)
+> 2. If you don't have a door/window sensor in your room, simply leave the sensor entity ID empty.
+> 3. **Only one mode is allowed**. You cannot configure a thermostat with both a sensor and auto detection. The two modes might contradict each other, so both modes cannot be active at the same time.
+> 4. It is not recommended to use auto mode for equipment subjected to frequent and normal temperature variations (hallways, open areas, etc.).
+> 5. To avoid interfering with your current preset settings, the actions _Frost protection_ and _Eco_ change the target temperature without changing the preset. So, you may notice a discrepancy between the selected preset and the setpoint.
+> 6. If you use the Versatile Thermostat UI card (see [here](additions.md#even-better-with-the-versatile-thermostat-ui-card)), open detection is represented as follows: ![window](images/window-detection-icon.png).

documentation/en/installation.md

@@ -0,0 +1,19 @@
+# How to Install Versatile Thermostat?
+
+## HACS Installation (Recommended)
+
+1. Install [HACS](https://hacs.xyz/). This way, you will automatically receive updates.
+2. The Versatile Thermostat integration is now available directly from the HACS interface (Integrations tab).
+3. Search for and install "Versatile Thermostat" in HACS and click "Install".
+4. Restart Home Assistant.
+5. Then, you can add a Versatile Thermostat integration in the Settings / Integrations page. Add as many thermostats as needed (usually one per radiator or group of radiators that need to be controlled, or per pump in the case of a centralized heating system).
+
+## Manual Installation
+
+1. Using your tool of choice, open your Home Assistant configuration directory (where you will find `configuration.yaml`).
+2. If you don't have a `custom_components` directory, you need to create one.
+3. Inside the `custom_components` directory, create a new folder called `versatile_thermostat`.
+4. Download _all_ files from the `custom_components/versatile_thermostat/` directory (folder) in this repository.
+5. Place the downloaded files in the new folder you created.
+6. Restart Home Assistant.
+7. Configure the new Versatile Thermostat integration.

documentation/en/over-climate.md

@@ -0,0 +1,86 @@
+# `over_climate` Type Thermostat
+
+- [`over_climate` Type Thermostat](#over_climate-type-thermostat)
+  - [Prerequisites](#prerequisites)
+  - [Configuration](#configuration)
+    - [The Underlying Entities](#the-underlying-entities)
+    - [AC Mode](#ac-mode)
+    - [Self-Regulation](#self-regulation)
+    - [Auto-Fan (Auto Ventilation)](#auto-fan-auto-ventilation)
+    - [Compensating for the Internal Temperature of the Underlying Equipment](#compensating-for-the-internal-temperature-of-the-underlying-equipment)
+  - [Specific Functions](#specific-functions)
+
+## Prerequisites
+
+The installation should look like this:
+
+![installation `over_climate`](images/over-climate-schema.png)
+
+1. The user or automation, or the Scheduler, sets a setpoint via a preset or directly using a temperature.
+2. Periodically, the internal thermometer (2), external thermometer (2b), or equipment's internal thermometer (2c) sends the measured temperature. The internal thermometer should be placed in a relevant spot for the user's comfort: ideally in the middle of the living space. Avoid placing it too close to a window or equipment.
+3. Based on the setpoint values, differences, and self-regulation parameters (see [auto-regulation](self-regulation.md)), VTherm will calculate a setpoint to send to the underlying `climate` entity.
+4. The `climate` entity controls the equipment using its own protocol.
+5. Depending on the chosen regulation options, VTherm may directly control the opening of a thermostatic valve or calibrate the equipment so that its internal temperature reflects the room temperature.
+
+## Configuration
+
+Click on the "Underlying Entities" option from the menu, and you will see this configuration page:
+
+![image](images/config-linked-entity2.png)
+
+### The Underlying Entities
+In the "Equipment to Control" list, you should add the `climate` entities that will be controlled by VTherm. Only entities of type `climate` are accepted.
+
+### AC Mode
+
+You can choose an `over_climate` thermostat to control an air conditioner (reversible or not) by checking the "AC Mode" box. If the equipment allows it, both 'Heating' and 'Cooling' modes will be available.
+
+### Self-Regulation
+
+In `over_climate` mode, the device uses its own regulation algorithm: it turns on/off and pauses automatically based on the setpoint transmitted by VTherm through its `climate` entity. It uses its internal thermometer and the received setpoint.
+
+Depending on the equipment, this internal regulation may vary in quality. It greatly depends on the quality of the equipment, the functionality of its internal thermometer, and its internal algorithm. To improve equipment that regulates poorly, VTherm offers a way to adjust the setpoint it sends by increasing or decreasing it based on the room temperature measured by VTherm, rather than the internal temperature.
+
+The self-regulation options are described in detail [here](self-regulation.md).
+
+To avoid overloading the underlying equipment (some may beep unpleasantly, others run on batteries, etc.), two thresholds are available to limit the number of requests:
+1. Regulation Threshold: a threshold in ° below which a new setpoint will not be sent. If the last setpoint was 22°, the next one will be 22° ± regulation threshold.
+2. Minimum Regulation Period (in minutes): a minimum time interval below which a new setpoint will not be sent. If the last setpoint was sent at 11:00, the next one cannot be sent before 11:00 + minimum regulation period.
+
+Improperly setting these thresholds may prevent correct self-regulation as new setpoints won't be sent.
+
+### Auto-Fan (Auto Ventilation)
+
+This mode, introduced in version 4.3, forces the use of ventilation if the temperature difference is significant. By activating ventilation, heat distribution occurs more quickly, which helps achieve the target temperature faster.
+You can choose which ventilation level to activate from the following options: Low, Medium, High, Turbo.
+
+Of course, your underlying equipment must have ventilation, and it must be controllable for this to work. If your equipment doesn't include the Turbo mode, the High mode will be used instead. Once the temperature difference becomes small again, the ventilation will switch to a "normal" mode, which depends on your equipment (in order): `Mute`, `Auto`, `Low`. The first available mode for your equipment will be chosen.
+
+### Compensating for the Internal Temperature of the Underlying Equipment
+
+Sometimes, the internal thermometer of the underlying equipment (TRV, air conditioner, etc.) is inaccurate to the point that self-regulation is insufficient. This happens when the internal thermometer is placed too close to the heat source. The internal temperature rises much faster than the room temperature, leading to regulation failures.
+Example:
+1. Room temperature is 18°, setpoint is 20°.
+2. The internal temperature of the equipment is 22°.
+3. If VTherm sends a setpoint of 21° (= 20° + 1° of self-regulation), the equipment will not heat because its internal temperature (22°) is higher than the setpoint (21°).
+
+To address this, a new optional feature has been added in version 5.4: ![Use of Internal Temperature](images/config-use-internal-temp.png)
+
+When activated, this feature adds the difference between the internal temperature and the room temperature to the setpoint to force heating.
+In the above example, the difference is +4° (22° - 18°), so VTherm will send 25° (21° + 4°) to the equipment, forcing it to heat.
+
+This difference is calculated for each underlying equipment since each has its own internal temperature. For example, a VTherm connected to three TRVs, each with its own internal temperature.
+
+This results in much more effective self-regulation that avoids issues with large internal temperature differences due to faulty sensors.
+
+However, be aware that some internal temperatures fluctuate so quickly and inaccurately that they completely skew the calculation. In this case, it’s better to disable this option.
+
+You will find advice on how to adjust these settings properly on the page [self-regulation](self-regulation.md).
+
+## Specific Functions
+
+Specific functions can be configured through a dedicated option in the menu.
+
+The specific functions that require configuration for this type of VTherm are:
+1. Auto-Start/Stop: Automatic start and stop of VTherm based on usage forecasts. This is described here: [auto-start/stop function](feature-auto-start-stop.md).
+2. If valve regulation is chosen, the TPI algorithm configuration is accessible from the menu. See ([algorithms](algorithms.md)).

documentation/en/over-switch.md

@@ -0,0 +1,55 @@
+# `over_switch` Type Thermostat
+
+- [`over_switch` Type Thermostat](#over_switch-type-thermostat)
+  - [Prerequisites](#prerequisites)
+  - [Configuration](#configuration)
+    - [The Underlying Entities](#the-underlying-entities)
+    - [Keep-Alive](#keep-alive)
+    - [AC Mode](#ac-mode)
+    - [Command Inversion](#command-inversion)
+
+
+## Prerequisites
+
+The installation should look like this:
+
+![installation `over_switch`](images/over-switch-schema.png)
+
+1. The user or automation, or the Scheduler, sets a setpoint via a preset or directly using a temperature.
+2. Periodically, the internal thermometer (2) or external thermometer (2b) sends the measured temperature. The internal thermometer should be placed in a relevant spot for the user's comfort: ideally in the middle of the living space. Avoid placing it too close to a window or too near the radiator.
+3. Based on the setpoint values, the different temperatures, and the TPI algorithm parameters (see [TPI](algorithms.md#lalgorithme-tpi)), VTherm will calculate a percentage of the on-time.
+4. It will then regularly command the turning on and off of the underlying `switch` entities.
+5. These underlying switch entities will control the physical switch.
+6. The physical switch will turn the radiator on or off.
+
+> The on-time percentage is recalculated each cycle, which is what allows regulating the room temperature.
+
+## Configuration
+
+Click on the "Underlying Entities" option from the menu, and you will see this configuration page:
+
+![image](images/config-linked-entity.png)
+
+### The Underlying Entities
+In the "Equipment to Control" list, you should add the switches that will be controlled by VTherm. Only `switch` or `input_boolean` entities are accepted.
+
+The algorithm currently available is TPI. See [algorithm](#algorithm).
+If multiple entities are configured, the thermostat staggers the activations to minimize the number of switches on at any given time. This allows for better power distribution, as each radiator will turn on in turn.
+
+VTherm will smooth the consumed power as much as possible by alternating activations. Example of staggered activations:
+
+![image](images/multi-switch-activation.png)
+
+Of course, if the requested power (`on_percent`) is too high, there will be an overlap of activations.
+
+### Keep-Alive
+
+Some equipment requires periodic activation to prevent a safety shutdown. Known as "keep-alive," this function can be activated by entering a non-zero number of seconds in the thermostat's keep-alive interval field. To disable the function or if in doubt, leave it empty or enter zero (default value).
+
+### AC Mode
+
+It is possible to choose a `thermostat_over_switch` to control an air conditioner by checking the "AC Mode" box. In this case, only the cooling mode will be visible.
+
+### Command Inversion
+
+If your equipment is controlled by a pilot wire with a diode, you may need to check the "Invert the Command" box. This will set the switch to `On` when you need to turn off the equipment and to `Off` when you need to turn it on. The cycle times will be inverted with this option.

documentation/en/over-valve.md

@@ -0,0 +1,30 @@
+# `thermostat_over_valve` Type Thermostat
+
+> ![Attention](images/tips.png) _*Notes*_
+> 1. The `over_valve` type is often confused with the `over_climate` type equipped with auto-regulation and direct valve control.
+> 2. You should only choose this type when you do not have an associated `climate` entity for your _TRV_ in Home Assistant, and if you only have a `number` type entity to control the valve's opening percentage. The `over_climate` with auto-regulation on the valve is much more powerful than the `over_valve` type.
+
+## Prerequisites
+
+The installation should be similar to the `over_switch` VTherm setup, except that the controlled equipment is directly the valve of a _TRV_:
+
+![installation `over_valve`](images/over-valve-schema.png)
+
+1. The user or automation, or the Scheduler, sets a setpoint via a preset or directly using a temperature.
+2. Periodically, the internal thermometer (2) or external thermometer (2b) or internal thermometer of the equipment (2c) sends the measured temperature. The internal thermometer should be placed in a relevant spot for the user's comfort: ideally in the middle of the living space. Avoid placing it too close to a window or too near the equipment.
+3. Based on the setpoint values, the different temperatures, and the TPI algorithm parameters (see [TPI](algorithms.md#lalgorithme-tpi)), VTherm will calculate the valve's opening percentage.
+4. It will then modify the value of the underlying `number` entities.
+5. These underlying `number` entities will control the valve opening rate on the _TRV_.
+6. This will regulate the radiator's heating.
+
+> The opening rate is recalculated each cycle, which allows regulating the room temperature.
+
+## Configuration
+
+Click on the "Underlying Entities" option from the menu, and you will see this configuration page, you should add the `number` entities that will be controlled by VTherm. Only `number` or `input_number` entities are accepted.
+
+![image](images/config-linked-entity3.png)
+
+The algorithm currently available is TPI. See [algorithm](#algorithm).
+
+It is possible to choose a `thermostat_over_valve` to control an air conditioner by checking the "AC Mode" box. In this case, only the cooling mode will be visible.

documentation/en/presentation.md

@@ -0,0 +1,43 @@
+# When to Use and Not Use It
+This thermostat can control 3 types of equipment:
+1. A radiator that only works in on/off mode (called `thermostat_over_switch`). The minimum configuration required to use this type of thermostat is:
+   1. An equipment like a radiator (a `switch` or equivalent),
+   2. A temperature sensor for the room (or an input_number),
+   3. An external temperature sensor (consider the weather integration if you don't have one).
+2. Another thermostat that has its own modes of operation (called `thermostat_over_climate`). For this type of thermostat, the minimum configuration requires:
+   1. Equipment – like air conditioning, a thermostatic valve – controlled by its own `climate` entity.
+3. Equipment that can take a value from 0 to 100% (called `thermostat_over_valve`). At 0, heating is off, and at 100% it is fully open. This type allows controlling a thermostatic valve (e.g., Shelly valve) that exposes a `number` type entity, enabling direct control of the valve's opening. Versatile Thermostat regulates the room temperature by adjusting the opening percentage, using both the internal and external temperature sensors, and utilizing the TPI algorithm described below.
+
+The `over_climate` type allows you to add all the features offered by VersatileThermostat to your existing equipment. The VersatileThermostat `climate` entity will control your underlying `climate` entity, turn it off if windows are open, switch to Eco mode if no one is present, etc. See [here](#pourquoi-un-nouveau-thermostat-implémentation). For this type of thermostat, all heating cycles are controlled by the underlying `climate` entity and not by the Versatile Thermostat itself. An optional auto-regulation function allows Versatile Thermostat to adjust the setpoint temperature to the underlying entity in order to reach the setpoint.
+
+Installations with a pilot wire and activation diode benefit from an option that allows inverting the on/off control of the underlying radiator. To do this, use the `over_switch` type and check the "Invert command" option.
+
+# Why a New Thermostat Implementation?
+
+This component, called __Versatile Thermostat__, manages the following use cases:
+- Configuration via the standard integration graphical interface (using the Config Entry flow),
+- Full use of **preset mode**,
+- Disable preset mode when the temperature is **set manually** on a thermostat,
+- Turn off/on a thermostat or change preset when a **door or windows are opened/closed** after a certain delay,
+- Change preset when **activity is detected** or not in a room for a defined time,
+- Use a **TPI (Time Proportional Interval)** algorithm thanks to [[Argonaute](https://forum.hacf.fr/u/argonaute/summary)],
+- Add **load shedding** management or regulation to not exceed a defined total power. When the maximum power is exceeded, a hidden preset of "power" is set on the `climate` entity. When the power goes below the maximum, the previous preset is restored.
+- **Presence management**. This feature allows dynamically modifying the preset temperature based on the presence sensor in your home.
+- **Actions to interact with the thermostat** from other integrations: you can force presence/non-presence using a service, and you can dynamically change preset temperatures and modify security settings.
+- Add sensors to view the thermostat's internal states,
+- Centralized control of all Versatile Thermostats to stop them all, set them all to frost protection, force them all to heating mode (in winter), force them all to cooling mode (in summer).
+- Control of a central heating boiler and VTherms that must control this boiler.
+- Automatic start/stop based on usage prediction for `over_climate`.
+
+All these functions are configurable either centrally or individually depending on your needs.
+
+## Incompatibilities
+Some TRV type thermostats are known to be incompatible with Versatile Thermostat. This includes the following valves:
+1. Danfoss POPP valves with temperature feedback. It is impossible to turn off this valve as it auto-regulates itself, causing conflicts with VTherm.
+2. "Homematic" thermostats (and possibly Homematic IP) are known to have issues with Versatile Thermostat due to the limitations of the underlying RF protocol. This problem particularly arises when trying to control multiple Homematic thermostats at once in a single VTherm instance. To reduce service cycle load, you can, for example, group thermostats using Homematic-specific procedures (e.g., using a wall-mounted thermostat) and let Versatile Thermostat control only the wall-mounted thermostat directly. Another option is to control a single thermostat and propagate mode and temperature changes via automation.
+3. Heatzy type thermostats that do not support `set_temperature` commands.
+4. Rointe type thermostats tend to wake up on their own. The rest works normally.
+5. TRVs like Aqara SRTS-A01 and MOES TV01-ZB, which lack the `hvac_action` state feedback to determine whether they are heating or not. Therefore, state feedback is inaccurate, but the rest seems functional.
+6. Airwell air conditioners with the "Midea AC LAN" integration. If two VTherm commands are too close together, the air conditioner stops itself.
+7. Climates based on the Overkiz integration do not work. It seems impossible to turn off or even change the temperature on these systems.
+

documentation/en/reference.md

@@ -0,0 +1,275 @@
+# Reference Documentation
+
+- [Reference Documentation](#reference-documentation)
+  - [Parameter Summary](#parameter-summary)
+- [Sensors](#sensors)
+- [Actions (Services)](#actions-services)
+  - [Force Presence/Occupation](#force-presenceoccupation)
+  - [Modify the Preset Temperature](#modify-the-preset-temperature)
+  - [Modify Security Settings](#modify-security-settings)
+  - [ByPass Window Check](#bypass-window-check)
+- [Events](#events)
+- [Custom Attributes](#custom-attributes)
+
+## Parameter Summary
+
+| Parameter                                 | Label                                                      | "over switch" | "over climate"      | "over valve" | "central configuration" |
+| ----------------------------------------- | ---------------------------------------------------------- | ------------- | ------------------- | ------------ | ----------------------- |
+| ``name``                                  | Name                                                       | X             | X                   | X            | -                       |
+| ``thermostat_type``                       | Thermostat type                                            | X             | X                   | X            | -                       |
+| ``temperature_sensor_entity_id``          | Temperature sensor entity id                               | X             | X (auto-regulation) | X            | -                       |
+| ``external_temperature_sensor_entity_id`` | External temperature sensor entity id                      | X             | X (auto-regulation) | X            | X                       |
+| ``cycle_min``                             | Cycle duration (minutes)                                   | X             | X                   | X            | -                       |
+| ``temp_min``                              | Minimum allowed temperature                                | X             | X                   | X            | X                       |
+| ``temp_max``                              | Maximum allowed temperature                                | X             | X                   | X            | X                       |
+| ``device_power``                          | Device power                                               | X             | X                   | X            | -                       |
+| ``use_central_mode``                      | Enable centralized control                                 | X             | X                   | X            | -                       |
+| ``use_window_feature``                    | With window detection                                      | X             | X                   | X            | -                       |
+| ``use_motion_feature``                    | With motion detection                                      | X             | X                   | X            | -                       |
+| ``use_power_feature``                     | With power management                                      | X             | X                   | X            | -                       |
+| ``use_presence_feature``                  | With presence detection                                    | X             | X                   | X            | -                       |
+| ``heater_entity1_id``                     | 1st heater                                                 | X             | -                   | -            | -                       |
+| ``heater_entity2_id``                     | 2nd heater                                                 | X             | -                   | -            | -                       |
+| ``heater_entity3_id``                     | 3rd heater                                                 | X             | -                   | -            | -                       |
+| ``heater_entity4_id``                     | 4th heater                                                 | X             | -                   | -            | -                       |
+| ``heater_keep_alive``                     | Switch refresh interval                                    | X             | -                   | -            | -                       |
+| ``proportional_function``                 | Algorithm                                                  | X             | -                   | -            | -                       |
+| ``climate_entity1_id``                    | Underlying thermostat                                      | -             | X                   | -            | -                       |
+| ``climate_entity2_id``                    | 2nd underlying thermostat                                  | -             | X                   | -            | -                       |
+| ``climate_entity3_id``                    | 3rd underlying thermostat                                  | -             | X                   | -            | -                       |
+| ``climate_entity4_id``                    | 4th underlying thermostat                                  | -             | X                   | -            | -                       |
+| ``valve_entity1_id``                      | Underlying valve                                           | -             | -                   | X            | -                       |
+| ``valve_entity2_id``                      | 2nd underlying valve                                       | -             | -                   | X            | -                       |
+| ``valve_entity3_id``                      | 3rd underlying valve                                       | -             | -                   | X            | -                       |
+| ``valve_entity4_id``                      | 4th underlying valve                                       | -             | -                   | X            | -                       |
+| ``ac_mode``                               | Use of air conditioning (AC)?                              | X             | X                   | X            | -                       |
+| ``tpi_coef_int``                          | Coefficient for internal temperature delta                 | X             | -                   | X            | X                       |
+| ``tpi_coef_ext``                          | Coefficient for external temperature delta                 | X             | -                   | X            | X                       |
+| ``frost_temp``                            | Frost preset temperature                                   | X             | X                   | X            | X                       |
+| ``window_sensor_entity_id``               | Window sensor (entity id)                                  | X             | X                   | X            | -                       |
+| ``window_delay``                          | Delay before turn-off (seconds)                            | X             | X                   | X            | X                       |
+| ``window_auto_open_threshold``            | High drop threshold for automatic detection (°/min)        | X             | X                   | X            | X                       |
+| ``window_auto_close_threshold``           | Low drop threshold for automatic closure detection (°/min) | X             | X                   | X            | X                       |
+| ``window_auto_max_duration``              | Maximum duration of automatic turn-off (minutes)           | X             | X                   | X            | X                       |
+| ``motion_sensor_entity_id``               | Motion sensor entity id                                    | X             | X                   | X            | -                       |
+| ``motion_delay``                          | Delay before motion is considered (seconds)                | X             | X                   | X            | -                       |
+| ``motion_off_delay``                      | Delay before end of motion is considered (seconds)         | X             | X                   | X            | X                       |
+| ``motion_preset``                         | Preset to use if motion is detected                        | X             | X                   | X            | X                       |
+| ``no_motion_preset``                      | Preset to use if no motion is detected                     | X             | X                   | X            | X                       |
+| ``power_sensor_entity_id``                | Total power sensor (entity id)                             | X             | X                   | X            | X                       |
+| ``max_power_sensor_entity_id``            | Max power sensor (entity id)                               | X             | X                   | X            | X                       |
+| ``power_temp``                            | Temperature during load shedding                           | X             | X                   | X            | X                       |
+| ``presence_sensor_entity_id``             | Presence sensor entity id (true if someone is present)     | X             | X                   | X            | -                       |
+| ``minimal_activation_delay``              | Minimum activation delay                                   | X             | -                   | -            | X                       |
+| ``security_delay_min``                    | Maximum delay between two temperature measurements         | X             | -                   | X            | X                       |
+| ``security_min_on_percent``               | Minimum power percentage to enter security mode            | X             | -                   | X            | X                       |
+| ``auto_regulation_mode``                  | Auto-regulation mode                                       | -             | X                   | -            | -                       |
+| ``auto_regulation_dtemp``                 | Auto-regulation threshold                                  | -             | X                   | -            | -                       |
+| ``auto_regulation_period_min``            | Minimum auto-regulation period                             | -             | X                   | -            | -                       |
+| ``inverse_switch_command``                | Inverse the switch command (for switches with pilot wire)  | X             | -                   | -            | -                       |
+| ``auto_fan_mode``                         | Automatic fan mode                                         | -             | X                   | -            | -                       |
+| ``auto_regulation_use_device_temp``       | Use of internal temperature of the underlying device       | -             | X                   | -            | -                       |
+| ``use_central_boiler_feature``            | Add central boiler control                                 | -             | -                   | -            | X                       |
+| ``central_boiler_activation_service``     | Boiler activation service                                  | -             | -                   | -            | X                       |
+| ``central_boiler_deactivation_service``   | Boiler deactivation service                                | -             | -                   | -            | X                       |
+| ``used_by_controls_central_boiler``       | Indicates if the VTherm controls the central boiler        | X             | X                   | X            | -                       |
+| ``use_auto_start_stop_feature``           | Indicates if the auto start/stop feature is enabled        | -             | X                   | -            | -                       |
+| ``auto_start_stop_level``                 | The detection level for auto start/stop                    | -             | X                   | -            | -                       |
+
+# Sensors
+
+With the thermostat, sensors are available to visualize alerts and the internal state of the thermostat. These are available in the entities of the device associated with the thermostat:
+
+![image](images/thermostat-sensors.png)
+
+In order, there are:
+1. the main ``climate`` entity for thermostat control,
+2. the entity allowing the auto-start/stop feature,
+3. the entity allowing _VTherm_ to follow changes in the underlying device,
+4. the energy consumed by the thermostat (value that increments continuously),
+5. the time of receipt of the last external temperature,
+6. the time of receipt of the last internal temperature,
+7. the average power of the device during the cycle (for TPI only),
+8. the time spent in the off state during the cycle (TPI only),
+9. the time spent in the on state during the cycle (TPI only),
+10. the load shedding state,
+11. the power percentage during the cycle (TPI only),
+12. the presence state (if presence management is configured),
+13. the security state,
+14. the window state (if window management is configured),
+15. the motion state (if motion management is configured),
+16. the valve opening percentage (for `over_valve` type),
+
+The presence of these entities depends on whether the associated feature is enabled.
+
+To color the sensors, add these lines and customize them as needed in your `configuration.yaml`:
+
+```yaml
+frontend:
+  themes:
+    versatile_thermostat_theme:
+      state-binary_sensor-safety-on-color: "#FF0B0B"
+      state-binary_sensor-power-on-color: "#FF0B0B"
+      state-binary_sensor-window-on-color: "rgb(156, 39, 176)"
+      state-binary_sensor-motion-on-color: "rgb(156, 39, 176)"
+      state-binary_sensor-presence-on-color: "lightgreen"
+      state-binary_sensor-running-on-color: "orange"
+```
+
+and choose the theme ```versatile_thermostat_theme``` in the panel configuration. You will get something like this:
+
+![image](images/colored-thermostat-sensors.png)
+
+# Actions (Services)
+
+This custom implementation offers specific actions (services) to facilitate integration with other Home Assistant components.
+
+## Force Presence/Occupation
+This service allows you to force the presence state independently of the presence sensor. This can be useful if you want to manage presence via a service rather than a sensor. For example, you can use your alarm to force absence when it is turned on.
+
+The code to call this service is as follows:
+
+```yaml
+service : versatile_thermostat.set_presence
+Les données:
+    présence : "off"
+cible:
+    entity_id : climate.my_thermostat
+```
+
+## Modify the Preset Temperature
+This service is useful if you want to dynamically change the preset temperature. Instead of switching presets, some use cases require modifying the temperature of the preset. This way, you can keep the scheduler unchanged to manage the preset while adjusting the preset temperature.
+If the modified preset is currently selected, the target temperature change is immediate and will be applied in the next calculation cycle.
+
+You can modify one or both temperatures (when present or absent) of each preset.
+
+Use the following code to set the preset temperature:
+```yaml
+service: versatile_thermostat.set_preset_temperature
+data:
+    preset: boost
+    temperature: 17.8
+    temperature_away: 15
+target:
+    entity_id: climate.my_thermostat
+```
+
+Or, to change the preset for the Air Conditioning (AC) mode, add the `_ac` prefix to the preset name like this:
+```yaml
+service: versatile_thermostat.set_preset_temperature
+data:
+    preset: boost_ac
+    temperature: 25
+    temperature_away: 30
+target:
+    entity_id: climate.my_thermostat
+```
+
+> ![Tip](images/tips.png) _*Notes*_
+>
+>    - After a restart, presets are reset to the configured temperature. If you want your change to be permanent, you need to modify the preset temperature in the integration configuration.
+
+## Modify Security Settings
+This service allows you to dynamically modify the security settings described here [Advanced Configuration](#advanced-configuration).
+If the thermostat is in ``security`` mode, the new settings are applied immediately.
+
+To change the security settings, use the following code:
+```yaml
+service: versatile_thermostat.set_security
+data:
+    min_on_percent: "0.5"
+    default_on_percent: "0.1"
+    delay_min: 60
+target:
+    entity_id: climate.my_thermostat
+```
+
+## ByPass Window Check
+This service allows you to enable or disable a bypass for the window check.
+It allows the thermostat to continue heating even if the window is detected as open.
+When set to ``true``, changes to the window's status will no longer affect the thermostat. When set to ``false``, the thermostat will be disabled if the window is still open.
+
+To change the bypass setting, use the following code:
+```yaml
+service: versatile_thermostat.set_window_bypass
+data:
+    bypass: true
+target:
+    entity_id: climate.my_thermostat
+```
+
+# Events
+The key events of the thermostat are notified via the message bus.
+The following events are notified:
+
+- ``versatile_thermostat_security_event``: the thermostat enters or exits the ``security`` preset
+- ``versatile_thermostat_power_event``: the thermostat enters or exits the ``power`` preset
+- ``versatile_thermostat_temperature_event``: one or both temperature measurements of the thermostat haven't been updated for more than `security_delay_min`` minutes
+- ``versatile_thermostat_hvac_mode_event``: the thermostat is turned on or off. This event is also broadcast at the thermostat's startup
+- ``versatile_thermostat_preset_event``: a new preset is selected on the thermostat. This event is also broadcast at the thermostat's startup
+- ``versatile_thermostat_central_boiler_event``: an event indicating a change in the boiler's state
+- ``versatile_thermostat_auto_start_stop_event``: an event indicating a stop or restart made by the auto-start/stop function
+
+If you've followed along, when a thermostat switches to security mode, 3 events are triggered:
+1. ``versatile_thermostat_temperature_event`` to indicate that a thermometer is no longer responding,
+2. ``versatile_thermostat_preset_event`` to indicate the switch to the ``security`` preset,
+3. ``versatile_thermostat_hvac_mode_event`` to indicate the potential shutdown of the thermostat
+
+Each event carries the event's key values (temperatures, current preset, current power, ...) as well as the thermostat's states.
+
+You can easily capture these events in an automation, for example, to notify users.
+
+# Custom Attributes
+
+To adjust the algorithm, you have access to the entire context seen and calculated by the thermostat via dedicated attributes. You can view (and use) these attributes in the "Developer Tools / States" section of HA. Enter your thermostat and you will see something like this:
+![image](images/dev-tools-climate.png)
+
+The custom attributes are as follows:
+| Attribute                         | Meaning                                                                                                                             |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| ``hvac_modes``                    | The list of modes supported by the thermostat                                                                                       |
+| ``temp_min``                      | The minimum temperature                                                                                                             |
+| ``temp_max``                      | The maximum temperature                                                                                                             |
+| ``preset_modes``                  | The presets visible for this thermostat. Hidden presets are not displayed here                                                      |
+| ``temperature_actuelle``          | The current temperature as reported by the sensor                                                                                   |
+| ``temperature``                   | The target temperature                                                                                                              |
+| ``action_hvac``                   | The action currently being executed by the heater. Can be idle, heating                                                             |
+| ``preset_mode``                   | The preset currently selected. Can be one of the 'preset_modes' or a hidden preset like power                                       |
+| ``[eco/confort/boost]_temp``      | The temperature configured for preset xxx                                                                                           |
+| ``[eco/confort/boost]_away_temp`` | The temperature configured for preset xxx when presence is disabled or not_home                                                     |
+| ``temp_power``                    | The temperature used during loss detection                                                                                          |
+| ``on_percent``                    | The calculated on percentage by the TPI algorithm                                                                                   |
+| ``on_time_sec``                   | The on period in seconds. Should be ```on_percent * cycle_min```                                                                    |
+| ``off_time_sec``                  | The off period in seconds. Should be ```(1 - on_percent) * cycle_min```                                                             |
+| ``cycle_min``                     | The calculation cycle in minutes                                                                                                    |
+| ``function``                      | The algorithm used for the cycle calculation                                                                                        |
+| ``tpi_coef_int``                  | The ``coef_int`` of the TPI algorithm                                                                                               |
+| ``tpi_coef_ext``                  | The ``coef_ext`` of the TPI algorithm                                                                                               |
+| ``saved_preset_mode``             | The last preset used before automatic preset switching                                                                              |
+| ``saved_target_temp``             | The last temperature used before automatic switching                                                                                |
+| ``window_state``                  | The last known state of the window sensor. None if the window is not configured                                                     |
+| ``window_bypass_state``           | True if the window open detection bypass is enabled                                                                                 |
+| ``motion_state``                  | The last known state of the motion sensor. None if motion detection is not configured                                               |
+| ``overpowering_state``            | The last known state of the overpower sensor. None if power management is not configured                                            |
+| ``presence_state``                | The last known state of the presence sensor. None if presence detection is not configured                                           |
+| ``security_delay_min``            | The delay before activating security mode when one of the two temperature sensors stops sending measurements                        |
+| ``security_min_on_percent``       | The heating percentage below which the thermostat will not switch to security                                                       |
+| ``security_default_on_percent``   | The heating percentage used when the thermostat is in security mode                                                                 |
+| ``last_temperature_datetime``     | The date and time in ISO8866 format of the last internal temperature reception                                                      |
+| ``last_ext_temperature_datetime`` | The date and time in ISO8866 format of the last external temperature reception                                                      |
+| ``security_state``                | The security state. True or false                                                                                                   |
+| ``minimal_activation_delay_sec``  | The minimal activation delay in seconds                                                                                             |
+| ``last_update_datetime``          | The date and time in ISO8866 format of this state                                                                                   |
+| ``friendly_name``                 | The name of the thermostat                                                                                                          |
+| ``supported_features``            | A combination of all features supported by this thermostat. See the official climate integration documentation for more information |
+| ``valve_open_percent``            | The valve opening percentage                                                                                                        |
+| ``regulated_target_temperature``  | The target temperature calculated by self-regulation                                                                                |
+| ``is_inversed``                   | True if the control is inverted (pilot wire with diode)                                                                             |
+| ``is_controlled_by_central_mode`` | True if the VTherm can be centrally controlled                                                                                      |
+| ``last_central_mode``             | The last central mode used (None if the VTherm is not centrally controlled)                                                         |
+| ``is_used_by_central_boiler``     | Indicates if the VTherm can control the central boiler                                                                              |
+| ``auto_start_stop_enable``        | Indicates if the VTherm is allowed to auto start/stop                                                                               |
+| ``auto_start_stop_level``         | Indicates the auto start/stop level                                                                                                 |
+| ``hvac_off_reason``               | Indicates the reason for the thermostat's off state (hvac_off). It can be Window, Auto-start/stop, or Manual                        |
+
+These attributes will be requested when you need assistance.

documentation/en/releases.md

@@ -0,0 +1,50 @@
+# Release Notes
+
+![New](images/new-icon.png)
+
+> * **Release 6.8**:
+>   - Added a new regulation method for `over_climate` type Versatile Thermostats. This method, called 'Direct Valve Control', allows direct control of a TRV valve and possibly an offset to calibrate the internal thermometer of your TRV. This new method has been tested with Sonoff TRVZB and extended to other TRV types where the valve can be directly controlled via `number` entities. More information [here](over-climate.md#lauto-régulation) and [here](self-regulation.md#auto-régulation-par-contrôle-direct-de-la-vanne).
+
+## **Release 6.5** :
+  - Added a new feature for the automatic stop and restart of a `VTherm over_climate` [585](https://github.com/jmcollin78/versatile_thermostat/issues/585)
+  - Improved handling of openings on startup. Allows to memorize and recalculate the state of an opening on Home Assistant restart [504](https://github.com/jmcollin78/versatile_thermostat/issues/504)
+
+## **Release 6.0** :
+  - Added `number` domain entities to configure preset temperatures [354](https://github.com/jmcollin78/versatile_thermostat/issues/354)
+  - Complete redesign of the configuration menu to remove temperatures and use a menu instead of a configuration tunnel [354](https://github.com/jmcollin78/versatile_thermostat/issues/354)
+
+## **Release 5.4** :
+  - Added temperature step [#311](https://github.com/jmcollin78/versatile_thermostat/issues/311),
+  - Added regulation thresholds for `over_valve` to prevent excessive battery drain for TRVs [#338](https://github.com/jmcollin78/versatile_thermostat/issues/338),
+  - Added an option to use the internal temperature of a TRV to force auto-regulation [#348](https://github.com/jmcollin78/versatile_thermostat/issues/348),
+  - Added a keep-alive function for `over_switch` VTherms [#345](https://github.com/jmcollin78/versatile_thermostat/issues/345)
+
+<details>
+<summary>Older releases</summary>
+
+> * **Release 5.3** : Added a function to control a central boiler [#234](https://github.com/jmcollin78/versatile_thermostat/issues/234) - more info here: [Central Boiler Control](#le-contrôle-dune-chaudière-centrale). Added the ability to disable security mode for the external thermometer [#343](https://github.com/jmcollin78/versatile_thermostat/issues/343)
+> * **Release 5.2** : Added a `central_mode` to control all VTherms centrally [#158](https://github.com/jmcollin78/versatile_thermostat/issues/158).
+> * **Release 5.1** : Limitation of values sent to valves and to the underlying climate temperature.
+> * **Release 5.0** : Added central configuration to combine configurable attributes [#239](https://github.com/jmcollin78/versatile_thermostat/issues/239).
+> * **Release 4.3** : Added an auto-fan mode for `over_climate` type to activate ventilation if temperature difference is large [#223](https://github.com/jmcollin78/versatile_thermostat/issues/223).
+> * **Release 4.2** : The temperature curve slope is now calculated in °/hour instead of °/min [#242](https://github.com/jmcollin78/versatile_thermostat/issues/242). Fixed automatic opening detection by adding temperature curve smoothing.
+> * **Release 4.1** : Added an **Expert** regulation mode where users can specify their own auto-regulation parameters instead of using pre-programmed ones [#194](https://github.com/jmcollin78/versatile_thermostat/issues/194).
+> * **Release 4.0** : Added support for **Versatile Thermostat UI Card**. See [Versatile Thermostat UI Card](https://github.com/jmcollin78/versatile-thermostat-ui-card). Added a **Slow** regulation mode for slow-latency heating devices [#168](https://github.com/jmcollin78/versatile_thermostat/issues/168). Changed how **power is calculated** for VTherms with multi-underlying equipment [#146](https://github.com/jmcollin78/versatile_thermostat/issues/146). Added support for AC and Heat for VTherms via a switch [#144](https://github.com/jmcollin78/versatile_thermostat/pull/144)
+> * **Release 3.8**: Added an **auto-regulation** function for `over_climate` thermostats regulated by the underlying climate. See [Auto-regulation](#lauto-régulation) and [#129](https://github.com/jmcollin78/versatile_thermostat/issues/129). Added the **ability to invert control** for `over_switch` thermostats to address installations with pilot wire and diode [#124](https://github.com/jmcollin78/versatile_thermostat/issues/124).
+> * **Release 3.7**: Added the `over_valve` Versatile Thermostat type to control a TRV valve directly or any other dimmer type equipment for heating. Regulation is done directly by adjusting the percentage of opening of the underlying entity: 0 means the valve is off, 100 means the valve is fully open. See [#131](https://github.com/jmcollin78/versatile_thermostat/issues/131). Added a bypass function for opening detection [#138](https://github.com/jmcollin78/versatile_thermostat/issues/138). Added Slovak language support.
+> * **Release 3.6**: Added the `motion_off_delay` parameter to improve motion detection handling [#116](https://github.com/jmcollin78/versatile_thermostat/issues/116), [#128](https://github.com/jmcollin78/versatile_thermostat/issues/128). Added AC mode (air conditioning) for `over_switch` VTherm. Prepared the GitHub project to facilitate contributions [#127](https://github.com/jmcollin78/versatile_thermostat/issues/127)
+> * **Release 3.5**: Multiple thermostats possible in "thermostat over climate" mode [#113](https://github.com/jmcollin78/versatile_thermostat/issues/113)
+> * **Release 3.4**: Bug fix and exposure of preset temperatures for AC mode [#103](https://github.com/jmcollin78/versatile_thermostat/issues/103)
+> * **Release 3.3**: Added Air Conditioning (AC) mode. This function allows you to use the AC mode of your underlying thermostat. To use it, you must check the "Use AC Mode" option and define temperature values for presets and away presets.
+> * **Release 3.2** : Added the ability to control multiple switches from the same thermostat. In this mode, switches are triggered with a delay to minimize the power required at any given time (minimizing overlap periods). See [Configuration](#sélectionnez-des-entités-pilotées)
+> * **Release 3.1** : Added window/door open detection by temperature drop. This new feature automatically stops a radiator when the temperature drops suddenly. See [Auto Mode](#le-mode-auto)
+> * **Major Release 3.0** : Added thermostat equipment and associated sensors (binary and non-binary). Much closer to the Home Assistant philosophy, you now have direct access to the energy consumed by the radiator controlled by the thermostat and many other sensors useful for your automations and dashboards.
+> * **Release 2.3** : Added measurement of power and energy for the radiator controlled by the thermostat.
+> * **Release 2.2** : Added a safety function to prevent leaving a radiator heating indefinitely in case of thermometer failure.
+> * **Major Release 2.0** : Added the "over climate" thermostat allowing any thermostat to be transformed into a Versatile Thermostat and gain all its functionalities.
+
+</details>
+
+> ![Tip](images/tips.png) _*Notes*_
+>
+> Complete release notes are available on the [GitHub of the integration](https://github.com/jmcollin78/versatile_thermostat/releases/).

documentation/en/self-regulation.md

@@ -0,0 +1,152 @@
+# Self-regulation
+
+- [Self-regulation](#self-regulation)
+      - [Self-regulation in Expert Mode](#self-regulation-in-expert-mode)
+      - [Summary of the Self-regulation Algorithm](#summary-of-the-self-regulation-algorithm)
+
+You have the option to activate the self-regulation feature only for _VTherms_ of type `over_climate`.
+
+There are generally two cases:
+1. If your underlying device is a _TRV_ and the valve is directly controllable in Home Assistant (e.g., Sonoff TRVZB), this function will allow _VTherm_ to directly manipulate the valve opening to regulate the temperature. The opening is then calculated by a _TPI_-type algorithm (see [here](algorithms.md)).
+2. Otherwise, Versatile Thermostat will adjust the temperature setpoint given to the underlying climate to ensure the room temperature actually reaches the setpoint.
+
+## Configuration
+
+### Self-regulation by direct valve control
+
+This type of self-regulation, named `Direct Valve Control`, requires:
+1. An entity of type `climate` that is included in the _VTherm_'s underlying devices.
+2. An entity of type `number` to control the valve opening rate of the _TRV_.
+3. An optional entity of type `number` for calibrating the internal temperature of the underlying device.
+4. An optional entity of type `number` to control the valve closure.
+
+When the chosen self-regulation is `Direct Valve Control` on an _VTherm_ `over_climate`, a new configuration page named `Valve Regulation Configuration` appears:
+
+![Configuration Menu](images/config-self-regulation-valve-1.png)
+
+This allows you to configure the valve control entities:
+
+![Configuration Entities](images/config-self-regulation-valve-2.png)
+
+You need to provide:
+1. As many valve opening control entities as there are underlying devices, and in the same order. These parameters are mandatory.
+2. As many temperature calibration entities as there are underlying devices, and in the same order. These parameters are optional; they must either all be provided or none.
+3. As many valve closure control entities as there are underlying devices, and in the same order. These parameters are optional; they must either all be provided or none.
+
+The opening rate calculation algorithm is based on the _TPI_ algorithm described [here](algorithms.md). This is the same algorithm used for _VTherms_ `over_switch` and `over_valve`.
+
+If a valve closure rate entity is configured, it will be set to 100 minus the opening rate to force the valve into a particular state.
+
+### Other self-regulation
+
+In the second case, Versatile Thermostat calculates an offset based on the following information:
+1. The current difference between the actual temperature and the setpoint temperature, called the gross error.
+2. The accumulation of past errors.
+3. The difference between the outdoor temperature and the setpoint.
+
+These three pieces of information are combined to calculate the offset, which will be added to the current setpoint and sent to the underlying climate.
+
+Self-regulation is configured with:
+1. A regulation degree:
+   1. Light - for small self-regulation needs. In this mode, the maximum offset will be 1.5°C.
+   2. Medium - for medium self-regulation needs. A maximum offset of 2°C is possible in this mode.
+   3. Strong - for high self-regulation needs. The maximum offset is 3°C in this mode, and the self-regulation will react strongly to temperature changes.
+2. A self-regulation threshold: the value below which no new regulation will be applied. For example, if at time t the offset is 2°C, and at the next calculation, the offset is 2.4°C, the regulation will not be applied. It will only be applied when the difference between the two offsets is at least equal to this threshold.
+3. Minimum period between two self-regulations: this number, expressed in minutes, indicates the duration between two regulation changes.
+
+These three parameters allow you to adjust the regulation and avoid applying too many regulation changes. Some devices, like TRVs or boilers, don't like frequent setpoint changes.
+
+> ![Tip](images/tips.png) _*Setup advice*_
+> 1. Do not start self-regulation immediately. Observe how your equipment's natural regulation works. If you notice that the setpoint is not reached or takes too long to reach, start the regulation.
+> 2. Start with light self-regulation and keep both parameters at their default values. Wait a few days and check if the situation improves.
+> 3. If it's not enough, switch to medium self-regulation and wait for stabilization.
+> 4. If it's still not enough, switch to strong self-regulation.
+> 5. If it's still not correct, you will need to switch to expert mode to finely adjust the regulation parameters.
+
+Self-regulation forces the equipment to push further by regularly adjusting its setpoint. This can increase both its consumption and wear.
+
+#### Self-regulation in Expert Mode
+
+In **Expert** mode, you can finely adjust the self-regulation parameters to meet your goals and optimize performance. The algorithm calculates the gap between the setpoint and the actual room temperature. This gap is called the error.
+
+The adjustable parameters are as follows:
+1. `kp`: the factor applied to the gross error,
+2. `ki`: the factor applied to the accumulated errors,
+3. `k_ext`: the factor applied to the difference between the indoor temperature and the outdoor temperature,
+4. `offset_max`: the maximum correction (offset) that the regulation can apply,
+5. `stabilization_threshold`: a stabilization threshold, which when reached by the error resets the accumulated errors to 0,
+6. `accumulated_error_threshold`: the maximum for error accumulation.
+
+For tuning, the following observations should be considered:
+1. `kp * error` will give the offset related to the gross error. This offset is directly proportional to the error and will be 0 when the target is reached.
+2. The accumulation of the error helps correct the stabilization curve even if there is still an error. The error accumulates and the offset increases progressively, which should stabilize the temperature around the target. To have a noticeable effect, this parameter should not be too small. A medium value is 30.
+3. `ki * accumulated_error_threshold` will give the maximum offset related to the accumulated error.
+4. `k_ext` allows immediate (without waiting for accumulated errors) correction when the outdoor temperature is much different from the target temperature. If the stabilization occurs too high when the temperature differences are large, this parameter might be too high. It should be adjustable to zero to allow the first two offsets to do the work.
+
+The pre-programmed values are as follows:
+
+**Slow regulation**:
+
+    kp: 0.2  # 20% of the current internal regulation offset are caused by the current difference of target temperature and room temperature
+    ki: 0.8 / 288.0  # 80% of the current internal regulation offset are caused by the average offset of the past 24 hours
+    k_ext: 1.0 / 25.0  # this will add 1°C to the offset when it's 25°C colder outdoor than indoor
+    offset_max: 2.0  # limit to a final offset of -2°C to +2°C
+    stabilization_threshold: 0.0  # this needs to be disabled as otherwise the long term accumulated error will always be reset when the temp briefly crosses from/to below/above the target
+    accumulated_error_threshold: 2.0 * 288  # this allows up to 2°C long term offset in both directions
+
+**Light regulation**:
+
+    kp: 0.2
+    ki: 0.05
+    k_ext: 0.05
+    offset_max: 1.5
+    stabilization_threshold: 0.1
+    accumulated_error_threshold: 10
+
+**Medium regulation**:
+
+    kp: 0.3
+    ki: 0.05
+    k_ext: 0.1
+    offset_max: 2
+    stabilization_threshold: 0.1
+    accumulated_error_threshold: 20
+
+**Strong regulation**:
+
+    """Strong parameters for regulation
+    A set of parameters which doesn't take into account the external temp
+    and concentrate on internal temp error + accumulated error.
+    This should work for cold external conditions which otherwise generate
+    high external_offset"""
+
+    kp: 0.4
+    ki: 0.08
+    k_ext: 0.0
+    offset_max: 5
+    stabilization_threshold: 0.1
+    accumulated_error_threshold: 50
+
+To use Expert mode, you must declare the values you wish to use for each of these parameters in your `configuration.yaml` as follows. Example for 'Extreme regulation':
+
+```yaml
+versatile_thermostat:
+    auto_regulation_expert:
+        kp: 0.6
+        ki: 0.1
+        k_ext: 0.0
+        offset_max: 10
+        stabilization_threshold: 0.1
+        accumulated_error_threshold: 80
+```
+and of course, configure the auto-regulation mode of the VTherm to Expert mode. All _VTherms_ in **Expert** mode will use the same parameters, it is not possible to have different expert settings.
+
+To apply the changes, you must either **restart Home Assistant completely** or just the Versatile Thermostat integration (Developer Tools / YAML / Reload Configuration / Versatile Thermostat).
+
+> ![Tip](images/tips.png) _*Notes*_
+>
+> 1. In expert mode, it is rarely necessary to use the option [Compensate the internal temperature of the underlying](over-climate.md#compensate-the-internal-temperature-of-the-underlying). This could result in very high setpoints.
+
+## Summary of the Auto-Regulation Algorithm
+
+A summary of the auto-regulation algorithm is described [here](algorithms.md#the-auto-regulation-algorithm-without-valve-control)

documentation/en/troubleshooting.md

@@ -0,0 +1,209 @@
+
+# Troubleshooting
+
+- [Troubleshooting](#troubleshooting)
+  - [Using a Heatzy](#using-a-heatzy)
+  - [Using a radiator with a pilot wire (Nodon SIN-4-FP-21)](#using-a-radiator-with-a-pilot-wire-nodon-sin-4-fp-21)
+  - [Only the first radiator heats](#only-the-first-radiator-heats)
+  - [The radiator heats even though the setpoint temperature is exceeded, or it does not heat when the room temperature is well below the setpoint](#the-radiator-heats-even-though-the-setpoint-temperature-is-exceeded-or-it-does-not-heat-when-the-room-temperature-is-well-below-the-setpoint)
+    - [Type `over_switch` or `over_valve`](#type-over_switch-or-over_valve)
+    - [Type `over_climate`](#type-over_climate)
+  - [Adjust the window open detection parameters in auto mode](#adjust-the-window-open-detection-parameters-in-auto-mode)
+  - [Why is my Versatile Thermostat going into Safety Mode?](#why-is-my-versatile-thermostat-going-into-safety-mode)
+    - [How to detect Safety Mode?](#how-to-detect-safety-mode)
+    - [How to Be Notified When This Happens?](#how-to-be-notified-when-this-happens)
+    - [How to Fix It?](#how-to-fix-it)
+  - [Using a Group of People as a Presence Sensor](#using-a-group-of-people-as-a-presence-sensor)
+  - [Enable Logs for the Versatile Thermostat](#enable-logs-for-the-versatile-thermostat)
+
+
+## Using a Heatzy
+
+Using a Heatzy or Nodon is possible provided you use a virtual switch with this model:
+
+```yaml
+- platform: template
+  switches:
+    chauffage_sdb:
+      unique_id: chauffage_sdb
+      friendly_name: Bathroom heating
+      value_template: "{{ is_state_attr('climate.bathroom', 'preset_mode', 'comfort') }}"
+      icon_template: >-
+        {% if is_state_attr('climate.bathroom', 'preset_mode', 'comfort') %}
+          mdi:radiator
+        {% elif is_state_attr('climate.bathroom', 'preset_mode', 'away') %}
+          mdi:snowflake
+        {% else %}
+          mdi:radiator-disabled
+        {% endif %}
+      turn_on:
+        service: climate.set_preset_mode
+        entity_id: climate.bathroom
+        data:
+          preset_mode: "comfort"
+      turn_off:
+        service: climate.set_preset_mode
+        entity_id: climate.bathroom
+        data:
+          preset_mode: "eco"
+```
+Thanks to @gael for this example.
+
+## Using a radiator with a pilot wire (Nodon SIN-4-FP-21)
+As with the Heatzy above, you can use a virtual switch that will change the preset of your radiator based on the VTherm’s on/off state.
+Example:
+
+```yaml
+- platform: template
+  switches:
+    chauffage_chb_parents:
+      unique_id: chauffage_chb_parents
+      friendly_name: Chauffage chambre parents
+      value_template: "{{ is_state('select.fp_chb_parents_pilot_wire_mode', 'comfort') }}"
+      icon_template: >-
+        {% if is_state('select.fp_chb_parents_pilot_wire_mode', 'comfort') %}
+          mdi:radiator
+        {% elif is_state('select.fp_chb_parents_pilot_wire_mode', 'frost_protection') %}
+          mdi:snowflake
+        {% else %}
+          mdi:radiator-disabled
+        {% endif %}
+      turn_on:
+        service: select.select_option
+        target:
+          entity_id: select.fp_chb_parents_pilot_wire_mode
+        data:
+          option: comfort
+      turn_off:
+        service: select.select_option
+        target:
+          entity_id: select.fp_chb_parents_pilot_wire_mode
+        data:
+          option: eco
+```
+
+## Only the first radiator heats
+
+In `over_switch` mode, if multiple radiators are configured for the same VTherm, the heating will be triggered sequentially to smooth out the consumption peaks as much as possible.
+This is completely normal and intentional. It is described here: [For a thermostat of type ```thermostat_over_switch```](#for-a-thermostat-of-type-thermostat_over_switch)
+
+## The radiator heats even though the setpoint temperature is exceeded, or it does not heat when the room temperature is well below the setpoint
+
+### Type `over_switch` or `over_valve`
+With a VTherm of type `over_switch` or `over_valve`, this issue simply indicates that the TPI algorithm parameters are not properly configured. See [TPI Algorithm](#tpi-algorithm) to optimize the settings.
+
+### Type `over_climate`
+With a VTherm of type `over_climate`, the regulation is handled directly by the underlying `climate`, and VTherm simply transmits the setpoints to it. So if the radiator is heating even though the setpoint temperature is exceeded, it is likely that its internal temperature measurement is biased. This often happens with TRVs and reversible air conditioners that have an internal temperature sensor, either too close to the heating element (so it's too cold in winter).
+
+Examples of discussions on these topics: [#348](https://github.com/jmcollin78/versatile_thermostat/issues/348), [#316](https://github.com/jmcollin78/versatile_thermostat/issues/316), [#312](https://github.com/jmcollin78/versatile_thermostat/discussions/312), [#278](https://github.com/jmcollin78/versatile_thermostat/discussions/278)
+
+To resolve this, VTherm is equipped with a feature called self-regulation, which allows it to adjust the setpoint sent to the underlying device until the setpoint is met. This function compensates for the bias of internal temperature sensors. If the bias is significant, the regulation should also be significant. See [Self-regulation](self-regulation.md) for configuring self-regulation.
+
+## Adjust the window open detection parameters in auto mode
+
+If you are unable to configure the automatic window open detection function (see [auto](feature-window.md#auto-mode)), you can try modifying the temperature smoothing algorithm parameters.
+Indeed, the automatic window open detection is based on calculating the temperature slope. To avoid artifacts caused by an imprecise temperature sensor, this slope is calculated using a temperature smoothed with an algorithm called Exponential Moving Average (EMA).
+This algorithm has 3 parameters:
+1. `lifecycle_sec`: the duration in seconds considered for smoothing. The higher it is, the smoother the temperature will be, but the detection delay will also increase.
+2. `max_alpha`: if two temperature readings are far apart in time, the second one will carry much more weight. This parameter limits the weight of a reading that comes well after the previous one. This value must be between 0 and 1. The lower it is, the less distant readings are taken into account. The default value is 0.5, meaning that a new temperature reading will never weigh more than half of the moving average.
+3. `precision`: the number of digits after the decimal point retained for calculating the moving average.
+
+To change these parameters, you need to modify the `configuration.yaml` file and add the following section (the values below are the default values):
+
+```yaml
+versatile_thermostat:
+  short_ema_params:
+    max_alpha: 0.5
+    halflife_sec: 300
+    precision: 2
+```
+
+These parameters are sensitive and quite difficult to adjust. Please only use them if you know what you’re doing and if your temperature readings are not already smoothed.
+
+## Why is my Versatile Thermostat going into Safety Mode?
+
+Safety mode is only available for VTherm types `over_switch` and `over_valve`. It occurs when one of the two thermometers (providing either the room temperature or the external temperature) has not sent a value for more than `security_delay_min` minutes, and the radiator had been heating at least `security_min_on_percent`. See [safety mode](feature-advanced.md#safety-mode)
+
+Since the algorithm relies on temperature measurements, if they are no longer received by the VTherm, there is a risk of overheating and fire. To prevent this, when the above conditions are detected, heating is limited to the `security_default_on_percent` parameter. This value should therefore be reasonably low (10% is a good value). It helps avoid a fire while preventing the radiator from being completely turned off (risk of freezing).
+
+All these parameters are configured on the last page of the VTherm configuration: "Advanced Settings".
+
+### How to detect Safety Mode?
+The first symptom is an unusually low temperature with a short and consistent heating time during each cycle.
+Example:
+
+[security mode](images/security-mode-symptome1.png)
+
+If you have installed the [Versatile Thermostat UI Card](https://github.com/jmcollin78/versatile-thermostat-ui-card), the affected VTherm will appear like this:
+
+[security mode UI Card](images/security-mode-symptome2.png)
+
+You can also check the VTherm's attributes for the dates of the last received values. **The attributes are available in the Developer Tools / States**.
+
+Example:
+
+```yaml
+security_state: true
+last_temperature_datetime: "2023-12-06T18:43:28.346010+01:00"
+last_ext_temperature_datetime: "2023-12-06T13:04:35.164367+01:00"
+last_update_datetime: "2023-12-06T18:43:28.351103+01:00"
+...
+security_delay_min: 60
+```
+
+We can see that:
+1. The VTherm is indeed in safety mode (`security_state: true`),
+2. The current time is 06/12/2023 at 18:43:28 (`last_update_datetime: "2023-12-06T18:43:28.351103+01:00"`),
+3. The last reception time of the room temperature is 06/12/2023 at 18:43:28 (`last_temperature_datetime: "2023-12-06T18:43:28.346010+01:00"`), so it's recent,
+4. The last reception time of the external temperature is 06/12/2023 at 13:04:35 (`last_ext_temperature_datetime: "2023-12-06T13:04:35.164367+01:00"`). The external temperature is over 5 hours late, which triggered the safety mode, as the threshold is set to 60 minutes (`security_delay_min: 60`).
+
+### How to Be Notified When This Happens?
+The VTherm sends an event as soon as this happens and again at the end of the safety alert. You can capture these events in an automation and send a notification, blink a light, trigger a siren, etc. It's up to you.
+
+For handling events generated by VTherm, see [Events](#events).
+
+### How to Fix It?
+It depends on the cause of the problem:
+1. If a sensor is faulty, it should be repaired (replace batteries, change it, check the weather integration that provides the external temperature, etc.),
+2. If the `security_delay_min` parameter is too small, it may generate many false alerts. A correct value is around 60 minutes, especially if you have battery-powered temperature sensors. See [my settings](tuning-examples.md#battery-powered-temperature-sensor),
+3. Some temperature sensors don't send measurements if the temperature hasn't changed. So if the temperature stays very stable for a long time, safety mode can trigger. This is not a big issue since it will deactivate once the VTherm receives a new temperature. On some thermometers (e.g., TuYA or Zigbee), you can force a max delay between two measurements. The max delay should be set to a value lower than `security_delay_min`,
+4. As soon as the temperature is received again, safety mode will turn off, and the previous preset, target temperature, and mode values will be restored.
+5. If the external temperature sensor is faulty, you can disable safety mode triggering as it has a minimal impact on the results. To do so, see [here](feature-advanced.md#safety-mode).
+
+## Using a Group of People as a Presence Sensor
+
+Unfortunately, groups of people are not recognized as presence sensors. Therefore, you cannot use them directly in VTherm.
+A workaround is to create a binary sensor template with the following code:
+
+File `template.yaml`:
+
+```yaml
+- binary_sensor:
+    - name: maison_occupee
+      unique_id: maison_occupee
+      state: "{{is_state('person.person1', 'home') or is_state('person.person2', 'home') or is_state('input_boolean.force_presence', 'on')}}"
+      device_class: occupancy
+```
+
+In this example, note the use of an `input_boolean` called `force_presence`, which forces the sensor to `True`, thereby forcing any VTherm that uses it to have active presence. This can be used, for example, to trigger a pre-heating of the house when leaving work or when an unrecognized person is present in HA.
+
+File `configuration.yaml`:
+
+```yaml
+...
+template: !include templates.yaml
+...
+```
+
+## Enable Logs for the Versatile Thermostat
+
+Sometimes, you will need to enable logs to fine-tune your analysis. To do this, edit the `logger.yaml` file in your configuration and configure the logs as follows:
+
+```yaml
+default: xxxx
+logs:
+  custom_components.versatile_thermostat: info
+```
+You must reload the YAML configuration (Developer Tools / YAML / Reload all YAML configuration) or restart Home Assistant for this change to take effect.
+
+Be careful, in debug mode, Versatile Thermostat is very verbose and can quickly slow down Home Assistant or saturate your hard drive. If you switch to debug mode for anomaly analysis, do so only for the time needed to reproduce the bug and disable debug mode immediately afterward.

documentation/en/tuning-examples.md

@@ -0,0 +1,60 @@
+# Tuning Examples
+
+- [Tuning Examples](#tuning-examples)
+  - [Electric Heating](#electric-heating)
+  - [Central Heating (gas or oil heating)](#central-heating-gas-or-oil-heating)
+  - [Battery-Powered Temperature Sensor](#battery-powered-temperature-sensor)
+  - [Reactive Temperature Sensor (plugged in)](#reactive-temperature-sensor-plugged-in)
+  - [My Presets](#my-presets)
+
+## Electric Heating
+- Cycle: between 5 and 10 minutes,
+- minimal_activation_delay_sec: 30 seconds
+
+## Central Heating (gas or oil heating)
+- Cycle: between 30 and 60 minutes,
+- minimal_activation_delay_sec: 300 seconds (due to response time)
+
+## Battery-Powered Temperature Sensor
+These sensors are often sluggish and do not always send temperature readings when the temperature is stable. Therefore, the settings should be loose to avoid false positives.
+
+- security_delay_min: 60 minutes (because these sensors are sluggish)
+- security_min_on_percent: 0.7 (70% - the system goes into security mode if the heater was on more than 70% of the time)
+- security_default_on_percent: 0.4 (40% - in security mode, we maintain 40% heating time to avoid getting too cold)
+
+These settings should be understood as follows:
+
+> If the thermometer stops sending temperature readings for 1 hour and the heating percentage (``on_percent``) was greater than 70%, then the heating percentage will be reduced to 40%.
+
+Feel free to adjust these settings to your specific case!
+
+The important thing is not to take too much risk with these parameters: assume you are absent for a long period, and the batteries of your thermometer are running low, your heater will run 40% of the time during the whole failure period.
+
+Versatile Thermostat allows you to be notified when such an event occurs. Set up the appropriate alerts as soon as you start using this thermostat. See (#notifications).
+
+## Reactive Temperature Sensor (plugged in)
+A powered thermometer is supposed to be very regular in sending temperature readings. If it doesn't send anything for 15 minutes, it most likely has an issue, and we can react faster without the risk of a false positive.
+
+- security_delay_min: 15 minutes
+- security_min_on_percent: 0.5 (50% - the system goes into ``security`` preset if the heater was on more than 50% of the time)
+- security_default_on_percent: 0.25 (25% - in ``security`` preset, we keep 25% heating time)
+
+## My Presets
+This is just an example of how I use the preset. You can adapt it to your configuration, but it may be useful to understand its functionality.
+
+``Frost Protection``: 10°C
+``Eco``: 17°C
+``Comfort``: 19°C
+``Boost``: 20°C
+
+When presence is disabled:
+``Frost Protection``: 10°C
+``Eco``: 16.5°C
+``Comfort``: 17°C
+``Boost``: 17.5°C
+
+The motion detector in my office is configured to use ``Boost`` when motion is detected and ``Eco`` otherwise.
+
+The security mode is configured as follows:
+
+![My settings](images/my-tuning.png)

documentation/fr/additions.md

@@ -1,19 +1,18 @@
 # Quelques compléments indispensables
 
 - [Quelques compléments indispensables](#quelques-compléments-indispensables)
-  - [Bien mieux avec le Versatile Thermostat UI Card](#bien-mieux-avec-le-versatile-thermostat-ui-card)
-  - [Encore mieux avec le composant Scheduler !](#encore-mieux-avec-le-composant-scheduler-)
-  - [Encore bien mieux avec la custom:simple-thermostat front integration](#encore-bien-mieux-avec-la-customsimple-thermostat-front-integration)
-  - [Toujours mieux avec Plotly pour régler votre thermostat](#toujours-mieux-avec-plotly-pour-régler-votre-thermostat)
-  - [Et toujours de mieux en mieux avec l'AappDaemon NOTIFIER pour notifier les évènements](#et-toujours-de-mieux-en-mieux-avec-laappdaemon-notifier-pour-notifier-les-évènements)
+  - [Versatile Thermostat UI Card](#versatile-thermostat-ui-card)
+  - [Composant Scheduler !](#composant-scheduler-)
+  - [Courbes de régulattion avec Plotly](#courbes-de-régulattion-avec-plotly)
+  - [Les notification avec l'AappDaemon NOTIFIER](#les-notification-avec-laappdaemon-notifier)
 
 
-## Bien mieux avec le Versatile Thermostat UI Card
+## Versatile Thermostat UI Card
 Une carte spéciale pour le Versatile Thermostat a été développée (sur la base du Better Thermostat). Elle est dispo ici [Versatile Thermostat UI Card](https://github.com/jmcollin78/versatile-thermostat-ui-card) et propose une vision moderne de tous les status du VTherm :
 
 ![image](https://github.com/jmcollin78/versatile-thermostat-ui-card/blob/master/assets/1.png?raw=true)
 
-## Encore mieux avec le composant Scheduler !
+## Composant Scheduler !
 
 Afin de profiter de toute la puissance du Versatile Thermostat, je vous invite à l'utiliser avec https://github.com/nielsfaber/scheduler-component
 En effet, le composant scheduler propose une gestion de la base climatique sur les modes prédéfinis. Cette fonctionnalité a un intérêt limité avec le thermostat générique mais elle devient très puissante avec le Versatile Thermostat :
@@ -39,58 +38,13 @@ Dans cet exemple, j'ai réglé le mode ECO pendant la nuit et le jour lorsqu'il
 
 J'espère que cet exemple vous aidera, n'hésitez pas à me faire part de vos retours !
 
-## Encore bien mieux avec la custom:simple-thermostat front integration
-Le ``custom:simple-thermostat`` [ici](https://github.com/nervetattoo/simple-thermostat) est une excellente intégration qui permet une certaine personnalisation qui s'adapte bien à ce thermostat.
-Vous pouvez avoir quelque chose comme ça très facilement ![image](images/simple-thermostat.png)
-Exemple de configuration :
-
-```
-      type: custom:simple-thermostat
-      entity: climate.thermostat_sam2
-      layout:
-        step: row
-      label:
-        temperature: T°
-        state: Etat
-      hide:
-        state: false
-      control:
-        hvac:
-          _name: Mode
-        preset:
-          _name: Preset
-      sensors:
-        - entity: sensor.total_puissance_radiateur_sam2
-          icon: mdi:lightning-bolt-outline
-      header:
-        toggle:
-          entity: input_boolean.etat_ouverture_porte_sam
-          name: Porte sam
-```
-
-Vous pouvez personnaliser ce composant à l'aide du composant HACS card-mod pour ajuster les couleurs des alertes. Exemple pour afficher en rouge les alertes sécurité et délestage :
-
-```
-          card_mod:
-            style: |
-              {% if is_state('binary_sensor.thermostat_chambre_security_state', 'on') %}
-              ha-card .body .sensor-heading ha-icon[icon="mdi:alert-outline"] {
-                color: red;
-              }
-              {% endif %}
-              {% if is_state('binary_sensor.thermostat_chambre_overpowering_state', 'on') %}
-              ha-card .body .sensor-heading ha-icon[icon="mdi:flash"] {
-                color: red;
-              }
-              {% endif %}
-```
-![image](images/custom-css-thermostat.png)
-
-## Toujours mieux avec Plotly pour régler votre thermostat
+## Courbes de régulattion avec Plotly
 Vous pouvez obtenir une courbe comme celle présentée dans [some results](#some-results) avec une sorte de configuration de graphique Plotly uniquement en utilisant les attributs personnalisés du thermostat décrits [ici](#custom-attributes) :
 
 Remplacez les valeurs entre [[ ]] par les votres.
-```
+<details>
+
+```yaml
 - type: custom:plotly-graph
   entities:
     - entity: '[[climate]]'
@@ -106,9 +60,13 @@ Remplacez les valeurs entre [[ ]] par les votres.
       yaxis: y1
       name: Ema
     - entity: '[[climate]]'
-      attribute: regulated_target_temperature
-      yaxis: y1
-      name: Regulated T°
+      attribute: on_percent
+      yaxis: y2
+      name: Power percent
+      fill: tozeroy
+      fillcolor: rgba(200, 10, 10, 0.3)
+      line:
+        color: rgba(200, 10, 10, 0.9)
     - entity: '[[slope]]'
       name: Slope
       fill: tozeroy
@@ -133,12 +91,19 @@ Remplacez les valeurs entre [[ ]] par les votres.
     yaxis:
       visible: true
       position: 0
+    yaxis2:
+      visible: true
+      position: 0
+      fixedrange: true
+      range:
+        - 0
+        - 1
     yaxis9:
       visible: true
       fixedrange: false
       range:
-        - -0.5
-        - 0.5
+        - -2
+        - 2
       position: 1
     xaxis:
       rangeselector:
@@ -154,17 +119,20 @@ Remplacez les valeurs entre [[ ]] par les votres.
           - count: 7
             step: day
 ```
+</details>
 
 Exemple de courbes obtenues avec Plotly :
 
 ![image](images/plotly-curves.png)
 
-## Et toujours de mieux en mieux avec l'AappDaemon NOTIFIER pour notifier les évènements
+## Les notification avec l'AappDaemon NOTIFIER
 Cette automatisation utilise l'excellente App Daemon nommée NOTIFIER développée par Horizon Domotique que vous trouverez en démonstration [ici](https://www.youtube.com/watch?v=chJylIK0ASo&ab_channel=HorizonDomotique) et le code est [ici](https://github.com/jlpouffier/home-assistant-config/blob/master/appdaemon/apps/notifier.py). Elle permet de notifier les utilisateurs du logement lorsqu'un des évènements touchant à la sécurité survient sur un des Versatile Thermostats.
 
 C'est un excellent exemple de l'utilisation des notifications décrites ici [notification](#notifications).
 
-```
+<details>
+
+```yaml
 alias: Surveillance Mode Sécurité chauffage
 description: Envoi une notification si un thermostat passe en mode sécurité ou power
 trigger:
@@ -245,3 +213,4 @@ action:
 mode: queued
 max: 30
 ```
+</details>

documentation/fr/base-attributes.md

@@ -1,3 +1,6 @@
+- [Choix des attributs de base](#choix-des-attributs-de-base)
+- [Choix des fonctions utilisées](#choix-des-fonctions-utilisées)
+
 # Choix des attributs de base
 
 Choisisez le menu "Principaux attributs".
@@ -20,7 +23,7 @@ Donnez les principaux attributs obligatoires. Ces attributs sont communs à tous
 10. une case à cocher si ce VTherm est utilisé pour déclencher une éventuelle chaudière centrale.
 
 > ![Astuce](images/tips.png) _*Notes*_
->  1. avec les types ```over_switch``` et ```over_valve```, les calculs sont effectués à chaque cycle. Donc en cas de changement de conditions, il faudra attendre le prochain cycle pour voir un changement. Pour cette raison, le cycle ne doit pas être trop long. **5 min est une bonne valeur** mais doit être adapté à votre type de chauffage. Plus l'inertie est grande et plus le cycle doit être long. Cf. 'TODO exemples de reglages,
+>  1. avec les types ```over_switch``` et ```over_valve```, les calculs sont effectués à chaque cycle. Donc en cas de changement de conditions, il faudra attendre le prochain cycle pour voir un changement. Pour cette raison, le cycle ne doit pas être trop long. **5 min est une bonne valeur** mais doit être adapté à votre type de chauffage. Plus l'inertie est grande et plus le cycle doit être long. Cf. [Exemples de réglages](tuning-examples.md),
 >  2. si le cycle est trop court, le radiateur ne pourra jamais atteindre la température cible. Pour le radiateur à accumulation par exemple il sera sollicité inutilement.
 
 # Choix des fonctions utilisées

documentation/fr/creation.md

@@ -1,16 +1,27 @@
 # Choix du Vtherm
 
+- [Choix du Vtherm](#choix-du-vtherm)
+  - [Création d'un nouveau Versatile Thermostat](#création-dun-nouveau-versatile-thermostat)
+- [Choix d'un type de VTherm](#choix-dun-type-de-vtherm)
+  - [Configuration centralisée](#configuration-centralisée)
+  - [VTherm sur un switch](#vtherm-sur-un-switch)
+  - [Vtherm sur un autre thermostat](#vtherm-sur-un-autre-thermostat)
+  - [VTherm sur une vanne](#vtherm-sur-une-vanne)
+- [Le bon choix](#le-bon-choix)
+- [Article en référence](#article-en-référence)
+
+
 > ![Astuce](images/tips.png) _*Notes*_
 >
 > Trois façons de travailler avec les VTherms sont disponibles :
 > 1. Chaque Versatile Thermostat est entièrement configurée de manière indépendante. Choisissez cette option si vous ne souhaitez avoir aucune configuration ou gestion centrale.
-> 2. Certains aspects sont configurés de manière centralisée. Cela permet par ex. définir la température min/max, la détection de fenêtre ouverte,… au niveau d'une instance centrale et unique. Pour chaque VTherm que vous configurez, vous pouvez alors choisir d'utiliser la configuration centrale ou de la remplacer par des paramètres personnalisés.
+> 2. Certains aspects peuvent être configurés de manière centralisée. Cela permet par ex. définir la température min/max, les paramètres de détection de fenêtre ouverte,… au niveau d'une instance centrale et unique. Pour chaque VTherm que vous configurez, vous pouvez alors choisir d'utiliser la configuration centrale ou de la remplacer par des paramètres personnalisés.
 > 3. En plus de cette configuration centralisée, tous les VTherm peuvent être contrôlées par une seule entité de type `select`. Cette fonction est nommé `central_mode`. Cela permet de stopper / démarrer / mettre en hors gel / etc tous les VTherms en une seule fois. Pour chaque VTherm, l'utilisateur indique si il est concerné par ce `central_mode`.
 
 
 ## Création d'un nouveau Versatile Thermostat
 
-Cliquez sur le bouton Ajouter une intégration dans la page d'intégration
+Cliquez sur le bouton Ajouter une intégration dans la page d'intégration (ou cliquez directement sur 'Ajouter un appareil' depuis la page de configuration de l'intégration)
 
 ![image](images/add-an-integration.png)
 

documentation/fr/feature-advanced.md

@@ -35,7 +35,7 @@ Mettre ce paramètre à ``0.00`` déclenchera le préréglage sécurité quelque
 Le quatrième paramètre (`security_default_on_percent`) est la valeur de `on_percent` qui sera utilisée lorsque le thermostat passe en mode ``security``. Si vous mettez `0` alors le thermostat sera coupé lorsqu'il passe en mode `security`, mettre 0,2% par exemple permet de garder un peu de chauffage (20% dans ce cas), même en mode ``security``. Ca évite de retrouver son logement totalement gelé lors d'une panne de thermomètre.
 
 Il est possible de désactiver la mise en sécurité suite à une absence de données du thermomètre extérieure. En effet, celui-ci ayant la plupart du temps un impact faible sur la régulation (dépendant de votre paramètrage), il est possible qu'il soit absent sans mettre en danger le logement. Pour cela, il faut ajouter les lignes suivantes dans votre `configuration.yaml` :
-```
+```yaml
 versatile_thermostat:
 ...
     safety_mode:

documentation/fr/feature-central-boiler.md

@@ -54,7 +54,7 @@ Cliquez sur 'Appeler l'action'. Si votre chaudière s'allume vous avez la bonne
 
 Exemple:
 
-Sous "Outils de développement / Service" :
+Sous "Outils de développement / Actions" :
 
 ![Configuration du service](images/dev-tools-turnon-boiler-1.png)
 
@@ -72,7 +72,7 @@ A chaque allumage ou extinction réussie de la chaudière un évènement est env
 Les évènements ressemblent à ça :
 
 Un évènement d'allumage :
-```
+```yaml
 event_type: versatile_thermostat_central_boiler_event
 data:
   central_boiler: true
@@ -88,7 +88,7 @@ context:
 ```
 
 Un évènement d'extinction :
-```
+```yaml
 event_type: versatile_thermostat_central_boiler_event
 data:
   central_boiler: false
@@ -106,4 +106,5 @@ context:
 ## Avertissement
 
 > ![Astuce](images/tips.png) _*Notes*_
+>
 > Le contrôle par du logiciel ou du matériel de type domotique d'une chaudière centrale peut induire des risques pour son bon fonctionnement. Assurez-vous avant d'utiliser ces fonctions, que votre chaudière possède bien des fonctions de sécurité et que celles-ci fonctionnent. Allumer une chaudière si tous les robinets sont fermés peut générer de la sur-pression par exemple.

documentation/fr/feature-central-mode.md

@@ -18,7 +18,7 @@ Si vous avez défini une configuration centralisée, vous avez une nouvelle enti
 
 Cette entité se présente sous la forme d'une liste de choix qui contient les choix suivants :
 1. `Auto` : le mode 'normal' dans lequel chaque VTherm se comporte de façon autonome,
-2. `Stooped` : tous les VTherms sont mis à l'arrêt (`hvac_off`),
+2. `Stopped` : tous les VTherms sont mis à l'arrêt (`hvac_off`),
 3. `Heat only` : tous les VTherms sont mis en mode chauffage lorsque ce mode est supporté par le VTherm, sinon il est stoppé,
 4. `Cool only` : tous les VTherms sont mis en mode climatisation lorsque ce mode est supporté par le VTherm, sinon il est stoppé,
 5. `Frost protection` : tous les VTherms sont mis en preset hors-gel lorsque ce preset est supporté par le VTherm, sinon il est stoppé.

documentation/fr/feature-power.md

@@ -27,6 +27,7 @@ Si le vehicle n'est pas en charge, la puissance totale consommé est de 1 kW, un
 ## Configurer la gestion de la puissance
 
 Si vous avez choisi la fonctionnalité `Avec détection de la puissance`, vous la configurez de la façon suivante :
+
 ![image](images/config-power.png)
 
 1. l'id d'entité du **capteur de puissance instantané consommé** de votre logement,
@@ -37,6 +38,7 @@ Notez que toutes les valeurs de puissance doivent avoir les mêmes unités (kW o
 Le fait d'avoir un **capteur de puissance maximale autorisée**, vous permet de modifier la puissance maximale au fil du temps à l'aide d'un planificateur ou d'une automatisation.
 
 > ![Astuce](images/tips.png) _*Notes*_
+>
 > 1. En cas de délestage, le radiateur est réglé sur le préréglage nommé `power`. Il s'agit d'un préréglage caché, vous ne pouvez pas le sélectionner manuellement.
 > 2. Gardez toujours une marge, car la puissance max peut être brièvement dépassée en attendant le calcul du prochain cycle typiquement ou par des équipements non régulés.
 > 3. Si vous ne souhaitez pas utiliser cette fonctionnalité, décochez la dans le menu 'Fonctions'.

documentation/fr/feature-presence.md

@@ -18,6 +18,7 @@ Les températures sont configurées dans les entités de l'équipement correspon
 ATTENTION : les groupes de personnes ne fonctionnent pas en tant que capteur de présence. Ils ne sont pas reconnus comme un capteur de présence. Vous devez utiliser, un template comme décrit ici [Utilisation d'un groupe de personnes comme capteur de présence](troubleshooting.md#utilisation-dun-groupe-de-personnes-comme-capteur-de-présence).
 
 > ![Astuce](images/tips.png) _*Notes*_
+>
 > 1. le changement de température est immédiat et se répercute sur le volet avant. Le calcul prendra en compte la nouvelle température cible au prochain calcul du cycle,
 > 2. vous pouvez utiliser le capteur direct person.xxxx ou un groupe de capteurs de Home Assistant. Le capteur de présence gère les états ``on`` ou ``home`` comme présents et les états ``off`` ou ``not_home`` comme absents.
 > 3. pour pré-chauffer votre logement alors que tout le monde est absent, vous pouvez ajouter une entité de type `input_boolean` dans votre groupe de personne. Si vous passez cet `input_boolean` sur 'On' alors le capteur de présence sera forcé sur 'On' et les presets avec présence seront utilisés. Vous pouvez aussi positionner cet `input_boolean` sur 'On' via une automatisation par exemple lorsque vous quittez une zone pour lancer le préchauffage de votre logement.

documentation/fr/feature-presets.md

@@ -6,7 +6,7 @@
 
 ## Configurer les températures préréglées
 
-Le mode préréglé (preset) vous permet de préconfigurer la température ciblée. Utilisé en conjonction avec Scheduler (voir [scheduler](additions##encore-mieux-avec-le-composant-scheduler-)) vous aurez un moyen puissant et simple d'optimiser la température par rapport à la consommation électrique de votre maison. Les préréglages gérés sont les suivants :
+Le mode préréglé (preset) vous permet de préconfigurer la température ciblée. Utilisé en conjonction avec Scheduler (voir [scheduler](additions#composant-scheduler-)) vous aurez un moyen puissant et simple d'optimiser la température par rapport à la consommation électrique de votre maison. Les préréglages gérés sont les suivants :
  - **Eco** : l'appareil est en mode d'économie d'énergie
  - **Confort** : l'appareil est en mode confort
  - **Boost** : l'appareil tourne toutes les vannes à fond
@@ -24,6 +24,7 @@ La liste des entités varient en fonction de vos choix de fonction :
 2. si vous avez choisi l'option _AC_, vous aurez en plus les presets en version 'climatisation' préfixé par _clim_
 
 > ![Astuce](images/tips.png) _*Notes*_
+>
 >  1. Lorsque vous modifiez manuellement la température cible, le préréglage passe sur Aucun (pas de préréglage),
 >  2. Le préréglage standard ``Away`` est un préréglage caché qui n'est pas directement sélectionnable. Versatile Thermostat utilise la gestion de présence ou la gestion de mouvement pour régler automatiquement et dynamiquement la température cible en fonction d'une présence dans le logement ou d'une activité dans la pièce. Voir [gestion de la présence](feature-presence.md).
 >  3. Si vous utilisez la gestion du délestage, vous verrez un préréglage caché nommé ``power``. Le préréglage de l'élément chauffant est réglé sur « puissance » lorsque des conditions de surpuissance sont rencontrées et que le délestage est actif pour cet élément chauffant. Voir [gestion de l'alimentation](feature-power.md).

documentation/fr/feature-window.md

@@ -9,10 +9,6 @@ La détection des ouvertures peut se faire de 2 manières:
 1. soit avec un capteur placé sur l'ouverture (mode capteur),
 2. soit en détectant une chute brutale de température (mode auto)
 
-La configuration de la détection d'ouverture est la suivante :
-
-![image](images/config-window-main.png)
-
 ## Le mode capteur
 Pour passer en mode capteur, vous devez donner une entité de type `binary_sensor` ou `input_boolean`.
 Dans ce mode, vous devez renseigner les informations suivantes:
@@ -36,6 +32,7 @@ Pareil, lorsque le détecteur passe à fermé :
 
 ## Le mode auto
 En mode auto, la configuration est la suivante:
+
 ![image](images/config-window-auto.png)
 
 1. un **délai en secondes** avant tout changement. Cela permet d'ouvrir rapidement une fenêtre sans arrêter le chauffage,
@@ -58,6 +55,7 @@ Pour bien régler il est conseillé d'affocher sur un même graphique historique
 ![image](images/window-auto-tuning.png)
 
 > ![Astuce](images/tips.png) _*Notes*_
+>
 >  1. Si vous souhaitez utiliser **plusieurs capteurs de porte/fenêtre** pour automatiser votre thermostat, créez simplement un groupe avec le comportement habituel (https://www.home-assistant.io/integrations/binary_sensor.group/)
 >  2. Si vous n'avez pas de capteur de fenêtre/porte dans votre chambre, laissez simplement l'identifiant de l'entité du capteur vide,
 >  3. **Un seul mode est permis**. On ne peut pas configurer un thermostat avec un capteur et une détection automatique. Les 2 modes risquant de se contredire, il n'est pas possible d'avoir les 2 modes en même temps,