Add docs for upcoming OpenUV changes (#11825)

* Add docs for upcoming OpenUV changes

* Simplify configuration example
This commit is contained in:
Aaron Bach 2020-01-23 01:37:58 -07:00 committed by Franck Nijhof
parent 2d86c6d96c
commit 4cfd3a649b

View File

@ -21,32 +21,17 @@ To generate an API key,
[simply log in to the OpenUV website](https://www.openuv.io/auth/google). [simply log in to the OpenUV website](https://www.openuv.io/auth/google).
<div class='note warning'> <div class='note warning'>
Beginning February 1, 2019, the "Limited" plan (which is what new users are Beginning February 1, 2019, the "Limited" plan (which is what new users are
given by default) is limited to 50 API requests per day. Because different given by default) is limited to 50 API requests per day. Because different
API plans and locations will have different requirements, the `openuv` API plans and locations will have different requirements, the `openuv`
component does not automatically query the API for new data after it initially component does not automatically query the API for new data after it initially
loads. To request new data, the `update_data` service may be used. loads. To request new data, the `update_data` service may be used.
</div> </div>
<div class='note warning'> <div class='note warning'>
Each use of the `update_data` service will consume 2 API calls from the daily quota
Each use of the `update_data` service will consume 1 or 2 API calls, depending (since it performs the same tasks as back-to-back calls of the `update_uv_index_data` and
on which monitored conditions are configured. the `update_protection_data` services).
If the OpenUV integration is configured through the Home Assistant UI (via the
`Configuration >> Integrations` panel), each service call will consume 2 API
calls from the daily quota.
If the OpenUV integration is configured via `configuration.yaml`, service calls
will consume 2 API calls if `monitored_conditions` contains both
`uv_protection_window` and any other condition; any other scenarios will only
consume 1 API call.
Ensure that you understand these specifications when calling the `update_data`
service.
</div> </div>
## Configuration ## Configuration
@ -64,82 +49,26 @@ api_key:
description: The OpenUV API key. description: The OpenUV API key.
required: true required: true
type: string type: string
binary_sensors: elevation:
description: The binary sensor-related configuration options. description: The elevation of the monitored location; if ommitted, the value specified in `configuration.yaml` will be used.
required: false required: false
type: map type: float
keys: latitude:
monitored_conditions: description: The latitude of the monitored location; if ommitted, the value specified in `configuration.yaml` will be used.
description: The conditions to create sensors from.
required: false
type: list
default: all
keys:
uv_protection_window:
description: Displays if UV protection (sunscreen, etc.) is recommended at the current date and time.
sensors:
description: The sensor-related configuration options.
required: false required: false
type: map type: float
keys: longitude:
monitored_conditions: description: The longitude of the monitored location; if ommitted, the value specified in `configuration.yaml` will be used.
description: The conditions to create sensors from. required: false
required: false type: float
type: list
default: all
keys:
current_ozone_level:
description: The current ozone level in du (Dobson Units).
current_uv_index:
description: The current UV index.
current_uv_level:
description: "The level of current UV index, which is calculated based on [UV Index Levels & Colors](https://www.openuv.io/kb/uv-index-levels-colors)."
max_uv_index:
description: The maximum UV index that will be encountered that day (at solar noon).
safe_exposure_time_type_1:
description: The approximate exposure time for skin type I.
safe_exposure_time_type_2:
description: The approximate exposure time for skin type II.
safe_exposure_time_type_3:
description: The approximate exposure time for skin type III.
safe_exposure_time_type_4:
description: The approximate exposure time for skin type IV.
safe_exposure_time_type_5:
description: The approximate exposure time for skin type V.
safe_exposure_time_type_6:
description: The approximate exposure time for skin type VI.
{% endconfiguration %} {% endconfiguration %}
## The Fitzpatrick Scale
The approximate number of minutes of a particular skin type can be exposed to The approximate number of minutes of a particular skin type can be exposed to
the sun before burning/tanning starts is based on the the sun before burning/tanning starts is based on the
[Fitzpatrick scale](https://en.wikipedia.org/wiki/Fitzpatrick_scale). [Fitzpatrick scale](https://en.wikipedia.org/wiki/Fitzpatrick_scale).
## Full Configuration Example
To configure additional functionality, add configuration options beneath a
`binary_sensor` and/or `sensor` key within the `openuv` section of the
`configuration.yaml` file as below:
```yaml
openuv:
api_key: YOUR_OPENUV_API_KEY
binary_sensors:
monitored_conditions:
- uv_protection_window
sensors:
monitored_conditions:
- current_ozone_level
- current_uv_index
- current_uv_level
- max_uv_index
- safe_exposure_time_type_1
- safe_exposure_time_type_2
- safe_exposure_time_type_3
- safe_exposure_time_type_4
- safe_exposure_time_type_5
- safe_exposure_time_type_6
```
<div class='note warning'> <div class='note warning'>
The above guidelines constitute estimates and are intended to help informed The above guidelines constitute estimates and are intended to help informed
decision making. They should not replace analysis, advice or diagnosis from a decision making. They should not replace analysis, advice or diagnosis from a
@ -182,7 +111,7 @@ automation:
service: openuv.update_data service: openuv.update_data
``` ```
Update only the sensors every 20 minutes while the sun is at least 10 degrees above the horizon: Update the UV index data every 20 minutes while the sun is at least 10 degrees above the horizon:
```yaml ```yaml
automation: automation: