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¶
- 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
-
uint16_t gain¶
-
VEML7700_I2C_ADDR¶