VEML7700 and VEML6030 light sensors (#3525)

* VEML7700 and VEML6030 light sensors

* VEML7700 math indent

* VEML7700 tidy

* VEML7700 tidy

* VEML7700 update

* VEML7700 pic fix

* VEML7700 typo

* VEML7700 doc fix

* Apply suggestions from code review

Co-authored-by: Keith Burzinski <kbx81x@gmail.com>

* VEML7700 minor fixes after the review

* simplified sensor config

* Update components/sensor/veml7700.rst

---------

Co-authored-by: Keith Burzinski <kbx81x@gmail.com>

components/sensor/veml7700.rst

@@ -0,0 +1,177 @@
+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`

index.rst

@@ -368,6 +368,8 @@ Light
     TSL2561, components/sensor/tsl2561, tsl2561.jpg, Lux
     TSL2591, components/sensor/tsl2591, tsl2591.jpg, Lux
     VEML3235, components/sensor/veml3235, veml3235.jpg, Lux
+    VEML6030, components/sensor/veml7700, veml6030.jpg, Lux
+    VEML7700, components/sensor/veml7700, veml7700.jpg, Lux
 
 
 Magnetic