diff --git a/components/sensor/images/veml3235.jpg b/components/sensor/images/veml3235.jpg new file mode 100644 index 000000000..19dd6efa7 Binary files /dev/null and b/components/sensor/images/veml3235.jpg differ diff --git a/components/sensor/veml3235.rst b/components/sensor/veml3235.rst new file mode 100644 index 000000000..8d80a5ab6 --- /dev/null +++ b/components/sensor/veml3235.rst @@ -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 `, 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 `__ 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 `. + +See Also +-------- + +- :ref:`sensor-filters` +- `Vishay VEML3235 product page `__ +- `Vishay VEML3235 datasheet `__ +- `Designing the VEML3235 Into an Application `__ +- :doc:`tsl2591` +- :doc:`tsl2561` +- :doc:`bh1750` +- :apiref:`veml3235/veml3235.h` +- :ghedit:`Edit` diff --git a/images/veml3235.jpg b/images/veml3235.jpg new file mode 100644 index 000000000..19dd6efa7 Binary files /dev/null and b/images/veml3235.jpg differ diff --git a/index.rst b/index.rst index f4a44f0de..b9f25a07c 100644 --- a/index.rst +++ b/index.rst @@ -361,6 +361,7 @@ Light TCS34725, components/sensor/tcs34725, tcs34725.jpg, Lux & RGB colour TSL2561, components/sensor/tsl2561, tsl2561.jpg, Lux TSL2591, components/sensor/tsl2591, tsl2591.jpg, Lux + VEML3235, components/sensor/veml3235, veml3235.jpg, Lux Magnetic