This library implements access to Viessmann devices by using the official API from the Viessmann Developer Portal.
device.circuits
to device.burners
and device.compressor
.PyViCare
class. Use this class to load all available devices.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.
raise_exception_on_rate_limit
)raise_exception_on_not_supported_device_feature
)To use PyViCare, every user has to register and create their personal API client. Follow these steps to create your client:
vicare://oauth-callback/everest
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.
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.
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.
asGazBoiler
for gas heatingsasHeatPump
for heat pumpsasFuelCell
for fuel cellsasPelletsBoiler
for pellets heatingsasOilBoiler
for oil heatingsasHybridDevice
for gas/heat pump hybrid heatingsimport 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())
Follow these steps to access the API in Postman:
Create an access token in the Authorization
tab with type OAuth 2.0
and following inputs:
PyViCare
Authorization Code (With PKCE)
vicare://oauth-callback/everest
https://iam.viessmann.com/idp/v3/authorize
https://iam.viessmann.com/idp/v3/token
SHA-256
IoT User
Send client credentials in body
.A login popup will open. Enter your ViCare username and password.
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
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
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.
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())