openviess / PyViCare

Python Library to access Viessmann ViCare API
Apache License 2.0
140 stars 91 forks source link

PyViCare

This library implements access to Viessmann devices by using the official API from the Viessmann Developer Portal.

Breaking changes in version 2.27.x

Breaking changes in version 2.8.x

Breaking changes in version 2.x

See the example below for how you can use that.

Breaking changes in version 1.x

Prerequisites

To use PyViCare, every user has to register and create their personal API client. Follow these steps to create your client:

  1. Login to the Viessmann Developer Portal with your existing ViCare app username/password.
  2. On the developer dashboard click add in the clients section.
  3. Create a new client using following data:
    • Name: PyViCare
    • Google reCAPTCHA: Disabled
    • Redirect URIs: vicare://oauth-callback/everest
  4. Copy the Client ID to use in your code. Pass it as constructor parameter to the device.

Please note that not all properties from older versions and the ViCare mobile app are available in the new API. Missing properties were removed and might be added later if they are available again.

Help

We need help testing and improving PyViCare, since the maintainers only have specific types of heating systems. For bugs, questions or feature requests join the PyViCare channel on Discord or create an issue in this repository.

Device Features / Errors

Depending on the device, some features are not available/supported. This results in a raising of a PyViCareNotSupportedFeatureError if the dedicated method is called. This is most likely not a bug, but a limitation of the device itself.

Tip: You can use Pythons contextlib.suppress to handle it gracefully.

Types of heatings

Basic Usage:

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

API Usage in Postman

Follow these steps to access the API in Postman:

  1. Create an access token in the Authorization tab with type OAuth 2.0 and following inputs:

    • Token Name: PyViCare
    • Grant Type: Authorization Code (With PKCE)
    • Callback URL: vicare://oauth-callback/everest
    • Authorize using browser: Disabled
    • Auth URL: https://iam.viessmann.com/idp/v3/authorize
    • Access Token URL: https://iam.viessmann.com/idp/v3/token
    • Client ID: Your personal Client ID created in the developer portal.
    • Client Secret: Blank
    • Code Challenge Method: SHA-256
    • Code Veriefier: Blank
    • Scope: IoT User
    • State: Blank
    • Client Authentication: Send client credentials in body.

    A login popup will open. Enter your ViCare username and password.

  2. Use this URL to access your installationId, gatewaySerial and deviceId:

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

    • installationId is data[0].id
    • gatewaySerial is data[0].gateways[0].serial
    • deviceId is data[0].gateways[0].devices[0].id
  3. Use above data to replace {installationId}, {gatewaySerial} and {deviceId} in this URL to investigate the Viessmann API:

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

Rate Limits

Due to latest changes in the Viessmann API rate limits can be hit. In that case a PyViCareRateLimitError is raised. You can read from the error (limitResetDate) when the rate limit is reset.

More different devices for test cases needed

In order to help ensuring making it easier to create more test cases you can run this code and make a pull request with the new test of your device type added. Your test should be committed into tests/response and named <family><model>.

The code to run to make this happen is below. This automatically removes "sensitive" information like installation id and serial numbers. You can either replace default values or use the PYVICARE_* environment variables.

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