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 <kstaniek@gmail.com>

* Update source/_components/binary_sensor.tod.markdown

Co-Authored-By: kstaniek <kstaniek@gmail.com>

* Update source/_components/binary_sensor.tod.markdown

Co-Authored-By: kstaniek <kstaniek@gmail.com>

* Update source/_components/binary_sensor.tod.markdown

Co-Authored-By: kstaniek <kstaniek@gmail.com>

* Update source/_components/binary_sensor.tod.markdown

Co-Authored-By: kstaniek <kstaniek@gmail.com>

* Update source/_components/binary_sensor.tod.markdown

Co-Authored-By: kstaniek <kstaniek@gmail.com>

* Update source/_components/binary_sensor.tod.markdown

Co-Authored-By: kstaniek <kstaniek@gmail.com>

* Update binary_sensor.tod.markdown

* ✏️ Tweaks

* Updated to follow latest configuration change

* Minor changes

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.