Device driver for Broadcom APDS99XX proximity and ambient light sensors. More...

Detailed Description

Device driver for Broadcom APDS99XX proximity and ambient light sensors.

The driver can be used with following Broadcom sensors: APDS9900, APDS9901, APDS9930, APDS9950, APDS9960

The driver is divided into two parts:

Basic driver apds99xx

The base driver apds99xx only supports a basic set of functions and has therefore a small size. The procedure for retrieving new data is polling. Ambient light and proximity sensing are supported.
Fully functional driver apds99xx_full

The fully functional driver apds99xx_full supports all the features supported by the base driver, as well as all other sensor features, including interrupts and their configuration. Data-ready interrupts can be used to retrieve data. In addition, threshold interrupts can be used and configured.

Note

In addition to specifying whether the base driver apds99xx or the fully featured driver apds99xx_full should be used, the application has to declare used sensor by means of various pseudomodules as follows:

 APDS9900:     USEMODULE=apds9900
 APDS9901:     USEMODULE=apds9901
 APDS9930:     USEMODULE=apds9930
 APDS9950:     USEMODULE=apds9950
 APDS9960:     USEMODULE=apds9960

This driver provides [S]ensor [A]ctuator [U]ber [L]ayer capabilities.

Measurement Cycle

APDS99XX sensor measurement cycles consists of the following three steps in the given order:

Proximity Sensing

The sensor generates a number of IR LED pulses and measures the amount of the IR energy reflected by an object to determine its distance. The time required for proximity sensing (t_prx ) results from the time it takes to generate the IR LED pulses and to accumulate the reflected IR energy (t_prx_acc) as well as the time for the ADC conversion (t_prx_cnv).

t_prx = t_prx_acc + t_prx_cnv

The time to generate the IR LED pulses and accumulate reflected IR energy t_prx_acc is defined by the number of pulses (parameter apds99xx_params_t::prx_pulses) and the period of one pulse t_prx_pulse.

t_prx_acc = prx_pulses * t_prx_pulse

The ADC conversion time t_prx_cnv and the period of one pulse t_prx_pulse depend on used sensor and are available as the defines APDS99XX_T_PRX_CNV and APDS99XX_T_PRX_PULSE for calculations by the application.

Sensor	t_prx_pulse APDS99XX_T_PRX_PULSE	t_prx_cnv APDS99XX_T_PRX_CNV
APDS9900	0.016 ms	2.720 ms
APDS9901	0.016 ms	2.720 ms
APDS9930	0.016 ms	2.730 ms
APDS9950	0.014 ms	2.400 ms
APDS9960	0.036 ms	0.814 ms

Proximity sensing uses the gain specified by parameter apds99xx_params_t::prx_gain and the LED current specified by parameter apds99xx_params_t::prx_drive.

Wait

The sensor waits for t_wait which is defined by the number of waiting steps wait_steps (apds99xx_params_t::wait_steps), the time per step t_step, and the wait long flag (apds99xx_params_t::wait_long);

t_wait = wait_steps * t_wait_step            (if wait_long is false)
t_wait = wait_steps * t_wait_step * 12       (if wait_long is true)

Parameter apds99xx_params_t::wait_steps can range from 0 to 256. If apds99xx_params_t::wait_steps is 0, waiting is disabled. The time per step t_wait_step depends on used sensor and is available as the define APDS99XX_T_WAIT_STEP for calculations by the application.

Sensor	t_als_step APDS99XX_T_WAIT_STEP	t_wait (wait_long=0)	t_wait (wait_long=1)
APDS9900	2.72 ms	`wait_steps` * 2.72 ms	`wait_steps` * 12 * 2.72 ms
APDS9901	2.72 ms	`wait_steps` * 2.72 ms	`wait_steps` * 12 * 2.72 ms
APDS9930	2.73 ms	`wait_steps` * 2.73 ms	`wait_steps` * 12 * 2.73 ms
APDS9950	2.40 ms	`wait_steps` * 2.40 ms	`wait_steps` * 12 * 2.40 ms
APDS9960	2.78 ms	`wait_steps` * 2.78 ms	`wait_steps` * 12 * 2.78 ms

Ambient Light Sensing (ALS)

The sensor converts the amplified photodiode currents using integrating ADCs. The time required for ALS is determined by the ALS integration time t_als_int, which is defined as the number of integration steps als_steps (parameter apds99xx_params_t::als_steps) and the time per step t_als_step.

t_als_int = als_steps * t_als_step

Parameter apds99xx_params_t::als_steps can range from 0 to 256. If apds99xx_params_t::als_steps is 0, ALS is disabled. The time per step t_als_step depends on used sensor and is available as the define APDS99XX_T_ALS_STEP for calculations by the application.

The ALS integration time in steps als_steps (parameter apds99xx_params_t::als_steps) affects the resolution and the full scale range cnt_als_max of ALS data.

cnt_als_max = als_steps * cnts_p_step

The counts per step cnts_p_step depend on used sensor and is available as defines APDS99XX_CNTS_P_STEP for calculations by the application

ALS uses the gain specified by parameter apds99xx_params_t::als_gain.

Sensor	t_als_step APDS99XX_T_ALS_STEP	cnts_p_step APDS99XX_CNTS_P_STEP	t_als_int	cnt_als_max
APDS9900	2.72 ms	1023	`als_steps` * 2.72 ms	`als_steps` * 1023
APDS9901	2.72 ms	1023	`als_steps` * 2.72 ms	`als_steps` * 1023
APDS9930	2.73 ms	1023	`als_steps` * 2.73 ms	`als_steps` * 1023
APDS9950	2.40 ms	1024	`als_steps` * 2.40 ms	`als_steps` * 1024
APDS9960	2.78 ms	1025	`als_steps` * 2.78 ms	`als_steps` * 1025

The overall measurement cycle time is given by:

t_cycle = t_prx + t_wait + t_als_int

For a given ALS integration time and a given proximity sensing time, the waiting time can be used to tune the overall measurement cycle time.

Interrupts

With the apds99xx_full driver, interrupts can be used either to fetch ALS and proximity data or to detect when these data exceed defined thresholds.

To use interrupts, the application must call the apds99xx_int_config function to specify an apds99xx_int_config_t interrupt configuration and an ISR with an optional argument that is invoked when an interrupt is raised. For details about configuring and enabling the interrupts, see apds99xx_int_config_t.

Note: The ISR of the application is executed in the interrupt context. Therefore, it must not be blocking or time consuming. In addition, it must not access the sensor directly via I2C. It should only indicate to the waiting application that an interrupt has occurred, which is then handled in the thread context.

While an interrupt is being serviced, the application can use the apds99xx_int_source function to query the type of interrupts triggered by the sensor. In addition, the function resets the interrupt signal.

Note: Since the interrupt signal is only reset by the function apds99xx_int_source, this function apds99xx_int_source must be executed by application, even if the type of the triggered interrupt is not of interest.

For using interrupts, the GPIO to which the sensor's INT output pin is connected has to be defined by the application in configuration parameters. The GPIO is initialized by the driver as soon as the interrupt configuration with the function # apds99xx_int_config is specified.

Illuminance in Lux and RGB count values

For all sensors, the clear channel and the RGB channels provide only count values. APDS9900, APDS9901, and APDS9930 have an IR photodiode in addition to the clear channel photodiode, which can be used to determine the illuminance in Lux with an algorithm described in their datasheets.

Unfortunately, APDS9950 and APDS9960 do not have such an additional IR photodiode, and there is no document which describes an approach to calculate the illuminance from the RGB channels. Therefore, it is not possible to determine the illuminance for these sensors.

Author: Gunar Schorcht gunar.nosp@m.@sch.nosp@m.orcht.nosp@m..net

Files
file	apds99xx_params.h
	Default configuration for Broadcom APDS99XX proximity and ambient light sensor.

file	apds99xx_regs.h
	Register definitions for Broadcom APDS99XX proximity and ambient light sensor.

file	apds99xx.h

Data Structures
struct	apds99xx_params_t
	APDS99XX device initialization parameters. More...

struct	apds99xx_int_config_t
	Interrupt configuration. More...

struct	apds99xx_int_source_t
	Interrupt source. More...

struct	apds99xx_t
	APDS99XX sensor device data structure type. More...

union	apds99xx_rgb_t
	RGB count value data structure (APDS9950 and APDS9960 only) More...

Macros
#define	APDS99XX_I2C_ADDRESS (0x39)
	APDS99XX I2C addresses.

Typedefs
typedef void(*	apds99xx_isr_t) (void *arg)
	Interrupt service routine function prototype.

Enumerations
enum	apds99xx_error_codes_t { APDS99XX_OK, APDS99XX_ERROR_I2C, APDS99XX_ERROR_WRONG_ID, APDS99XX_ERROR_NO_DATA, APDS99XX_ERROR_RAW_DATA }
	Definition of error codes. More...

enum	apds99xx_als_gain_t { APDS99XX_ALS_GAIN_1 = 0, APDS99XX_ALS_GAIN_8, APDS99XX_ALS_GAIN_16, APDS99XX_ALS_GAIN_64, APDS99XX_ALS_GAIN_120 }
	Ambient light sensing (ALS) gain. More...

enum	apds99xx_prx_gain_t { APDS99XX_PRX_GAIN_1 = 0, APDS99XX_PRX_GAIN_2, APDS99XX_PRX_GAIN_4, APDS99XX_PRX_GAIN_8 }
	Proximity sensing (PRX) gain. More...

enum	apds99xx_prx_drive_t { APDS99XX_PRX_DRIVE_100 = 0, APDS99XX_PRX_DRIVE_50, APDS99XX_PRX_DRIVE_25, APDS99XX_PRX_DRIVE_12_5 }
	Proximity sensing (PRX) LED drive strength. More...

Functions
int	apds99xx_init (apds99xx_t dev, const apds99xx_params_t params)
	Initialize the APDS99XX sensor device. More...

int	apds99xx_data_ready_als (const apds99xx_t *dev)
	Ambient light sensing (ALS) data-ready status function. More...

int	apds99xx_read_als_raw (const apds99xx_t dev, uint16_t raw)
	Read one raw data sample of ambient light sensing (ALS) More...

int	apds99xx_read_illuminance (const apds99xx_t dev, uint16_t lux)
	Read one data sample of illuminance in lux. More...

int	apds99xx_read_rgb_raw (const apds99xx_t dev, apds99xx_rgb_t rgb)
	Read one raw RGB color data sample (APDS9950 and APDS9960 only) More...

int	apds99xx_data_ready_prx (const apds99xx_t *dev)
	Proximity sensing (PRX) data-ready status function. More...

int	apds99xx_read_prx_raw (const apds99xx_t dev, uint16_t prx)
	Read one data sample of proximity sensing (PRX) More...

int	apds99xx_power_down (const apds99xx_t *dev)
	Power down the sensor. More...

int	apds99xx_power_up (const apds99xx_t *dev)
	Power up the sensor. More...

int	apds99xx_int_config (apds99xx_t dev, apds99xx_int_config_t cfg, apds99xx_isr_t isr, void *isr_arg)
	Configure the interrupts of the sensor. More...

int	apds99xx_int_source (apds99xx_t dev, apds99xx_int_source_t src)
	Get the source of an interrupt. More...

APDS99XX device properties
Defines for different device properties for supported sensor types. These properties can be used by the application for calculations.
#define	APDS99XX_ID (0xab)
	Device ID of ADPS-9960.

#define	APDS99XX_T_PRX_PULSE (36)
	LED IR pulse period `t_pulse` in us (for PPLEN=8 us)

#define	APDS99XX_T_PRX_CNV (841)
	Proximity ADC conversion time `t_prx_conv` in us (tINIT + tCNVT for PPLEN=8 us)

#define	APDS99XX_T_WAIT_STEP (2780)
	Wait time step size `t_step` in us.

#define	APDS99XX_T_ALS_STEP (2780)
	ALS integration time step size `t_step` in.

#define	APDS99XX_CNTS_P_STEP (1025)
	Counts per step `cnts_p_step`

Enumeration Type Documentation

◆ apds99xx_als_gain_t

enum apds99xx_als_gain_t

Ambient light sensing (ALS) gain.

Enumerator
APDS99XX_ALS_GAIN_1	1 x gain (default)
APDS99XX_ALS_GAIN_8	8 x gain
APDS99XX_ALS_GAIN_16	16 x gain
APDS99XX_ALS_GAIN_64	64 x gain (APDS9950, APDS9960 only)
APDS99XX_ALS_GAIN_120	120 x gain (APDS9900, APDS9901, APDS9930 only)

Definition at line 289 of file apds99xx.h.

◆ apds99xx_error_codes_t

enum apds99xx_error_codes_t

Definition of error codes.

Enumerator
APDS99XX_OK	success
APDS99XX_ERROR_I2C	I2C communication error.
APDS99XX_ERROR_WRONG_ID	wrong id read
APDS99XX_ERROR_NO_DATA	no data are available
APDS99XX_ERROR_RAW_DATA	reading raw data failed

Definition at line 278 of file apds99xx.h.

◆ apds99xx_prx_drive_t

enum apds99xx_prx_drive_t

Proximity sensing (PRX) LED drive strength.

Enumerator
APDS99XX_PRX_DRIVE_100	100.0 mA (default)
APDS99XX_PRX_DRIVE_50	50.0 mA
APDS99XX_PRX_DRIVE_25	25.0 mA
APDS99XX_PRX_DRIVE_12_5	12.5 mA

Definition at line 316 of file apds99xx.h.

◆ apds99xx_prx_gain_t

enum apds99xx_prx_gain_t

Proximity sensing (PRX) gain.

Enumerator
APDS99XX_PRX_GAIN_1	1 x gain (default)
APDS99XX_PRX_GAIN_2	2 x gain (APDS9930, APDS9960 only)
APDS99XX_PRX_GAIN_4	4 x gain (APDS9930, APDS9960 only)
APDS99XX_PRX_GAIN_8	8 x gain (APDS9930, APDS9960 only)

Definition at line 304 of file apds99xx.h.

Function Documentation

◆ apds99xx_data_ready_als()

int apds99xx_data_ready_als ( const apds99xx_t * dev )

Ambient light sensing (ALS) data-ready status function.

The function reads the ALS valid flag in status register and returns. It can be used for polling new ambient light sensing data.

Parameters

[in] dev device descriptor of APDS99XX sensor

Return values

APDS99XX_OK	new abmient light data available
APDS99XX_ERROR_NO_DATA	no new abmient light data available
APDS99XX_ERROR_*	negative error code, see apds99xx_error_codes_t

◆ apds99xx_data_ready_prx()

int apds99xx_data_ready_prx ( const apds99xx_t * dev )

Proximity sensing (PRX) data-ready status function.

The function reads the proximity valid flag in status register and returns. It can be used for polling new proximity sensing data.

Parameters

[in] dev device descriptor of APDS99XX sensor

Return values

APDS99XX_OK	new proximity data available
APDS99XX_ERROR_NO_DATA	no new proximity data available
APDS99XX_ERROR_*	negative error code, see apds99xx_error_codes_t

◆ apds99xx_init()

int apds99xx_init	(	apds99xx_t *	dev,
		const apds99xx_params_t *	params
	)

Initialize the APDS99XX sensor device.

This function resets the sensor and initializes the sensor according to given initialization parameters. All registers are reset to default values.

Parameters

[in]	dev	device descriptor of APDS99XX sensor to be initialized
[in]	params	configuration parameters, see apds99xx_params_t

Return values

APDS99XX_OK	on success
APDS99XX_ERROR_*	a negative error code on error, see apds99xx_error_codes_t

◆ apds99xx_int_config()

int apds99xx_int_config	(	apds99xx_t *	dev,
		apds99xx_int_config_t *	cfg,
		apds99xx_isr_t	isr,
		void *	isr_arg
	)

Configure the interrupts of the sensor.

The function configures the interrupts of the sensor and sets the ISR as well as its argument for handling the interrupts.

If any interrupt is enabled by the configuration (apds99xx_int_config_t::als_int_en or apds99xx_int_config_t::als_int_en are set), the function

initializes the GPIO defined by apds99xx_params_t::int_pin, and
attaches the ISR specified by the isr parameter to the interrupt.

Note: Since the ISR is executed in the interrupt context, it must not be blocking or time consuming. In addition, it must not access the sensor directly via I2C. It should only indicate to a waiting thread that an interrupt has occurred, which is then handled in the thread context.

Parameters

[in]	dev	device descriptor of APDS99XX sensor
[in]	cfg	interrupt configuration, see apds99xx_int_config_t
[in]	isr	ISR called for all types of interrupts
[in]	isr_arg	ISR argument, can be NULL

Return values

APDS99XX_OK	on success
APDS99XX_ERROR_*	negative error code on error, see apds99xx_error_codes_t

◆ apds99xx_int_source()

int apds99xx_int_source	(	apds99xx_t *	dev,
		apds99xx_int_source_t *	src
	)

Get the source of an interrupt.

The function clears the interrupt signal and returns the source of the interrupt. Since the interrupt signal is only reset by this function, it must be executed to reset the interrupt signal, even if the type of the triggered interrupt is not of interest.

Note: It must not be called from the ISR to avoid I2C bus accesses in the interrupt context.

Parameters

[in]	dev	device descriptor of APDS99XX sensor
[out]	src	interrupt source, see apds99xx_int_source_t

Return values

APDS99XX_OK	on success
APDS99XX_ERROR_*	negative error code on error, see apds99xx_error_codes_t

◆ apds99xx_power_down()

int apds99xx_power_down ( const apds99xx_t * dev )

Power down the sensor.

The sensor is switched into sleep mode. It remains operational on the I2C interface. Depending on the sensor used, it consumes only about 1 to 3 uA in this mode.

Parameters

[in] dev device descriptor of APDS99XX sensor

Return values

APDS99XX_OK	on success
APDS99XX_ERROR_*	a negative error code on error, see apds99xx_error_codes_t

◆ apds99xx_power_up()

int apds99xx_power_up ( const apds99xx_t * dev )

Power up the sensor.

The sensor is woken up from sleep mode.

Parameters

[in] dev device descriptor of APDS99XX sensor

Return values

APDS99XX_OK	on success
APDS99XX_ERROR_*	a negative error code on error, see apds99xx_error_codes_t

◆ apds99xx_read_als_raw()

int apds99xx_read_als_raw	(	const apds99xx_t *	dev,
		uint16_t *	raw
	)

Read one raw data sample of ambient light sensing (ALS)

Raw ambient light sensing (ALS) data are available as 16-bit count values (cnt_als). The range of these count values depends on the ALS integration time apds99xx_params_t::als_steps and the ALS gain apds99xx_params_t::als_gain. The maximum count value (cnt_als_max) is:

 cnt_als_max = APDS99XX_CNTS_P_STEP * als_steps * als_gain

If there are no new data ready to read, last valid data sample is returned. Function apds99xx_data_ready_als could be used to check whether new data are available before this function is called.

Parameters

[in]	dev	device descriptor of APDS99XX sensor
[out]	raw	raw ambient light sensing data as count value

Return values

APDS99XX_OK	on success
APDS99XX_ERROR_*	negative error code, see apds99xx_error_codes_t

◆ apds99xx_read_illuminance()

int apds99xx_read_illuminance	(	const apds99xx_t *	dev,
		uint16_t *	lux
	)

Read one data sample of illuminance in lux.

Illuminance in lux is computed from raw ambient light sensing (ALS) data which are measured in counts. Since the range of ALS data depend on ALS integration time apds99xx_params_t::als_steps and the ALS gain apds99xx_params_t::als_gain, these parameters also affect the sensitivity of the illuminance.

Note: This function is only available for APDS9900, APDS9901 and APD9930.

Parameters

[in]	dev	device descriptor of APDS99XX sensor
[out]	lux	illuminance in lux

Return values

APDS99XX_OK	on success
APDS99XX_ERROR_*	negative error code, see apds99xx_error_codes_t

◆ apds99xx_read_prx_raw()

int apds99xx_read_prx_raw	(	const apds99xx_t *	dev,
		uint16_t *	prx
	)

Read one data sample of proximity sensing (PRX)

Proximity data samples are given as a 16-bit count values (cnt_prx).

Note: APDS9960 returns only 8-bit values in the range of 0 to 255.

The range of the count values depends on the PRX LED drive strength apds99xx_params_t::prx_drive the PRX gain apds99xx_params_t::prx_gain, and if used, the PRX integration time apds99xx_params_t::prx_time.

Note: A number of disturbing effects such as DC noise, sensor coverage, or surrounding objects cause an offset in the measured proximity values. The application should remove this offset, for example, by finding the minimum value ever measured and subtracting it from the current reading. The minimum value is then assumed to be 0 (no proximity).

Parameters

[in]	dev	device descriptor of APDS99XX sensor
[out]	prx	proximity sensing data as count value

Return values

APDS99XX_OK	on success
APDS99XX_ERROR_*	a negative error code on error, see apds99xx_error_codes_t

◆ apds99xx_read_rgb_raw()

int apds99xx_read_rgb_raw	(	const apds99xx_t *	dev,
		apds99xx_rgb_t *	rgb
	)

Read one raw RGB color data sample (APDS9950 and APDS9960 only)

In APDS9950 and APDS9960 sensors, ambient light sensing (ALS) also detects spectral components of the light as RGB count values. This function can be used to fetch raw RGB data.

Raw RGB data are available as 16-bit count values (cnt_als). The range of these count values depends on the ALS integration time apds99xx_params_t::als_steps and the ALS gain apds99xx_params_t::als_gain. The maximum count value (cnt_rgb_max) is:

 cnt_rgb_max = APDS99XX_CNTS_P_STEP * als_steps * als_gain

If there are no data ready to read, last valid data sample is returned. Function apds99xx_data_ready_als could be used to check whether new data are available before this function is called.

Note: This function is only available for APDS9950 and APD9960.

Parameters

[in]	dev	device descriptor of APDS99XX sensor
[out]	rgb	RGB color data sample as count values

Return values

APDS99XX_OK	on success
APDS99XX_ERROR_*	negative error code, see apds99xx_error_codes_t

Detailed Description

Measurement Cycle

Interrupts

Illuminance in Lux and RGB count values

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

APDS99XX device properties

Enumeration Type Documentation

◆ apds99xx_als_gain_t

◆ apds99xx_error_codes_t

◆ apds99xx_prx_drive_t

◆ apds99xx_prx_gain_t

Function Documentation

◆ apds99xx_data_ready_als()

◆ apds99xx_data_ready_prx()

◆ apds99xx_init()

◆ apds99xx_int_config()

◆ apds99xx_int_source()

◆ apds99xx_power_down()

◆ apds99xx_power_up()

◆ apds99xx_read_als_raw()

◆ apds99xx_read_illuminance()

◆ apds99xx_read_prx_raw()

◆ apds99xx_read_rgb_raw()