À propos du projet

Ce dépôt fournit une documentation non officielle, obtenue par rétro-ingénierie, de l'API cloud Hoval Connect IoT, ainsi qu'une intégration personnalisée Home Assistant installable via HACS. Il n'est pas affilié à Hoval et se présente comme le successeur d'un projet antérieur de passerelle CAN-bus/MQTT ; l'approche cloud ne nécessite aucun matériel supplémentaire, seulement les identifiants du compte Hoval Connect. Capacités de l'intégration L'installation se fait en ajoutant le dépôt comme intégration HACS personnalisée, en redémarrant Home Assistant, puis en saisissant l'e-mail et le mot de passe Hoval Connect. Les installations et les circuits sont découverts automatiquement. Le README souligne que la version 1.0.8 ou ultérieure est requise, car l'Azure Application Gateway de Hoval rejette les requêtes dont le User-Agent contient « homeassistant » ; l'intégration envoie son propre identifiant à la place. Les versions plus anciennes échoueraient avec un HTTP 403 ressemblant à un problème d'identifiants ou de réseau. Les entités exposées comprennent : - Une entité Fan par circuit de ventilation HV : curseur de vitesse continu de 0 à 100 % avec entrée anti-rebond, bascule marche/arrêt, mode d'activation configurable (reprendre le dernier programme hebdomadaire observé, ou explicitement week1/week2). - Une entité Climate par circuit de chauffage HK : température cible, température ambiante actuelle, modes HVAC Heat/Auto/Off, et action HVAC reflétant l'état du circuit. - Une entité Water heater par circuit d'eau chaude sanitaire WW : température cible de 10 à 65 C par pas de 0,5 C sous forme de boost temporaire expirant à minuit, plus les modes de fonctionnement pompe à chaleur et arrêt. - Une sélection de programme par circuit HV/HK/WW : week1, week2, mode éco, veille, constant, affichant les noms de programmes définis par l'utilisateur et distinguant les doublons. - Des entités Sensor filtrées par type de circuit, couvrant les températures extérieure, d'extraction, de départ, ambiante, de ballon et de tampon, le volume d'air, l'humidité, le CO2/VOC, l'état de régulation, les heures de fonctionnement, les cycles de commutation, la chaleur produite, l'énergie consommée, la modulation et des valeurs associées. - Des capteurs au niveau de l'installation pour la condition météo, la température prévue, le dernier type/message/horodatage d'événement et le nombre d'événements actifs. - Des binary sensors pour en ligne/hors ligne, l'état d'erreur et l'état de modification temporaire par circuit. - Une exportation de diagnostics avec caviardage automatique des jetons, identifiants et identifiants d'installation. Les options incluent le mode d'activation, la durée de dérogation temporaire et l'intervalle d'interrogation (60 s par défaut). Un service, hoval_connect.reset_temporary_change, annule une dérogation active sur une entité fan, climate ou water heater. En interne, l'intégration utilise une gestion de jetons en deux étapes (jeton d'ID plus Plant Access Token) avec mise en cache TTL, rafraîchissement automatique et verrouillage single-flight, ignore les appels lorsqu'une installation est hors ligne, effectue des récupérations parallèles avec un nombre borné de requêtes de circuit en vol, sérialise les commandes de contrôle par installation et par circuit, et applique une mise en cache par niveaux pour les programmes, les événements et la météo. Elle prend en charge la découverte dynamique de nouveaux circuits sans redémarrage et normalise les réponses paginées. Un Blueprint Home Assistant inclus met en œuvre un boost estival optionnel qui porte le HomeVent à 90 % les après-midis chauds lorsqu'une pièce non-bureau dépasse un seuil de confort et que l'air extérieur est modéré et plus frais que l'intérieur, avec fin sur conditions configurables. Des exemples autonomes en Python et Bash/curl sont inclus pour lire les valeurs en direct, la météo et les événements. Les limitations documentées incluent la prise en charge des circuits HV, HK, BL, WW et PS uniquement (pas le solaire ni l'eau fraîche), l'absence d'édition des programmes horaires, l'absence d'historique d'énergie ou de température, l'absence de contrôle du mode vacances, et une seule entrée de configuration par compte Hoval. Les prérequis sont un compte Hoval Connect et Home Assistant 2024.11.0 ou ultérieur. Documentation de l'API Le README documente l'architecture cloud (appareil vers passerelle IoT vers Azure IoT Hub vers API cœur vers application/intégration), les URL d'infrastructure et un flux d'authentification en deux étapes : une autorisation par mot de passe OAuth2 auprès de SAP Cloud Identity Services produisant un jeton d'ID (environ 30 minutes) utilisé comme Bearer token, suivie d'un appel aux paramètres d'installation renvoyant un Plant Access Token (environ 15 minutes) envoyé comme X-Plant-Access-Token. Il liste les endpoints pour le bootstrap, les paramètres utilisateur, les installations, les contrats, les paramètres d'installation, les circuits, les programmes, les réglages, les modifications temporaires, le mode vacances et les endpoints partenaires, avec des exemples de charges utiles JSON et des notes sur les types de circuits (HK, BL, WW, FRIWA, HV, SOL, SOLB, PS, GW). Il consigne un changement d'API d'avril 2026 supprimant les endpoints de circuit v1 au profit de v3 (et v4 pour les modifications temporaires), décrit les endpoints de contrôle renvoyant HTTP 204, et indique quels endpoints sont documentés mais non testés.