皮维护理

皮维护理

该库通过使用 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日停止工作。所有用户需要迁移到版本1.0.0才能继续使用该API。
• 如果库遇到 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
   • 谷歌 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 ())