mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-18 23:06:58 +00:00
rework ViCare integration docs (#34040)
* rework vicare docs * Update vicare.markdown * Update vicare.markdown * Update vicare.markdown * Update vicare.markdown * Update vicare.markdown * Update vicare.markdown * Update vicare.markdown * Tiny tweaks * Tiny tweaks Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Apply suggestions from code review * Apply suggestions from code review * Apply suggestions from code review Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update vicare.markdown * Apply suggestions from code review * fix https://github.com/home-assistant/home-assistant.io/issues/32943 * fix coderabbitai findings * fix typo --------- Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
This commit is contained in:
Christopher Fenner
GitHub
parent
906ec102eb
commit
1694d0c1b4
@ -3,6 +3,7 @@ title: Viessmann ViCare
|
||||
description: Instructions how to integrate Viessmann heating devices with Home Assistant
|
||||
ha_category:
|
||||
- Climate
|
||||
- Water heater
|
||||
ha_release: 0.99
|
||||
ha_iot_class: Cloud Polling
|
||||
ha_config_flow: true
|
||||
@ -24,122 +25,156 @@ ha_codeowners:
|
||||
The **Viessmann ViCare** {% term integration %} lets you control [Viessmann](https://www.viessmann.com) 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:
|
||||
## Prerequisites
|
||||
|
||||
- [Climate](#climate) (Heating)
|
||||
- [Water heater](#water-heater) (Domestic hot water)
|
||||
- [Sensor](#sensor) (Sensor)
|
||||
- [Button](#button) (Button)
|
||||
- [Number](#number)
|
||||
You will need to sign in on the [Viessmann developer portal](https://app.developer.viessmann.com/) with **your existing ViCare app user credentials**.
|
||||
|
||||
Create a new API client by selecting **Add** in the **Clients** section on the developer dashboard with the following settings:
|
||||
- Name: `HomeAssistant`
|
||||
- Google reCAPTCHA: `disabled`
|
||||
- Redirect URIs: `vicare://oauth-callback/everest`
|
||||
|
||||
Copy the **Client ID** in the **Clients** section on the developer dashboard for the setup in Home Assistant.
|
||||
|
||||
{% important %}
|
||||
You have to set up the {% term integration %} from your device (phone) where you have the ViCare app installed. Otherwise, your device does not know how to handle the `vicare://` redirect URL, and you will receive an **Invalid credentials** notification and the setup procedure will fail.
|
||||
{% endimportant %}
|
||||
|
||||
{% note %}
|
||||
It may take up to an hour for your new client to become active and usable. Otherwise, you will not receive any devices in Home Assistant.
|
||||
{% endnote %}
|
||||
|
||||
### API limits
|
||||
|
||||
The Viessmann API is rate-limited. If you exceed one of the limits below, you will be blocked for 24 hours:
|
||||
|
||||
- 120 calls for a time window of 10 minutes
|
||||
- 1450 calls for a time window of 24 hours
|
||||
|
||||
The {% term integration %} polls the API every 60 seconds and will work within these limits. However, any additional requests to the API, for example, by setting the temperature via the integration but also by interacting with the ViCare app, count into those limits.
|
||||
|
||||
{% note %}
|
||||
If you have multiple Viessmann devices in Home Assistant, the limit is shared between them, meaning the poll interval is increased, and the values are less frequently updated!
|
||||
{% endnote %}
|
||||
|
||||
{% include integrations/config_flow.md %}
|
||||
|
||||
Use your ViCare app login credentials for *username* and *password*.
|
||||
## Entities
|
||||
|
||||
The required *client ID* can be obtained from the [Viessmann Developer Portal](https://app.developer.viessmann.com/):
|
||||
1. Log in with **your existing ViCare app username and password**.
|
||||
2. On the developer dashboard, select **Add** in the **Clients** section.
|
||||
3. Create a new client using the following data:
|
||||
- Name: `HomeAssistant`
|
||||
- Google reCAPTCHA: Disabled
|
||||
- Redirect URIs: `vicare://oauth-callback/everest`
|
||||
4. Find the **Client ID** in the **Clients** section on the developer dashboard.
|
||||
ViCare represents devices as a set of [data points](https://documentation.viessmann.com/static/iot/data-points) and the ViCare {% term integration %} maps those to {% term entity entities %} of different {% term platform platforms %} in Home Assistant. A single device may be represented by one or more platforms.
|
||||
|
||||
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`.
|
||||
### Climate
|
||||
|
||||
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 {% term integration %} from your phone.
|
||||
Represents the heating controls of your device.
|
||||
|
||||
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.
|
||||
{% note %}
|
||||
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.
|
||||
{% endnote %}
|
||||
|
||||
## Viessmann API limits
|
||||
### Water heater
|
||||
|
||||
The Viessmann API is rate-limited. If you exceed one of the limits below you will be banned for 24 hours:
|
||||
Represents the domestic hot water controls of your device.
|
||||
|
||||
- Limit 1: 120 calls for a time window of 10 minutes
|
||||
- Limit 2: 1450 calls for a time window of 24 hours
|
||||
{% note %}
|
||||
It is not possible to turn on/off water heating via the water heater {% term integration %} since this would conflict with the operation modes of the heating integration. Therefore, the operation mode of that integration is just available as an attribute and cannot be modified.
|
||||
{% endnote %}
|
||||
|
||||
The {% term integration %} 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 {% term integration %} but also by interacting with the ViCare app also counts into those limits.
|
||||
### Sensor
|
||||
|
||||
## Climate
|
||||
Additional data for a device is available as separate sensors. The sensors are automatically discovered based on the available API data points.
|
||||
|
||||
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.
|
||||
### Button
|
||||
|
||||
### Supported services `climate.vicare_heating`
|
||||
Button entities are available for triggering like a one-time charge of the water heater.
|
||||
|
||||
The following services of the [Climate integration](/integrations/climate/) are provided by the ViCare {% term integration %}: `set_temperature`, `set_hvac_mode`, `set_preset_mode`
|
||||
### Number
|
||||
|
||||
#### Service `set_temperature`
|
||||
Number entities are available to adjust values like the predefined temperature for different heating programs or the heating curve shift and slope.
|
||||
|
||||
Sets the target temperature to the given temperature.
|
||||
## Services
|
||||
|
||||
| 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
|
||||
The following services of the [climate integration](/integrations/climate/) are provided by the ViCare integration: `set_temperature`, `set_hvac_mode`, `set_preset_mode`
|
||||
|
||||
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).
|
||||
The following services of the [water_heater integration](/integrations/water_heater/) are provided by the ViCare integration: `set_temperature`
|
||||
|
||||
#### Service `climate.set_hvac_mode`
|
||||
|
||||
Set HVAC mode for the climate device. The following modes are supported:
|
||||
|
||||
The `climate.vicare_heating` {% term integration %} 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`
|
||||
### Service `vicare.set_vicare_mode`
|
||||
|
||||
Set the mode for the climate device as defined by Viessmann (see [set_hvac_mode](#service-climateset_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 {% term entity %}.
|
||||
| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. To target all entities, use the `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 entity. |
|
||||
|
||||
#### Service `set_preset_mode`
|
||||
### Service `climate.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 ViCare {% term integration %} 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_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.
|
||||
| `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 {% term integration %} since this would conflict with the operation modes of the heating {% term integration %}. Therefore the operation mode of that {% term integration %} is just available as an attribute and cannot be modified.
|
||||
|
||||
### Supported services `water_heater.vicare_water`
|
||||
|
||||
The following services of the [water heater integration](/integrations/water_heater/) are provided by the ViCare {% term integration %}: `set_temperature`
|
||||
|
||||
#### Service `set_temperature`
|
||||
### Service `water_heater.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
|
||||
| `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
|
||||
## Troubleshooting
|
||||
|
||||
Additional data from ViCare is available as separate sensors. The sensors are automatically discovered based on the available API data points.
|
||||
### UTF-8 characters in passwords
|
||||
|
||||
## Button
|
||||
The underlying PyViCare Python library cannot handle UTF-8 characters in passwords, so do not use for example `ü`, `ø`, etc. in passwords.
|
||||
|
||||
Button entities are available for triggering like a one-time charge of the water heater.
|
||||
### GATEWAY_OFFLINE
|
||||
|
||||
## Number
|
||||
The ViCare API tends to lose contact with the gateway from time to time. This will be logged in Home Assistant with:
|
||||
|
||||
Number entities are available to adjust values like the predefined temperature for different heating programs or the heating curve shift and slope.
|
||||
```log
|
||||
Invalid data from Vicare server: {
|
||||
'viErrorId': '...',
|
||||
'statusCode': 400,
|
||||
'errorType': 'DEVICE_COMMUNICATION_ERROR',
|
||||
'message': '',
|
||||
'extendedPayload': {
|
||||
'httpStatusCode': 'NotFound',
|
||||
'code': '404',
|
||||
'reason': 'GATEWAY_OFFLINE'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Usually, this resolves itself after a while, but if this state persists, try to power cycle your gateway.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user