Add analog_threshold component (#1901)

components/binary_sensor/analog_threshold.rst

@@ -0,0 +1,59 @@
+Analog Threshold Binary Sensor
+==============================
+
+.. seo::
+    :description: Instructions for setting up an analog threshold binary sensors.
+    :image: analog_threshold.svg
+
+The ``analog_threshold`` binary sensor platform allows you to convert analog values 
+(i.e. :doc:`sensor </components/sensor/index>` readings) 
+into boolean values, using a threshold as a reference. 
+When the signal is above or equal to the threshold the binary sensor is `true` 
+(this behavior can be changed adding and `invert` filter).
+
+It provides an *hysteresis* option to reduce instability when the source signal is noisy
+using different limits depending on the current state. 
+Additionally a :ref:`delay filter <binary_sensor-filters>` could be used to only change 
+after a new state has been kept a minimum time.
+
+If the source sensor is uninitialized at the moment of component creation, the initial
+state of the binary sensor wil be `false`, if later it has some reading errors, those
+invalid source updates will be ignored, and the binary sensor will keep it´s last state.
+
+For example, below configuration would turn the readings of current sensor into
+a binary sensor.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    binary_sensor:
+      - platform: analog_threshold
+        name: "Garage Door Opening"
+        sensor_id: motor_current_sensor
+        threshold: 0.5
+
+
+Configuration variables
+-----------------------
+
+-  **name** (**Required**, string): The name of the binary sensor.
+-  **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+-  **sensor_id** (**Required**, :ref:`config-id`): The ID of the source sensor.
+-  **threshold** (**Required**, float or mapping): Configures the reference for comparison. Accepts either a shorthand 
+   float number that will be used as both upper/lower threshold, or a mapping to define different values for each (to 
+   use hysteresis).
+
+   -  **upper** (**Required**, float): Upper threshold, that needs to be crossed to transition from ``low`` to ``high`` states.
+   -  **lower** (**Required**, float): Lower threshold, that needs to be crossed to transition from ``high`` to ``low`` states.
+-  All other options from :ref:`Binary Sensor <config-binary_sensor>`.
+
+
+
+See Also
+--------
+
+- :doc:`/components/binary_sensor/index`
+- :doc:`/components/sensor/index`
+- :ref:`automation`
+- :apiref:`analog_threshold/analog_threshold_binary_sensor.h`
+- :ghedit:`Edit`

images/analog_threshold.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24"><defs></defs><path d="M 3 9.695 L 4.718 9.695 L 7.372 4.79 L 8.098 10.143 L 10.081 7.699 L 12.132 9.695 L 14.084 9.695 L 14.084 10.889 L 11.621 10.889 L 10.186 9.497 L 7.261 13.118 L 6.658 8.685 L 5.463 10.889 L 3 10.889 L 3 9.695 Z" style=""></path><path style="stroke: rgb(0, 0, 0); fill: rgb(255, 255, 255); fill-opacity: 0;" d="M 2.959 18.7 L 5.9 18.7 L 5.864 15.547 L 8.7 15.5 L 8.7 18.7 L 14 18.7"></path></svg>

index.rst

@@ -393,6 +393,7 @@ Binary Sensor Components
     GPIO, components/binary_sensor/gpio, pin.svg
     Home Assistant, components/binary_sensor/homeassistant, home-assistant.svg
     Status, components/binary_sensor/status, server-network.svg
+    Analog Threshold, components/binary_sensor/analog_threshold, analog_threshold.svg
     ESP32 BLE Presence, components/binary_sensor/ble_presence, bluetooth.svg
     ESP32 Touch Pad, components/binary_sensor/esp32_touch, touch.svg
     MPR121  Capacitive Touch Sensor, components/binary_sensor/mpr121, mpr121.jpg