esphome-docs/components/sensor/ultrasonic.rst

69 lines
2.3 KiB
ReStructuredText
Raw Normal View History

2018-05-13 11:37:02 +02:00
Ultrasonic Distance Sensor
==========================
2018-11-14 22:12:27 +01:00
.. seo::
2019-02-16 23:25:23 +01:00
:description: Instructions for setting up ultrasonic distance measurement sensors in ESPHome.
2018-11-14 22:12:27 +01:00
:image: ultrasonic.jpg
:keywords: ultrasonic, hc-sr04
2018-05-13 11:37:02 +02:00
The ultrasonic distance sensor allows you to use simple ultrasonic
sensors like the HC-SR04
(`datasheet <https://www.electroschematics.com/wp-content/uploads/2013/07/HC-SR04-datasheet-version-2.pdf>`__,
2019-02-16 23:25:23 +01:00
`sparkfun <https://www.sparkfun.com/products/13959>`__) with ESPHome
2018-05-13 11:37:02 +02:00
to measure distances. These sensors usually cant measure anything more
than about two meters and may sometimes make some annoying clicking
sounds.
This sensor platform expects a sensor that can be sent a **trigger
pulse** on a specific pin and will send out a **echo pulse** once a
measurement has been taken. Because sometimes (for example if no object
is detected) the echo pulse is never returned, this sensor also has a
2019-03-14 16:41:37 +01:00
timeout option which specifies how long to wait for values.
2018-05-13 11:37:02 +02:00
2018-06-07 14:54:11 +02:00
.. figure:: images/ultrasonic-full.jpg
2018-06-01 18:10:00 +02:00
:align: center
:width: 50.0%
2018-05-13 11:37:02 +02:00
2018-06-01 18:10:00 +02:00
HC-SR04 Ultrasonic Distance Sensor.
2018-05-13 11:37:02 +02:00
2018-06-01 18:10:00 +02:00
.. figure:: images/ultrasonic-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
sensor:
- platform: ultrasonic
trigger_pin: D1
echo_pin: D2
name: "Ultrasonic Sensor"
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
- **trigger_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The output pin to
periodically send the trigger pulse to.
- **echo_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The input pin on which to
wait for the echo.
- **name** (**Required**, string): The name of the sensor.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
2019-01-06 18:56:14 +01:00
sensor. Defaults to ``60s``.
2019-02-17 12:28:17 +01:00
- All other options from :ref:`Sensor <config-sensor>`.
2018-06-01 18:10:00 +02:00
2019-05-12 22:44:59 +02:00
Advanced options:
- **timeout** (*Optional*, float): The number of meters for the
timeout. Most sensors can only sense up to 2 meters. Defaults to 2 meters.
- **pulse_time** (*Optional*, :ref:`config-time`): The duration for which the trigger pin will be
active. Defaults to ``10us``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
2018-06-08 20:41:42 +02:00
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
- :ref:`sensor-filters`
- :doc:`template`
2019-05-12 22:44:59 +02:00
- :apiref:`ultrasonic/ultrasonic_sensor.h`
- :ghedit:`Edit`