mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-11-14 10:35:27 +01:00
97 lines
4.6 KiB
ReStructuredText
97 lines
4.6 KiB
ReStructuredText
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`
|