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

  • Some base classes have been renamed to provide a better support for non heating devices. See PR #307

Breaking changes in version 2.8.x

  • The circuit, burner (Gaz) and compressor (Heat Pump) is now separated. Accessing the properties of the burner/compressor is moved from device.circuits to device.burners and device.compressor.

Breaking changes in version 2.x

  • The API to access your device changed to a general PyViCare class. Use this class to load all available devices.
  • The API to access the heating circuit of the device has moved to the Device class. You can now access and iterate over all available circuits via device.circuits. This allows to easily see which properties are depending on the circuit.

See the example below for how you can use that.

Breaking changes in version 1.x

  • The versions prior to 1.x used an unofficial API which stopped working on July, 15th 2021. All users need to migrate to version 1.0.0 to continue using the API.
  • Exception is raised if the library runs into a API rate limit. (See feature flag raise_exception_on_rate_limit)
  • Exception is raised if an unsupported device feature is used. (See feature flag raise_exception_on_not_supported_device_feature)
  • Python 3.4 is no longer supported.
  • Python 3.9 is now supported.

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

  • Use asGazBoiler for gas heatings
  • Use asHeatPump for heat pumps
  • Use asFuelCell for fuel cells
  • Use asPelletsBoiler for pellets heatings
  • Use asOilBoiler for oil heatings
  • Use asHybridDevice for gas/heat pump hybrid 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[1]
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-climatesolutions.com/idp/v3/authorize
    • Access Token URL: https://iam.viessmann-climatesolutions.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-climatesolutions.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-climatesolutions.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())

To make the test data comparable with future updates, it must be sorted. No worries, this can be done automatically using jq.

jq ".data|=sort_by(.feature)" --sort-keys testData.json > testDataSorted.json

Testing

Home Assistant

To test a certain change in Home Assistant, one needs to have a ViCare integration installed as a custom component. Change the dependency in the manifest.json to point to a GitHub branch or commit SHA:

  "requirements": [
    "PyViCare@git+https://github.com/openviess/PyViCare.git@<branchname>"
  ],

To install ViCare as a custom component, one can use the terminal addon to install the changes from a certain Home Assistant PR:

curl -o- -L https://gist.githubusercontent.com/bdraco/43f8043cb04b9838383fd71353e99b18/raw/core_integration_pr | bash /dev/stdin -d vicare -p <pr-number>

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

3 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for crazyfx1 from gravatar.com crazyfx1 Avatar for somm15 from gravatar.com somm15 Avatar for woehrl01 from gravatar.com woehrl01

Credits

Author: Simon Gillet

Maintainer: Christopher Fenner

License

Apache Software License (Apache-2.0)

Requires

Python <4.0, >=3.10

Tags

viessmann vicare api

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyvicare-2.62.0.tar.gz (36.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

pyvicare-2.62.0-py3-none-any.whl (48.7 kB view details)

Uploaded Python 3

File details

Details for the file pyvicare-2.62.0.tar.gz.

File metadata

  • Download URL: pyvicare-2.62.0.tar.gz
  • Upload date:
  • Size: 36.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyvicare-2.62.0.tar.gz
Algorithm Hash digest
SHA256 109d9c0b5a22d3b06bdfbf31447a148d83e0ab16e73ea48352f8933d6010cab5
MD5 8aa07f41e1d21f2e2fcc5050545b2eb6
BLAKE2b-256 5b4ffec89600acadd3e5019af478afcf3bc6902fd115378c08108ab99767f407

See more details on using hashes here.

File details

Details for the file pyvicare-2.62.0-py3-none-any.whl.

File metadata

  • Download URL: pyvicare-2.62.0-py3-none-any.whl
  • Upload date:
  • Size: 48.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyvicare-2.62.0-py3-none-any.whl
Algorithm Hash digest
SHA256 a628c946bba0d96ee3b13f4b2597142c59673054d4665c450f535f5897c3628d
MD5 369a176e6f2e4cfd6389207b13070401
BLAKE2b-256 c64f0274b2427e52b12accf10acee9e674c8387c1794804d0fad0249d8a6c6d6

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

2.62.0 This release

2 files

2.61.0

2 files

2.60.2

2 files

2.60.1

2 files

2.60.0

2 files

2.59.1

2 files

2.59.0

2 files

2.58.1

2 files

2.58.0

2 files

2.57.0

2 files

2.56.0

2 files

2.55.1

2 files

2.55.0

2 files

2.54.0

2 files

2.53.1

2 files

2.53.0

2 files

2.52.0

2 files

2.51.0

2 files

2.50.0

2 files

2.44.0

2 files

2.43.1

2 files

2.43.0

2 files

2.42.1

2 files

2.42.0

2 files

2.41.2

2 files

2.41.1

2 files

2.41.0

2 files

2.40.0

2 files

2.39.2

2 files

2.39.1

2 files

2.39.0

2 files

2.38.0

2 files

2.37.0

2 files

2.36.0

2 files

2.35.0

2 files

2.34.1

2 files

2.34.0

2 files

2.33.1

2 files

2.33.0

2 files

2.32.0

2 files

2.31.0

2 files

2.30.0

2 files

2.29.0

2 files

2.28.1

2 files

2.28.0

2 files

2.27.2

2 files

2.27.1

2 files

2.27.0

2 files

2.26.0

2 files

2.25.0

2 files

2.24.0

2 files

2.23.0

2 files

2.22.0

2 files

2.21.0

2 files

2.20.0

2 files

2.19.0

2 files

2.18.0

2 files

2.17.0

2 files

2.16.4

2 files

2.16.3

2 files

2.16.2

2 files

2.16.1

2 files

2.16.0

2 files

2.15.0

2 files

2.14.0

2 files

2.13.1

2 files

2.13.0

2 files

2.12.0

2 files

2.11.1

2 files

2.11.0

2 files

2.10.0

2 files

2.9.1

2 files

2.9.0

2 files

2.8.1

2 files

2.8

2 files

2.7.1

2 files

2.7

2 files

2.6

2 files

2.5.2

2 files

2.5.1

2 files

2.5

2 files

2.4.1

2 files

2.4

2 files

2.3.3

2 files

2.3.2

2 files

2.3.1

2 files

2.3

2 files

2.2

2 files

2.1

2 files

2.0

2 files

1.1

2 files

1.0.0

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.1

2 files

0.2.0

2 files

0.1.10

2 files

0.1.9

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

0.0.30

2 files

0.0.21

2 files

0.0.20

2 files

0.0.17

2 files

0.0.9

2 files

0.0.8

2 files

0.0.7

3 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page