From f7899afcd4a93a26af7702871aee7ad0e38e97a7 Mon Sep 17 00:00:00 2001 From: Hans Oischinger Date: Sat, 7 Sep 2019 22:04:49 +0200 Subject: [PATCH] Add ViCare component documentation (#10211) * Create vicare.markdown * Add viessmann.png for vicare component * Update vicare.markdown More documentation on services * Update vicare.markdown Added missing configuration parameter. Thanks @klaasnicolaas * Document Water Heater component * :pencil2: Tweak * Apply suggestions from code review Co-Authored-By: Martin Hjelmare * Mention all keyword in service calls * Add missing all keyword reference * :pencil2: Tweaks --- source/_components/vicare.markdown | 113 +++++++++++++++++++ source/images/supported_brands/viessmann.png | Bin 0 -> 3229 bytes 2 files changed, 113 insertions(+) create mode 100644 source/_components/vicare.markdown create mode 100644 source/images/supported_brands/viessmann.png diff --git a/source/_components/vicare.markdown b/source/_components/vicare.markdown new file mode 100644 index 00000000000..f01f5140282 --- /dev/null +++ b/source/_components/vicare.markdown @@ -0,0 +1,113 @@ +--- +title: "Viessmann climate controller" +description: "Instructions how to integrate Viessmann heating devices with Home Assistant" +logo: viessmann.png +ha_category: Climate +ha_release: 0.99 +ha_iot_class: Cloud Polling +--- + +The `ViCare` 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: + +- [Climate](#climate) (Heating) +- [Water Heater](#water-heater) (Domestic Hot Water) + +## Configuration + +To set it up, add the following information to your `configuration.yaml` file: + +```yaml +vicare: + username: VICARE_EMAIL + password: VICARE_PASSWORD +``` + +{% configuration %} +username: + description: Your username for the ViCare App + required: true + type: string +password: + description: Your password for the ViCare App + required: true + type: string +name: + description: The friendly_name of the device (will be appended with *Heating* or *Water*) + required: false + default: ViCare + type: string +circuit: + description: Heating circuit of your heating device if multiple exist + required: false + type: integer +{% endconfiguration %} + +Two components will be created: `climate.vicare_heating` and `water_heater.vicare_water` (for domestic hot water). +Unless you specify a `circuit` parameter, it will pick up the first heating circuit of your installation. + +## 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 component](/components/climate/) are provided by the ViCare integration: `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` component 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 `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 temporary. 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 hold mode. + +## Water Heater + +It is not possible to turn on/off water heating via the Water Heater component since this would conflict with the operation modes of the heating component. Therefore the operation mode of that component is just available as an attribute and cannot be modified. + +### Supported services `water_heater.vicare_water` + +The following services of the [Water Heater component](/components/water_heater/) are provided by the ViCare integration: `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 water heater devices to control. To target all entities, use `all` keyword instead of entity_id. +| `temperature` | no | New target temperature for water heater + + diff --git a/source/images/supported_brands/viessmann.png b/source/images/supported_brands/viessmann.png new file mode 100644 index 0000000000000000000000000000000000000000..a6e304ef67062b84db25241ced326d65e0d9e362 GIT binary patch literal 3229 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 P00000NkvXXu0mjfkYy)J literal 0 HcmV?d00001