veml7700 - Driver for ambient light sensor VEML7700

The VEML7700 is a high-accuracy ambient light sensor. All measurements and filtering is done on the chip which makes it easy to integrate. The sensitivity can be adjusted by a gain setting and by changing the integration time. The output of the sensor is a count value which must be converted using the resolution value in the driver.

The sensor has power saving features which reduces the repetition of measurements. It has also a power off feature to save even more power.

The ambient light sensor value is filterd very clone to the caracteristic of the human eye. Besides, als the white channel with a wider wavelength spectrum. In most applications, the ambient light value will do just fine.

Power consumption

  • 0.5 μA in shut-down mode (@3.3V)

  • down to 2 μA in power save mode 4 (@3.3V)

  • 45 μA on 100ms integration time (@3.3V)

Communication interface

I2C is used as communication interface without any further interrupt pins. It has six command codes for the settings and the output values. Read the datasheet or application note for further information.

To reduce interactions with the integrated microcontroller, the interrupt feature can be used. Therefore, one must configure the low and high threshold and enable the interrupt.

Interrupt application examples

If values below a certain threshold is of interest, i.e. to activate lights when its getting dark outside, the low threshold should be adjusted and setting the high threshold to maximum (65535).

Another application could be an automated rollershutter, then both thresholds sould be set to trigger the up and down movement of rollershutters.

Measurement process

The measurement takes time and the sensor should not be read out faster than the measurement time. Therefore the application should be adjusted to the sensor configuration regarting integration time and power save modes. Alternatively, the interrupt feature can be used by repeatetive reading of the interrupt status.

Usage

This driver uses i2cdev which must be initialized first. Then initialize the device decriptor, one discriptor per device. The sensor can be used without configuration, but has a high chance of over-saturation on sunlight. Therefore, change gain and integration time to your needs and configure the device.

Then, the veml7700_ambient_light and veml7700_white_channel functions can be used to read out the brightness. The driver converts the counts from the device to lx using the configuration.

Hardware configurations

The driver supports multiple VEML7700 sensors at the same time that are connected to I2C. Following figure show some possible hardware configurations.

First figure shows the configuration with one sensor at I2C bus 0.

+------------------+   +----------+
| ESP8266 / ESP32  |   | VEML7700 |
|                  |   |          |
|   GPIO 14 (SCL)  ----> SCL      |
|   GPIO 13 (SDA)  <---> SDA      |
+------------------+   +----------+

Next figure shows a possible configuration with two I2C buses.

+------------------+   +----------+
| ESP8266 / ESP32  |   | VEML7700 |
|                  |   |          |
|   GPIO 14 (SCL)  ----> SCL      |
|   GPIO 13 (SDA)  <---> SDA      |
|                  |   +----------+
|                  |   | VEML7700 |
|                  |   |          |
|   GPIO 5  (SCL)  ----> SCL      |
|   GPIO 4  (SDA)  <---> SDA      |
+------------------+   +----------+

Only one sensor per I2C bus is possible, since it uses a unconfigurable I2C slave address. However, one could also use GPIO controller bus buffer to connect the bus to different devices.

References

Datasheet

Application Note

group veml7700

ESP-IDF driver for VEML7700 brightness sensors for I2C-bus.

Copyright (c) 2022 Marc Luehr marcluehr@gmail.com

ISC Licensed as described in the file LICENSE

Defines

VEML7700_I2C_ADDR
VEML7700_INTEGRATION_TIME_25MS
VEML7700_INTEGRATION_TIME_50MS
VEML7700_INTEGRATION_TIME_100MS
VEML7700_INTEGRATION_TIME_200MS
VEML7700_INTEGRATION_TIME_400MS
VEML7700_INTEGRATION_TIME_800MS
VEML7700_GAIN_1
VEML7700_GAIN_2
VEML7700_GAIN_DIV_8
VEML7700_GAIN_DIV_4
VEML7700_POWER_SAVING_MODE_500MS
VEML7700_POWER_SAVING_MODE_1000MS
VEML7700_POWER_SAVING_MODE_2000MS
VEML7700_POWER_SAVING_MODE_4000MS
VEML7700_PERSISTENCE_PROTECTION_1
VEML7700_PERSISTENCE_PROTECTION_2
VEML7700_PERSISTENCE_PROTECTION_4
VEML7700_PERSISTENCE_PROTECTION_8

Functions

esp_err_t veml7700_init_desc(i2c_dev_t *dev, i2c_port_t port, gpio_num_t sda_gpio, gpio_num_t scl_gpio)

Initialize device descriptor.

Default SCL frequency is 100kHz. The I2C address is fix.

Parameters:

  • dev – Pointer to I2C device descriptor

  • port – I2C port number

  • sda_gpio – SDA GPIO

  • scl_gpio – SCL GPIO

Returns:

ESP_OK on success

esp_err_t veml7700_free_desc(i2c_dev_t *dev)

Free device descriptor.

Parameters:

dev – Pointer to I2C device descriptor

Returns:

ESP_OK on success

esp_err_t veml7700_probe(i2c_dev_t *dev)

Probe if the device exist on the bus.

Parameters:

dev – Pointer to I2C device descriptor

Returns:

ESP_OK on success

esp_err_t veml7700_set_config(i2c_dev_t *dev, veml7700_config_t *config)

Write the config to the device.

Parameters:

  • dev – Pointer to I2C device descriptor

  • config – Pointer to the config descriptor

Returns:

ESP_OK on success

esp_err_t veml7700_get_config(i2c_dev_t *dev, veml7700_config_t *config)

Read the config to the device.

Parameters:

  • dev – Pointer to I2C device descriptor

  • config – Pointer to the config descriptor

Returns:

ESP_OK on success

esp_err_t veml7700_get_ambient_light(i2c_dev_t *dev, veml7700_config_t *config, uint32_t *value_lux)

Read ambient light sensor value from the device.

Parameters:

  • dev – Pointer to I2C device descriptor

  • config – Pointer to the config descriptor

  • value_lux – Pointer as return value in lux

Returns:

ESP_OK on success

esp_err_t veml7700_get_white_channel(i2c_dev_t *dev, veml7700_config_t *config, uint32_t *value_lux)

Read white channel value from the device.

Parameters:

  • dev – Pointer to I2C device descriptor

  • config – Pointer to the config descriptor

  • value_lux – Pointer as return value in lux

Returns:

ESP_OK on success

esp_err_t veml7700_get_interrupt_status(i2c_dev_t *dev, bool *low_threshold, bool *high_threshold)

Read the interrupt status from the device.

Parameters:

  • dev – Pointer to I2C device descriptor

  • low_threshold – Pointer to return the low threshold passed indicator

  • high_threshold – Pointer to return the high threshold passed indicator

Returns:

ESP_OK on success

struct veml7700_config_t
#include <veml7700.h>

VEML configuration descriptor.

Public Members

uint16_t gain

control the sensitivity

uint16_t integration_time

time to measure

uint16_t persistence_protect

sample count before the interrupt triggers

uint16_t interrupt_enable

enable threshold interrupt

uint16_t shutdown

set to 1 to shutdown the device, set to 0 to wakeup

uint16_t threshold_high

high threshold for the interrupt

uint16_t threshold_low

low threshold for the interrupt

uint16_t power_saving_mode

power saving mode

uint16_t power_saving_enable

enable the pover saving mode