프로젝트 소개

이 저장소는 Hoval Connect IoT 클라우드 API에 대한 비공식 리버스 엔지니어링 문서와 HACS를 통해 설치 가능한 Home Assistant 커스텀 통합을 제공합니다. Hoval과 제휴 관계가 없으며, 이전 CAN 버스/MQTT 게이트웨이 프로젝트의 후속으로 제시됩니다. 클라우드 방식은 추가 하드웨어가 필요 없고 Hoval Connect 계정 자격 증명만 있으면 됩니다. 통합 기능 설치는 저장소를 커스텀 HACS 통합으로 추가하고 Home Assistant를 재시작한 뒤 Hoval Connect 이메일과 비밀번호를 입력하면 됩니다. 플랜트와 회로는 자동으로 검색됩니다. README는 버전 1.0.8 이상이 필요하다고 강조합니다. Hoval의 Azure Application Gateway가 User-Agent에 "homeassistant"가 포함된 요청을 거부하기 때문이며, 통합은 자체 식별자를 대신 전송합니다. 이전 릴리스는 자격 증명 또는 네트워크 문제처럼 보이는 HTTP 403으로 실패한다고 보고됩니다. 노출되는 엔티티는 다음과 같습니다: - HV 환기 회로당 팬 엔티티: 디바운스 입력이 있는 연속 0-100% 속도 슬라이더, 켜기/끄기 토글, 구성 가능한 켜기 모드(마지막으로 관찰된 주간 프로그램 재개 또는 명시적 week1/week2). - HK 난방 회로당 기후 엔티티: 목표 온도, 현재 실내 온도, HVAC 모드 Heat/Auto/Off, 회로 상태를 반영하는 HVAC 동작. - WW 온수 회로당 온수기 엔티티: 자정에 만료되는 임시 부스트로서 0.5 C 단위로 10-65 C 목표 온도, 그리고 히트펌프 및 끄기 작동 모드. - HV/HK/WW 회로당 프로그램 선택: week1, week2, 에코 모드, 대기, 상수, 사용자 정의 프로그램 이름 표시 및 중복 구분. - 회로 유형별로 필터링된 센서 엔티티: 외기, 배기, 유량, 실내, 탱크 및 버퍼 온도, 풍량, 습도, CO2/VOC, 제어 상태, 작동 시간, 스위칭 사이클, 생성 열, 소비 에너지, 변조 및 관련 값. - 플랜트 수준 센서: 날씨 상태, 예보 온도, 최신 이벤트 유형/메시지/타임스탬프 및 활성 이벤트 수. - 회로당 온라인/오프라인, 오류 상태, 임시 변경 상태에 대한 바이너리 센서. - 토큰, 자격 증명, 플랜트 ID를 자동으로 삭제하는 진단 내보내기. 옵션에는 켜기 모드, 임시 재정의 지속 시간, 폴링 간격(기본 60초)이 있습니다. 서비스 hoval_connect.reset_temporary_change는 팬, 기후 또는 온수기 엔티티의 활성 재정의를 취소합니다. 내부적으로 통합은 TTL 캐싱, 자동 새로 고침, 단일 비행 잠금을 사용하는 2단계 토큰 관리(ID 토큰 + Plant Access Token)를 사용하고, 플랜트가 오프라인이면 호출을 건너뛰고, 제한된 수의 진행 중 회로 요청으로 병렬 가져오기를 수행하며, 플랜트 및 회로별 제어 명령을 직렬화하고, 프로그램, 이벤트, 날씨에 계층적 캐싱을 적용합니다. 재시작 없이 새 회로의 동적 검색을 지원하고 페이지가 매겨진 응답을 정규화합니다. 번들로 제공되는 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, 2단계 인증 흐름을 문서화합니다. SAP Cloud Identity Services에 대한 OAuth2 비밀번호 그랜트로 ID 토큰(약 30분)을 얻어 Bearer 토큰으로 사용하고, 이어서 플랜트 설정 호출로 Plant Access Token(약 15분)을 반환받아 X-Plant-Access-Token으로 전송합니다. 부트스트랩, 사용자 설정, 플랜트, 계약, 플랜트 설정, 회로, 프로그램, 설정, 임시 변경, 휴가 모드 및 파트너 엔드포인트에 대한 엔드포인트를 예제 JSON 페이로드와 회로 유형(HK, BL, WW, FRIWA, HV, SOL, SOLB, PS, GW)에 대한 참고 사항과 함께 나열합니다. 2026년 4월 API 변경으로 v1 회로 엔드포인트가 제거되고 v3(임시 변경의 경우 v4)이 선호된다는 점을 기록하고, HTTP 204를 반환하는 제어 엔드포인트를 설명하며, 문서화되었지만 테스트되지 않은 엔드포인트를 명시합니다.