LTR390 UV and Ambient Light Sensor
==================================================

.. seo::
    :description: Instructions for setting up LTR390 UV and light sensor
    :image: ltr390.jpg

The ``ltr390`` sensor platform  allows you to use your LTR390 UV and ambient
light sensor
(`datasheet <https://optoelectronics.liteon.com/upload/download/DS86-2015-0004/LTR-390UV_Final_%20DS_V1%201.pdf>`__, `Adafruit`_) with ESPHome.

The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this sensor to work.

.. figure:: images/ltr390-full.jpg
    :align: center
    :width: 80.0%

.. _Adafruit: https://www.adafruit.com/product/4831

.. code-block:: yaml

    sensor:
      - platform: ltr390
        uv:
          name: "UV Index"
        light:
          name: "Light"

Configuration variables:
------------------------

- **uv_index** (*Optional*): UV index (UVI). All options from :ref:`Sensor <config-sensor>`.
- **uv** (*Optional*): Sensor counts for the UV sensor (#). All options from :ref:`Sensor <config-sensor>`.
- **light** (*Optional*): Lux of ambient light (lx). All options from :ref:`Sensor <config-sensor>`.
- **ambient_light** (*Optional*): Sensor counts for the Ambient light sensor (#). All options from :ref:`Sensor <config-sensor>`.
- **gain** (*Optional*, string): Adjusts the sensitivity of the sensor. A larger value means higher sensitivity. See table below for details. Default is ``"X3"``.
- **resolution** (*Optional*, int): ADC resolution. Higher resolutions require longer sensor integration times. See table below for details. Default is ``18``.
- **window_correction_factor** (*Optional*, float): Window correction factor. Use larger values when using under tinted windows. Default is ``1.0``, must be ``>= 1.0``.
- **address** (*Optional*, int): Manually specify the I²C address of the sensor. Default is `0x53`.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
  sensor. Defaults to ``60s``. It is recommended that the update interval is at least 1 second since updates can take up to 800ms when using a high resolution value.

Lux and UVI Formulas
--------------------

.. math::

    \text{lux} = \frac{0.6 \times \text{als}}{\text{gain} \times \text{int}} \times \text{wfac}

.. math::

    \text{UVI} = \frac{\text{uv}}{\text{sensitivity}} \times \text{wfac}

where:

- ``als`` and ``uv`` are the sensor values
- ``gain`` is the amount of gain, see the table below for details
- ``int`` is the integration time in 100s of ms and is tied to the resolution, see the table below for details
- ``sensitivity`` has the value ``2300`` and is the sensor's count per UVI
- ``wfac`` is the window correction factor

Gain
----

.. list-table::
    :widths: 25 25
    :header-rows: 1

    * - Gain Parameter
      - gain
    * - X1
      - 1
    * - X3
      - 3
    * - X6
      - 6
    * - X9
      - 9
    * - X18
      - 18


Resolution
----------

.. list-table:: Resolution
    :widths: 25 25 10
    :header-rows: 1

    * - Resolution Parameter (bits)
      - Integration Time (ms)
      - int
    * - 16
      - 25
      - 0.25
    * - 17
      - 50
      - 0.5
    * - 18
      - 100
      - 1
    * - 19
      - 200
      - 2
    * - 20
      - 400
      - 4

See Also
--------

- :doc:`/components/sensor/bh1750`
- :doc:`/components/sensor/tsl2561`
- :doc:`/cookbook/temt6000`
- :ref:`sensor-filters`
- :apiref:`ltr390/ltr390.h`
- :ghedit:`Edit`