From d125a5de77c2ee312fbf8f1114431fa4b4e09437 Mon Sep 17 00:00:00 2001
From: Stanislav Meduna <stano@meduna.org>
Date: Thu, 13 May 2021 22:37:06 +0200
Subject: [PATCH] Add the documentation for the autorepeat filter (#1093)

* add the documentation for the autorepeat filter

* make no timing equivalent to a single default one
---
 components/binary_sensor/index.rst | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/components/binary_sensor/index.rst b/components/binary_sensor/index.rst
index f0d99c21c..0ae7fd74f 100644
--- a/components/binary_sensor/index.rst
+++ b/components/binary_sensor/index.rst
@@ -78,6 +78,13 @@ of these entries matters!)
           - delayed_on: 100ms
           - delayed_off: 100ms
           - delayed_on_off: 100ms
+          - autorepeat:
+            - delay: 1s
+              time_off: 100ms
+              time_on: 900ms
+            - delay: 5s
+              time_off: 100ms
+              time_on: 400ms
           - lambda: |-
               if (id(other_binary_sensor).state) {
                 return x;
@@ -113,6 +120,28 @@ Only send an OFF value if the binary sensor has stayed OFF for at least the spec
 for at least the specified time period.
 **Useful for debouncing binary switches**.
 
+``autorepeat``
+**************
+
+A filter implementing the autorepeat behavior. The filter is parametrized by a list of timing descriptions.
+When a signal ON is received it is passed to the output and the first ``delay`` is started. When this
+interval expires the output is turned OFF and toggles using the ``time_off`` and ``time_on`` durations
+for the OFF and ON state respectively. At the same time the ``delay`` of the second timing description
+is started and the process is repeated until the list is exhausted, in which case the timing of the
+last description remains in use. Receiving an OFF signal stops the whole process and immediately outputs OFF.
+
+The example thus waits one second with the output being ON, toggles it once per second for five seconds,
+then toggles twice per second until OFF is received.
+
+An ``autorepeat`` filter with no timing description is equivalent to one timing with all the parameters
+set to default values.
+
+Configuration variables:
+
+- **delay** (*Optional*, :ref:`config-time`): Delay to proceed to the next timing. Defaults to ``1s``.
+- **time_off** (*Optional*, :ref:`config-time`): Interval to hold the output at OFF. Defaults to ``100ms``.
+- **time_on** (*Optional*, :ref:`config-time`): Interval to hold the output at ON. Defaults to ``900ms``.
+
 ``lambda``
 **********