Binary Sensor Component ======================= .. seo:: :description: Information about the base representation of all binary sensors. :image: folder-open.png With ESPHome you can use different types of binary sensors. They will automatically appear in the Home Assistant front-end and have several configuration options. .. _config-binary_sensor: Base Binary Sensor Configuration -------------------------------- All binary sensors have a platform and an optional device class. By default, the binary will chose the appropriate device class itself, but you can always override it. .. code-block:: yaml binary_sensor: - platform: ... device_class: motion Configuration variables: - **device_class** (*Optional*, string): The device class for the sensor. See https://www.home-assistant.io/components/binary_sensor/ for a list of available options. - **filters** (*Optional*, list): A list of filters to apply on the binary sensor values such as inverting signals. See :ref:`binary_sensor-filters`. Automations: - **on_press** (*Optional*, :ref:`Automation `): An automation to perform when the button is pressed. See :ref:`binary_sensor-on_press`. - **on_release** (*Optional*, :ref:`Automation `): An automation to perform when the button is released. See :ref:`binary_sensor-on_release`. - **on_state** (*Optional*, :ref:`Automation `): An automation to perform when a state is published. See :ref:`binary_sensor-on_state`. - **on_click** (*Optional*, :ref:`Automation `): An automation to perform when the button is held down for a specified period of time. See :ref:`binary_sensor-on_click`. - **on_double_click** (*Optional*, :ref:`Automation `): An automation to perform when the button is pressed twice for specified periods of time. See :ref:`binary_sensor-on_double_click`. - **on_multi_click** (*Optional*, :ref:`Automation `): An automation to perform when the button is pressed in a specific sequence. See :ref:`binary_sensor-on_multi_click`. Advanced options: - **internal** (*Optional*, boolean): Mark this component as internal. Internal components will not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without a ``name`` will implicitly set this to true. - If MQTT enabled, all other options from :ref:`MQTT Component `. .. _binary_sensor-filters: Binary Sensor Filters --------------------- With binary sensor filters you can customize how ESPHome handles your binary sensor values even more. They are similar to :ref:`Sensor Filters `. All filters are processed in a pipeline. This means all binary sensor filters are processed in the order given in the configuration (so order of these entries matters!) .. code-block:: yaml binary_sensor: - platform: ... # ... filters: - invert: - delayed_on: 100ms - delayed_off: 100ms - lambda: |- if (id(other_binary_sensor).state) { return x; } else { return {}; } Supported filters: - **invert**: Simple filter that just inverts every value from the binary sensor. - **delayed_on**: 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. **Useful for debouncing push buttons**. - **delayed_off**: 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. **Useful for debouncing push buttons**. - **lambda**: Specify any :ref:`lambda ` for more complex filters. The input value from the binary sensor is ``x`` and you can return ``true`` for ON, ``false`` for OFF, and ``{}`` to stop the filter chain. Binary Sensor Automation ------------------------ The triggers for binary sensors in ESPHome use the lingo from computer mouses. For example, a ``press`` is triggered in the first moment when the button on your mouse is pushed down. You can access the current state of the binary sensor in :ref:`lambdas ` using ``id(binary_sensor_id).state``. .. _binary_sensor-on_press: ``on_press`` ************ This automation will be triggered when the button is first pressed down, or in other words on the leading edge of the signal. .. code-block:: yaml binary_sensor: - platform: gpio # ... on_press: then: - switch.turn_on: relay_1 Configuration variables: See :ref:`Automation `. .. _binary_sensor-on_release: ``on_release`` ************** This automation will be triggered when a button press ends, or in other words on the falling edge of the signal. .. code-block:: yaml binary_sensor: - platform: gpio # ... on_release: then: - switch.turn_off: relay_1 Configuration variables: See :ref:`Automation `. .. _binary_sensor-on_state: ``on_state`` ************ This automation will be triggered when a new state is received (and thus combines ``on_press`` and ``on_release`` into one trigger). The new state will be given as the variable ``x`` as a boolean and can be used in :ref:`lambdas `. .. code-block:: yaml binary_sensor: - platform: gpio # ... on_state: then: - switch.turn_off: relay_1 Configuration variables: See :ref:`Automation `. .. _binary_sensor-on_click: ``on_click`` ************ This automation will be triggered when a button is pressed down for a time period of length ``min_length`` to ``max_length``. Any click longer or shorter than this will not trigger the automation. The automation is therefore also triggered on the falling edge of the signal. .. code-block:: yaml binary_sensor: - platform: gpio # ... on_click: min_length: 50ms max_length: 350ms then: - switch.turn_off: relay_1 Configuration variables: - **min_length** (*Optional*, :ref:`config-time`): The minimum duration the click should last. Defaults to ``50ms``. - **max_length** (*Optional*, :ref:`config-time`): The maximum duration the click should last. Defaults to ``350ms``. - See :ref:`Automation `. .. _binary_sensor-on_double_click: ``on_double_click`` ******************* This automation will be triggered when a button is pressed down twice, with the first click lasting between ``min_length`` and ``max_length``. When a second leading edge then happens within ``min_length`` and ``max_length``, the automation is triggered. .. code-block:: yaml binary_sensor: - platform: gpio # ... on_double_click: min_length: 50ms max_length: 350ms then: - switch.turn_off: relay_1 Configuration variables: - **min_length** (*Optional*, :ref:`config-time`): The minimum duration the click should last. Defaults to ``50ms``. - **max_length** (*Optional*, :ref:`config-time`): The maximum duration the click should last. Defaults to ``350ms``. - See :ref:`Automation `. .. _binary_sensor-on_multi_click: ``on_multi_click`` ****************** This automation will be triggered when a button is pressed in a user-specified sequence. .. code-block:: yaml binary_sensor: - platform: gpio # ... on_multi_click: - timing: - ON for at most 1s - OFF for at most 1s - ON for 0.5s to 1s - OFF for at least 0.2s then: - logger.log: "Double-Clicked" Configuration variables: - **timing** (**Required**): The timing of the multi click. This uses a language-based grammar using these styles: - `` for