mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-10-31 08:31:29 +01:00
196 lines
5.9 KiB
ReStructuredText
196 lines
5.9 KiB
ReStructuredText
Binary Sensor Component
|
||
=======================
|
||
|
||
With esphomelib 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:: 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.
|
||
- **inverted** (*Optional*, boolean): Whether to invert the binary
|
||
sensor output, i.e. report ON states as OFF and vice versa. Defaults
|
||
to ``False``.
|
||
- **on_press** (*Optional*, :ref:`Automation <automation>`): An automation to perform
|
||
when the button is pressed. See :ref:`binary_sensor-on_press`.
|
||
- **on_release** (*Optional*, :ref:`Automation <automation>`): An automation to perform
|
||
when the button is released. See :ref:`binary_sensor-on_release`.
|
||
- **on_click** (*Optional*, :ref:`Automation <automation>`): An automation to perform
|
||
when the button is held down for a specified period of time.
|
||
See :ref:`binary_sensor-on_click`.
|
||
- **on_click** (*Optional*, :ref:`Automation <automation>`): An automation to perform
|
||
when the button is pressed twice for specified periods of time.
|
||
See :ref:`binary_sensor-on_double_click`.
|
||
- All other options from :ref:`MQTT Component <config-mqtt-component>`.
|
||
|
||
Binary Sensor Automation
|
||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
The triggers for binary sensors in esphomeyaml use the lingo from computer mouses. This naming might not
|
||
perfectly fit every use case, but at least makes the naming consistent. 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 <config-lambda>` using
|
||
``id(binary_sensor_id).value``.
|
||
|
||
.. _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:: yaml
|
||
|
||
binary_sensor:
|
||
- platform: gpio
|
||
# ...
|
||
on_press:
|
||
then:
|
||
- switch.turn_on:
|
||
id: relay_1
|
||
|
||
Configuration variables: See :ref:`Automation <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:: yaml
|
||
|
||
binary_sensor:
|
||
- platform: gpio
|
||
# ...
|
||
on_release:
|
||
then:
|
||
- switch.turn_off:
|
||
id: relay_1
|
||
|
||
Configuration variables: See :ref:`Automation <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:: yaml
|
||
|
||
binary_sensor:
|
||
- platform: gpio
|
||
# ...
|
||
on_click:
|
||
min_length: 50ms
|
||
max_length: 350ms
|
||
then:
|
||
- switch.turn_off:
|
||
id: 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 <automation>`.
|
||
|
||
.. _binary_sensor-on_double_click:
|
||
|
||
``on_double_click``
|
||
"""""""""""""""""""
|
||
|
||
.. warning::
|
||
|
||
This trigger is not final and could be replaced by a ``on_multi_click`` option which would
|
||
allow triggering for any number of clicks.
|
||
|
||
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:: yaml
|
||
|
||
binary_sensor:
|
||
- platform: gpio
|
||
# ...
|
||
on_double_click:
|
||
min_length: 50ms
|
||
max_length: 350ms
|
||
then:
|
||
- switch.turn_off:
|
||
id: 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 <automation>`.
|
||
|
||
lambda calls
|
||
""""""""""""
|
||
|
||
From :ref:`lambdas <config-lambda>`, you can call several methods on all binary sensors to do some
|
||
advanced stuff (see the full :doc:`API Reference </api/binary_sensor/index>` for more info).
|
||
|
||
- ``publish_state()``: Manually cause the binary sensor to publish and store a state from anywhere
|
||
in the program.
|
||
|
||
.. code:: yaml
|
||
|
||
// Within lambda, publish an OFF state.
|
||
id(my_binary_sensor).publish_state(false);
|
||
|
||
// Within lambda, publish an ON state.
|
||
id(my_binary_sensor).publish_state(true);
|
||
|
||
- ``value``: Retrieve the current value of the binary sensor.
|
||
|
||
.. code:: yaml
|
||
|
||
// Within lambda, get the binary sensor state and conditionally do something
|
||
if (id(my_binary_sensor).value) {
|
||
// Binary sensor is ON, do something here
|
||
} else {
|
||
// Binary sensor is OFF, do something else here
|
||
}
|
||
|
||
|
||
See Also
|
||
--------
|
||
|
||
- :doc:`API Reference </api/binary_sensor/index>`
|
||
- `Edit this page on GitHub <https://github.com/OttoWinter/esphomedocs/blob/current/esphomeyaml/components/binary_sensor/index.rst>`__
|
||
|
||
.. toctree::
|
||
:maxdepth: 1
|
||
|
||
gpio.rst
|
||
status.rst
|
||
esp32_ble.rst
|
||
esp32_touch.rst
|
||
template.rst
|