esphome-docs/esphomeyaml/components/binary_sensor/index.rst

305 lines
9.7 KiB
ReStructuredText
Raw Normal View History

2018-05-13 11:37:02 +02:00
Binary Sensor Component
=======================
2018-11-14 22:12:27 +01:00
.. seo::
:description: Information about the base representation of all binary sensors.
:image: folder-open.png
2018-11-14 22:12:27 +01:00
2018-05-13 11:37:02 +02:00
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.
2018-06-01 18:10:00 +02:00
.. _config-binary_sensor:
2018-05-13 11:37:02 +02:00
Base Binary Sensor Configuration
2018-06-01 18:10:00 +02:00
--------------------------------
2018-05-13 11:37:02 +02:00
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
2018-05-13 11:37:02 +02:00
binary_sensor:
- platform: ...
2018-06-01 18:10:00 +02:00
device_class: motion
2018-05-13 11:37:02 +02:00
Configuration variables:
2018-06-01 18:10:00 +02:00
- **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.
2018-06-13 22:38:49 +02:00
- **filters** (*Optional*, list): A list of filters to apply on the binary sensor values such as
inverting signals. See :ref:`binary_sensor-filters`.
Automations:
2018-06-01 18:10:00 +02:00
- **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`.
2018-06-13 22:38:49 +02:00
- **on_double_click** (*Optional*, :ref:`Automation <automation>`): An automation to perform
2018-06-01 18:10:00 +02:00
when the button is pressed twice for specified periods of time.
See :ref:`binary_sensor-on_double_click`.
- **on_multi_click** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the button is pressed in a specific sequence.
See :ref:`binary_sensor-on_multi_click`.
2018-06-01 18:10:00 +02:00
- All other options from :ref:`MQTT Component <config-mqtt-component>`.
2018-06-13 22:38:49 +02:00
.. _binary_sensor-filters:
Binary Sensor Filters
---------------------
With binary sensor filters you can customize how esphomelib handles your binary sensor values even more.
They are similar to :ref:`Sensor Filters <sensor-filters>`.
.. code-block:: yaml
2018-06-13 22:38:49 +02:00
binary_sensor:
- platform: ...
# ...
filters:
- invert:
- delayed_on: 100ms
2018-06-14 00:05:10 +02:00
- delayed_off: 100ms
2018-06-13 22:38:49 +02:00
- lambda: >-
if (id(other_binary_sensor).state) {
2018-06-13 22:38:49 +02:00
return x;
} else {
return {};
}
2018-09-23 19:00:31 +02:00
- heartbeat: 5s
2018-06-13 22:38:49 +02:00
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**.
2018-06-14 00:05:10 +02:00
- **delayed_off**: When a signal OFF is received, wait for the specified time period until publishing
2018-06-13 22:38:49 +02:00
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 <config-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.
2018-09-23 19:00:31 +02:00
- **heartbeat**: Periodically send out the last received value from the binary sensor with the given
interval. All state changes are still immediately published.
2018-06-13 22:38:49 +02:00
2018-06-01 18:10:00 +02:00
Binary Sensor Automation
2018-06-13 22:38:49 +02:00
------------------------
2018-06-01 18:10:00 +02:00
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).state``.
2018-06-01 18:10:00 +02:00
.. _binary_sensor-on_press:
``on_press``
2018-10-12 16:33:22 +02:00
************
2018-06-01 18:10:00 +02:00
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
2018-06-01 18:10:00 +02:00
binary_sensor:
- platform: gpio
# ...
on_press:
then:
2018-11-10 14:31:27 +01:00
- switch.turn_on: relay_1
2018-06-01 18:10:00 +02:00
Configuration variables: See :ref:`Automation <automation>`.
.. _binary_sensor-on_release:
``on_release``
2018-10-12 16:33:22 +02:00
**************
2018-06-01 18:10:00 +02:00
This automation will be triggered when a button press ends, or in other words on the falling
edge of the signal.
.. code-block:: yaml
2018-06-01 18:10:00 +02:00
binary_sensor:
- platform: gpio
# ...
on_release:
then:
2018-11-10 14:31:27 +01:00
- switch.turn_off: relay_1
2018-06-01 18:10:00 +02:00
Configuration variables: See :ref:`Automation <automation>`.
.. _binary_sensor-on_click:
``on_click``
2018-10-12 16:33:22 +02:00
************
2018-06-01 18:10:00 +02:00
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
2018-06-01 18:10:00 +02:00
binary_sensor:
- platform: gpio
# ...
on_click:
min_length: 50ms
max_length: 350ms
then:
2018-11-10 14:31:27 +01:00
- switch.turn_off: relay_1
2018-06-01 18:10:00 +02:00
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``
2018-10-12 16:33:22 +02:00
*******************
2018-06-01 18:10:00 +02:00
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
2018-06-01 18:10:00 +02:00
binary_sensor:
- platform: gpio
# ...
on_double_click:
min_length: 50ms
max_length: 350ms
then:
2018-11-10 14:31:27 +01:00
- switch.turn_off: relay_1
2018-06-01 18:10:00 +02:00
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_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:
2018-11-13 19:00:58 +01:00
- logger.log: "Double-Clicked"
Configuration variables:
- **timing** (**Required**): The timing of the multi click. This uses a language-based grammar using
these styles:
- ``<ON/OFF> for <TIME> to <TIME>``
- ``<ON/OFF> for at least <TIME>``
- ``<ON/OFF> for at most <TIME>``
- **invalid_cooldown** (*Optional*, :ref:`config-time`): If a multi click is started, but the timing
set in ``timing`` does not match, a "cool down" period will be activated during which no timing
will be matched. Defaults to ``1s``.
- See :ref:`Automation <automation>`.
.. note::
Getting the timing right for your use-case can sometimes be a bit difficult. If you set the
:ref:`global log level <logger-log_levels>` to ``VERBOSE``, the multi click trigger shows logs
about what stopped the trigger from happening.
You can use an ``OFF`` timing at the end of the timing sequence to differentiate between different
kinds of presses. For example the configuration below will differentiate between double, long and short
presses.
.. code-block:: yaml
on_multi_click:
- timing:
2018-11-13 19:00:58 +01:00
- ON for at most 1s
- OFF for at most 1s
- ON for at most 1s
- OFF for at least 0.2s
then:
2018-11-13 19:00:58 +01:00
- logger.log: "Double Clicked"
- timing:
2018-11-13 19:00:58 +01:00
- OFF for 1s to 2s
- ON for 1s to 2s
- OFF for at least 0.5s
then:
2018-11-13 19:00:58 +01:00
- logger.log: "Single Long Clicked"
- timing:
2018-11-13 19:00:58 +01:00
- ON for at most 1s
- OFF for at least 0.5s
then:
2018-11-13 19:00:58 +01:00
- logger.log: "Single Short Clicked"
2018-06-07 15:55:31 +02:00
lambda calls
2018-10-12 16:33:22 +02:00
************
2018-06-07 15:55:31 +02:00
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-block:: yaml
2018-06-07 15:55:31 +02:00
// 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);
- ``.state``: Retrieve the current state of the binary sensor.
2018-06-07 15:55:31 +02:00
.. code-block:: yaml
2018-06-07 15:55:31 +02:00
// Within lambda, get the binary sensor state and conditionally do something
if (id(my_binary_sensor).state) {
2018-06-07 15:55:31 +02:00
// Binary sensor is ON, do something here
} else {
// Binary sensor is OFF, do something else here
}
2018-06-01 18:10:00 +02:00
See Also
--------
- :doc:`API Reference </api/binary_sensor/index>`
2018-06-04 08:17:22 +02:00
- `Edit this page on GitHub <https://github.com/OttoWinter/esphomedocs/blob/current/esphomeyaml/components/binary_sensor/index.rst>`__
2018-06-01 18:10:00 +02:00
.. toctree::
:maxdepth: 1
:glob:
2018-06-01 18:10:00 +02:00
*
2018-10-12 16:33:22 +02:00
.. disqus::