Об этом проекте

Этот репозиторий содержит неофициальную реверс-инженерную документацию облачного API Hoval Connect IoT вместе с пользовательской интеграцией Home Assistant, устанавливаемой через HACS. Он не связан с Hoval и представлен как преемник более раннего проекта шлюза CAN-шина/MQTT; облачный подход не требует дополнительного оборудования, только учётные данные Hoval Connect. Возможности интеграции Установка выполняется путём добавления репозитория как пользовательской интеграции HACS, перезапуска Home Assistant и ввода электронной почты и пароля Hoval Connect. Установки и контуры обнаруживаются автоматически. В README подчёркивается, что требуется версия 1.0.8 или новее, поскольку Azure Application Gateway компании Hoval отклоняет запросы, чей User-Agent содержит "homeassistant"; интеграция отправляет собственный идентификатор. Более старые выпуски, как сообщается, завершаются ошибкой HTTP 403, похожей на проблему с учётными данными или сетью. Предоставляемые сущности включают: - Сущность вентилятора для каждого вентиляционного контура HV: непрерывный ползунок скорости 0-100% с подавлением дребезга ввода, переключатель вкл/выкл, настраиваемый режим включения (возобновить последнюю наблюдавшуюся недельную программу или явно week1/week2). - Сущность климата для каждого отопительного контура HK: целевая температура, текущая температура в помещении, режимы HVAC Heat/Auto/Off и действие HVAC, отражающее состояние контура. - Сущность водонагревателя для каждого контура горячей воды WW: целевая температура 10-65 C с шагом 0,5 C в виде временного повышения, истекающего в полночь, плюс режимы работы теплового насоса и выключения. - Выбор программы для каждого контура HV/HK/WW: week1, week2, эко-режим, ожидание, постоянный, с отображением заданных пользователем названий программ и различением дубликатов. - Сущности датчиков, фильтруемые по типу контура, охватывающие температуры наружного воздуха, вытяжного воздуха, подачи, помещения, бака и буфера, объём воздуха, влажность, CO2/VOC, статус управления, часы работы, циклы переключения, выработанное тепло, потреблённую энергию, модуляцию и связанные значения. - Датчики уровня установки для погодных условий, прогнозируемой температуры, типа/сообщения/временной метки последнего события и количества активных событий. - Бинарные датчики для онлайн/офлайн, статуса ошибки и состояния временного изменения для каждого контура. - Экспорт диагностики с автоматическим скрытием токенов, учётных данных и идентификаторов установок. Опции включают режим включения, длительность временного переопределения и интервал опроса (по умолчанию 60 с). Служба hoval_connect.reset_temporary_change отменяет активное переопределение для сущности вентилятора, климата или водонагревателя. Внутри интеграция использует двухэтапное управление токенами (ID-токен плюс Plant Access Token) с кэшированием по TTL, автообновлением и блокировкой single-flight, пропускает вызовы, когда установка офлайн, выполняет параллельные запросы с ограниченным числом одновременных запросов к контурам, сериализует команды управления по установке и контуру и применяет многоуровневое кэширование для программ, событий и погоды. Она поддерживает динамическое обнаружение новых контуров без перезапуска и нормализует постраничные ответы. В комплект входит Home Assistant Blueprint, реализующий опциональный летний буст, который повышает HomeVent до 90% в тёплые дни после полудня, когда температура в неофисном помещении превышает порог комфорта, а наружный воздух умеренный и холоднее, чем внутри, и завершается при настраиваемых условиях. Приведены автономные примеры на Python и Bash/curl для чтения текущих значений, погоды и событий. Задокументированные ограничения включают поддержку только контуров HV, HK, BL, WW и PS (не солнечных и не свежей воды), отсутствие редактирования временных программ, отсутствие истории энергии и температуры, отсутствие управления режимом отпуска и одну запись конфигурации на аккаунт Hoval. Требования: учётная запись Hoval Connect и Home Assistant 2024.11.0 или новее. Документация API В README описана облачная архитектура (устройство — IoT-шлюз — Azure IoT Hub — основной API — приложение/интеграция), URL-адреса инфраструктуры и двухэтапный поток аутентификации: предоставление пароля OAuth2 к SAP Cloud Identity Services, дающее ID-токен (около 30 минут), используемый как Bearer-токен, затем вызов настроек установки, возвращающий Plant Access Token (около 15 минут), отправляемый как X-Plant-Access-Token. Перечислены конечные точки для начальной загрузки, пользовательских настроек, установок, контрактов, настроек установки, контуров, программ, настроек, временных изменений, режима отпуска и партнёрских конечных точек, с примерами JSON-полезной нагрузки и примечаниями о типах контуров (HK, BL, WW, FRIWA, HV, SOL, SOLB, PS, GW). Зафиксировано изменение API в апреле 2026 года, удаляющее конечные точки контуров v1 в пользу v3 (и v4 для временных изменений), описаны конечные точки управления, возвращающие HTTP 204, и отмечено, какие конечные точки задокументированы, но не протестированы.