Troubleshoot security mode

README-fr.md

@@ -49,7 +49,7 @@
   - [Modifier la température des préréglages](#modifier-la-température-des-préréglages)
   - [Modifier les paramètres de sécurité](#modifier-les-paramètres-de-sécurité)
   - [ByPass Window Check](#bypass-window-check)
-- [Notifications](#notifications)
+- [Evènements](#evènements)
 - [Attributs personnalisés](#attributs-personnalisés)
 - [Quelques résultats](#quelques-résultats)
 - [Encore mieux](#encore-mieux)
@@ -64,6 +64,10 @@
   - [Utilisation d'un radiateur avec un fil pilote](#utilisation-dun-radiateur-avec-un-fil-pilote)
   - [Seul le premier radiateur chauffe](#seul-le-premier-radiateur-chauffe)
   - [Régler les paramètres de détection d'ouverture de fenêtre en mode auto](#régler-les-paramètres-de-détection-douverture-de-fenêtre-en-mode-auto)
+  - [Pourquoi mon Versatile Thermostat se met en Securite ?](#pourquoi-mon-versatile-thermostat-se-met-en-securite-)
+    - [Comment détecter le mode sécurité ?](#comment-détecter-le-mode-sécurité-)
+    - [Comment être averti lorsque cela se produit ?](#comment-être-averti-lorsque-cela-se-produit-)
+    - [Comment réparer ?](#comment-réparer-)
 
 Ce composant personnalisé pour Home Assistant est une mise à niveau et est une réécriture complète du composant "Awesome thermostat" (voir [Github](https://github.com/dadge/awesome_thermostat)) avec l'ajout de fonctionnalités.
 
@@ -497,7 +501,7 @@ Voir [exemple de réglages](#examples-tuning) pour avoir des exemples de réglag
 ## Synthèse des paramètres
 
 | Paramètre                                 | Libellé                                                                           | "over switch" | "over climate"      | over valve |
-| - | - | - | - | - |
+| ----------------------------------------- | --------------------------------------------------------------------------------- | ------------- | ------------------- | ---------- |
 | ``name``                                  | Nom                                                                               | X             | X                   | X          |
 | ``thermostat_type``                       | Type de thermostat                                                                | X             | X                   | X          |
 | ``temperature_sensor_entity_id``          | Temperature sensor entity id                                                      | X             | X (auto-regulation) | X          |
@@ -506,11 +510,11 @@ Voir [exemple de réglages](#examples-tuning) pour avoir des exemples de réglag
 | ``temp_min``                              | Température minimale permise                                                      | X             | X                   | X          |
 | ``temp_max``                              | Température maximale permise                                                      | X             | X                   | X          |
 | ``device_power``                          | Puissance de l'équipement                                                         | X             | X                   | X          |
-| ``use_window_feature`` | Avec détection des ouvertures | X | X | X |
+| ``use_window_feature``                    | Avec détection des ouvertures                                                     | X             | X                   | X          |
-| ``use_motion_feature`` | Avec détection de mouvement | X | X | X |
+| ``use_motion_feature``                    | Avec détection de mouvement                                                       | X             | X                   | X          |
 | ``use_power_feature``                     | Avec gestion de la puissance                                                      | X             | X                   | X          |
 | ``use_presence_feature``                  | Avec détection de présence                                                        | X             | X                   | X          |
-| ``heater_entity1_id`` | 1er radiateur | X | - | - |
+| ``heater_entity1_id``                     | 1er radiateur                                                                     | X             | -                   | -          |
 | ``heater_entity2_id``                     | 2ème radiateur                                                                    | X             | -                   | -          |
 | ``heater_entity3_id``                     | 3ème radiateur                                                                    | X             | -                   | -          |
 | ``heater_entity4_id``                     | 4ème radiateur                                                                    | X             | -                   | -          |
@@ -743,7 +747,7 @@ target:
     entity_id : climate.my_thermostat
 ```
 
-# Notifications
+# Evènements
 Les évènements marquant du thermostat sont notifiés par l'intermédiaire du bus de message.
 Les évènements notifiés sont les suivants:
 
@@ -770,7 +774,7 @@ Pour régler l'algorithme, vous avez accès à tout le contexte vu et calculé p
 Les attributs personnalisés sont les suivants :
 
 | Attribut                          | Signification                                                                                                                                                            |
-| ----------| --------|
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | ``hvac_modes``                    | La liste des modes supportés par le thermostat                                                                                                                           |
 | ``temp_min``                      | La température minimale                                                                                                                                                  |
 | ``temp_max``                      | La température maximale                                                                                                                                                  |
@@ -796,7 +800,7 @@ Les attributs personnalisés sont les suivants :
 | ``motion_state``                  | Le dernier état connu du capteur de mouvement. Aucun si le mouvement n'est pas configuré                                                                                 |
 | ``overpowering_state``            | Le dernier état connu du capteur surpuissant. Aucun si la gestion de l'alimentation n'est pas configurée                                                                 |
 | ``presence_state``                | Le dernier état connu du capteur de présence. Aucun si la gestion de présence n'est pas configurée                                                                       |
-| ``security_delay_min`` | Le délai avant de régler le mode de sécurité lorsque le capteur de température est éteint |
+| ``security_delay_min``            | Le délai avant d'activer le mode de sécurité lorsque un des 2 capteurs de température n'envoie plus de mesures                                                           |
 | ``security_min_on_percent``       | Pourcentage de chauffe en dessous duquel le thermostat ne passera pas en sécurité                                                                                        |
 | ``security_default_on_percent``   | Pourcentage de chauffe utilisé lorsque le thermostat est en sécurité                                                                                                     |
 | ``last_temperature_datetime``     | La date et l'heure au format ISO8866 de la dernière réception de température interne                                                                                     |
@@ -1150,6 +1154,54 @@ versatile_thermostat:
 
 Ces paramètres sont sensibles et assez difficiles à régler. Merci de ne les utiliser que si vous savez ce que vous faites et que vos mesures de température ne sont pas déjà lisses.
 
+## Pourquoi mon Versatile Thermostat se met en Securite ?
+Le mode sécurité n'est possible que sur les VTherm `over_switch` et `over_valve`. Il survient lorsqu'un des 2 thermomètres qui donne la température de la pièce ou la température extérieure n'a pas envoyé de valeur depuis plus de `security_delay_min` minutes et que le radiateur chauffait à au moins `security_min_on_percent`.
+
+Comme l'algorithme est basé sur les mesures de température, si elles ne sont plus reçues par le VTherm, il y a un risque de surchauffe et d'incendie. Pour éviter ça, lorsque les conditions rappelées ci-dessus sont détectées, la chauffe est limité au paramètre `security_default_on_percent`. Cette valeur doit donc être raisonnablement faible (10% est une bonne valeur). Elle permet d'éviter un incendie tout en évitant de couper totalement le radiateur (risque de gel).
+
+Tous ces paramètres se règlent dans la dernière page de la configuration du VTherm : "Paramètres avancés".
+
+### Comment détecter le mode sécurité ?
+Le premier symptôme est une température anormalement basse avec un temps de chauffe faible à chaque cycle et régulier.
+Exemple:
+
+[security mode](https://github.com/jmcollin78/versatile_thermostat/blob/main/images/security-mode-symptome1.png?raw=true)
+
+Si vous avez installé la carte [Versatile Thermostat UI Card](https://github.com/jmcollin78/versatile-thermostat-ui-card), le VTherm en question aura cette forme là :
+
+[security mode UI Card](https://github.com/jmcollin78/versatile_thermostat/blob/main/images/security-mode-symptome2.png?raw=true)
+
+Vous pouvez aussi vérifier dans les attributs du VTherm les dates de réception des différentes dates. **Les attributs sont disponibles dans les Outils de développement / Etats**.
+
+Exemple :
+```
+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
+```
+
+On voit que :
+1. le VTherm est bien en mode sécurité (`security_state: true`),
+2. l'heure courante est le 06/12/2023 à 18h43:28 (`last_update_datetime: "2023-12-06T18:43:28.351103+01:00"`),
+3. l'heure de dernière réception de la température intérieure est le 06/12/2023 à 18h43:28 (`last_temperature_datetime: "2023-12-06T18:43:28.346010+01:00"`). Elle est donc récente,
+4. l'heure de dernière réception de la température extérieure est le 06/12/2023 à 13h04:35 (`last_ext_temperature_datetime: "2023-12-06T13:04:35.164367+01:00`). C'est donc l'heure extérieure qui a plus de 5 h de retard et qui a provoquée le passage en mode sécurité, car le seuil est limité à 60 min (`security_delay_min: 60`).
+
+### Comment être averti lorsque cela se produit ?
+Pour être averti, le VTherm envoie un évènement dès que ça se produit et un en fin d'alerte sécurité. Vous pouvez capter ces évènements dans une automatisation et envoyer une notification par exemple, faire clignoter un voyant, déclencher une sirène, ... A vous de voir.
+
+Pour manipuler les évènements générés par le VTherm, cf. [Eveènements](#evènements).
+
+### Comment réparer ?
+Cela va dépendre de la cause du problème :
+1. Si un capteur est en défaut, il faut le réparer (remettre des piles, le changer, vérifier l'intégration Météo qui donne la température extérieure, ...),
+2. Si le paramètre `security_delay_min` est trop petit, cela rsique de générer beaucoup de fausses alertes. Une valeur correcte est de l'ordre de 60 min, surtout si vous avez des capteurs de température à pile.
+3. Certains capteurs de température, n'envoie pas de mesure si la température n'a pas changée. Donc en cas de température très stable pendant longtemps, le mode sécurité peut se déclencher. Ce n'est pas très grave puisqu'il s'enlève dès que le VTherm reçoit à nouveau une température. Sur certain thermomètre (TuYA par exemple), on peut forcer le délai max entre 2 mesures. Il conviendra de mettre un délai max < `security_delay_min`,
+4. Dès que la température sera a nouveau reçue le mode sécurité s'enlèvera et les valeurs précédentes de preset, température cible et mode seront restaurées.
+
+
 ***
 
 [versatile_thermostat]: https://github.com/jmcollin78/versatile_thermostat

README.md

@@ -48,7 +48,7 @@
   - [Change the temperature of presets](#change-the-temperature-of-presets)
   - [Change security settings](#change-security-settings)
   - [ByPass Window Check](#bypass-window-check)
-- [Notifications](#notifications)
+- [Events](#events)
 - [Custom attributes](#custom-attributes)
 - [Some results](#some-results)
 - [Even better](#even-better)
@@ -63,6 +63,10 @@
   - [Using a Heatsink with a Pilot Wire](#using-a-heatsink-with-a-pilot-wire)
   - [Only the first radiator heats](#only-the-first-radiator-heats)
   - [Adjust window opening detection parameters in auto mode](#adjust-window-opening-detection-parameters-in-auto-mode)
+  - [Why does my Versatile Thermostat go into Safety?](#why-does-my-versatile-thermostat-go-into-safety)
+    - [How to detect security mode?](#how-to-detect-security-mode)
+    - [How can I be notified when this happens?](#how-can-i-be-notified-when-this-happens)
+    - [How to repair?](#how-to-repair)
 
 
 This custom component for Home Assistant is an upgrade and is a complete rewrite of the component "Awesome thermostat" (see [Github](https://github.com/dadge/awesome_thermostat)) with addition of features.
@@ -480,7 +484,7 @@ See [example tuning](#examples-tuning) for common tuning examples
 ## Parameters synthesis
 
 | Paramètre                                 | Libellé                                                                       | "over switch" | "over climate"      | "over valve" |
-| ----------| --------| --- | --- | -- |
+| ----------------------------------------- | ----------------------------------------------------------------------------- | ------------- | ------------------- | ------------ |
 | ``name``                                  | Name                                                                          | X             | X                   | X            |
 | ``thermostat_type``                       | Thermostat type                                                               | X             | X                   | X            |
 | ``temperature_sensor_entity_id``          | Temperature sensor entity id                                                  | X             | X (self-regulation) | X            |
@@ -489,11 +493,11 @@ See [example tuning](#examples-tuning) for common tuning examples
 | ``temp_min``                              | Minimal temperature allowed                                                   | X             | X                   | X            |
 | ``temp_max``                              | Maximal temperature allowed                                                   | X             | X                   | X            |
 | ``device_power``                          | Device power                                                                  | X             | X                   | X            |
-| ``use_window_feature`` | Use window detection | X | X | X |
+| ``use_window_feature``                    | Use window detection                                                          | X             | X                   | X            |
-| ``use_motion_feature`` | Use motion detection | X | X | X |
+| ``use_motion_feature``                    | Use motion detection                                                          | X             | X                   | X            |
 | ``use_power_feature``                     | Use power management                                                          | X             | X                   | X            |
 | ``use_presence_feature``                  | Use presence detection                                                        | X             | X                   | X            |
-| ``heater_entity1_id`` | 1rst heater switch | X | - | - |
+| ``heater_entity1_id``                     | 1rst heater switch                                                            | X             | -                   | -            |
 | ``heater_entity2_id``                     | 2nd heater switch                                                             | X             | -                   | -            |
 | ``heater_entity3_id``                     | 3rd heater switch                                                             | X             | -                   | -            |
 | ``heater_entity4_id``                     | 4th heater switch                                                             | X             | -                   | -            |
@@ -725,7 +729,7 @@ target:
     entity_id : climate.my_thermostat
 ```
 
-# Notifications
+# Events
 Significant thermostat events are notified via the message bus.
 The notified events are as follows:
 
@@ -752,7 +756,7 @@ To tune the algorithm you have access to all context seen and calculted by the t
 Custom attributes are the following:
 
 | Attribute                         | Meaning                                                                                                                          |
-| ----------| --------|
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
 | ``hvac_modes``                    | The list of modes supported by the thermostat                                                                                    |
 | ``min_temp``                      | The minimal temperature                                                                                                          |
 | ``max_temp``                      | The maximal temperature                                                                                                          |
@@ -1130,6 +1134,54 @@ versatile_thermostat:
 
 These parameters are sensitive and quite difficult to adjust. Please only use them if you know what you are doing and your temperature measurements are not already smooth.
 
+## Why does my Versatile Thermostat go into Safety?
+Safety mode is only possible on VTherm `over_switch` and `over_valve`. It occurs when one of the 2 thermometers which gives the room temperature or the outside temperature has not sent a value for more than `security_delay_min` minutes and the radiator was heating at least `security_min_on_percent`.
+
+As the algorithm is based on temperature measurements, if they are no longer received by the VTherm, there is a risk of overheating and fire. To avoid this, when the conditions mentioned above are detected, heating is limited to the `security_default_on_percent` parameter. This value must therefore be reasonably low. It helps prevent a fire while avoiding completely cutting off the radiator (risk of freezing).
+
+All these parameters are adjusted on the last page of the VTherm configuration: “Advanced parameters”.
+
+### How to detect security mode?
+The first symptom is an abnormally low temperature with a slow and regular heating time in each cycle.
+Example:
+
+[security mode](https://github.com/jmcollin78/versatile_thermostat/blob/main/images/security-mode-symptome1.png?raw=true)
+
+If you installed the [Versatile Thermostat UI Card](https://github.com/jmcollin78/versatile-thermostat-ui-card), the VTherm in question will have this shape:
+
+[security mode UI Card](https://github.com/jmcollin78/versatile_thermostat/blob/main/images/security-mode-symptome2.png?raw=true)
+
+You can also check in the VTherm attributes the dates of receipt of the different dates. Attributes are available in Development Tools / Reports.
+
+Example :
+```
+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 see that :
+1. the VTherm is in security 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 received time of indoor temperature is 06/12/2023 at 18:43:28 (`last_temperature_datetime: "2023-12-06T18:43:28.346010+01:00"`). So she's on time,
+4. the last reception time of the outdoor temperature is 06/12/2023 at 1:04:35 p.m. (`last_ext_temperature_datetime: "2023-12-06T13:04:35.164367+01:00`). external time which is more than 5 hours late and which caused the switch to security mode, because the threshold is limited to 60 min (`security_delay_min: 60`)
+
+### How can I be notified when this happens?
+To be notified, the VTherm sends an event as soon as it happens and one at the end of the security alert. You can capture these events in an automation and send a notification for example, flash a light, trigger a siren, etc. It's up to you.
+
+To manipulate the events generated by VTherm, cf. [Events](#events).
+
+### How to repair?
+This will depend on the cause of the problem:
+1. If a sensor is faulty, it must be repaired (replace batteries, change it, check the Weather integration which gives the outside temperature, etc.),
+2. If the `security_delay_min` parameter is too small, it risks generating a lot of false alerts. A correct value is around 60 min, especially if you have battery-powered temperature sensors.
+3. Some temperature sensors do not send a measurement if the temperature has not changed. So in the event of a very stable temperature for a long time, the safety mode may be triggered. This is not very serious since it is removed as soon as the VTherm receives a temperature again. On certain thermometers (TuYA for example), you can force the maximum delay between 2 measurements. It will be appropriate to set a max delay < `security_delay_min`,
+4. As soon as the temperature is received again the security mode will be removed and the previous values of preset, target temperature and mode will be restored.
+
+
 ***
 
 [versatile_thermostat]: https://github.com/jmcollin78/versatile_thermostat