diff --git a/components/sensor/ld2420.rst b/components/sensor/ld2420.rst new file mode 100644 index 000000000..ea1770d30 --- /dev/null +++ b/components/sensor/ld2420.rst @@ -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 ` 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 `. + +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` diff --git a/images/ld2420.jpg b/images/ld2420.jpg new file mode 100644 index 000000000..3743d96b8 Binary files /dev/null and b/images/ld2420.jpg differ diff --git a/index.rst b/index.rst index fef5cd9d0..29735af56 100644 --- a/index.rst +++ b/index.rst @@ -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