esphome-docs/components/sensor/ltr390.rst
Stephen Tierney 8b8d9aa237
Add docs for LTR390 (#979)
* Add docs

* Fix code block indentation

* Add emtpy lines for math directive

* Fix table indentation

* Fix table indentation

* Fix math indentation

* Add adafruit link

* Changed docs order to place important feature first

* Update components/sensor/ltr390.rst

Co-authored-by: Otto Winter <otto@otto-winter.com>

* Update components/sensor/ltr390.rst

Co-authored-by: Otto Winter <otto@otto-winter.com>

* Update components/sensor/ltr390.rst

Co-authored-by: Otto Winter <otto@otto-winter.com>

Co-authored-by: Otto Winter <otto@otto-winter.com>
2021-09-22 13:24:25 +02:00

118 lines
3.4 KiB
ReStructuredText

LTR390 UV and Ambient Light Sensor
==================================================
.. seo::
:description: Instructions for setting up LTR390 UV and light sensor
:image: images/ltr390-full.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
uvi:
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`