mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-12-24 17:08:15 +01:00
LD2420 Documentation (#2956)
Co-authored-by: Keith Burzinski <kbx81x@gmail.com> Co-authored-by: descipher <120155735+GelidusResearch@users.noreply.github.com> Co-authored-by: descipher <mike.laspina@gelidus.ca>
This commit is contained in:
Mike La Spina
GitHub
parent
c499ef2522
commit
7022723bc7
450
components/sensor/ld2420.rst
Normal file
450
components/sensor/ld2420.rst
Normal file
@ -0,0 +1,450 @@
|
||||
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.
|
||||
|
||||
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
|
||||
uart:
|
||||
id: ld2420_uart
|
||||
tx_pin: REPLACEME
|
||||
rx_pin: REPLACEME
|
||||
baud_rate: 115200
|
||||
parity: NONE
|
||||
stop_bits: 1
|
||||
|
||||
# The LD2420 has 16 time gate intervals (0-15) with a gate
|
||||
# resolution of 0.70 meters
|
||||
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
|
||||
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.
|
||||
|
||||
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.
|
||||
- **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.
|
||||
- **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.
|
||||
- **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.
|
||||
- **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.
|
||||
|
||||
- **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:**
|
||||
|
||||
- **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.
|
||||
- **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.
|
||||
|
||||
- **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.
|
||||
- **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.
|
||||
|
||||
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.
|
||||
|
||||
- **restart_module** (*Optional*): Reboots the LD2420 modules.
|
||||
|
||||
- **revert_config** (*Optional*): Undoes in-progress edits prior to their application via the ``apply_config`` button.
|
||||
|
||||
- **factory_reset** (*Optional*): Restores a base set of LD2420 configuration values.
|
||||
|
||||
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.
|
||||
All 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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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`
|
||||
BIN
images/ld2420.jpg
Normal file
BIN
images/ld2420.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
@ -409,6 +409,8 @@ Motion
|
||||
MPU6050, components/sensor/mpu6050, mpu6050.jpg, Accelerometer & Gyroscope
|
||||
MPU6886, components/sensor/mpu6886, mpu6886.jpg, Accelerometer & Gyroscope
|
||||
RuuviTag, components/sensor/ruuvitag, ruuvitag.jpg, Temperature & Humidity & Accelerometer
|
||||
HLK-LD2410, components/sensor/ld2410, ld2410.jpg, Motion & Presence
|
||||
HLK-LD2420, components/sensor/ld2420, ld2420.jpg, Motion & Presence
|
||||
|
||||
|
||||
Thermocouple
|
||||
@ -502,7 +504,6 @@ Miscellaneous
|
||||
Analog Threshold, components/binary_sensor/analog_threshold, analog_threshold.svg, dark-invert
|
||||
ESP32 BLE Presence, components/binary_sensor/ble_presence, bluetooth.svg, dark-invert
|
||||
Hydreon Rain Sensor Binary Sensor, components/binary_sensor/hydreon_rgxx, hydreon_rg9.jpg
|
||||
LD2410, components/sensor/ld2410, ld2410.jpg
|
||||
Modbus Binary Sensor, components/binary_sensor/modbus_controller, modbus.png
|
||||
PipSolar - compatible PV Inverter, components/pipsolar, pipsolar.jpg
|
||||
Qwiic PIR Motion, components/binary_sensor/qwiic_pir, qwiic_pir.jpg
|
||||
|
||||
Loading…
Reference in New Issue
Block a user