Ambient light sensor

Ambient light sensor (ALS) driver interface. More...

Macros
#define	AMBIENT_LIGHT_LEVEL_ENUM_COUNT   (AmbientLightLevelVeryLight + 1)
	Number of AmbientLightLevel values.

Enumerations
enum	AmbientLightLevel {   AmbientLightLevelUnknown = 0 , AmbientLightLevelVeryDark , AmbientLightLevelDark , AmbientLightLevelLight ,   AmbientLightLevelVeryLight }
	Light level enum. More...

Functions
void	ambient_light_init (void)
	Initialize the ambient light sensor.
uint32_t	ambient_light_get_light_level (void)
	Read the light level.
void	ambient_light_prime (void)
	Announce that readings will be wanted soon.
void	ambient_light_release (void)
	Drop a reference taken with ambient_light_prime().
void	ambient_light_suspend (void)
	Stop sampling until the matching ambient_light_resume().
void	ambient_light_resume (void)
	Drop a reference taken with ambient_light_suspend().
void	ambient_light_common_init (void)
	Initialize the reference counting common to all drivers.
void	ambient_light_driver_set_state (bool active, bool sampling)
	Apply the sampling state computed by the common code.
uint32_t	ambient_light_get_dark_threshold (void)
	Get the threshold between light and dark.
void	ambient_light_set_dark_threshold (uint32_t new_threshold)
	Set the threshold between light and dark.
bool	ambient_light_is_light ()
	Check whether it is light.
AmbientLightLevel	ambient_light_level_to_enum (uint32_t light_level)
	Classify a light level against the dark threshold.
bool	ambient_light_lux_available (void)
	Check whether the board has raw-count to lux coefficients.
uint32_t	ambient_light_level_to_lux (uint32_t light_level)
	Convert a light level to lux using the board coefficients.

Variables
static const uint32_t	AMBIENT_LIGHT_LEVEL_MAX = (1U << CONFIG_AMBIENT_LIGHT_BITS)
	Upper bound of the raw light level scale (CONFIG_AMBIENT_LIGHT_BITS bits).

Detailed Description

Ambient light sensor (ALS) driver interface.

Readings are raw counts between 0 and AMBIENT_LIGHT_LEVEL_MAX. Boards with calibration coefficients can convert them to lux with ambient_light_level_to_lux().

Sampling is controlled by two reference counts kept by the common code: a client that will read the sensor soon primes it, and code that would disturb the reading (e.g. backlight bleed-through) suspends it. The sensor samples while primed and not suspended.

ambient_light_prime();
...
uint32_t lux = ambient_light_level_to_lux(ambient_light_get_light_level());
ambient_light_release();

Macro Definition Documentation

AMBIENT_LIGHT_LEVEL_ENUM_COUNT

#define AMBIENT_LIGHT_LEVEL_ENUM_COUNT   (AmbientLightLevelVeryLight + 1)

Number of AmbientLightLevel values.

Enumeration Type Documentation

AmbientLightLevel

enum AmbientLightLevel

Light level enum.

Enumerator
AmbientLightLevelUnknown	No reading available.
AmbientLightLevelVeryDark	Well below the dark threshold.
AmbientLightLevelDark	Below the dark threshold.
AmbientLightLevelLight	At or slightly above the dark threshold.
AmbientLightLevelVeryLight	Well above the dark threshold.

Function Documentation

ambient_light_common_init()

void ambient_light_common_init

(

void

)

Initialize the reference counting common to all drivers.

Called by the driver's ambient_light_init(); prime and suspend requests made earlier are ignored.

ambient_light_driver_set_state()

void ambient_light_driver_set_state	(	bool	active,
		bool	sampling
	)

Apply the sampling state computed by the common code.

Implemented by the driver and called with the common lock held whenever a reference count changes. A no-op for drivers without a sampling gate.

Parameters

active	True while primed.
sampling	True while primed and not suspended.

ambient_light_get_dark_threshold()

uint32_t ambient_light_get_dark_threshold

(

void

)

Get the threshold between light and dark.

Returns

Threshold, in the units returned by ambient_light_level_to_lux().

ambient_light_get_light_level()

uint32_t ambient_light_get_light_level

(

void

)

Read the light level.

Returns

Raw light level between 0 and AMBIENT_LIGHT_LEVEL_MAX, 0 if the sensor is not initialized.

ambient_light_init()

void ambient_light_init

(

void

)

Initialize the ambient light sensor.

ambient_light_is_light()

bool ambient_light_is_light

(

)

Check whether it is light.

Returns

True if the current level, converted with ambient_light_level_to_lux(), is above the dark threshold; false if dark or the sensor is unavailable.

ambient_light_level_to_enum()

AmbientLightLevel ambient_light_level_to_enum

(

uint32_t

light_level

)

Classify a light level against the dark threshold.

Parameters

light_level

Light level, in the units of the dark threshold.

Returns

Light level class, AmbientLightLevelUnknown if the sensor is unavailable.

ambient_light_level_to_lux()

uint32_t ambient_light_level_to_lux

(

uint32_t

light_level

)

Convert a light level to lux using the board coefficients.

On boards without coefficients the level is returned unchanged, so callers can use the result unconditionally.

Parameters

light_level

Light level, after screen compensation if any.

Returns

Light level in lux, or light_level if uncalibrated.

ambient_light_lux_available()

bool ambient_light_lux_available

(

void

)

Check whether the board has raw-count to lux coefficients.

Returns

True if ambient_light_level_to_lux() converts to lux.

ambient_light_prime()

void ambient_light_prime

(

void

)

Announce that readings will be wanted soon.

Reference counted; balance with ambient_light_release(). Lets drivers that sample continuously start ahead of the first read.

ambient_light_release()

void ambient_light_release

(

void

)

Drop a reference taken with ambient_light_prime().

ambient_light_resume()

void ambient_light_resume

(

void

)

Drop a reference taken with ambient_light_suspend().

ambient_light_set_dark_threshold()

void ambient_light_set_dark_threshold

(

uint32_t

new_threshold

)

Set the threshold between light and dark.

Parameters

new_threshold

Threshold, in the units returned by ambient_light_level_to_lux(), at most AMBIENT_LIGHT_LEVEL_MAX.

ambient_light_suspend()

void ambient_light_suspend

(

void

)

Stop sampling until the matching ambient_light_resume().

Reference counted. Used while something disturbs the sensor, e.g. backlight bleed-through.

Variable Documentation

AMBIENT_LIGHT_LEVEL_MAX

const uint32_t AMBIENT_LIGHT_LEVEL_MAX = (1U << CONFIG_AMBIENT_LIGHT_BITS)

static

Upper bound of the raw light level scale (CONFIG_AMBIENT_LIGHT_BITS bits).