.. include:: ../Plugin/_plugin_substitutions_p01x.repl .. _P013_page: |P013_typename| ================================================== |P013_shortinfo| Plugin details -------------- Type: |P013_type| Name: |P013_name| Status: |P013_status| GitHub: |P013_github|_ Maintainer: |P013_maintainer| Used libraries: |P013_usedlibraries|_ Supported hardware ------------------ HC-SR04 ======= .. image:: P013_HC-SR04_1.jpg :width: 600 RCW-0001 ======== .. image:: P013_RCW-0001_1.jpg US-100 ====== .. image:: P013_US-100_1.jpg Introduction ------------ The HC-SR04/RCW-0001/US-100 is an ultrasonic distance sensor. It's able to indicate distances between 2 cm up to about 300 cm at a resolution of about 0.3 cm. Specifications: * Ultrasonic distance sensor * Measure angle: 30° * Ranging distance: 2cm - 300cm (some have reporting it work good up to 400 cm) Wiring ------ The HC-SR04/RCW-0001/US-100 must be run on 5V. Running it with 3.3V will show very weak results or nothing at all. .. code-block:: none ESP HC-SR04/RCW-0001/US-100 GPIO (X) <--> Trigger GPIO (X) <--> Echo (voltage divider!) Power 5.0V <--> VCC GND <--> GND .. warning:: Do not connect 5V directly to the ESP! Read more about :ref:`P000_Level_converter_page`. Setup ----- .. image:: P013_Setup_HC-SR04_1.png Task settings ~~~~~~~~~~~~~ * **Device**: Name of plugin * **Name**: Name of the task (example name **HCSR04**), should not be empty. * **Enable**: Should the task be enabled or not Sensor ^^^^^^ * **GPIO --> Trigger**: Set the GPIO to trigger the signal. * **GPIO --> Echo, 5V**: Set the GPIO to receive the echo signal, a voltage divider is needed. .. image:: P013_ModeOptions.png * **Mode**: ``Value`` is the most used setting, it will output the distance in centimeters. If you want the plugin to report a ``1`` or a ``0`` you use the ``State`` setting. State or Combined will open up a new field called "Threshold" which will allow you to enter a value. If the unit detects a value below the given threshold the task will be set to ``1``, if the detected value is above the given threshold the task will be ``0``. You should set the Interval to zero in case of using the state setting, just to make sure the action is triggered as soon as possible. A third option is to combine both the ``Value`` and ``State`` modes, to have both the distance and state values available. This mode is called ``Combined``. .. .. image:: P013_StateEvent.png .. * **State event (also) on Interval**: Only available when **Mode** is set to ``State`` or ``Combined``. When enabled will repeat the last State on every Interval, when disabled will only send an event if the state is actually changed. * **Threshold**: Set the distance that will trigger the event for the ``State`` or ``Combined`` mode. * **Max distance**: Set the max value the task will show. If the actual value is above the max distance the max distance will be displayed. Set to ``0`` will disable the max distance setting. Max according to the specifications is ``300`` cm. * **Unit**: You can show the output value as imperial without the need to do it using the formula function. * **Filter**: The signal might be a bit shaky for some applications, try to use the ``Median`` filtering setting in that case. * **Trigger width**: For hardware that doesn't exactly follow the timing guidelines, it may be needed to extend the pulse delay somewhat to receive a usable echo. The default is 10 microsoconds, and can be increased in small steps to max. 20 microseconds. Data acquisition ^^^^^^^^^^^^^^^^ * **Single event with all values**: This setting combines all values for the plugin in a single ``#All,[,]`` event. * **Send to controller** 1..3: Check which controller (if any) you want to publish to. All or no controller can be used. * **Interval**: How often should the task publish its value (1..5 seconds is normal for the ``Value`` or ``Combined`` settings, 0 for the ``State`` setting). Indicators (recommended settings) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. csv-table:: :header: "Indicator", "Value Name", "Interval", "Decimals", "Extra information" :widths: 8, 5, 5, 5, 40 "Distance", "Distance", "1", "1", "Used to get the actual distance that the sensor is measuring." "State", "State", "0", "0", "Used to set the value high or low, just like a normal switch input device." Rules examples -------------- .. code-block:: on HCSR04#distance do if %eventvalue1%<50 and %eventvalue1%>45 GPIO,14,1 //light up LED to show that you're at the correct position else GPIO,14,0 endif endon .. Commands available .. ~~~~~~~~~~~~~~~~~~ .. .. include:: P013_commands.repl Where to buy ------------ .. csv-table:: :header: "Store", "Link" :widths: 5, 40 "AliExpress","`Link 1 ($) `_" "Banggood","`Link 2 ($) `_" "eBay","`Link 3 ($) `_" |affiliate| Change log ---------- .. versionchanged:: 2.0 ... |added| Major overhaul for 2.0 release. .. versionadded:: 1.0 ... |added| Initial release version.