Ambient Light Sensor

[中文]

The ambient light sensor can be used as a light intensity sensor, a color sensor, a UV sensor or a sensor with multiple functions.

Adapted Products

Name

Function

Bus

Vendor

Datasheet

HAL

BH1750

Light

I2C

rohm

Datasheet

√

VEML6040

Light RGBW

I2C

Vishay

Datasheet

√

VEML6075

Light UVA UVB

I2C

Vishay

Datasheet

√

API Reference

The following APIs have implemented hardware abstraction on the ambient light sensor. Users can call the code from this layer directly to write a sensor application, or use the sensor interface in sensor_hub for easier development.

Header File

Functions

sensor_light_handle_t light_sensor_create(bus_handle_t bus, int id)

Create a light sensor instance. same series’ sensor or sensor with same address can only be created once.

Return

sensor_light_handle_t return light sensor handle if succeed, return NULL if failed.

Parameters

  • bus: i2c bus handle the sensor attached to

  • id: id declared in light_sensor_id_t

esp_err_t light_sensor_delete(sensor_light_handle_t *sensor)

Delete and release the sensor resource.

Return

esp_err_t

  • ESP_OK Success

  • ESP_FAIL Fail

Parameters

  • sensor: point to light sensor handle, will set to NULL if delete succeed.

esp_err_t light_sensor_test(sensor_light_handle_t sensor)

Test if sensor is active.

Return

esp_err_t

  • ESP_OK Success

  • ESP_FAIL Fail

Parameters

  • sensor: light sensor handle to operate.

esp_err_t light_sensor_acquire_light(sensor_light_handle_t sensor, float *lux)

Acquire light sensor illuminance result one time.

Return

esp_err_t

  • ESP_OK Success

  • ESP_FAIL Fail

  • ESP_ERR_NOT_SUPPORTED Function not supported on this sensor

Parameters

  • sensor: light sensor handle to operate.

  • lux: result data (unit:lux)

esp_err_t light_sensor_acquire_rgbw(sensor_light_handle_t sensor, rgbw_t *rgbw)

Acquire light sensor color result one time. light color includes red green blue and white.

Return

esp_err_t

  • ESP_OK Success

  • ESP_FAIL Fail

  • ESP_ERR_NOT_SUPPORTED Function not supported on this sensor

Parameters

  • sensor: light sensor handle to operate.

  • rgbw: result data (unit:lux)

esp_err_t light_sensor_acquire_uv(sensor_light_handle_t sensor, uv_t *uv)

Acquire light sensor ultra violet result one time. light Ultraviolet includes UVA UVB and UV.

Return

esp_err_t

  • ESP_OK Success

  • ESP_FAIL Fail

  • ESP_ERR_NOT_SUPPORTED Function not supported on this sensor

Parameters

  • sensor: light sensor handle to operate.

  • uv: result data (unit:lux)

esp_err_t light_sensor_sleep(sensor_light_handle_t sensor)

Set sensor to sleep mode.

Return

esp_err_t

  • ESP_OK Success

  • ESP_FAIL Fail

  • ESP_ERR_NOT_SUPPORTED Function not supported on this sensor

Parameters

  • sensor: light sensor handle to operate.

esp_err_t light_sensor_wakeup(sensor_light_handle_t sensor)

Wakeup sensor from sleep mode.

Return

esp_err_t

  • ESP_OK Success

  • ESP_FAIL Fail

  • ESP_ERR_NOT_SUPPORTED Function not supported on this sensor

Parameters

  • sensor: light sensor handle to operate.

esp_err_t light_sensor_acquire(sensor_light_handle_t sensor, sensor_data_group_t *data_group)

acquire a group of sensor data

Return

esp_err_t

  • ESP_OK Success

  • ESP_FAIL Fail

Parameters

  • sensor: light sensor handle to operate

  • data_group: acquired data

esp_err_t light_sensor_control(sensor_light_handle_t sensor, sensor_command_t cmd, void *args)

control sensor mode with control commands and args

Parameters

  • sensor: light sensor handle to operate

  • cmd: control commands detailed in sensor_command_t

  • args: control commands args

    • ESP_OK Success

    • ESP_FAIL Fail

    • ESP_ERR_NOT_SUPPORTED Function not supported on this sensor

Type Definitions

typedef void *sensor_light_handle_t

light sensor handle

Enumerations

enum light_sensor_id_t

light sensor id, used for light_sensor_create

Values:

BH1750_ID = 0x01

BH1750 light sensor id

VEML6040_ID

VEML6040 light sensor id

VEML6075_ID

VEML6075 light sensor id

LIGHT_MAX_ID

max light sensor id

Provide feedback about this document