Repository files navigation

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

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

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

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

See the example below for how you can use that.

• 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 flagraise_exception_on_rate_limit)
• Exception is raised if an unsupported device feature is used. (See feature flagraise_exception_on_not_supported_device_feature)
• Python 3.4 is no longer supported.
• Python 3.9 is now supported.

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

1. Login to theViessmann Developer Portal withyour existing ViCare app username/password.
2. On the developer dashboard clickadd in theclients section.
3. Create a new client using following data:
   • Name: PyViCare
   • Google reCAPTCHA: Disabled
   • Redirect URIs:vicare://oauth-callback/everest
4. Copy theClient 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 thePyViCare 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 aPyViCareNotSupportedFeatureError if the dedicated method is called. This is most likely not a bug, but a limitation of the device itself.

Tip: You can use Pythonscontextlib.suppress to handle it gracefully.

• UseasGazBoiler for gas heatings
• UseasHeatPump for heat pumps
• UseasFuelCell for fuel cells
• UseasPelletsBoiler for pellets heatings
• UseasOilBoiler for oil heatings
• UseasHybridDevice for gas/heat pump hybrid heatings

importsysimportloggingfromPyViCare.PyViCareimportPyViCareclient_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"ifdevice.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 circuitprint(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 burnerprint(burner.getActive())compressor=t.compressors[0]#select compressorprint(compressor.getActive())

Follow these steps to access the API in Postman:

1. Create an access token in theAuthorization tab with typeOAuth 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 yourinstallationId,gatewaySerial anddeviceId:

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

   • installationId isdata[0].id
   • gatewaySerial isdata[0].gateways[0].serial
   • deviceId isdata[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

Due to latest changes in the Viessmann API rate limits can be hit. In that case aPyViCareRateLimitError 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 intotests/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 thePYVICARE_* environment variables.

importsysimportosfromPyViCare.PyViCareimportPyViCareclient_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")withopen(f"dump.json",mode='w')asoutput: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 usingjq.

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