diff --git a/components/binary_sensor/gpio.rst b/components/binary_sensor/gpio.rst index 96bbca3be..65aefcb12 100644 --- a/components/binary_sensor/gpio.rst +++ b/components/binary_sensor/gpio.rst @@ -1,3 +1,5 @@ +.. _gpio-binary-sensor: + GPIO Binary Sensor ================== diff --git a/components/sensor/bh1750.rst b/components/sensor/bh1750.rst index 3c5326afc..b571bef6e 100644 --- a/components/sensor/bh1750.rst +++ b/components/sensor/bh1750.rst @@ -1,3 +1,5 @@ +.. _BH1750: + BH1750 Ambient Light Sensor =========================== diff --git a/components/sensor/images/ld2410-card.png b/components/sensor/images/ld2410-card.png new file mode 100644 index 000000000..c5a6b1d3e Binary files /dev/null and b/components/sensor/images/ld2410-card.png differ diff --git a/components/sensor/ld2410.rst b/components/sensor/ld2410.rst index 8dbcc3652..0a032b55e 100644 --- a/components/sensor/ld2410.rst +++ b/components/sensor/ld2410.rst @@ -11,8 +11,8 @@ Component/Hub The ``ld2410`` sensor platform allows you to use HI-LINK LD2410 motion and presence sensor (`datasheet and user manual `__) with ESPHome. -The :ref:`UART ` is required to be set up in your configuration for this sensor to work. +The :ref:`UART ` is required to be set up in your configuration for this sensor to work, ``parity`` and ``stop_bits`` **must be** respectively ``NONE`` and ``1``. Use of hardware UART pins is highly recommended, in order to support the out-of-the-box 256000 baud rate of the LD2410 sensor. .. figure:: images/ld2410.jpg @@ -24,59 +24,265 @@ Use of hardware UART pins is highly recommended, in order to support the out-of- .. code-block:: yaml # Example configuration entry - uart: - tx_pin: REPLACEME - rx_pin: REPLACEME - baud_rate: 256000 - parity: NONE - stop_bits: 1 - ld2410: - timeout: 150s - max_move_distance : 6m - max_still_distance: 0.75m - g0_move_threshold: 10 - g0_still_threshold: 20 - g1_move_threshold: 10 - g1_still_threshold: 20 - g2_move_threshold: 20 - g2_still_threshold: 21 - g3_move_threshold: 30 - g3_still_threshold: 31 - g4_move_threshold: 40 - g4_still_threshold: 41 - g5_move_threshold: 50 - g5_still_threshold: 51 - g6_move_threshold: 60 - g6_still_threshold: 61 - g7_move_threshold: 70 - g7_still_threshold: 71 - g8_move_threshold: 80 - g8_still_threshold: 81 - - -.. note:: - - For UART configuration, ``baud_rate``, ``parity`` and ``stop_bits`` **must be** respectively ``256000``, ``NONE`` and ``1``. - - Use of hardware UART pins is highly recommended, in order to support the out-of-the-box 256000 baud rate of the LD2410 sensor. Configuration variables: ************************ -The configuration is made up of three parts: The central component, individual sensors, -and binary sensors. +- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component ` if you want + to use multiple UART buses. +- **throttle** (*Optional*, int): Time in milliseconds to control the rate of data updates. Defaults to ``1000ms``. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this :doc:`ld2410` component if you need multiple components. + +Binary Sensor +------------- + +The ``ld2410`` binary sensor allows you to use your :doc:`ld2410` to perform different +measurements. + +.. code-block:: yaml + + binary_sensor: + - platform: ld2410 + has_target: + name: Presence + has_moving_target: + name: Moving Target + has_still_target: + name: Still Target + out_pin_presence_status: + name: out pin presence status + +Configuration variables: +************************ + +- **has_target** (*Optional*): If true target detect either still or in movement. + All options from :ref:`Binary Sensor `. +- **has_moving_target** (*Optional*): If true a moving target is detected. + All options from :ref:`Binary Sensor `. +- **has_still_target** (*Optional*): If true a still target is detected. + All options from :ref:`Binary Sensor `. +- **out_pin_presence_status** (*Optional*): When in :ref:`engineering mode`, indicates whether the OUT pin indicates presence or not, otherwise ``false``. + OUT pin indication depends on the :ref:`light function` configuration. Might need latest firmware to work. + All options from :ref:`Binary Sensor `. +- **ld2410_id** (*Optional*, :ref:`config-id`): Manually specify the ID for the :doc:`ld2410` component if you are using multiple components. + +Sensor +------ + +The ``ld2410`` sensor allows you to use your :doc:`ld2410` to perform different +measurements. + +.. code-block:: yaml + + sensor: + - platform: ld2410 + light: + name: light + moving_distance: + name : Moving Distance + still_distance: + name: Still Distance + moving_energy: + name: Move Energy + still_energy: + name: Still Energy + detection_distance: + name: Detection Distance + g0: + move_energy: + name: g0 move energy + still_energy: + name: g0 still energy + g1: + move_energy: + name: g1 move energy + still_energy: + name: g1 still energy + g2: + move_energy: + name: g2 move energy + still_energy: + name: g2 still energy + g3: + move_energy: + name: g3 move energy + still_energy: + name: g3 still energy + g4: + move_energy: + name: g4 move energy + still_energy: + name: g4 still energy + g5: + move_energy: + name: g5 move energy + still_energy: + name: g5 still energy + g6: + move_energy: + name: g6 move energy + still_energy: + name: g6 still energy + g7: + move_energy: + name: g7 move energy + still_energy: + name: g7 still energy + g8: + move_energy: + name: g8 move energy + still_energy: + name: g8 still energy + +.. _ld2410-sensors: + +Configuration variables: +************************ + +- **light** (*Optional*, int): When in :ref:`engineering mode`, indicates the light sensitivity, otherwise ``unknown``. + Value between ``0`` and ``255`` inclusive. Though it seems that the value ``85`` is the lowest value at complete darkness. + All options from :ref:`Sensor `. +- **moving_distance** (*Optional*, int): Distance in cm of detected moving target. + All options from :ref:`Sensor `. +- **still_distance** (*Optional*, int): Distance in cm of detected still target. + All options from :ref:`Sensor `. +- **moving_energy** (*Optional*, int): Energy for moving target. + Value between ``0`` and ``100`` inclusive. + All options from :ref:`Sensor `. +- **still_energy** (*Optional*, int): Energy for still target. + Value between ``0`` and ``100`` inclusive. + All options from :ref:`Sensor `. +- **detection_distance** (*Optional*, int): Distance in cm of target. + All options from :ref:`Sensor `. +- **gX** (*Optional*): Energies for the Xth gate (X => 0 to 8). + - **move_energy** (*Optional*, int): When in :ref:`engineering mode`, the move energy of the gate, otherwise ``unknown``. + Value between ``0`` and ``100`` inclusive. + All options from :ref:`Sensor `. + - **still_energy** (*Optional*, int): When in :ref:`engineering mode`, the still energy of the gate, otherwise ``unknown``. + Value between ``0`` and ``100`` inclusive. + All options from :ref:`Sensor `. +- **ld2410_id** (*Optional*, :ref:`config-id`): Manually specify the ID for the :doc:`ld2410` component if you are using multiple components. + +Switch +------ + +The ``ld2410`` switch allows you to control your :doc:`ld2410`. + +.. code-block:: yaml + + switch: + - platform: ld2410 + engineering_mode: + name: "engineering mode" + bluetooth: + name: "control bluetooth" + +.. _ld2410-engineering-mode: + +Configuration variables: +************************ + +- **engineering_mode** (*Optional*): enable/disable engineering mode. Defaults to ``false``. + Notice this requires more resources and is not recommended to be enabled when not necessary. + All options from :ref:`Switch `. +- **bluetooth** (*Optional*): Turn on/off the bluetooth adapter. Defaults to ``true``. + All options from :ref:`Switch `. +- **ld2410_id** (*Optional*, :ref:`config-id`): Manually specify the ID for the :doc:`ld2410` component if you are using multiple components. + + +.. _ld2410-number: + +Number +------ + +The ``ld2410`` number allows you to control the configuration of your :doc:`ld2410`. + +.. code-block:: yaml + + number: + - platform: ld2410 + timeout: + name: timeout + light_threshold: + name: light threshold + max_move_distance_gate: + name: max move distance gate + max_still_distance_gate: + name: max still distance gate + g0: + move_threshold: + name: g0 move threshold + still_threshold: + name: g0 still threshold + g1: + move_threshold: + name: g1 move threshold + still_threshold: + name: g1 still threshold + g2: + move_threshold: + name: g2 move threshold + still_threshold: + name: g2 still threshold + g3: + move_threshold: + name: g3 move threshold + still_threshold: + name: g3 still threshold + g4: + move_threshold: + name: g4 move threshold + still_threshold: + name: g4 still threshold + g5: + move_threshold: + name: g5 move threshold + still_threshold: + name: g5 still threshold + g6: + move_threshold: + name: g6 move threshold + still_threshold: + name: g6 still threshold + g7: + move_threshold: + name: g7 move threshold + still_threshold: + name: g7 still threshold + g8: + move_threshold: + name: g8 move threshold + still_threshold: + name: g8 still threshold + +.. _ld2410-light-threshold: + +Configuration variables: +************************ - **timeout** (*Optional*, int): Time in seconds during which presence state will stay present - after leaving. Defaults to ``5s``. -- **max_move_distance** (*Optional*, int): Maximum distance for movement detection. - Value between ``0.75m`` and ``6m`` inclusive. Defaults to ``4.5m``. -- **max_still_distance** (*Optional*, int): Maximum distance for still detection. - Value between ``0.75m`` and ``6m`` inclusive. Defaults to ``4.5m``. -- **gX_move_threshold** (*Optional*, int): Threshold for the Xth gate for motion detection (X => 0 to 8). - Above this level for the considered gate (distance), movement detection will be triggered. Defaults to ``see table below``. -- **gX_still_threshold** (*Optional*, int): Threshold for the Xth gate for still detection. (X => 0 to 8). - Above this level for the considered gate (distance), still detection will be triggered. Defaults to ``see table below``. + after leaving. Defaults to ``5s`` + All options from :ref:`Number `. +- **light_threshold** (*Optional*, int): Sets the light threshold for the :ref:`light function`. + Value between ``0`` and ``255`` inclusive. Defaults to ``128``. + All options from :ref:`Number `. +- **max_move_distance_gate** (*Optional*, int): Maximum distance gate for movement detection. + Value between ``2`` and ``8`` inclusive. Defaults to ``8``. + All options from :ref:`Number `. +- **max_still_distance_gate** (*Optional*, int): Maximum distance gate for still detection. + Value between ``2`` and ``8`` inclusive. Defaults to ``8``. + All options from :ref:`Number `. +- **gX** (*Optional*): Thresholds for the Xth gate (X => 0 to 8). + - **move_threshold** (**Required**, int): Threshold for the gate for motion detection. + Above this level for the considered gate (distance), movement detection will be triggered. + Value between ``0`` and ``100`` inclusive. See default values below. + All options from :ref:`Number `. + - **still_threshold** (**Required**, int): Threshold for the gate for still detection. + Above this level for the considered gate (distance), still detection will be triggered. + Value between ``0`` and ``100`` inclusive. See default values below. + All options from :ref:`Number `. +- **ld2410_id** (*Optional*, :ref:`config-id`): Manually specify the ID for the :doc:`ld2410` component if you are using multiple components. .. list-table:: Default values for gate threshold :widths: 25 25 25 @@ -95,86 +301,418 @@ and binary sensors. - 40 - 40 * - 3 - - 40 + - 30 - 40 * - 4 - - 40 - - 40 + - 20 + - 30 * - 5 - - 40 - - 40 + - 15 + - 30 * - 6 - - 30 - 15 + - 20 * - 7 - - 30 - 15 + - 20 * - 8 - - 30 - 15 + - 20 -Sensor +Button ------ -The ``ld2410`` sensor allows you to use your :doc:`ld2410` to perform different -measurements. +The ``ld2410`` button allows you to perfrom actions on your :doc:`ld2410`. .. code-block:: yaml - sensor: + button: - platform: ld2410 - moving_distance: - name : Moving Distance - still_distance: - name: Still Distance - moving_energy: - name: Move Energy - still_energy: - name: Still Energy - detection_distance: - name: Detection Distance + factory_reset: + name: "factory reset" + restart: + name: "restart" + query_params: + name: query params Configuration variables: ************************ -- **moving_distance** (*Optional*): Distance of detected moving target. - All options from :ref:`Sensor `. -- **still_distance** (*Optional*): Distance of detected still target. - All options from :ref:`Sensor `. -- **moving_energy** (*Optional*): Energy for moving target. - All options from :ref:`Sensor `. -- **still_energy** (*Optional*): Energy for still target. - All options from :ref:`Sensor `. -- **detection_distance** (*Optional*): Distance in cm of target. - All options from :ref:`Sensor `. +- **factory_reset** (*Optional*): This command is used to restore all configuration values to their original values. + All options from :ref:`Button `. +- **restart** (*Optional*): Restart the device. + All options from :ref:`Button `. +- **query_params** (*Optional*): Refresh all sensors values of the device. + All options from :ref:`Button `. +- **ld2410_id** (*Optional*, :ref:`config-id`): Manually specify the ID for the :doc:`ld2410` component if you are using multiple components. -Binary Sensor -------------- +Text Sensor +----------- -The ``ld2410`` binary sensor allows you to use your :doc:`ld2410` to perform different -measurements. +The ``ld2410`` text sensor allows you get information about your :doc:`ld2410`. + +.. code-block:: yaml + + text_sensor: + - platform: ld2410 + version: + name: "firmware version" + mac_address: + name: "mac address" + +Configuration variables: +************************ + +- **version** (*Optional*): The firmware version. + All options from :ref:`Text Sensor `. +- **mac_address** (*Optional*): The bluetooth mac address. Will be set to ``unknown`` when bluetooth is off. + All options from :ref:`Text Sensor `. +- **ld2410_id** (*Optional*, :ref:`config-id`): Manually specify the ID for the :doc:`ld2410` component if you are using multiple components. + +Select +----------- + +The ``ld2410`` select allows you control your :doc:`ld2410`. + +.. code-block:: yaml + + select: + - platform: ld2410 + distance_resolution: + name: "distance resolution" + baud_rate: + name: "baud rate" + light_function: + name: light function + out_pin_level: + name: out pin level + +.. _ld2410-light-function: + +Configuration variables: +************************ + +- **distance_resolution** (*Optional*): Control the gates distance resolution. Can be ``0.75m`` or ``0.2m``. Defaults to ``0.75m``. + All options from :ref:`Select `. +- **baud_rate** (*Optional*): Control the serial port baud rate. Defaults to ``256000``. + Once changed, all sensors will stop working until a fresh install with an updated :ref:`UART Component ` configuration. + All options from :ref:`Select `. +- **light_function** (*Optional*): If set, will affect the OUT pin value, based on :ref:`light threshold`. Can be ``off``, ``low`` or ``above``. Defaults to ``off``. + All options from :ref:`Select `. +- **out_pin_level** (*Optional*): Control OUT pin ``away`` value. Can be ``low`` or ``high``. Defaults to ``low``. + All options from :ref:`Select `. +- **ld2410_id** (*Optional*, :ref:`config-id`): Manually specify the ID for the :doc:`ld2410` component if you are using multiple components. + +Automations +----------- + +``bluetooth_password.set`` Action +********************************* + +This is an :ref:`Action ` for setting the bluetooth password. + +.. code-block:: yaml + + - bluetooth_password.set: + id: my_ld2410 + password: "HiLink" + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The ID of the :doc:`ld2410` component to set. +- **password** (**Required**, string, :ref:`templatable `): + The password to set. Case sensitive. Must be exactly 6 characters long. Default password is `HiLink`. + +To change the password from HA you can use the following example config: + +.. code-block:: yaml + + ld2410: + id: my_ld2410 + + api: + services: + - service: set_ld2410_bluetooth_password + variables: + password: string + then: + - bluetooth_password.set: + id: my_ld2410 + password: !lambda 'return password;' + +OUT pin +------- + +In order to monitor the presence indicated by the component, with the :ref:`light function` taken +under account, you can set up a :ref:`GPIO Binary Sensor `: .. code-block:: yaml binary_sensor: - - platform: ld2410 - has_target: - name: Presence - has_moving_target: - name: Moving Target - has_still_target: - name: Still Target + - platform: gpio + pin: REPLACEME + name: gpio out pin presence + device_class: presence -Configuration variables: -************************ -- **has_target** (*Optional*): If true target detect either still or in movement. - All options from :ref:`Binary Sensor `. -- **has_moving_target** (*Optional*): If true a moving target is detected. - All options from :ref:`Binary Sensor `. -- **has_still_target** (*Optional*): If true a still target is detected. - All options from :ref:`Binary Sensor `. +Calibration Process +------------------- +In order to calibrate your ``ld2410`` sensor perform the following: + +1. Enable :ref:`engineering mode`. +2. Monitor the ``gX_move_energy`` and ``gX_still_energy`` :ref:`sensors`. +3. Change the :ref:`thresholds` and repeat step 2 until satisfaction. +4. Disable :ref:`engineering mode`. + +Home Assistant Card +******************* + +For easy calibration process you can use the following custom manual card. + +.. code-block:: yaml + + type: vertical-stack + title: 'DEVICE' + cards: + - type: horizontal-stack + cards: + - type: entities + entities: + - entity: 'switch.DEVICE_engineering_mode' + name: engineering mode + - type: vertical-stack + cards: + - type: entities + entities: + - entity: 'number.DEVICE_timeout' + name: timeout + - entity: 'number.DEVICE_max_move_distance_gate' + name: max move distance gate + - entity: 'number.DEVICE_max_still_distance_gate' + name: max still distance gate + - entity: 'select.DEVICE_light_function' + name: light function + - entity: 'number.DEVICE_light_threshold' + name: light threshold + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_distance_detection_cm' + name: distance + - type: entity + entity: 'sensor.DEVICE_moving_distance_cm' + name: move + - type: entity + entity: 'sensor.DEVICE_still_distance_cm' + name: still + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_move_energy' + name: move energy + - type: entity + entity: 'sensor.DEVICE_still_energy' + name: still energy + - type: horizontal-stack + cards: + - type: entity + entity: 'binary_sensor.DEVICE_gpio_out_pin_presence' + name: gpio presence + state_color: true + - type: entity + entity: 'binary_sensor.DEVICE_presence' + name: presence + state_color: true + - type: entity + entity: 'binary_sensor.DEVICE_movement' + name: movement + state_color: true + - type: entity + entity: 'binary_sensor.DEVICE_still' + name: still + state_color: true + - type: conditional + conditions: + - entity: 'switch.DEVICE_engineering_mode' + state: 'on' + card: + type: vertical-stack + cards: + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_light' + name: light + - type: entity + entity: 'binary_sensor.DEVICE_out_pin_presence_status' + name: out pin presence + state_color: true + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_g0_move_energy' + name: 'g0' + - type: entity + entity: 'number.DEVICE_g0_move_threshold' + name: ' ' + - type: entity + entity: 'sensor.DEVICE_g0_still_energy' + name: ' ' + - type: entity + entity: 'number.DEVICE_g0_still_threshold' + name: ' ' + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_g1_move_energy' + name: 'g1' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g1_move_threshold' + name: ' ' + icon: ' ' + - type: entity + entity: 'sensor.DEVICE_g1_still_energy' + name: ' ' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g1_still_threshold' + name: ' ' + icon: ' ' + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_g2_move_energy' + name: 'g2' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g2_move_threshold' + name: ' ' + icon: ' ' + - type: entity + entity: 'sensor.DEVICE_g2_still_energy' + name: ' ' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g2_still_threshold' + name: ' ' + icon: ' ' + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_g3_move_energy' + name: 'g3' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g3_move_threshold' + name: ' ' + icon: ' ' + - type: entity + entity: 'sensor.DEVICE_g3_still_energy' + name: ' ' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g3_still_threshold' + name: ' ' + icon: ' ' + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_g4_move_energy' + name: 'g4' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g4_move_threshold' + name: ' ' + icon: ' ' + - type: entity + entity: 'sensor.DEVICE_g4_still_energy' + name: ' ' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g4_still_threshold' + name: ' ' + icon: ' ' + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_g5_move_energy' + name: 'g5' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g5_move_threshold' + name: ' ' + icon: ' ' + - type: entity + entity: 'sensor.DEVICE_g5_still_energy' + name: ' ' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g5_still_threshold' + name: ' ' + icon: ' ' + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_g6_move_energy' + name: 'g6' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g6_move_threshold' + name: ' ' + icon: ' ' + - type: entity + entity: 'sensor.DEVICE_g6_still_energy' + name: ' ' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g6_still_threshold' + name: ' ' + icon: ' ' + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_g7_move_energy' + name: 'g7' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g7_move_threshold' + name: ' ' + icon: ' ' + - type: entity + entity: 'sensor.DEVICE_g7_still_energy' + name: ' ' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g7_still_threshold' + name: ' ' + icon: ' ' + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_g8_move_energy' + name: 'g8' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g8_move_threshold' + name: ' ' + icon: ' ' + - type: entity + entity: 'sensor.DEVICE_g8_still_energy' + name: ' ' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g8_still_threshold' + name: ' ' + icon: ' ' + +Then replace all instances of ``DEVICE`` with your device name + +The result: + +.. figure:: images/ld2410-card.png + :align: center See Also --------