Add docs for VEML3235 lux sensor (#3471)
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
This commit is contained in:
Keith Burzinski
GitHub
parent
a27d88dacf
commit
92c48dd837
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
|
|
@ -0,0 +1,96 @@
|
|||
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`
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
Loading…
Reference in New Issue