Document scan_interval and preset modes (home-assistant#12528)

oischinger · frenck · web-flow · commit 7831b6d644e7 · 2020-03-30T14:50:33.000+02:00
* Document scan_interval and preset modes

* Fix anchor

* ✏️ Tweaks

Co-authored-by: Franck Nijhof &lt;frenck@frenck.nl&gt;
diff --git a/source/_integrations/vicare.markdown b/source/_integrations/vicare.markdown
@@ -51,11 +51,25 @@ heating_type:
   required: false
   type: string
   default: generic
+scan_interval:
+  description: The update frequency of this component in seconds. See [Viessmann API limits](#viessmann-api-limits)
+  default: 60
+  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.
 
+## Viessmann API limits
+
+Recently Viessmann has introduced a rate limit on their REST API. 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 default `scan_interval` of 60 seconds will work within these limits. Note however that any additional requests to the API, e.g., by setting the temperature via the integration but also by interacting with the ViCare app also counts into those limits. It is therefore advised to adjust the scan_interval to your usage scenario.
+
 ## 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.
@@ -94,12 +108,13 @@ The `climate.vicare_heating` component has the following mapping of HVAC modes t
 
 #### 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.
+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 hold mode.
+| `preset_mode` | no | New value of preset mode.
 
 ## Water Heater
 
