Viessmann ViCare
The Viessmann ViCare integration集成将 Home Assistant 与您的设备、服务等连接和集成。 [Learn more] lets you control Viessmann
Prerequisites
You will need to sign in on the Viessmann developer portal
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.
You have to set up the integration集成将 Home Assistant 与您的设备、服务等连接和集成。 [Learn more] 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.
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.
API limits
The Viessmann API is rate-limited. In the “Basic” (free) tier of their API plans, 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
For the paid API plans this limit increases to 3000 calls in 24 hours. The integration集成将 Home Assistant 与您的设备、服务等连接和集成。 [Learn more] 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 and interacting with the ViCare app, count into those limits.
For any Viessmann API plan except the most expensive “Advanced” tier, Viessmann imposes certain limits on which APIs are accessible for end-user consumption. Unfortunately, this also affects APIs useful for smart home integrations, like controlling thermostats (TRVs) and climate sensors, which are only available in the “Advanced” plan API tier. In case you set up the integration with a lower-tier plan, TRVs and other smart home entities will not become accessible in your Home Assistant installation.
Please consider providing feedback to Viessmann as described in their FAQ
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!
配置
要将 Viessmann ViCare integration 添加到您的 Home Assistant 实例中，请使用此 My 按钮：
Viessmann ViCare 可以被 Home Assistant 自动发现。如果发现了实例， 它将显示为 已发现。您可以立即进行设置。
如果没有自动发现，请不要担心！您可以设置一个 手动集成条目：
-
浏览到您的 Home Assistant 实例。
-
转到
设置 > 设备与服务。 -
在右下角，选择
Add Integration 按钮。 -
从列表中选择 Viessmann ViCare。
-
按照屏幕上的说明完成设置。
Entities
ViCare represents devices as a set of data points
Climate
Represents the heating controls of your device.
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.
Fan
Ventilation units are displayed as fans and enable the change of speed and use of presets.
Water heater
Represents the domestic hot water controls of your device.
It is not possible to turn on/off water heating via the water heater integration集成将 Home Assistant 与您的设备、服务等连接和集成。 [Learn more] 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.
Sensor
Additional data for a device 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.
Actions
The following actions of the climate integration are provided by the ViCare integration: set_temperature, set_hvac_mode, set_preset_mode
The following actions of the water_heater integration are provided by the ViCare integration: set_temperature
Action vicare.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.
| 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 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实体表示 Home Assistant 中的传感器、执行器或功能。实体用于监控物理属性或控制其他实体。实体通常是设备或服务的一部分。 [Learn more]. |
Action climate.set_temperature
Sets the target temperature to the given temperature.
| 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).
Action climate.set_hvac_mode
Set HVAC mode for the climate device. The following modes are supported:
The ViCare integration集成将 Home Assistant 与您的设备、服务等连接和集成。 [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. |
| 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. |
Action 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.
| 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. |
Action water_heater.set_temperature
Sets the target temperature of domestic hot water to the given temperature.
| 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. |
Troubleshooting
UTF-8 characters in passwords
The underlying PyViCare Python library cannot handle UTF-8 characters in passwords, so do not use for example ü, ø, etc. in passwords.
GATEWAY_OFFLINE
The ViCare API tends to lose contact with the gateway from time to time. This will be logged in Home Assistant with:
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.
Removing the integration
This integration follows standard integration removal. Once the integration is removed, you can remove the API client (assuming it was only used by this integration) by going to the Viessmann developer portal
从Home Assistant中移除集成实例
- 前往 设置 > 设备与服务 并选择集成卡片。
- 从设备列表中，选择要删除的集成实例。
- 在条目旁边，选择三个点
菜单。然后，选择 删除。