178 lines
8.7 KiB
ReStructuredText
178 lines
8.7 KiB
ReStructuredText
VEML7700 and VEML6030 Ambient Light Sensors
|
|
===========================================
|
|
|
|
.. seo::
|
|
:description: Instructions for setting up VEML7700 / VEML6030 ambient light sensors in ESPHome.
|
|
:image: veml7700.jpg
|
|
:keywords: VEML7700, VEML6300
|
|
|
|
The ``veml7700`` sensor platform allows you to use the Vishay VEML7700 and VEML6030 ambient light sensors with ESPHome.
|
|
Communication with the device is over :ref:`I²C <i2c>`, which must be present in your configuration. VEML7700 and VEML6030
|
|
are basically the same but in different packages. The VEML7700 uses a fixed address of ``0x10``, while the smaller VEML6030
|
|
can be configured to use either ``0x10`` or ``0x48``.
|
|
|
|
The VEML 7700/6030 devices are available on breakout boards from a number of vendors including `Adafruit`_, `SparkFun`_,
|
|
`DFRobot`_, and others.
|
|
|
|
.. _Adafruit: http://www.adafruit.com/products/4162
|
|
.. _SparkFun: https://www.sparkfun.com/products/15436
|
|
.. _DFRobot: https://www.dfrobot.com/product-1620.html
|
|
|
|
|
|
.. figure:: images/veml7700-full.jpg
|
|
:align: center
|
|
:width: 70.0%
|
|
|
|
VEML7700 Ambient Light Sensor on a board and standalone sensors.
|
|
|
|
.. figure:: images/veml7700-ui.png
|
|
:align: center
|
|
:width: 60.0%
|
|
|
|
VEML sensor in Home Assistant UI.
|
|
|
|
The sensor is a high accuracy ambient light digital 16-bit resolution sensor with dynamic range from 0 lux to about 120,000 lux.
|
|
Its wide range of measurements is enabled by four configurable *gain* levels and six different *integration time* options.
|
|
Higher gain values are typically used for lower light conditions.
|
|
|
|
The sensor has two photodiodes with different spectral response represented by two channels: an *ALS* channel and a *WHITE* channel.
|
|
The *ALS*, or *Ambient light* channel follows a so-called human eye curve very closely. The *WHITE* channel covers a much wider wavelength/spectrum, capturing quite a lot of near-infrared radiance.
|
|
|
|
.. figure:: images/veml7700-spectral.png
|
|
:align: center
|
|
:width: 100.0%
|
|
|
|
ALS and WHITE channels spectral response
|
|
|
|
|
|
Using this component's automatic measurement mode is advised; in this mode, proper *gain* and *integration time* are automatically selected by the component after
|
|
taking several measurements. To do so, it follows a process recommended by the manufacturer.
|
|
|
|
Should you desire to manually control those parameters - please note that:
|
|
|
|
- Gain levels of 1/8 and 1/4 shall be used in most cases.
|
|
- Gain levels of 1 an 2 are only intended to be used in low light conditions < 100 lux. For very high illuminations it shows high non-linearity.
|
|
- In the range of 0 lux - 1000 lux the sensor measurements are stricly linear for Gain 1/4 and 1/8, after 1000 lux it shows non-linearity.
|
|
|
|
|
|
A lux compensation formula is used to get better readings in bright conditions.
|
|
However, it gives quite high error in very bright direct sunlight (instead of 100-120 kilolux it might give 150-200k+).
|
|
|
|
This Wikipedia `article <https://en.wikipedia.org/wiki/Lux>`__ has a table of some lux values for comparison.
|
|
|
|
Automatic measurement mode
|
|
--------------------------
|
|
|
|
In automatic measurement mode the component starts from Gain 1/8 and 100 ms (*default*).
|
|
|
|
- If illuminance is higher than 46 lx (100 counts) it gradually reduces integration time to get good reading (best in range 100 - 10,000 counts).
|
|
- In case of low illuminance (less than 46 lx) it tries to gradually increase gain and only then increase integration time.
|
|
|
|
Please note, that in low light conditions measurement process might take several seconds due to long exposure periods and sensor reconfigurations.
|
|
|
|
Starting values can be overriden by setting ``gain`` and ``integration_time`` parameters. The gain value gets adjusted first if possible.
|
|
|
|
Lux compensation
|
|
----------------
|
|
|
|
Lux compensation is done as recommended by the manufacturer, however it can be turned off by
|
|
setting ``lux_compensation: false`` in your device's configuration.
|
|
|
|
.. math::
|
|
|
|
\displaystyle \begin{array}{l}
|
|
lux & = & counts \times resolution(time, gain)\\
|
|
lux_{comp} & =& 6.0135e \times 10^{-13} \times lux^4 - 9.3924e \times 10^{-9} \times lux^3\\
|
|
& & + 8.1488e \times 10^{-5} \times lux^2 + 1.0023 \times lux\\
|
|
\\
|
|
\text{Where:} & & \\
|
|
counts & - & \text{sensor readings, counts}\\
|
|
resolution & - & \text{sensor resolution for given integration time and gain, lx/counts}\\
|
|
lux & - & \text{calculated illumination, lx}\\
|
|
lux_{comp} & - & \text{compensated illumniation, lx}\\
|
|
\end{array}
|
|
|
|
Available data
|
|
--------------
|
|
|
|
The implementation offers seven sensors:
|
|
- Two providing *lux* value,
|
|
- Two unitless data measurements directly from the device,
|
|
- Two actual *gain* and *integration time* values used for the measurement (useful in automatic mode), and
|
|
- One fully artificial, somewhat representing near-infrared part of spectrum.
|
|
|
|
- **ambient_light**: Illuminance value for *ALS* channel representing human eye, lx
|
|
- **full_spectrum**: Illuminance value for *WHITE* channel with wide spectrum, lx
|
|
- **infrared**: Calculated illuminance value (*WHITE* minus *ALS*) representing near-infrared spectre, lx
|
|
- **ambient_light_counts**: Raw 16 bit reading from *ALS* channel, counts
|
|
- **full_spectrum_counts**: Raw 16 bit reading from *WHITE* channel, counts
|
|
- **actual_gain**: The actual gain value being used for values reported, multiplier
|
|
- **actual_integration_time**: The actual integration time being used for values reported, ms
|
|
|
|
Example configuration
|
|
---------------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
sensor:
|
|
- platform: veml7700
|
|
address: 0x10
|
|
update_interval: 60s
|
|
|
|
# short variant of sensor definition:
|
|
ambient_light: "Ambient light"
|
|
# longer variant of sensor definition:
|
|
actual_gain:
|
|
name: "Actual gain"
|
|
|
|
|
|
Configuration variables:
|
|
------------------------
|
|
|
|
- **auto_mode** (*Optional*, boolean): Automatic gain and integration time selection. Defaults to ``True``.
|
|
- **integration_time** (*Optional*, :ref:`config-time`):
|
|
The amount of time the sensor is exposed. Valid values are ``25ms``, ``50ms``, ``100ms`` *(default)*,
|
|
``200ms``, ``400ms``, ``800ms``. *In automatic mode it sets starting value*.
|
|
- **gain** (*Optional*, string): The gain the device will use for the internal ADC. Valid values are
|
|
``1/8x`` *(default)*, ``1/4x``, ``1x``, ``2x``. Higher values are better in low-light conditions.
|
|
*In automatic mode it sets starting gain value*.
|
|
- **lux_compensation** (*Optional*, boolean): Lux compensation formula is used as per manufacturer.
|
|
Defaults to ``True``.
|
|
- **glass_attenuation_factor** (*Optional*): The attenuation factor of glass if it's behind some glass
|
|
or plastic facia. Default is ``1.0`` means ``100%`` transmissivity. ``2`` means ``50%`` transmissivity etc.
|
|
- **update_interval** (*Optional*, :ref:`config-time`): The interval for checking the sensors.
|
|
Defaults to ``60s``.
|
|
- All other options for I²C devices described at :ref:`I²C Bus <i2c>`.
|
|
The sensor supports bus modes "standard" and "fast": 10 kHz to 400 kHz.
|
|
|
|
Sensors
|
|
.......
|
|
|
|
You can configure all or any subset of the sensors described earlier.
|
|
Each configured sensor is reported separately on each ``update_interval``. **name** (**Required**, string) is required for
|
|
every sensor. All other options from :ref:`Sensor <config-sensor>`.
|
|
|
|
However, if you don't need any other options, you can just use shorthands like this: ``ambient_light: Ambient light``.
|
|
|
|
- **ambient_light** (*Optional*): Illuminance for visible light (*ALS channel*), lx.
|
|
- **full_spectrum** (*Optional*): Illuminance for the full spectrum sensor (*WHITE channel*), lx.
|
|
- **infrared** (*Optional*): Calculated illuminance for the Near-IR spectrum (*WHITE* minus *ALS*), lx.
|
|
- **ambient_light_counts** (*Optional*): The reading for visible light (*ALS channel*), counts.
|
|
- **full_spectrum_counts** (*Optional*): The reading for the full spectrum sensor (*WHITE channel*), counts.
|
|
- **actual_gain** (*Optional*): The value of gain used for reported values. Particularly useful when "auto_mode" is selected.
|
|
- **actual_integration_time** (*Optional*): Integration time used for reported values, ms. Particularly useful when "auto_mode" is selected.
|
|
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :ref:`sensor-filters`
|
|
- `VEML 7700 datasheet <https://github.com/latonita/datasheets-storage/blob/main/sensors/VEML7700.pdf>`__
|
|
- Application note `Designing the VEML7700 Into an Application <https://github.com/latonita/datasheets-storage/blob/main/sensors/VEML7700-designing.pdf>`__
|
|
- `VEML 6030 datasheet <https://github.com/latonita/datasheets-storage/blob/main/sensors/VEML6030.pdf>`__
|
|
- Application note `Designing the VEML6030 Into an Application <https://github.com/latonita/datasheets-storage/blob/main/sensors/VEML6030-designing.pdf>`__
|
|
- `Radiometric vs. Photometric Units <https://www.thorlabs.de/catalogPages/506.pdf>`__
|
|
- :apiref:`veml7700/veml7700.h`
|
|
- :ghedit:`Edit`
|