Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2024-11-17 11:05:39 +01:00
Code Issues Projects Releases Wiki Activity
c8ff8f8d75
esphome-docs/components/sensor/ld2420.rst
Dawid Cieszyński 0ee6b29edb
Update ld2420.rst (#3402) 
Replace timeout with presence_timeout in the example
2023-11-28 11:08:02 +01:00

447 lines
14 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.

LD2420 24Ghz mmWave Radar Sensor
================================
.. seo::
:description: Instructions for setting up LD2420 sensors.
:image: ld2420.jpg
Component
---------
.. _ld2420-component:
The ``ld2420`` sensor platform allows you to use the HLK-LD2420 motion and presence sensor.
The :ref:`UART <uart>` is required to be set up in your configuration for this sensor to work.
Depending on the firmware you have serial baudrates will be 256000 for any module with less than
firmware v1.5.3 and 115200 on newer versions. The tx_pin changed from ot2 to ot1 with firmware v1.5.3.
Firmware v1.5.4 and up now features the ability to observe gate energy signal levels and with this
release we can dynamically calibrate gate still and move thresholds.
This component has dynamic configuration functionallity with a compact UI format.
Select, number and button components provide configuration value inputs and control.
.. figure:: /images/ld2420.jpg
:align: center
:width: 50.0%
HLK-LD2420 Low power motion and presence sensor.
Module Pinouts
--------------
.. list-table:: Firmware 1.5.2 and older
:widths: 25 25 25
:header-rows: 1
* - Pin#
- Name
- Function
* - 1
- 3v3
- VCC
* - 2
- GND
- GND
* - 3
- OT1
- Presence Signal Output
* - 4
- RX
- Serial Rx (to ESP Tx)
* - 5
- OT2
- Serial Tx (to ESP Rx)
.. list-table:: Firmware 1.5.3 and newer
:widths: 25 25 25
:header-rows: 1
* - Pin#
- Name
- Function
* - 1
- 3v3
- VCC
* - 2
- GND
- GND
* - 3
- OT1
- Serial Tx (to ESP Rx)
* - 4
- RX
- Serial Rx (to ESP Tx)
* - 5
- OT2
- Presence Signal Output
.. code-block:: yaml
# Example configuration entry
ld2420:
text_sensor:
- platform: ld2420
fw_version:
name: LD2420 Firmware
sensor:
- platform: ld2420
moving_distance:
name : Moving Distance
binary_sensor:
- platform: ld2420
has_target:
name: Presence
select:
- platform: ld2420
operating_mode:
name: Operating Mode
number:
- platform: ld2420
presence_timeout:
name: Detection Presence Timeout
min_gate_distance:
name: Detection Gate Minimum
max_gate_distance:
name: Detection Gate Maximum
# See "Number" section below for detail
gate_select:
name: Select Gate to Set
still_threshold:
name: Set Still Threshold Value
move_threshold:
name: Set Move Threshold Value
button:
- platform: ld2420
apply_config:
name: Apply Config
factory_reset:
name: Factory Reset
restart_module:
name: Restart Module
revert_config:
name: Undo Edits
Platform
--------
.. code-block:: yaml
ld2420:
Configuration variables:
************************
**ld2420** (*Required*): Component platform.
Select
------
**Operating Modes:**
.. code-block:: yaml
select:
- platform: ld2420
operating_mode:
name: Operating Mode
The dynamic UI provides three operational modes: **Normal**, **Calibrate** and **Simple**. The select component allows
you to choose the active mode.
- **Normal**: This is the default mode. It sets the ld2420 in energy reporting mode and is availble with firmware
v1.5.4 or greater. When in this mode the module logs all gate energy levels continuouly in a local array making it
available for dynamic calibration functions.
- **Calibrate**: When calibration mode is selected the module will collect the average and peak energy levels,
reporting them every five seconds. The report is provided in the log console for information only. In order to
calibrate the gate configuration, no objects should be present in the target environment. The recording will
establish the mmWave noise floor levels and undesirable reflections or signal distortions peaks. This should be
collected for at least 30 seconds. Longer runs can catch more potential false signals when devices near the module
are used such as microwave ovens and other sources of noise.
When the **apply_config** button is pressed in calibration mode the LD2420 will be configured with calculated values
based on its collected noise floor data and the module will return to Normal Mode. Selecting any other mode drops the
session's collected noise data and no changed settings are staged. Once the **apply_config** action is performed, the
computed values will then persist. The gate values can be manually adjusted or calibrated again or you can use the
factory reset button to restore the module's default settings.
- **Simple**: Provides backward compatibility with firmware v1.5.3 and older and will be automatically set when the
detected firmware version is v1.5.3 or older.
Configuration variables:
************************
- **operating_mode** (*Required*): Provisions the operating mode select component.
May contain any options from :ref:`Select <config-select>`.
Number
------
.. code-block:: yaml
number:
- platform: ld2420
presence_timeout:
name: Detection Presence Timeout
min_gate_distance:
name: Detection Gate Minimum
max_gate_distance:
name: Detection Gate Maximum
gate_select:
name: Select Gate to Set
still_threshold:
name: Set Still Threshold Value
move_threshold:
name: Set Move Threshold Value
gate_move_sensitivity:
name: Move Calibration Sensitivity Factor
gate_still_sensitivity:
name: Still Calibration Sensitivity Factor
gate_0:
move_threshold:
name: Gate 0 Move Threshold
still_threshold:
name: Gate 0 Still Threshold
gate_1:
move_threshold:
name: Gate 1 Move Threshold
still_threshold:
name: Gate 1 Still Threshold
Configuration variables:
************************
- **presence_timeout** (*Optional*): The time in seconds during which the occupied state (presence) will persist after
presence is no longer detected. Any energy detection within the time window restarts the countdown from this value.
Defaults to 120s. **Required** when ``min_gate_distance`` and ``max_gate_distance`` is specified. May contain any
options from :ref:`Number <config-number>`.
- **min_gate_distance** (*Optional*): Minimum distance for move or still energy detection. Value between 0 and
``max_gate_distance`` - 1. Each increment equals 70 cm. Defaults to 1. **Required** when ``presence_timeout`` and
``max_gate_distance`` is specified. May contain any options from :ref:`Number <config-number>`.
- **max_gate_distance** (*Optional*): Maximum gate for movement detection. Value from 1 to 15. Each gate detects
movement and still energy at 70 cm increments. At the maximum value, the sensor’s range equates to 16 * 70 cm
resulting in an approximately 12-meter range; however, accuracy at this range may be diminished. The recommended
maximum value is 12 * 70 cm which results in approximately 9 meters. **Required** when ``presence_timeout`` and
``min_gate_distance`` is specified. May contain any options from :ref:`Number <config-number>`.
- **gate_still_sensitivity** (*Optional*): Gate still threshold calibration sensitivity factor. Defaults to 0.5 with a
range of 0-1, 0 = high and 1 = low. May contain any options from :ref:`Number <config-number>`.
- **gate_move_sensitivity** (*Optional*): Gate move threshold calibration sensitivity factor. Defaults to 0.5 with a
range of 0-1, 0 = high and 1 = low. May contain any options from :ref:`Number <config-number>`.
- **gate_select** (*Optional*): Selection of gate value to edit (gate # from 0 to 15). Gate thresholds
are edited by selecting the gate number and then adjusting the move and still thresholds. **Note that when this
variable is defined, the component will run in compact UI mode and the following two configuration variables are then
required:** May contain any options from :ref:`Number <config-number>`.
- **still_threshold** (*Optional*): Gate still value threshold level for motion energy detection on a currently
selected gate number. A value greater than that specified for the gate (distance) will trigger movement detection.
May contain any options from :ref:`Number <config-number>`.
- **move_threshold** (*Optional*): Gate move value threshold level for still energy detection on a currently selected
gate number. A value less than that specified for the gate (distance) will trigger still detection. May contain any
options from :ref:`Number <config-number>`.
- **gate_n** (*Optional*): Provides individual gate threshold number inputs. Range is ``gate_0`` to ``gate_15``.
**May not be used with** ``gate_select`` (above). Each gate entry requires a ``still_threshold`` and ``move_threshold``:
- **still_threshold** (*Required for each gate_n entry*): Gate still value threshold level for motion energy
detection on currently selected gate number. A value greater than that specified for the gate (distance) will
trigger movement detection. May contain any options from :ref:`Number <config-number>`.
- **move_threshold** (*Required for each gate_n entry*): Gate move value threshold level for still energy
detection on currently selected gate number. A value less than that specified for the gate (distance) will
trigger still detection. May contain any options from :ref:`Number <config-number>`.
Button
------
.. code-block:: yaml
button:
- platform: ld2420
apply_config:
name: Apply Config
factory_reset:
name: Factory Reset
restart_module:
name: Restart Module
revert_config:
name: Undo Edits
Four button components are available enabling configuration controls for editing, saving, restarting and factory reseting the LD2420 module.
Configuration variables:
************************
- **apply_config** (*Optional*): Saves both manual config tuning or the auto calibrate still and move threshold config
settings. May contain any options from :ref:`Button <config-button>`.
- **restart_module** (*Optional*): Reboots the LD2420 modules. May contain any options from :ref:`Button <config-button>`.
- **revert_config** (*Optional*): Undoes in-progress edits prior to their application via the ``apply_config`` button.
May contain any options from :ref:`Button <config-button>`.
- **factory_reset** (*Optional*): Restores a base set of LD2420 configuration values. May contain any options from
:ref:`Button <config-button>`.
Factory Reset Values:
*********************
.. _ld2420-default_values_for_gate_threshold:
.. list-table::
:widths: 25 25
:header-rows: 1
* - Setting:
- Value:
* - Timeout
- 120s
* - Min Gate Distance
- 1
* - Max Gate Distance
- 12
.. list-table::
:widths: 25 25 25
:header-rows: 1
* - Gate Number:
- Move threshold
- Still threshold
* - 0
- 60000
- 40000
* - 1
- 30000
- 20000
* - 2
- 400
- 200
* - 3
- 300
- 250
* - 4
- 250
- 150
* - 5
- 250
- 150
* - 6
- 250
- 150
* - 7
- 250
- 150
* - 8
- 300
- 150
* - 9
- 250
- 150
* - 10
- 250
- 150
* - 11
- 250
- 150
* - 12
- 250
- 100
* - 13
- 200
- 100
* - 14
- 200
- 100
* - 15
- 200
- 100
Sensor
------
The ``ld2420`` sensor allows you to use your :doc:`ld2420` to approximate the distance
between the sensor and an object moving within its field of detection.
.. code-block:: yaml
sensor:
- platform: ld2420
moving_distance:
name : Moving Distance
Configuration variables:
************************
- **moving_distance** (*Optional*): Distance between the sensor and the detected moving target. May contain any options
from :ref:`Sensor <config-sensor>`.
Binary Sensor
-------------
The ``ld2420`` binary sensor allows you to use your :doc:`ld2420` to sense presence.
.. code-block:: yaml
binary_sensor:
- platform: ld2420
has_target:
name: Presence
Configuration variables:
************************
- **has_target** (*Optional*): If a target is detected with either still or in movement **has_target** will be set true
for the duration of the **presence_time_window** setting. May contain any options from
:ref:`Binary Sensor <config-binary_sensor>`.
Text Sensor
-----------
The ``ld2420`` text sensor provides version information for the :doc:`ld2420`.
.. code-block:: yaml
text_sensor:
- platform: ld2420
fw_version:
name: LD2420 Firmware
Configuration variables:
************************
- **fw_version** (*Optional*): Allows you to retrieve the :doc:`ld2420` firmware version. May contain any options from
:ref:`Text Sensor <config-text_sensor>`.
Important Information
---------------------
Solid objects and noise outside the ``detection_gate_max`` and ``detection_gate_min`` may cause false
detections or result in abnormal gate thresholds. For example, a wall within the gate max range can result
in signal reflections. If your sensor reports unexpected detections, you should test it by placing it in a
completely open room with no moving objects.
Also, never place two or more sensors in a manner such that their detection fields overlap, as this will certainly
result in false detections.
Firmware update capability is available using the LD2420 tool provided by HLKTech.
You will need to email them and request the bin file.
At this time only firmware version v1.5.6 and up can be upgraded.
**DO NOT** attempt to update to older firmware versions. It will brick the module.
See Also
--------
- Official Datasheet/Manuals are still in development; for info email `sales@hlktech.com`.
- Official web site `https://www.hlktech.net/`
- :ghedit:`Edit`
Reference in New Issue View Git Blame Copy Permalink