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