From 3b335cb1bf72c25a49a869d731a3a876181de3f0 Mon Sep 17 00:00:00 2001 From: Oleksii Serdiuk Date: Wed, 21 Nov 2018 09:58:08 +0100 Subject: [PATCH] Update Dark Sky Sensor documentation (#7424) * Update darksky sensor component configuration (#7571) * Update Dark Sky Sensor documentation Update `forecast` configuration parameter documentation to include `0`, add missing descriptions for `icon`, `nearest_storm_distance`, and `nearest_storm_bearing`. Descriptions were updated to correspond as closely as makes sense to the official Dark Sky API documentation. * :pencil2: Tweaks --- source/_components/sensor.darksky.markdown | 56 +++++++++++++--------- 1 file changed, 33 insertions(+), 23 deletions(-) diff --git a/source/_components/sensor.darksky.markdown b/source/_components/sensor.darksky.markdown index 036865b3de2..5f39f039eb6 100644 --- a/source/_components/sensor.darksky.markdown +++ b/source/_components/sensor.darksky.markdown @@ -30,10 +30,12 @@ To add Dark Sky to your installation, add the following to your `configuration.y sensor: - platform: darksky api_key: YOUR_API_KEY + forecast: + - 0 monitored_conditions: - summary - icon - - nearest_storm_distance + - temperature ``` {% configuration %} @@ -47,7 +49,7 @@ name: default: Dark Sky type: string forecast: - description: List of days in the 7 day forecast you would like to receive data on, starting with tomorrow as day 1. Any `monitored_condition` with a daily forecast by DarkSky will generate a sensor tagged with `_`. + description: List of days in the 7-day forecast you would like to receive data on, starting with today as day 0 and ending with day 7. Any condition from `monitored_conditions` with a daily forecast by Dark Sky will generate a sensor with entity_id `_`. required: false type: list language: @@ -71,27 +73,29 @@ monitored_conditions: type: list keys: summary: - description: A human-readable text summary of the current conditions. + description: A human-readable text summary. + icon: + description: A machine-readable text summary, suitable for selecting an icon for display. See [Dark Sky API documentation][] for the list of possible values. precip_type: - description: The type of precipitation occurring. + description: The type of precipitation occurring at the given time. If `precip_intensity` is zero, then this property will be `unknown`. See [Dark Sky API documentation][] for the list of possible values. precip_intensity: - description: The average expected intensity of precipitation occurring. + description: The intensity of precipitation occurring at the given time. This value is conditional on probability (that is, assuming any precipitation occurs at all). precip_probability: - description: A value between 0 and 1 which is representing the probability of precipitation. + description: The probability of precipitation occurring, in percents. precip_accumulation: - description: Daily snow accumulation. Returns unknown if no snow accumulation available. + description: The amount of snowfall accumulation expected to occur. If no snowfall is expected, this property will be `undefined`. temperature: - description: The current temperature. + description: The air temperature. apparent_temperature: - description: A numerical value representing the apparent (or "feels like") temperature. + description: The apparent (or "feels like") temperature. dew_point: description: The dew point. wind_speed: description: The wind speed. wind_gust: - description: The wind gust. + description: The wind gust speed. wind_bearing: - description: Where the wind is coming from in degrees, with true north at 0° and progressing clockwise. + description: The direction that the wind is coming **from** in degrees, with true north at 0° and progressing clockwise. If `wind_speed` is 0, then this value is `unknown`. cloud_cover: description: The percentage of sky occluded by clouds. humidity: @@ -101,29 +105,33 @@ monitored_conditions: visibility: description: The average visibility. ozone: - description: The columnar density of total atmospheric ozone in Dobson. + description: The columnar density of total atmospheric ozone at the given time in Dobson units. minutely_summary: description: A human-readable text summary for the next hour. hourly_summary: - description: A human-readable text summary for the next 24 hours. + description: A human-readable text summary for the next two days. daily_summary: - description: A human-readable text summary for the next 7 days. + description: A human-readable text summary for the next week. temperature_high: - description: Today's daytime expected high temperature. + description: The daytime high temperature. temperature_low: - description: Today's overnight expected low temperature. + description: The overnight low temperature. apparent_temperature_high: - description: Today's daytime expected apparent high temperature. + description: The daytime high apparent temperature. apparent_temperature_low: - description: Today's overnight expected apparent low temperature. + description: The overnight low apparent temperature. precip_intensity_max: - description: Today's expected maximum intensity of precipitation. + description: The maximum value of `precip_intensity` during a given day. uv_index: - description: The current UV index. + description: The UV index. moon_phase: - description: The fractional part of the lunation number during the given day. + description: "The fractional part of the lunation number during the given day: a value of 0 corresponds to a new moon, 0.25 to a first quarter moon, 0.5 to a full moon, and 0.75 to a last quarter moon." + nearest_storm_distance: + description: The approximate distance to the nearest storm in miles. + nearest_storm_bearing: + description: The approximate direction of the nearest storm in degrees, with true north at 0° and progressing clockwise. units: - description: Specify the unit system. Valid options are `auto`, `us`, `si`, `ca`, `uk` and `uk2`. `auto` will let Dark Sky decide the unit system based on location. + description: Specify the unit system. Valid options are `auto`, `us`, `si`, `ca` and `uk2`. `auto` will let Dark Sky decide the unit system based on location. required: false default: "`si` or `us`, based on the temperature preference in Home Assistant." type: string @@ -196,4 +204,6 @@ All language options are described in this table that you can use for the dark s While the platform is called "darksky" the sensors will show up in Home Assistant as "dark_sky" (eg: sensor.dark_sky_summary).

-Details about the API are available in the [Dark Sky documentation](https://darksky.net/dev/docs). +More details about the API are available in the [Dark Sky API documentation][]. + +[Dark Sky API documentation]: https://darksky.net/dev/docs