파이비케어

파이비케어

이 라이브러리는 Viessmann 개발자 포털의 공식 API를 사용하여 Viessmann 장치에 대한 액세스를 구현합니다.

버전 2.27.x의 주요 변경 사항

• 비 가열 장치에 대한 더 나은 지원을 제공하기 위해 일부 기본 클래스의 이름이 변경되었습니다. 홍보 #307 참조

버전 2.8.x의 주요 변경 사항

• 이제 회로, 버너(Gaz) 및 압축기(히트펌프)가 분리되었습니다. 버너/압축기의 속성에 대한 액세스가 device.circuits 에서 device.burners 및 device.compressor 로 이동되었습니다.

버전 2.x의 주요 변경 사항

• 장치에 액세스하기 위한 API가 일반 PyViCare 클래스로 변경되었습니다. 이 클래스를 사용하여 사용 가능한 모든 장치를 로드합니다.
• 장치의 가열 회로에 액세스하기 위한 API가 Device 클래스로 이동되었습니다. 이제 device.circuits 통해 사용 가능한 모든 회로에 액세스하고 반복할 수 있습니다. 이를 통해 회로에 따라 어떤 속성이 달라지는지 쉽게 확인할 수 있습니다.

이를 사용하는 방법은 아래 예를 참조하세요.

버전 1.x의 주요 변경 사항

• 1.x 이전 버전은 2021년 7월 15일에 작동이 중단된 비공식 API를 사용했습니다. API를 계속 사용하려면 모든 사용자가 버전 1.0.0으로 마이그레이션해야 합니다.
• 라이브러리가 API 속도 제한에 도달하면 예외가 발생합니다. (기능 플래그 raise_exception_on_rate_limit 참조)
• 지원되지 않는 장치 기능이 사용되면 예외가 발생합니다. (기능 플래그 raise_exception_on_not_supported_device_feature 참조)
• Python 3.4는 더 이상 지원되지 않습니다.
• 이제 Python 3.9가 지원됩니다.

전제 조건

PyViCare를 사용하려면 모든 사용자는 개인 API 클라이언트를 등록하고 생성해야 합니다. 클라이언트를 생성하려면 다음 단계를 따르세요.

1. 기존 ViCare 앱 사용자 이름/비밀번호를 사용하여 Viessmann 개발자 포털에 로그인하세요.
2. 개발자 대시보드의 클라이언트 섹션에서 추가를 클릭하세요.
3. 다음 데이터를 사용하여 새 클라이언트를 만듭니다.
   • 이름: PyViCare
   • Google reCAPTCHA: 비활성화됨
   • 리디렉션 URI: vicare://oauth-callback/everest
4. 코드에 사용할 Client ID 복사하세요. 장치에 생성자 매개변수로 전달합니다.

이전 버전과 ViCare 모바일 앱의 모든 자산을 새 API에서 사용할 수 있는 것은 아닙니다. 누락된 속성은 제거되었으며 나중에 다시 사용할 수 있게 되면 추가될 수 있습니다.

돕다

관리자는 특정 유형의 난방 시스템만 보유하고 있으므로 PyViCare를 테스트하고 개선하는 데 도움이 필요합니다. 버그, 질문 또는 기능 요청의 경우 Discord의 PyViCare 채널에 가입하거나 이 저장소에 문제를 생성하세요.

장치 기능/오류

기기에 따라 일부 기능을 사용할 수 없거나 지원하지 않을 수 있습니다. 이로 인해 전용 메서드가 호출되면 PyViCareNotSupportedFeatureError 가 발생합니다. 이는 버그가 아니라 장치 자체의 제한일 가능성이 높습니다.

팁: Python contextlib.suppress를 사용하여 적절하게 처리할 수 있습니다.

난방 유형

• 가스 가열에는 asGazBoiler 사용
• 히트펌프용 asHeatPump 사용
• 연료전지용 asFuelCell 사용
• 펠릿 가열을 위해 asPelletsBoiler 사용
• 석유 가열을 위해 asOilBoiler 사용
• 가스/히트펌프 하이브리드 난방에 asHybridDevice 사용

기본 사용법:

 import sys
import logging
from PyViCare . PyViCare import PyViCare

client_id = "INSERT CLIENT ID"
email = "email@domain"
password = "password"

vicare = PyViCare ()
vicare . initWithCredentials ( email , password , client_id , "token.save" )
device = vicare . devices [ 0 ]
print ( device . getModel ())
print ( "Online" if device . isOnline () else "Offline" )

t = device . asAutoDetectDevice ()
print ( t . getDomesticHotWaterConfiguredTemperature ())
print ( t . getDomesticHotWaterStorageTemperature ())
print ( t . getOutsideTemperature ())
print ( t . getRoomTemperature ())
print ( t . getBoilerTemperature ())
print ( t . setDomesticHotWaterTemperature ( 59 ))

circuit = t . circuits [ 0 ] #select heating circuit

print ( circuit . getSupplyTemperature ())
print ( circuit . getHeatingCurveShift ())
print ( circuit . getHeatingCurveSlope ())

print ( circuit . getActiveProgram ())
print ( circuit . getPrograms ())

print ( circuit . getCurrentDesiredTemperature ())
print ( circuit . getDesiredTemperatureForProgram ( "comfort" ))
print ( circuit . getActiveMode ())

print ( circuit . getDesiredTemperatureForProgram ( "comfort" ))
print ( circuit . setProgramTemperature ( "comfort" , 21 ))
print ( circuit . activateProgram ( "comfort" ))
print ( circuit . deactivateComfort ())

burner = t . burners [ 0 ] #select burner
print ( burner . getActive ())

compressor = t . compressors [ 0 ] #select compressor
print ( compressor . getActive ())

Postman의 API 사용

Postman에서 API에 액세스하려면 다음 단계를 따르세요.

1. OAuth 2.0 유형과 다음 입력을 사용하여 Authorization 탭에서 액세스 토큰을 만듭니다.

   • 토큰 이름: PyViCare
   • 부여 유형: Authorization Code (With PKCE)
   • 콜백 URL: vicare://oauth-callback/everest
   • 브라우저를 사용하여 승인: 비활성화됨
   • 인증 URL: https://iam.viessmann.com/idp/v3/authorize
   • 액세스 토큰 URL: https://iam.viessmann.com/idp/v3/token
   • 클라이언트 ID: 개발자 포털에서 생성된 개인 클라이언트 ID입니다.
   • 클라이언트 비밀번호: 공백
   • 코드 챌린지 방법: SHA-256
   • 코드 검증기: 공백
   • 범위: IoT User
   • 상태: 공백
   • 클라이언트 인증: Send client credentials in body .

   로그인 팝업이 열립니다. ViCare 사용자 이름과 비밀번호를 입력하세요.

2. 이 URL을 사용하여 installationId , gatewaySerial 및 deviceId 에 액세스하세요.

   https://api.viessmann.com/iot/v1/equipment/installations?includeGateways=true

   • installationId data[0].id 입니다.
   • gatewaySerial 은 data[0].gateways[0].serial 입니다.
   • deviceId 는 data[0].gateways[0].devices[0].id 입니다.

3. Viessmann API를 조사하려면 위 데이터를 사용하여 이 URL에서 {installationId} , {gatewaySerial} 및 {deviceId} 를 교체하세요.

   https://api.viessmann.com/iot/v1/features/installations/{installationId}/gateways/{gatewaySerial}/devices/{deviceId}/features

비율 제한

Viessmann API 비율 제한의 최신 변경으로 인해 도달할 수 있습니다. 이 경우 PyViCareRateLimitError 가 발생합니다. 비율 제한이 재설정되면 오류( limitResetDate )에서 읽을 수 있습니다.

테스트 케이스를 위한 더 다양한 장치 필요

더 많은 테스트 사례를 더 쉽게 생성할 수 있도록 이 코드를 실행하고 추가된 장치 유형의 새 테스트로 끌어오기 요청을 만들 수 있습니다. 테스트는 테스트/응답에 커밋되어야 하며 이름은 이어야 합니다.

이를 실행하기 위해 실행하는 코드는 다음과 같습니다. 이렇게 하면 설치 ID 및 일련번호와 같은 "민감한" 정보가 자동으로 제거됩니다. 기본값을 바꾸거나 PYVICARE_* 환경 변수를 사용할 수 있습니다.

 import sys
import os
from PyViCare . PyViCare import PyViCare

client_id = os . getenv ( "PYVICARE_CLIENT_ID" , "INSERT CLIENT_ID" )
email = os . getenv ( "PYVICARE_EMAIL" , "email@domain" )
password = os . getenv ( "PYVICARE_PASSWORD" , "password" )

vicare = PyViCare ()
vicare . initWithCredentials ( email , password , client_id , "token.save" )

with open ( f"dump.json" , mode = 'w' ) as output :
   output . write ( vicare . devices [ 0 ]. dump_secure ())