From 8e019dd2517cb702d432007700fddec2b2531616 Mon Sep 17 00:00:00 2001 From: Klaudiusz Staniek Date: Fri, 15 Feb 2019 14:00:42 +0100 Subject: [PATCH] Create binary_sensor.tod.markdown (#8172) * Create binary_sensor.tod.markdown * Update binary_sensor.tod.markdown * Update source/_components/binary_sensor.tod.markdown Co-Authored-By: kstaniek * Update source/_components/binary_sensor.tod.markdown Co-Authored-By: kstaniek * Update source/_components/binary_sensor.tod.markdown Co-Authored-By: kstaniek * Update source/_components/binary_sensor.tod.markdown Co-Authored-By: kstaniek * Update source/_components/binary_sensor.tod.markdown Co-Authored-By: kstaniek * Update source/_components/binary_sensor.tod.markdown Co-Authored-By: kstaniek * Update source/_components/binary_sensor.tod.markdown Co-Authored-By: kstaniek * Update binary_sensor.tod.markdown * :pencil2: Tweaks * Updated to follow latest configuration change * Minor changes --- source/_components/binary_sensor.tod.markdown | 76 +++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 source/_components/binary_sensor.tod.markdown diff --git a/source/_components/binary_sensor.tod.markdown b/source/_components/binary_sensor.tod.markdown new file mode 100644 index 00000000000..fafbd195876 --- /dev/null +++ b/source/_components/binary_sensor.tod.markdown @@ -0,0 +1,76 @@ +--- +layout: page +title: "Times of the Day Binary Sensor" +description: "Instructions on how to integrate Times of the Day binary sensors within Home Assistant." +date: 2019-01-14 23:35 +sidebar: true +comments: false +sharing: true +footer: true +ha_category: Binary Sensor +ha_release: 0.88 +ha_iot_class: "Local Push" +logo: home-assistant.png +ha_qa_scale: internal +--- + +The `tod` platform supports binary sensors which get their values by checking if the current time is within defined time ranges. + +The time ranges can be provided as absolute local time or using the `sunrise` or `sunset` keyword calculated based on the sun position for location. The location must be provided in the configuration. + +In addition for sun position based ranges, the negative or positive offset can be configured. + +## {% linkable_title Configuration %} + +Here is an example of adding a sensor to the `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +binary_sensor: + - platform: tod + name: Early Morning + after: sunrise + after_offset: '-02:00' + before: '07:00' +``` + +{% configuration %} +name: + description: Name of the sensor. + required: true + type: string +before: + description: The absolute local time value or sun event for beginning of the time range. + required: true + type: string or time +before_offset: + description: The time offset of the beginning time range. + required: false + type: time +after: + description: The absolute local time value or sun event for ending of the time range. + required: true + type: string or time +after_offset: + description: The time offset of the beginning time range. + type: time + required: false +{% endconfiguration %} + +## {% linkable_title Considerations %} + +The primary purpose of this sensor is to use a simple time range definition instead of creating a complex template with references to `sun.sun` component attributes. + +The sensor state is ON when this condition `after` + `after_offset` <= `current time` < `before` + `before_offset`. + +If `after` time is later than `before` then the next day is considered, i.e.: + +```yaml +binary_sensor: + - platform: tod + name: Night + after: sunset + before: sunrise +``` + +In the above example, the next day `sunrise` is calculated as a time range end.