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_index:
          name: "UV Index"
        uv:
          name: "UV Sensor Counts"
        light:
          name: "Light"
        ambient_light:
          name: "Light Sensor Counts"

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. Default is ``"X18"``, see table below for options.
- **resolution** (*Optional*, int): ADC resolution. Higher resolutions require longer sensor integration times. Default is ``20``, see table below for options.
- **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.

Granular control over gain and resolution
.........................................
By default, the ``gain`` and ``resolution`` parameters set same values for both ALS and UV measurements. In real life scenarios there might be significant
differences in the light intensity and UV index, so it is recommended to use different gain and resolution values for ALS and for UV sensor to avoid saturation.
See the example below, where the gain and resolution are set to different values for ALS and UV sensors.:

.. code-block:: yaml

    sensor:
      - platform: ltr390
        uv:
          name: "UV Sensor Counts"
        ambient_light:
          name: "Light Sensor Counts"
        gain:
          ambient_light: X9
          uv: X3
        resolution:
          ambient_light: 18
          uv: 13


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

.. math::

    \text{lux} = \frac{0.6 \times \text{als}}{\text{gain} \times \frac{\text{int}}{100} } \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 sensor gain, see the table below for details.
- ``int`` is the integration time in ms and is tied to the resolution, see the table below for details.
- ``sensitivity`` is the sensor's count per UVI. See note below for details.
- ``wfac`` is the window correction factor.

It is recommended to use the defaults of ``X18`` gain and resolution of 20 bits when UV Index sensing is required since
the data sheet only provides accurate conversion formula for this combination. The UVI value is linearly scaled from
this reference point when using other combinations of gain and resolution, which may be slightly inaccurate. The scaling
formula is:

.. math::

    \text{sensitivity} = 2300 \times \frac{\text{gain}}{18} \times \frac{\text{int}}{400}

where :math:`2300` is the sensor count per UVI at the default configuration.

Gain
----

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

    * - Configuration value
      - gain
    * - X1
      - 1
    * - X3
      - 3
    * - X6
      - 6
    * - X9
      - 9
    * - X18
      - 18


Resolution
----------

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

    * - Configuration value
      - Resolution (bits)
      - Integration Time (ms)
    * - 16
      - 16
      - 25
    * - 17
      - 17
      - 50
    * - 18
      - 18
      - 100
    * - 19
      - 19
      - 200
    * - 20
      - 20
      - 400

See Also
--------

- :doc:`/components/sensor/bh1750`
- :doc:`/components/sensor/tsl2561`
- `TEMT6000 <https://devices.esphome.io/devices/temt6000>`__
- :ref:`sensor-filters`
- :apiref:`ltr390/ltr390.h`
- :ghedit:`Edit`