binary_sensor templatable delays (#3034)

components/binary_sensor/index.rst

@@ -94,7 +94,11 @@ of these entries matters!)
           - invert:
           - delayed_on: 100ms
           - delayed_off: 100ms
-          - delayed_on_off: 100ms
+          # Templated, delays for 1s (1000ms) only if a reed switch is active
+          - delayed_on_off: !lambda "if (id(reed_switch).state) return 1000; else return 0;"
+          - delayed_on_off:
+              time_on: 10s
+              time_off: !lambda "if (id(reed_switch).state) return 1000; else return 0;"
           - autorepeat:
             - delay: 1s
               time_off: 100ms
@@ -117,26 +121,64 @@ Simple filter that just inverts every value from the binary sensor.
 ``delayed_on``
 **************
 
-(**Required**, :ref:`config-time`): When a signal ON is received, wait for the specified time period until publishing
-an ON state. If an OFF value is received while waiting, the ON action is discarded. Or in other words:
+(**Required**, time, :ref:`templatable <config-templatable>`): When a signal ON is received,
+wait for the specified time period until publishing an ON state. If an OFF value is received
+while waiting, the ON action is discarded. Or in other words:
 Only send an ON value if the binary sensor has stayed ON for at least the specified time period.
+When using a lambda call, you should return the delay value in milliseconds.
 **Useful for debouncing push buttons**.
 
 ``delayed_off``
 ***************
 
-(**Required**, :ref:`config-time`): When a signal OFF is received, wait for the specified time period until publishing
-an OFF state. If an ON value is received while waiting, the OFF action is discarded. Or in other words:
+(**Required**, time, :ref:`templatable <config-templatable>`): When a signal OFF is received,
+wait for the specified time period until publishing an OFF state. If an ON value is received
+while waiting, the OFF action is discarded. Or in other words:
 Only send an OFF value if the binary sensor has stayed OFF for at least the specified time period.
+When using a lambda call, you should return the delay value in milliseconds.
 **Useful for debouncing push buttons**.
 
 ``delayed_on_off``
 ******************
 
-(**Required**, :ref:`config-time`): Only send an ON or OFF value if the binary sensor has stayed in the same state
-for at least the specified time period.
+Only send an ON or OFF value if the binary sensor has stayed in the same state for at least the specified time period.
+
+This filter uses two time delays: on and off.
+
+If the delays are equal, then you can configure the filter in short form by passing the time parameter:
+
+.. code-block:: yaml
+
+    binary_sensor:
+      - platform: ...
+        # ...
+        filters:
+          - delayed_on_off: 1s
+
+(**Required**, time, :ref:`templatable <config-templatable>`): ON and OFF delay.
+When using a lambda call, you should return the delay value in milliseconds.
 **Useful for debouncing binary switches**.
 
+If the delays are different, then you need to pass them as in the example below:
+
+.. code-block:: yaml
+
+    binary_sensor:
+      - platform: ...
+        # ...
+        filters:
+          - delayed_on_off:
+              time_on: 10s
+              time_off: 20s
+
+Configuration variables:
+
+- **time_on** (**Required**, time, :ref:`templatable <config-templatable>`): ON delay.
+- **time_off** (**Required**, time, :ref:`templatable <config-templatable>`): OFF delay.
+
+When using a lambda call, you should return the delay value in milliseconds.
+
+
 ``autorepeat``
 **************