Ambient light sensor

Ambient light sensor (ALS) class. More...

Modules
	OPT3001
	TI OPT3001 Ambient light sensor driver.
	POSIX
	Ambient light sensor of a native build: always dark.
	QEMU
	QEMU ambient light sensor.
	W1160
	W1160 Ambient light sensor driver.

Data Structures
struct	pbl_als_scale
	Raw count to lux calibration: lux = (raw - offset) * num / den. More...
struct	pbl_als_ops
	Ambient light sensor driver operations, called with the device lock held. More...
struct	pbl_als_state
	Ambient light sensor runtime state. More...
struct	pbl_als
	Ambient light sensor. More...

Macros
#define	PBL_ALS_STATE_DEFINE(sym)
	Define the class state of an ambient light sensor.
#define	PBL_ALS_INIT(sym, _name, _parent, _ops, _scale)
	Initialize a struct pbl_als.

Functions
int	pbl_als_read (const struct pbl_als *als, uint32_t *level)
	Read the light level.
void	pbl_als_prime (const struct pbl_als *als)
	Announce that readings will be wanted soon.
void	pbl_als_release (const struct pbl_als *als)
	Drop a reference taken with pbl_als_prime().
void	pbl_als_suspend (const struct pbl_als *als)
	Stop sampling until the matching pbl_als_resume().
void	pbl_als_resume (const struct pbl_als *als)
	Drop a reference taken with pbl_als_suspend().
bool	pbl_als_has_lux (const struct pbl_als *als)
	Check whether the sensor is calibrated to lux.
uint32_t	pbl_als_to_lux (const struct pbl_als *als, uint32_t level)
	Convert a light level to lux.

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).
const struct pbl_als *const	ALS
	The board's ambient light sensor.

Detailed Description

Ambient light sensor (ALS) class.

An ambient light sensor is a struct pbl_als device. Readings are raw counts between 0 and AMBIENT_LIGHT_LEVEL_MAX; a calibrated instance converts them to lux with pbl_als_to_lux().

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

Every call into the driver runs with the device lock held, a recursive mutex.

uint32_t level;
 
pbl_als_prime(ALS);
...
if (pbl_als_read(ALS, &level) == 0) {
  uint32_t lux = pbl_als_to_lux(ALS, level);
}
pbl_als_release(ALS);

---

Data Structure Documentation

pbl_als_scale

struct pbl_als_scale

Raw count to lux calibration: lux = (raw - offset) * num / den.

Covers the sensor and the optical path in front of it, so it belongs to the board.

Data Fields
uint32_t	den	Denominator.
uint32_t	num	Numerator.
uint32_t	offset	Dark offset, in raw counts.

pbl_als_state

struct pbl_als_state

Ambient light sensor runtime state.

Data Fields
struct pbl_mutex	lock	Device lock.
uint16_t	prime_count	Prime references.
uint16_t	suspend_count	Suspend references.

pbl_als

struct pbl_als

Ambient light sensor.

Data Fields
struct pbl_device	dev	Device.
const struct pbl_als_ops *	ops	Driver operations.
const struct pbl_als_scale *	scale	Lux calibration, or NULL if uncalibrated.
struct pbl_als_state *	state	Runtime state.

Macro Definition Documentation

PBL_ALS_INIT

#define PBL_ALS_INIT	(		sym,
			_name,
			_parent,
			_ops,
			_scale
	)

Value:

  {                                                                         \
    .dev = PBL_DEVICE_INIT(sym, _name, pbl_als_dev_init, _parent, nullptr), \
    .ops = (_ops),                                                          \
    .state = &sym##_als_state,                                              \
    .scale = (_scale),                                                      \
  }

Initialize a struct pbl_als.

Parameters

sym	Symbol of the instance, as passed to PBL_ALS_STATE_DEFINE().
_name	Device name.
_parent	Parent device.
_ops	Driver operations.
_scale	Lux calibration, or NULL.

PBL_ALS_STATE_DEFINE

#define PBL_ALS_STATE_DEFINE

(

sym

)

Value:

  PBL_DEVICE_STATE_DEFINE(sym);   \
  static struct pbl_als_state sym##_als_state = {.lock = PBL_MUTEX_INITIALIZER}

Define the class state of an ambient light sensor.

Parameters

sym	Symbol of the instance.

Function Documentation

pbl_als_has_lux()

bool pbl_als_has_lux

(

const struct pbl_als *

als

)

Check whether the sensor is calibrated to lux.

Parameters

als	Ambient light sensor.

Returns

true if pbl_als_to_lux() converts to lux.

pbl_als_prime()

void pbl_als_prime

(

const struct pbl_als *

als

)

Announce that readings will be wanted soon.

Reference counted; balance with pbl_als_release(). Lets drivers that sample continuously start ahead of the first read. Does nothing if the sensor is not ready.

Parameters

als	Ambient light sensor.

pbl_als_read()

int pbl_als_read	(	const struct pbl_als *	als,
		uint32_t *	level
	)

Read the light level.

Parameters

	als	Ambient light sensor.
[out]	level	Raw light level between 0 and AMBIENT_LIGHT_LEVEL_MAX.

Returns

0, -ENODEV if the sensor is not ready, or a negative errno.

pbl_als_release()

void pbl_als_release

(

const struct pbl_als *

als

)

Drop a reference taken with pbl_als_prime().

Parameters

als	Ambient light sensor.

pbl_als_resume()

void pbl_als_resume

(

const struct pbl_als *

als

)

Drop a reference taken with pbl_als_suspend().

Parameters

als	Ambient light sensor.

pbl_als_suspend()

void pbl_als_suspend

(

const struct pbl_als *

als

)

Stop sampling until the matching pbl_als_resume().

Reference counted. Used while something disturbs the sensor, e.g. backlight bleed-through. Does nothing if the sensor is not ready.

Parameters

als	Ambient light sensor.

pbl_als_to_lux()

uint32_t pbl_als_to_lux	(	const struct pbl_als *	als,
		uint32_t	level
	)

Convert a light level to lux.

On uncalibrated sensors the level is returned unchanged, so callers can use the result unconditionally.

Parameters

als	Ambient light sensor.
level	Light level, after screen compensation if any.

Returns

Light level in lux, or level if uncalibrated.

Variable Documentation

ALS

const struct pbl_als* const ALS

extern

The board's ambient light sensor.

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).