first version of the boiler controlled by ebusd

docs/radiator-heating.md

@@ -0,0 +1,107 @@
+# Chauffage radiateurs — AppDaemon et C6
+
+L'app `radiator_heating` expose `climate.radiator_heating` par MQTT Discovery.
+Les publications utilisent le service `mqtt.publish` de Home Assistant, comme
+l'ancienne implémentation de SmartObject. Aucun identifiant MQTT supplémentaire
+ni plugin MQTT AppDaemon n'est nécessaire.
+
+## Fichiers
+
+- `apps/boilerclimate.py` : MQTT Discovery, consigne, mode, mesures et commandes.
+- `apps/boilerregulator.py` : calcul indépendant de la température d'eau.
+- `apps/global/heating.yaml`, bloc `radiator_heating` : paramètres actifs de l'app.
+- `homeassistant/packages/radiator_heating_mqtt.yaml` : copie des deux
+  automatisations installées via l'API de configuration de Home Assistant.
+  Ne pas inclure aussi cette copie comme package : les automatisations existent
+  déjà dans Home Assistant. Leur modification dans cette copie ne les redéploie pas.
+
+## Régulation
+
+Avec S la consigne ambiante, Ti la température du couloir et Te celle de devant :
+
+    courbe = S + pente × (S − Te) + décalage
+    correction P = kp × (S − Ti)
+    correction I += ki × (S − Ti) × durée_en_heures
+    demande = courbe + correction bornée(P + I)
+
+La sortie est arrondie au demi-degré et limitée entre 30 et 50 °C initialement.
+`ki` est exprimé en degrés d'eau par degré d'écart intérieur et par heure.
+Les bornes de sortie et de correction disposent d'une protection anti-windup.
+L'intégrale est remise à zéro à l'arrêt, en cas de mesure invalide, au changement
+manuel de consigne et au redémarrage. Consigne et mode sont persistés dans
+`apps/data/appdaemon_radiator_heating.json`, exclu de Git.
+Une sauvegarde absente au premier lancement utilise la configuration initiale.
+Une sauvegarde illisible ou invalide impose le mode `off` avec un avertissement.
+Une erreur d'écriture est journalisée sans bloquer la commande chaudière,
+notamment l'arrêt demandé par l'utilisateur ou l'arrêt ordonné de l'app.
+
+À l'équilibre, la chauffe peut rester demandée même lorsque Ti = S.
+L'app inhibe le chauffage si Ti >= S + 0,5 °C, ou si la demande calculée descend
+sous la température minimale utile (avec une hystérésis de 1 °C d'eau).
+Après arrêt, le redémarrage exige Ti <= S + 0,1 °C et une demande suffisante.
+Les gains sont des valeurs initiales à ajuster après les essais de circulation,
+pas des coefficients identifiés pour cette maison.
+
+Les deux capteurs doivent fournir des valeurs finies en °C, entre −40 et 60 °C.
+Une température inchangée, même ancienne, reste valide : ces sondes peuvent
+ne publier qu'en cas de changement. Aucun délai sur l'âge de la mesure n'est
+appliqué. Les états indisponibles/inconnus, les valeurs invalides et les unités
+incorrectes provoquent toujours l'inhibition. Une sonde déconnectée conservant
+une valeur plausible n'est donc pas détectée par ce contrôle.
+
+Un défaut publie un log ERROR avec l'identifiant, le nom du capteur et sa cause
+(état invalide, unité ou valeur incohérente). Le log est émis
+à l'apparition du défaut ou au changement des capteurs concernés, sans répétition
+chaque minute. Le détail actualisé reste disponible dans l'attribut `sensor_error`
+du capteur « État de la régulation », même quand le climate est indisponible.
+Un log INFO signale le rétablissement. L'app utilise le pipeline standard
+`LoggerInterface` (`log_info`, `log_warning`, `log_error`) ; les erreurs sont
+également envoyées dans `error_log`. L'option `ascii_encode=False`, propre à
+cette app, conserve les accents et le symbole °C.
+
+## MQTT et disponibilité
+
+- Configuration : `homeassistant/climate/appdaemon_radiator_heating/config`.
+- Commandes utilisateur : `appdaemon/radiator_heating/command/mode` (`heat`/`off`)
+  et `/command/temperature` (consigne ambiante entre 10 et 23 °C).
+- État et diagnostics : `appdaemon/radiator_heating/state` et `/attributes`.
+- Chaudière : `themaplus-condens/bai/SetMode/set`.
+
+L'automatisation de retour transmet les commandes MQTT et les retours chaudière
+à l'événement `APPDAEMON_BOILER_MQTT`, écouté par l'app. Le watchdog marque le
+climate indisponible après trois minutes sans heartbeat. Il ne commande PAS
+la chaudière : il signale l'arrêt de l'app. Configuration et états sont retenus ;
+les commandes utilisateur et chaudière ne doivent jamais être retenues.
+
+`SetMode` est renouvelé chaque minute et lors d'un changement de demande.
+Les retours de télémétrie ne renouvellent pas la commande. Un arrêt ordonné
+publie une inhibition du chauffage ; un crash repose sur l'expiration observée
+de la commande chaudière. Les champs de consigne ECS sont `null` et les bits
+d'inhibition sanitaire restent à zéro.
+
+`heating_requested` désigne la demande de l'app. L'action `heating` du climate
+n'est annoncée qu'avec un état chaudière S.04 récent et est actualisée dès
+réception du statut, sans recalcul ni renouvellement de commande ; une chauffe sanitaire
+n'est pas comptée comme chauffage des radiateurs. Sans télémétrie récente,
+`idle` ne constitue pas une preuve d'absence de flamme : consulter aussi la
+chaudière. L'écho SetMode confirme une transmission C6, pas la consigne effective.
+
+## Essais actuels
+
+Les écritures sont autorisées (`send_commands: true`), pont thermostat fermé.
+Le climate démarre en mode `heat`, consigne 18 °C, sauf état utilisateur persisté.
+Un couloir plus chaud que la consigne entraîne normalement une inhibition.
+Le retour au réglage local de 10 °C après environ 15 minutes sans renouvellement
+a été observé pont ouvert. L'arrêt réel après perte de communication reste à
+vérifier avec circulation autorisée ; ce délai n'est pas une coupure immédiate.
+
+Un premier essai pont fermé avec une consigne ambiante de 23 °C a produit une
+demande d'eau à 46 °C et un démarrage de la chauffe. Les réglages restent à
+ajuster selon l'évolution réelle des températures. Ne pas modifier les mesures
+réelles pour simuler la chauffe.
+`send_commands: false` permet de conserver l'interface et les calculs sans écrire
+SetMode. Les lectures de télémétrie continuent.
+
+## Vérification
+
+    python -m unittest discover -s tests -p test_boilerclimate.py -v