esphome-docs/components/binary_sensor/gpio.rst

107 lines
2.7 KiB
ReStructuredText
Raw Normal View History

.. _gpio-binary-sensor:
2018-05-13 11:37:02 +02:00
GPIO Binary Sensor
==================
2018-11-14 22:12:27 +01:00
.. seo::
2019-02-16 23:25:23 +01:00
:description: Instructions for setting up GPIO binary sensors with ESPHome.
:image: pin.svg
2018-11-14 22:12:27 +01:00
2018-05-13 11:37:02 +02:00
The GPIO Binary Sensor platform allows you to use any input pin on your
device as a binary sensor.
2018-06-01 18:10:00 +02:00
.. figure:: images/gpio-ui.png
:align: center
:width: 80.0%
2018-05-13 11:37:02 +02:00
.. code-block:: yaml
2018-05-13 11:37:02 +02:00
# Example configuration entry
binary_sensor:
- platform: gpio
pin: D2
name: "Living Room Window"
device_class: window
Configuration variables:
2018-08-24 22:44:01 +02:00
------------------------
2018-05-13 11:37:02 +02:00
2018-06-01 18:10:00 +02:00
- **pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin to periodically check.
- **name** (**Required**, string): The name of the binary sensor.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
2019-02-17 12:28:17 +01:00
- All other options from :ref:`Binary Sensor <config-binary_sensor>`.
2018-06-01 18:10:00 +02:00
2019-02-16 23:25:23 +01:00
Activating internal pullups
---------------------------
2018-06-13 22:38:49 +02:00
2019-02-16 23:25:23 +01:00
If you're hooking up a button without an external pullup or see lots of ON/OFF events
in the log output all the time, this often means the GPIO pin is floating.
2018-06-13 22:38:49 +02:00
2019-02-16 23:25:23 +01:00
For these cases you need to manually enable the pull-up (or pull-down) resistors on the ESP,
you can do so with the :ref:`Pin Schema <config-pin_schema>`.
2018-06-13 22:38:49 +02:00
2019-02-16 23:25:23 +01:00
.. code-block:: yaml
binary_sensor:
- platform: gpio
pin:
number: D2
mode:
input: true
pullup: true
2019-02-16 23:25:23 +01:00
name: ...
2018-06-13 22:38:49 +02:00
Inverting Values
2018-08-24 22:44:01 +02:00
----------------
2018-06-13 22:38:49 +02:00
Use the ``inverted`` property of the :ref:`Pin Schema <config-pin_schema>` to invert the binary
sensor:
.. code-block:: yaml
2018-06-13 22:38:49 +02:00
# Example configuration entry
binary_sensor:
- platform: gpio
pin:
number: D2
inverted: true
2018-06-13 22:38:49 +02:00
name: ...
Debouncing Values
2018-08-24 22:44:01 +02:00
-----------------
2018-06-13 22:38:49 +02:00
Some binary sensors are a bit unstable and quickly transition between the ON and OFF state while
they're pressed. To fix this and debounce the signal, use the :ref:`binary sensor filters <binary_sensor-filters>`:
.. code-block:: yaml
2018-06-13 22:38:49 +02:00
# Example configuration entry
binary_sensor:
- platform: gpio
pin: D2
name: ...
filters:
- delayed_on: 10ms
Above example will only make the signal go high if the button has stayed high for more than 10ms.
Alternatively, below configuration will make the binary sensor publish an ON value immediately, but
will wait 10ms before publishing an OFF value:
.. code-block:: yaml
2018-06-13 22:38:49 +02:00
# Example configuration entry
binary_sensor:
- platform: gpio
pin: D2
name: ...
filters:
- delayed_off: 10ms
2018-06-01 18:10:00 +02:00
See Also
2018-08-24 22:44:01 +02:00
--------
2018-06-01 18:10:00 +02:00
- :doc:`/components/binary_sensor/index`
2018-06-01 18:10:00 +02:00
- :ref:`config-pin_schema`
2019-05-12 22:44:59 +02:00
- :apiref:`gpio/binary_sensor/gpio_binary_sensor.h`
- :ghedit:`Edit`