hoval-connect-api

This repository provides unofficial, reverse-engineered documentation of the Hoval Connect IoT cloud API together with a Home Assistant custom integration installable through HACS. It is not affiliated with Hoval and is presented as a successor to an earlier CAN-bus/MQTT gateway project; the cloud approach needs no extra hardware, only Hoval Connect account credentials. Integration capabilities Installation is done by adding the repository as a custom HACS integration, restarting Home Assistant, and entering the Hoval Connect email and password. Plants and circuits are discovered automatically. The README stresses that version 1.0.8 or newer is required, because Hoval's Azure Application Gateway rejects requests whose User-Agent contains "homeassistant"; the integration sends its own identifier instead. Older releases reportedly fail with an HTTP 403 that resembles a credential or network problem. Entities exposed include: - Fan entity per HV ventilation circuit: continuous 0-100% speed slider with debounced input, on/off toggle, configurable turn-on mode (resume last observed week program, or explicitly week1/week2). - Climate entity per HK heating circuit: target temperature, current room temperature, HVAC modes Heat/Auto/Off, and HVAC action reflecting circuit status. - Water heater entity per WW hot-water circuit: target temperature 10-65 C in 0.5 C steps as a temporary boost expiring at midnight, plus heat-pump and off operation modes. - Program select per HV/HK/WW circuit: week1, week2, eco mode, standby, constant, showing user-defined program names and disambiguating duplicates. - Sensor entities filtered by circuit type, covering outside, exhaust, flow, room, tank and buffer temperatures, air volume, humidity, CO2/VOC, control status, operating hours, switching cycles, heat produced, energy consumed, modulation and related values. - Plant-level sensors for weather condition, forecast temperature, latest event type/message/timestamp and active event count. - Binary sensors for online/offline, error status, and temporary-change state per circuit. - Diagnostics export with automatic redaction of tokens, credentials and plant IDs. Options include turn-on mode, temporary override duration, and polling interval (default 60 s). A service, hoval_connect.reset_temporary_change, cancels an active override on a fan, climate or water-heater entity. Internally the integration uses two-step token management (ID token plus Plant Access Token) with TTL caching, auto-refresh and single-flight locking, skips calls when a plant is offline, performs parallel fetches with a bounded number of in-flight circuit requests, serializes control commands per plant and circuit, and applies tiered caching for programs, events and weather. It supports dynamic discovery of new circuits without restart and normalizes paginated responses. A bundled Home Assistant Blueprint implements an optional summer boost that raises the HomeVent to 90% on warm afternoons when a non-office room exceeds a comfort threshold and outside air is moderate and cooler than indoors, ending on configurable conditions. Standalone Python and Bash/curl examples are included for reading live values, weather and events. Documented limitations include support for HV, HK, BL, WW and PS circuits only (not solar or fresh-water), no time-program editing, no energy or temperature history, no holiday mode control, and one config entry per Hoval account. Requirements are a Hoval Connect account and Home Assistant 2024.11.0 or newer. API documentation The README documents the cloud architecture (device to IoT gateway to Azure IoT Hub to core API to app/integration), infrastructure URLs, and a two-step authentication flow: an OAuth2 password grant against SAP Cloud Identity Services yielding an ID token (about 30 minutes) used as Bearer token, followed by a plant settings call returning a Plant Access Token (about 15 minutes) sent as X-Plant-Access-Token. It lists endpoints for bootstrap, user settings, plants, contracts, plant settings, circuits, programs, settings, temporary changes, holiday mode and partner endpoints, with example JSON payloads and notes on circuit types (HK, BL, WW, FRIWA, HV, SOL, SOLB, PS, GW). It records an April 2026 API change removing v1 circuit endpoints in favor of v3 (and v4 for temporary changes), describes control endpoints returning HTTP 204, and notes which endpoints are documented but untested.