mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-12-26 17:27:47 +01:00
447 lines
14 KiB
ReStructuredText
447 lines
14 KiB
ReStructuredText
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
|
||
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`
|