ピビケア

ピビケア

このライブラリは、Viessmann Developer Portal の公式 API を使用して Viessmann デバイスへのアクセスを実装します。

バージョン 2.27.x の重大な変更

• 一部の基本クラスは、非加熱デバイスのサポートを向上させるために名前が変更されました。 PR #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. Authorizationタブで、タイプOAuth 2.0と次の入力を使用してアクセス トークンを作成します。

   • トークン名: 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. 上記のデータを使用して、この URL の{installationId} 、 {gatewaySerial}および{deviceId}を置き換えて、Viessmann API を調査します。

   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 ())