esphome-docs/components/sensor/ultrasonic.rst
2019-03-05 20:42:43 +01:00

91 lines
3.2 KiB
ReStructuredText
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Ultrasonic Distance Sensor
==========================
.. seo::
:description: Instructions for setting up ultrasonic distance measurement sensors in ESPHome.
:image: ultrasonic.jpg
:keywords: ultrasonic, hc-sr04
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>`__,
`sparkfun <https://www.sparkfun.com/products/13959>`__) with ESPHome
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
timeout option which specifies how long to wait for values. During this
timeout period the whole core will be blocked and therefore shouldn't be
set too high.
.. figure:: images/ultrasonic-full.jpg
:align: center
:width: 50.0%
HC-SR04 Ultrasonic Distance Sensor.
.. figure:: images/ultrasonic-ui.png
:align: center
:width: 80.0%
.. code-block:: yaml
# Example configuration entry
sensor:
- platform: ultrasonic
trigger_pin: D1
echo_pin: D2
name: "Ultrasonic Sensor"
Configuration variables:
------------------------
- **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.
- **timeout_meter** (*Optional*, float): The number of meters for the
timeout. Use either this or ``timeout_time``. Defaults to 2 meters.
- **timeout_time** (*Optional*, int): The number of microseconds for
the timeout. Use either this or ``timeout_meter``. Defaults to
11662µs.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
sensor. Defaults to ``60s``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- All other options from :ref:`Sensor <config-sensor>`.
Ultrasonic Timeouts
-------------------
The ultrasonic sensor works by sending a small ultrasonic pulse out and then waiting until
the pulse arrives back. However, there are cases where no such signal arrives back. This is most commonly caused
by either having the sensor pointed at a soft surface that muffles the incoming signal. The other case where this
can happen is when the the object is too far away and the timeout set by the ``timeout_meter`` or ``timeout_time``
option kicks in.
To remove ``NAN`` values from the sensor stream, use the ``filter_nan`` :ref:`sensor filter <sensor-filters>`:
.. code-block:: yaml
sensor:
- platform: ultrasonic
trigger_pin: D1
echo_pin: D2
name: "Ultrasonic Sensor"
filters:
- filter_nan:
See Also
--------
- :ref:`sensor-filters`
- :doc:`template`
- :apiref:`sensor/ultrasonic_sensor.h`
- :ghedit:`Edit`