Viessmann ViCare
The Viessmann ViCare integrationIntegrations connect and integrate Home Assistant with your devices, services, and more.
[Learn more] lets you control Viessmann devices via the Viessmann ViCare (REST) API.
Most recent network-connected Viessmann heating devices (e.g., gas boilers) should be supported.
There is currently support for the following device types within Home Assistant:
- Climate (Heating)
- Water heater (Domestic hot water)
- Sensor (Sensor)
- Button (Button)
- Number
Configuration
To add the Viessmann ViCare integration to your Home Assistant instance, use this My button:
Viessmann ViCare can be auto-discovered by Home Assistant. If an instance was found, it will be shown as Discovered. You can then set it up right away.
If it wasn’t discovered automatically, don’t worry! You can set up a manual integration entry:
-
Browse to your Home Assistant instance.
-
In the bottom right corner, select the Add Integration button.
-
From the list, select Viessmann ViCare.
-
Follow the instructions on screen to complete the setup.
Use your ViCare app login credentials for username and password.
The required client ID can be obtained from the Viessmann Developer Portal:
- Log in with your existing ViCare app username and password.
- On the developer dashboard, select Add in the Clients section.
- Create a new client using the following data:
- Name:
HomeAssistant - Google reCAPTCHA: Disabled
- Redirect URIs:
vicare://oauth-callback/everest
- Name:
- Find the Client ID in the Clients section on the developer dashboard.
The heating_type can either be auto to automatically find the most suitable type for your device or one of gas, oil, pellets, heatpump, fuelcell, hybrid.
Important: the redirect URI that you configure requires that you perform the initial setup on a device that has the ViCare application installed. If your device does not know how to handle the vicare:// URL, you will receive an Invalid credentials notification and the setup procedure will fail. This means: install the ViCare app on your phone and set up the integrationIntegrations connect and integrate Home Assistant with your devices, services, and more.
[Learn more] from your phone.
Multiple device instances might be generated depending on the number of burners and/or circuits of your installation. If there is more than a single instance all devices are suffixed with the circuit or burner ID.
Viessmann API limits
The Viessmann API is rate-limited. If you exceed one of the limits below you will be banned for 24 hours:
- Limit 1: 120 calls for a time window of 10 minutes
- Limit 2: 1450 calls for a time window of 24 hours
The integrationIntegrations connect and integrate Home Assistant with your devices, services, and more.
[Learn more] polls the Viessmann API every 60 seconds and will work within these limits. Note however that any additional requests to the API, e.g., by setting the temperature via the integrationIntegrations connect and integrate Home Assistant with your devices, services, and more.
[Learn more] but also by interacting with the ViCare app also counts into those limits.
Climate
A note about the current temperature attribute: Viessmann devices with room temperature sensing will show the current room temperature via current_temperature. All other devices will show the current supply temperature of the heating circuit.
Supported services climate.vicare_heating
The following services of the Climate integration are provided by the ViCare integrationIntegrations connect and integrate Home Assistant with your devices, services, and more.
[Learn more]: set_temperature, set_hvac_mode, set_preset_mode
Service set_temperature
Sets the target temperature to the given temperature.
| Service data attribute | Optional | Description |
|---|---|---|
entity_id |
yes | String or list of strings that point at entity_id’s of climate devices to control. To target all entities, use all keyword instead of entity_id. |
temperature |
no | Desired target temperature |
Note that set_temperature will always affect the current normal temperature or, if a preset is set, the temperature of the preset (i.e., Viessman program like eco or comfort).
Service climate.set_hvac_mode
Set HVAC mode for the climate device. The following modes are supported:
The climate.vicare_heating integrationIntegrations connect and integrate Home Assistant with your devices, services, and more.
[Learn more] has the following mapping of HVAC modes to Viessmann operation modes:
| HVAC mode | Viessmann mode | Description |
|---|---|---|
off |
ForcedReduced |
Permanently set heating to reduced temperature. Note: This will also deactivate domestic hot water |
heat |
ForcedNormal |
Permanently set heating to normal temperature. |
auto |
DHWandHeating |
Switches between reduced and normal temperature as by the heating schedule programmed in your device |
| Service data attribute | Optional | Description |
|---|---|---|
entity_id |
yes | String or list of strings that point at entity_id’s of climate devices to control. To target all entities, use all keyword instead of entity_id. |
hvac_mode |
no | New value of HVAC mode |
Service climate.set_vicare_mode
Set the mode for the climate device as defined by Viessmann (see set_hvac_mode for a mapping to Home Assistant Climate modes. This allows more-fine grained control of the heating modes.
| Service data attribute | Optional | Description |
|---|---|---|
entity_id |
yes | String or list of strings that point at entity_id’s of climate devices to control. To target all entities, use all keyword instead of entity_id. |
vicare_mode |
no | New value of ViCare mode. For supported values see the vicare_modes attribute of the climate entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service.
|
|
[Learn more]. |
Service set_preset_mode
Sets the preset mode. Supported preset modes are eco and comfort. These are identical to the respective Viessmann programs and are only active temporarily for 8 hours. Eco mode reduces the target temperature by 3°C, whereas Comfort mode sets the target temperature to a configurable value. Please consult your heating device manual for more information.
| Service data attribute | Optional | Description |
|---|---|---|
entity_id |
yes | String or list of strings that point at entity_id’s of climate devices to control. To target all entities, use all keyword instead of entity_id. |
preset_mode |
no | New value of preset mode. |
Water heater
It is not possible to turn on/off water heating via the water heater integrationIntegrations connect and integrate Home Assistant with your devices, services, and more.
[Learn more] since this would conflict with the operation modes of the heating integrationIntegrations connect and integrate Home Assistant with your devices, services, and more.
[Learn more]. Therefore the operation mode of that integrationIntegrations connect and integrate Home Assistant with your devices, services, and more.
[Learn more] is just available as an attribute and cannot be modified.
Supported services water_heater.vicare_water
The following services of the water heater integration are provided by the ViCare integrationIntegrations connect and integrate Home Assistant with your devices, services, and more.
[Learn more]: set_temperature
Service set_temperature
Sets the target temperature of domestic hot water to the given temperature.
| Service data attribute | Optional | Description |
|---|---|---|
entity_id |
yes | String or list of strings that point at entity_id’s of climate devices to control. |
temperature |
no | New target temperature for water heater |
Sensor
Additional data from ViCare is available as separate sensors. The sensors are automatically discovered based on the available API data points.
Button
Button entities are available for triggering like a one-time charge of the water heater.
Number
Number entities are available to adjust values like the predefined temperature for different heating programs or the heating curve shift and slope.