155 lines
4.8 KiB
ReStructuredText
155 lines
4.8 KiB
ReStructuredText
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`
|