皮維護理

皮維護理

該程式庫透過使用 Viessmann 開發者入口網站的官方 API 實現對 Viessmann 設備的存取。

2.27.x 版本中的重大更改

• 一些基類已被重新命名，以便為非加熱設備提供更好的支援。請參閱 PR #307

2.8.x 版本中的重大更改

• 電路、燃燒器（燃氣）和壓縮機（熱泵）現已分離。存取燒錄機/壓縮機的屬性已從device.circuits移至device.burners和device.compressor 。

2.x 版本中的重大更改

• 用於存取您裝置的 API 變更為通用PyViCare類別。使用此類加載所有可用設備。
• 用於存取設備加熱電路的 API 已移至Device類別。您現在可以透過device.circuits存取和迭代所有可用電路。這樣可以輕鬆查看哪些屬性取決於電路。

請參閱下面的範例以了解如何使用它。

1.x 版本中的重大更改

• 1.x先前的版本使用非官方API，該API於2021年7月15日停止運作。
• 如果程式庫遇到 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
   • 使用瀏覽器授權：已停用
   • 授權網址： https://iam.viessmann.com/idp/v3/authorize
   • 訪問令牌 URL： https://iam.viessmann.com/idp/v3/token ://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 ())