hoval-connect-api

Este repositorio proporciona documentación no oficial, obtenida por ingeniería inversa, de la API en la nube de Hoval Connect IoT junto con una integración personalizada de Home Assistant instalable mediante HACS. No está afiliado a Hoval y se presenta como sucesor de un proyecto anterior de puerta de enlace CAN-bus/MQTT; el enfoque en la nube no necesita hardware adicional, solo las credenciales de la cuenta de Hoval Connect. Capacidades de la integración La instalación se realiza añadiendo el repositorio como una integración personalizada de HACS, reiniciando Home Assistant e introduciendo el correo electrónico y la contraseña de Hoval Connect. Las plantas y los circuitos se descubren automáticamente. El README destaca que se requiere la versión 1.0.8 o posterior, porque Azure Application Gateway de Hoval rechaza las solicitudes cuyo User-Agent contiene "homeassistant"; la integración envía su propio identificador en su lugar. Al parecer, las versiones anteriores fallan con un HTTP 403 que se parece a un problema de credenciales o de red. Las entidades expuestas incluyen: - Entidad de ventilador por circuito de ventilación HV: control deslizante de velocidad continua de 0-100% con entrada con antirrebote, interruptor de encendido/apagado, modo de encendido configurable (reanudar el último programa semanal observado, o explícitamente week1/week2). - Entidad de clima por circuito de calefacción HK: temperatura objetivo, temperatura ambiente actual, modos HVAC Heat/Auto/Off y acción HVAC que refleja el estado del circuito. - Entidad de calentador de agua por circuito de agua caliente WW: temperatura objetivo de 10-65 C en pasos de 0,5 C como refuerzo temporal que expira a medianoche, además de modos de funcionamiento de bomba de calor y apagado. - Selección de programa por circuito HV/HK/WW: week1, week2, modo eco, standby, constante, mostrando nombres de programa definidos por el usuario y desambiguando duplicados. - Entidades de sensor filtradas por tipo de circuito, que cubren temperaturas exterior, de escape, de flujo, ambiente, de depósito y de acumulador, volumen de aire, humedad, CO2/VOC, estado de control, horas de funcionamiento, ciclos de conmutación, calor producido, energía consumida, modulación y valores relacionados. - Sensores a nivel de planta para condición meteorológica, temperatura prevista, tipo/mensaje/marca temporal del último evento y recuento de eventos activos. - Sensores binarios para en línea/fuera de línea, estado de error y estado de cambio temporal por circuito. - Exportación de diagnósticos con redacción automática de tokens, credenciales e ID de planta. Las opciones incluyen el modo de encendido, la duración de la anulación temporal y el intervalo de sondeo (60 s por defecto). Un servicio, hoval_connect.reset_temporary_change, cancela una anulación activa en una entidad de ventilador, clima o calentador de agua. Internamente, la integración utiliza gestión de tokens en dos pasos (token de ID más Plant Access Token) con caché TTL, actualización automática y bloqueo de vuelo único, omite las llamadas cuando una planta está fuera de línea, realiza obtenciones en paralelo con un número limitado de solicitudes de circuito en vuelo, serializa los comandos de control por planta y circuito y aplica caché por niveles para programas, eventos y meteorología. Admite el descubrimiento dinámico de nuevos circuitos sin reiniciar y normaliza las respuestas paginadas. Un Blueprint de Home Assistant incluido implementa un refuerzo de verano opcional que eleva el HomeVent al 90% en tardes cálidas cuando una habitación que no es oficina supera un umbral de confort y el aire exterior es moderado y más frío que el interior, finalizando según condiciones configurables. Se incluyen ejemplos independientes de Python y Bash/curl para leer valores en vivo, meteorología y eventos. Las limitaciones documentadas incluyen el soporte solo para circuitos HV, HK, BL, WW y PS (no solar ni agua dulce), sin edición de programas horarios, sin historial de energía o temperatura, sin control de modo vacaciones y una entrada de configuración por cuenta de Hoval. Los requisitos son una cuenta de Hoval Connect y Home Assistant 2024.11.0 o posterior. Documentación de la API El README documenta la arquitectura en la nube (dispositivo a puerta de enlace IoT a Azure IoT Hub a API central a aplicación/integración), las URL de la infraestructura y un flujo de autenticación en dos pasos: una concesión de contraseña OAuth2 contra SAP Cloud Identity Services que produce un token de ID (unos 30 minutos) usado como token Bearer, seguida de una llamada de configuración de planta que devuelve un Plant Access Token (unos 15 minutos) enviado como X-Plant-Access-Token. Enumera endpoints para bootstrap, configuración de usuario, plantas, contratos, configuración de planta, circuitos, programas, ajustes, cambios temporales, modo vacaciones y endpoints de socios, con ejemplos de cargas JSON y notas sobre tipos de circuito (HK, BL, WW, FRIWA, HV, SOL, SOLB, PS, GW). Registra un cambio de API de abril de 2026 que elimina los endpoints de circuito v1 en favor de v3 (y v4 para cambios temporales), describe endpoints de control que devuelven HTTP 204 y señala qué endpoints están documentados pero no probados.