VEML3235 Ambient Light Sensor
=============================

.. seo::
    :description: Instructions for setting up VEML3235 ambient light sensors in ESPHome.
    :image: veml3235.jpg
    :keywords: VEML3235

The ``veml3235`` sensor platform allows you to use the Vishay VEML3235 ambient light sensor with ESPHome.
Communication with the device is over :ref:`I²C <i2c>`, which must be present in your configuration.

.. figure:: images/veml3235.jpg
    :align: center
    :width: 50.0%

    The VEML3235 Ambient Light Sensor

This sensor provides a 16-bit dynamic range for ambient light detection ranging from 0 lx to nearly 18 klx, with a
resolution as small as 0.0021 lx/counts. It achieves that range by having two configurable ``gain`` values and a range
of integration times. For many applications, you can enable auto gain to have ESPHome select a suitable gain setting
based on the previous measurement. If light levels change dramatically, the next reading may saturate, after which the
gain will be adjusted to bring subsequent readings back in range. In general, use higher gain values and/or longer
integration times when measuring less intense light sources.

This Wikipedia `article <https://en.wikipedia.org/wiki/Lux>`__ has a table of some lux values for comparison.

Values reported are in units of ``lux``, but understand that measurement of any lux value requires careful calibration
for the light frequency or frequencies under measurement, conversion coefficients for the specific device, and other
factors. In short, to really get a true lux value measurement, you should do a laboratory-grade calibration specific
to your use case. If you are the sort of person who can do a laboratory-grade calibration, you probably knew all of
that already. Still, you can still get values that will be "in the ballpark" without calibration. This is especially
true if you just want to distinguish among "no light", "a little bit of light", "a lot of light", etc.

.. code-block:: yaml

    # Example configuration entry
    sensor:
      - platform: veml3235
        id: veml3235_sensor
        name: VEML3235 Light Sensor
        auto_gain: true
        auto_gain_threshold_high: 90%
        auto_gain_threshold_low: 20%
        digital_gain: 1X
        gain: 1X
        integration_time: 50ms

Configuration variables:
------------------------
- **gain** (*Optional*, string): The gain the device will use. Higher values are better in low-light conditions.
  You cannot specify an arbitrary gain multiplier. It must be one of:

  - ``1x``  *(default)*
  - ``2x``
  - ``4x``

- **digital_gain** (*Optional*, string): Similar to ``gain``; provides an additional multipler, further increasing
  range. You cannot specify an arbitrary digital gain multiplier. It must be one of:

  - ``1x``  *(default)*
  - ``2x``

- **integration_time** (*Optional*, :ref:`config-time`): The time the device will use for each measurement. Longer
  means more accurate values. You cannot specify an arbitrary amount of time. It must be the equivalent of one of:

  - ``50ms``   *(default)*
  - ``100ms``
  - ``200ms``
  - ``400ms``
  - ``800ms``

- **auto_gain** (*Optional*, boolean): When set to ``true`` (the default), ``gain``, ``digital_gain`` and
  ``integration_time`` will be adjusted automatically to avoid saturating the sensor and allow use of the maximum
  possible resolution; if these values are included in the configuration, they will be used as initial values only.
- **auto_gain_threshold_high** (*Optional*, percentage): A percentage of the maximum possible lux measurement given the
  current gains and integration time; when the lux measurement climbs above this value, the ``gain``, ``digital_gain``
  and ``integration_time`` values will be reset and recalculated to avoid saturation and maximize resolution. The
  default value is ``90%``.
- **auto_gain_threshold_low** (*Optional*, percentage): A percentage of the maximum possible lux measurement given the
  current gains and integration time; when the lux measurement falls below this value, the ``gain``, ``digital_gain``
  and ``integration_time`` values will be reset and recalculated to avoid saturation and maximize resolution. The
  default value is ``20%``.
- All other options from :ref:`Sensor <config-sensor>`.

See Also
--------

- :ref:`sensor-filters`
- `Vishay VEML3235 product page <https://www.vishay.com/en/product/80131/>`__
- `Vishay VEML3235 datasheet <https://www.vishay.com/docs/80131/veml3235.pdf>`__
- `Designing the VEML3235 Into an Application <https://www.vishay.com/docs/80222/designingveml3235.pdf>`__
- :doc:`tsl2591`
- :doc:`tsl2561`
- :doc:`bh1750`
- :apiref:`veml3235/veml3235.h`
- :ghedit:`Edit`