APDS99XX proximity and ambient light sensors

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:

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:

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

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 291 of file apds99xx.h.

◆ 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 280 of file apds99xx.h.

◆ 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 318 of file apds99xx.h.

◆ 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 306 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]devdevice descriptor of APDS99XX sensor
Return values
APDS99XX_OKnew abmient light data available
APDS99XX_ERROR_NO_DATAno 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]devdevice descriptor of APDS99XX sensor
Return values
APDS99XX_OKnew proximity data available
APDS99XX_ERROR_NO_DATAno 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]devdevice descriptor of APDS99XX sensor to be initialized
[in]paramsconfiguration parameters, see apds99xx_params_t
Return values
APDS99XX_OKon 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]devdevice descriptor of APDS99XX sensor
[in]cfginterrupt configuration, see apds99xx_int_config_t
[in]isrISR called for all types of interrupts
[in]isr_argISR argument, can be NULL
Return values
APDS99XX_OKon 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]devdevice descriptor of APDS99XX sensor
[out]srcinterrupt source, see apds99xx_int_source_t
Return values
APDS99XX_OKon 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]devdevice descriptor of APDS99XX sensor
Return values
APDS99XX_OKon 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]devdevice descriptor of APDS99XX sensor
Return values
APDS99XX_OKon 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]devdevice descriptor of APDS99XX sensor
[out]rawraw ambient light sensing data as count value
Return values
APDS99XX_OKon 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]devdevice descriptor of APDS99XX sensor
[out]luxilluminance in lux
Return values
APDS99XX_OKon 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]devdevice descriptor of APDS99XX sensor
[out]prxproximity sensing data as count value
Return values
APDS99XX_OKon 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]devdevice descriptor of APDS99XX sensor
[out]rgbRGB color data sample as count values
Return values
APDS99XX_OKon success
APDS99XX_ERROR_*negative error code, see apds99xx_error_codes_t