Documentation (not finished)

custom_components/versatile_thermostat/thermostat_climate_valve.py

@@ -52,10 +52,6 @@ def __init__(
         """Initialize the ThermostatOverClimateValve class"""
         _LOGGER.debug("%s - creating a ThermostatOverClimateValve VTherm", name)
         super().__init__(hass, unique_id, name, entry_infos)
-        # self._valve_open_percent: int = 0
-        # self._last_calculation_timestamp: datetime | None = None
-        # self._auto_regulation_dpercent: float | None = None
-        # self._auto_regulation_period_min: int | None = None
 
     @overrides
     def post_init(self, config_entry: ConfigData):
@@ -114,7 +110,8 @@ def update_custom_attributes(self):
         )
 
         self._attr_extra_state_attributes["underlyings_valve_regulation"] = [
-            underlying.entity_id for underlying in self._underlyings_valve_regulation
+            underlying.valve_entity_ids
+            for underlying in self._underlyings_valve_regulation
         ]
 
         self._attr_extra_state_attributes["on_percent"] = (

custom_components/versatile_thermostat/underlyings.py

@@ -1179,3 +1179,16 @@ def is_device_active(self):
             return get_safe_float(self._hass, self._opening_degree_entity_id) > 0
         except Exception:  # pylint: disable=broad-exception-caught
             return False
+
+    @property
+    def valve_entity_ids(self) -> [str]:
+        """get an arrary with all entityd id of the valve"""
+        ret = []
+        for entity in [
+            self.opening_degree_entity_id,
+            self.closing_degree_entity_id,
+            self.offset_calibration_entity_id,
+        ]:
+            if entity:
+                ret.append(entity)
+        return ret

documentation/fr/base-attributes.md

@@ -0,0 +1,42 @@
+# Choix des attributs de base
+
+Choisisez le menu "Principaux attributs".
+
+![image](images/config-main.png)
+
+Donnez les principaux attributs obligatoires. Ces attributs sont communs à tous les VTherms :
+1. un nom (sera le nom de l'intégration et aussi le nom de l'entité `climate`)
+4. un identifiant d'entité de capteur de température qui donne la température de la pièce dans laquelle le radiateur est installé,
+5. une entité facultative de capteur de donnant la date et heure de dernière vue du capteur (`last_seen`). Si vous avez ce capteur donnez le ici, il permet d'éviter des mises en sécurité lorsque la température est stable et que le capteur ne remonte plus de température pendant longtemps. (cf. TODO),
+6. une durée de cycle en minutes. A chaque cycle :
+   1. `over_switch` : VTherm allumera/éteindra le radiateur en modulant la proportion de temps allumé,
+   2. `over_valve` : VTherm calculera une nouvelle ouverture de la vanne et lui enverra si elle a changée,
+   3. `over_climate` : le cycle permet d'effectuer les contrôles de base et recalcule les coefficients de l'auto-régulation. Le cycle peut déboucher sur une nouvelle consigne envoyée au sous-jacents ou sur une modification d'ouverture de la vanne dans le cas d'un _TRV_ dont la vanne est commandable.
+8. une puissance de l'équipement ce qui va activer les capteurs de puissance et énergie consommée par l'appareil,
+9.  la possibilité d'utiliser des paramètres complémentaires venant de la configuration centralisée :
+    1.  capteur de température extérieure,
+    2.  température minimale / maximale et pas de température
+10. la possibilité de controler le thermostat de façon centralisée. Cf [controle centralisé](#le-contrôle-centralisé),
+11. 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,
+>  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
+
+Choisissez le menu "Fonctions".
+
+![image](images/config-features.png)
+
+Les différentes fonctions que vous souhaitez utiliser pour ce VTherm :
+1. la détection d'ouvertures (portes, fenêtres) permettant de stopper le chauffage lorsque l'ouverture est ouverte. (f. TODO)
+2. la détection de mouvement : VTherm peut adapter une consigne de température lorsqu'un mouvement est détecté dans la pièce. (cf. TODO)
+3. la gestion de la puissance : VTherm peut stopper un équipement si la puissance consommée dans votre habitation dépasse un seuil. (cf TODO)
+4. la détection de présence : si vous avez un capteur indiquant une présence ou non dans votre habitation, vous pouvez l'utiliser pour changer la température de consigne. CF. TODO. Attention de ne pas confondre cette fonction avec la détection de mouvement. La présence est plus faite pour être à l'échelle de l'habitation alors que le mouvement est plus fait pour être à l'échelle de la pièce.
+5. l'arrêt/démarrage automatique : pour les VTherm de type `over_climate` uniquement. Cette fonction permet d'arrêter un équipement lorsque VTherm détete qu'il ne sera plus néessaire pendant un certain temps. Il utilise la courbe de température pour prévoir quand l'équipement sera de nouveau utile et le rallumera à ce moment là.
+
+> ![Astuce](images/tips.png) _*Notes*_
+> 1. La liste des fonctions disponibles s'adapte à votre type de VTherm.
+> 2. Lorsque vous cochez une fonction, une nouvelle entrée menu s'ajoute pour configurer la fonction.
+> 3. Vous ne pourrez pas valider la création d'un VTherm si tous les paramètres de toutes les fonctions n'ont pas été saisis.

documentation/fr/creation.md

@@ -0,0 +1,61 @@
+# Choix du Vtherm
+
+> ![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.
+> 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
+
+![image](images/add-an-integration.png)
+
+puis
+
+![image](images/config-main0.png)
+
+La configuration peut être modifiée via la même interface. Sélectionnez simplement le thermostat à modifier, appuyez sur "Configurer" et vous pourrez modifier certains paramètres ou la configuration.
+
+Suivez ensuite les étapes de configuration en sélectionnant dans le menu l'option à configurer.
+
+# Choix d'un type de VTherm
+
+## Configuration centralisée
+Ce choix permet de configurer une fois pour tous les VTherms certains aspects qui peuvent être répétitifs comme :
+1. les paramètres des différents algorithmes (TPI, détection d'ouvertures, détection de mouvements, capteurs de puissance de votre habitation, la détection de présence). Tous ces paramètres sont transverses à tous les VTherms. Vous pouvez donc ne les saisir qu'une seule fois dans la `Configuration centralisée`. Cette configuration ne créé pas de VTherm à proprement parler. Elle permet juste de mettre en commun des paramètres qu'il serait fastidieux de resaisir pour chaque VTherm. Noter que vous pouvez surcharger les paramètres sur les VTherms pour les spécialisés au besoin,
+2. la configuration de la commande d'un chauffage central,
+3. certains paramètre avancés comme la mise en sécurité
+
+## VTherm sur un switch
+Ce VTherm permet de contrôler un interrupteur qui allume ou étient un radiateur. Cet interrupteur peut être un interrupteur physique qui allume ou éteint directement un radiateur (souvent électrique) ou un interrupteur virtuel qui pourra effectuer les actions que vous voulez sur demande d'allumage ou extinction. Ce dernier type permet par exemple de commander des switchs avec fil pilote ou deu DIY avec diode pour fil pilote. VTherm va moduler la proportion de temps allumé vs éteint pour obtenir la température souhaitée. Si il fait froid, il allume plus souvent (jusqu'à 100%), si il fait chaud il baisse le pourcentage d'allumage. Ce pourcentage d'allumage en nommé `on_percent`.
+
+Les entités sous-jacentes sont donc des `switchs` ou des `input_boolean`.
+
+## Vtherm sur un autre thermostat
+Lorsque votre équipement est contrôlé par une entité de type `climate` dans Home Assistant et que vous n'avez que ça à disposition, vous devez utiliser ce type de VTherm. Dans ce cas, le VTherm va simplement commander la température de consigne du `climate` sous-jacent.
+Ce type est aussi équipé de fonction d' auto-régulations avancées permettant de moduler la consigne donnée aux sous-jacent pour atteindre plus vite la consigne et de s'affranchir de la régulation interne de ces équipements qui est parfois mauvaise. C'est le cas, si le thermomètre interne de l'équipement est trop proche du corps de chauffe. L'équipement peut croire qu'il fait chaud alors qu'au bout de la pièce, la consigne n'est pas du tout atteinte.
+
+Depuis la version 6.8, ce type de VTherm permet aussi de réguler avec une action directe sur la vanne. Idéal pour les _TRV_ pour lesquels la vanne est commandable, ce type est recommandé si vous êtes équipés.
+
+Les entités sous-jacentes de ce type de VTherm sont donc des `climate` exclusivement.
+
+## VTherm sur une vanne
+Lorsque tout ce que vous avez à disposition pour réguler la température de votre radiateur est une entité de type `number` vous devez utiliser le type `over_valve`. VTherm ouvre ou ferme la vanne en fonction de l'écart entre la consigne et la température réelle de la pièce (et de la température extérieure).
+
+Ce type peut être utilisé pour les _TRV_ qui n'ont pas de `climate` associé ou tout autre solution type DIY qui expose une entité `number`.
+
+# Le bon choix
+> ![Astuce](images/tips.png) _*Comment choisir le type*_
+> Le choix du type est important. Il n'est plus possible de le modifier via l'IHM de configuration. Pour bien chsoisir, il faut se poser les quelques questions suivantes :
+> 1. **quel type d'équipement je vais piloter ?** Dans l'ordre voici ce qu'il faut faire :
+>    1. si vous avez une vanne thermostatique (_TRV_) commandable dans Home Assistant via une entité de type ```number``` (par exemple une _Shelly TRV_), choisissez le type `over_valve`. C'est le type le plus direct et qui assure la meilleure régulation,
+>    2. si vous avez un radiateur électrique (avec ou sans fil pilote) et qu'une entité de type ```switch``` permet de l'allumer ou de l'éteindre, alors le type ```over_switch``` est préférable. La régulation sera faite par le Versatile Thermostat en fonction de la température mesuré par votre thermomètre, à l'endroit ou vous l'avez placé,
+>    3. dans tous les autres cas, utilisez le mode ```over_climate```. Vous gardez votre entité ```climate``` d'origine et le Versatile Thermostat "ne fait que" piloter le on/off et la température cible de votre thermostat d'origine. La régulation est faite par votre thermostat d'origine dans ce cas. Ce mode est particulièrement adapté aux climatisations réversible tout-en-un dont l'exposition dans Home Assistant se limite à une entité de type ```climate```. Une auto-régulation avancée permet d'atteindre la consigne en forçant la consigne ou un pilotant directement la vanne lorsque c'est possible.
+> 2. **quelle type de régulation je veux ?** Si l'équipement piloté possède son propre mécanisme de régulation (clim, certaine vanne TRV) et que cette régulation fonctionne bien, optez pour un ```over_climate```. Si l'équipement est de type _TRV_ avec une vanne pilotable sous HA, alors le type `over_climate` avec une auto-régulation `Contrôle direct de la vanne` est le meilleur choix.
+
+# Article en référence
+Un article permettant d'aller plus loin sur les concepts est visible ici (en Français) : https://www.hacf.fr/optimisation-versatile-thermostat/#optimiser-vos-vtherm