RIOT-OS/RIOT
RIOT-OS/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2024-12-29 04:50:03 +01:00
Code Releases Activity
af89824cfd
RIOT/drivers/include/apds99xx.h
Schorcht 7548a6e849 drivers: add APDS99XX ALS and proximity
2020-03-11 14:21:47 +01:00

688 lines
28 KiB
C
Raw Blame History

/*
* Copyright (C) 2018 Gunar Schorcht
*
* This file is subject to the terms and conditions of the GNU Lesser
* General Public License v2.1. See the file LICENSE in the top level
* directory for more details.
*/
/**
* @defgroup drivers_apds99xx APDS99XX proximity and ambient light sensors
* @ingroup drivers_sensors
* @ingroup drivers_saul
* @brief 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 @ref drivers_saul 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<br> | t_prx_pulse<br>APDS99XX_T_PRX_PULSE | t_prx_cnv<br>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
* <br>
*
* 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<br> | t_als_step<br>APDS99XX_T_WAIT_STEP | t_wait (wait_long=0) <br> | t_wait (wait_long=1) <br>
* ---------- | ------- | ---------------------------| ------------------------
* 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
* <br>
*
* - **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<br> | t_als_step<br>APDS99XX_T_ALS_STEP | cnts_p_step<br>APDS99XX_CNTS_P_STEP | t_als_int<br> | cnt_als_max<br>
* -------- | ------- | ---- | ----------------------- | ----------------
* 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@schorcht.net>
* @file
*/
#ifndef APDS99XX_H
#define APDS99XX_H
#ifdef __cplusplus
extern "C"
{
#endif
#include <stdbool.h>
#include <stdint.h>
#include "periph/gpio.h"
#include "periph/i2c.h"
/**
* @name APDS99XX device properties
*
* Defines for different device properties for supported sensor types. These
* properties can be used by the application for calculations.
* @{
*/
#if MODULE_APDS9900
#define APDS99XX_ID (0x29) /**< Device ID of ADPS-9900 */
#define APDS99XX_T_PRX_PULSE (16) /**< LED IR pulse period ```t_pulse``` in us */
#define APDS99XX_T_PRX_CNV (2720) /**< Proximity ADC conversion time ```t_prx_conv``` in us */
#define APDS99XX_T_WAIT_STEP (2720) /**< Wait time step size ```t_step``` in us */
#define APDS99XX_T_ALS_STEP (2720) /**< ALS integration time step size ```t_step``` in */
#define APDS99XX_CNTS_P_STEP (1023) /**< Counts per step ```cnts_p_step``` */
#elif MODULE_APDS9901
#define APDS99XX_ID (0x20) /**< Device ID of ADPS-9901 */
#define APDS99XX_T_PRX_PULSE (16) /**< LED IR pulse period ```t_pulse``` in us */
#define APDS99XX_T_PRX_CNV (2720) /**< Proximity ADC conversion time ```t_prx_conv``` in us */
#define APDS99XX_T_WAIT_STEP (2720) /**< Wait time step size ```t_step``` in us */
#define APDS99XX_T_ALS_STEP (2720) /**< ALS integration time step size ```t_step``` in */
#define APDS99XX_CNTS_P_STEP (1023) /**< Counts per step ```cnts_p_step``` */
#elif MODULE_APDS9930
#define APDS99XX_ID (0x39) /**< Device ID of ADPS-9930 */
#define APDS99XX_T_PRX_PULSE (16) /**< LED IR pulse period ```t_pulse``` in us */
#define APDS99XX_T_PRX_CNV (2730) /**< Proximity ADC conversion time ```t_prx_conv``` in us */
#define APDS99XX_T_WAIT_STEP (2730) /**< Wait time step size ```t_step``` in us */
#define APDS99XX_T_ALS_STEP (2730) /**< ALS integration time step size ```t_step``` in */
#define APDS99XX_CNTS_P_STEP (1023) /**< Counts per step ```cnts_p_step``` */
#elif MODULE_APDS9950
#define APDS99XX_ID (0x69) /**< Device ID of ADPS-9950 */
#define APDS99XX_T_PRX_PULSE (14) /**< LED IR pulse period ```t_pulse``` in us */
#define APDS99XX_T_PRX_CNV (2400) /**< Proximity ADC conversion time ```t_prx_conv``` in us */
#define APDS99XX_T_WAIT_STEP (2400) /**< Wait time step size ```t_step``` in us */
#define APDS99XX_T_ALS_STEP (2400) /**< ALS integration time step size ```t_step``` in */
#define APDS99XX_CNTS_P_STEP (1024) /**< Counts per step ```cnts_p_step``` */
#elif MODULE_APDS9960 || DOXYGEN
#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``` */
#else
#error "Please provide a valid aps99xx variant (apds9900, apds9901, adps9930, apds9950, apds9960)"
#endif
/** @} */
/**
* @brief APDS99XX I2C addresses
*/
#define APDS99XX_I2C_ADDRESS (0x39)
/**
* @brief Definition of error codes
*/
typedef enum {
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 */
} apds99xx_error_codes_t;
/**
* @brief Ambient light sensing (ALS) gain
*/
typedef enum {
APDS99XX_ALS_GAIN_1 = 0, /**< 1 x gain (default) */
APDS99XX_ALS_GAIN_8, /**< 8 x gain */
APDS99XX_ALS_GAIN_16, /**< 16 x gain */
#if MODULE_APDS9950 || MODULE_APDS9960 || DOXYGEN
APDS99XX_ALS_GAIN_64, /**< 64 x gain (APDS9950, APDS9960 only) */
#endif /* MODULE_APDS9950 || MODULE_APDS9960 || DOXYGEN */
#if MODULE_APDS9900 || MODULE_APDS9901 || APDS9930 || DOXYGEN
APDS99XX_ALS_GAIN_120, /**< 120 x gain (APDS9900, APDS9901, APDS9930 only) */
#endif /* MODULE_APDS9900 || MODULE_APDS9901 || APDS9930 || DOXYGEN */
} apds99xx_als_gain_t;
/**
* @brief Proximity sensing (PRX) gain
*/
typedef enum {
APDS99XX_PRX_GAIN_1 = 0, /**< 1 x gain (default) */
#if MODULE_APDS9930 || MODULE_APDS9960 || DOXYGEN
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) */
#endif /* MODULE_APDS9930 || MODULE_APDS9960 || DOXYGEN */
} apds99xx_prx_gain_t;
/**
* @brief Proximity sensing (PRX) LED drive strength
*/
typedef enum {
APDS99XX_PRX_DRIVE_100 = 0, /**< 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 */
} apds99xx_prx_drive_t;
/**
* @brief APDS99XX device initialization parameters
*/
typedef struct {
unsigned dev; /**< I2C device (default I2C_DEV(0)) */
uint16_t als_steps; /**< ALS integration time in steps. If 0,
ALS is disabled. (default 64) */
apds99xx_als_gain_t als_gain; /**< Gain used for ALS.
(default #APDS99XX_ALS_GAIN_1) */
uint8_t prx_pulses; /**< IR LED pulses for proximity sensing.
If 0, proximity sensing is disabled.
(default 8 as recommended) */
apds99xx_prx_drive_t prx_drive; /**< IR LED current for proximity sensing
(default #APDS99XX_PRX_DRIVE_100) */
apds99xx_prx_gain_t prx_gain; /**< Gain used for proximity sensing.
(default #APDS99XX_PRX_GAIN_1) */
uint16_t wait_steps; /**< Waiting time in steps. If 0, waiting is
disabled. (default 0) */
bool wait_long; /**< Long waiting time. If true, waitng time is
increased by a factor 12. (default false) */
gpio_t int_pin; /**< interrupt pin: #GPIO_UNDEF if not used */
} apds99xx_params_t;
#if MODULE_APDS99XX_FULL || DOXYGEN
/**
* @brief Interrupt configuration
*
* The interrupt enable flags apds99xx_int_config_t::als_int_en and
* apds99xx_int_config_t::prx_int_en control whether ALS and proximity sensor
* interrupts are enable.
*
* The persistence values apds99xx_int_config_t::als_pers and
* apds99xx_int_config_t::prx_pers specify how many ALS or proximity
* values have to be outside of the thresholds defined by
* apds99xx_int_config_t::als_thresh_low and
* apds99xx_int_config_t::als_thresh_high or
* apds99xx_int_config_t::prx_thresh_low and
* apds99xx_int_config_t::prx_thresh_high.
*
* @note If the persistence values are 0, an interrupt is generated in each
* cycle at the end of the corresponding measurement step, regardless of the
* values and the defined threshold. The corresponding interrupt is thus used
* as a data-ready interrupt.
*/
typedef struct {
bool als_int_en; /**< ALS interrupt enabled */
uint8_t als_pers; /**< Number of consecutive ALS values that have to be
outside the thresholds to generate an interrupt:
Value | Interrupt is generated
--------| -------
0 | every cycle (ALS data-ready interrupt)
1...15 | when n values are outside the thresholds */
uint16_t als_thresh_low; /**< Low threshold value for ALS interrupts */
uint16_t als_thresh_high; /**< High threshold value for ALS interrupts */
bool prx_int_en; /**< Proximity interrupt enabled */
uint8_t prx_pers; /**< Number of consecutive proximity values that have
to be outside the thresholds to generate an
interrupt:
Value | Interrupt is generated
--------| -------
0 | every cycle (PRX data-ready interrupt)
1, 2, 3 | when 1, 2, or 3 values are outside the thresholds
4...15 | when (n - 3) * 5 values are outside the thresholds */
uint16_t prx_thresh_low; /**< Low threshold for proximity values
(only the low byte is used for APDS9960) */
uint16_t prx_thresh_high; /**< High threshold for proximity values
(only the low byte is used for APDS9960) */
} apds99xx_int_config_t;
/**
* @brief Interrupt source
*
* The type is used to
*/
typedef struct {
bool als_int; /**< ALS interrupt happened */
bool prx_int; /**< Proximity interrupt happened */
} apds99xx_int_source_t;
/**
* @brief Interrupt service routine function prototype
*/
typedef void (*apds99xx_isr_t)(void *arg);
#endif /* MODULE_APDS99XX_FULL */
/**
* @brief APDS99XX sensor device data structure type
*/
typedef struct {
apds99xx_params_t params; /**< device initialization parameters */
#if MODULE_APDS99XX_FULL || DOXYGEN
apds99xx_isr_t isr; /**< user ISR */
void* isr_arg; /**< user ISR argument */
bool gpio_init; /**< GPIO is already initialized */
#endif /* MODULE_APDS99XX_FULL */
} apds99xx_t;
#if MODULE_APDS9950 || MODULE_APDS9960 || DOXYGEN
/**
* @brief RGB count value data structure (APDS9950 and APDS9960 only)
*/
typedef union {
struct {
uint16_t red; /**< R photodiode count value (red) */
uint16_t green; /**< G photodiode count value (green) */
uint16_t blue; /**< B photodiode count value (blue) */
};
uint16_t val[3]; /**< RGB count values as array */
} apds99xx_rgb_t;
#endif
/**
* @brief 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.
*
* @param[in] dev device descriptor of APDS99XX sensor to be initialized
* @param[in] params configuration parameters, see #apds99xx_params_t
*
* @retval APDS99XX_OK on success
* @retval APDS99XX_ERROR_* a negative error code on error,
* see #apds99xx_error_codes_t
*/
int apds99xx_init(apds99xx_t *dev, const apds99xx_params_t *params);
/**
* @brief 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.
*
* @param[in] dev device descriptor of APDS99XX sensor
*
* @retval APDS99XX_OK new abmient light data available
* @retval APDS99XX_ERROR_NO_DATA no new abmient light data available
* @retval APDS99XX_ERROR_* negative error code,
* see #apds99xx_error_codes_t
*/
int apds99xx_data_ready_als(const apds99xx_t *dev);
/**
* @brief 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.
*
* @param[in] dev device descriptor of APDS99XX sensor
* @param[out] raw raw ambient light sensing data as count value
*
* @retval APDS99XX_OK on success
* @retval APDS99XX_ERROR_* negative error code,
* see #apds99xx_error_codes_t
*/
int apds99xx_read_als_raw(const apds99xx_t *dev, uint16_t *raw);
#if MODULE_APDS9900 || MODULE_APDS9901 || MODULE_APDS9930 || DOXYGEN
/**
* @brief 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.
*
* @param[in] dev device descriptor of APDS99XX sensor
* @param[out] lux illuminance in lux
*
* @retval APDS99XX_OK on success
* @retval APDS99XX_ERROR_* negative error code,
* see #apds99xx_error_codes_t
*/
int apds99xx_read_illuminance(const apds99xx_t *dev, uint16_t *lux);
#endif /* MODULE_APDS9900 || MODULE_APDS9901 || MODULE_APDS9930 || DOXYGEN */
#if MODULE_APDS9950 || MODULE_APDS9960 || DOXYGEN
/**
* @brief 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.
*
* @param[in] dev device descriptor of APDS99XX sensor
* @param[out] rgb RGB color data sample as count values
*
* @retval APDS99XX_OK on success
* @retval APDS99XX_ERROR_* negative error code,
* see #apds99xx_error_codes_t
*/
int apds99xx_read_rgb_raw(const apds99xx_t *dev, apds99xx_rgb_t *rgb);
#endif /* MODULE_APDS9950 || MODULE_APDS9960 || DOXYGEN */
/**
* @brief 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.
*
* @param[in] dev device descriptor of APDS99XX sensor
*
* @retval APDS99XX_OK new proximity data available
* @retval APDS99XX_ERROR_NO_DATA no new proximity data available
* @retval APDS99XX_ERROR_* negative error code,
* see #apds99xx_error_codes_t
*/
int apds99xx_data_ready_prx(const apds99xx_t *dev);
/**
* @brief 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).
*
* @param[in] dev device descriptor of APDS99XX sensor
* @param[out] prx proximity sensing data as count value
*
* @retval APDS99XX_OK on success
* @retval APDS99XX_ERROR_* a negative error code on error,
* see #apds99xx_error_codes_t
*/
int apds99xx_read_prx_raw(const apds99xx_t *dev, uint16_t *prx);
/**
* @brief 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.
*
* @param[in] dev device descriptor of APDS99XX sensor
*
* @retval APDS99XX_OK on success
* @retval APDS99XX_ERROR_* a negative error code on error,
* see #apds99xx_error_codes_t
*/
int apds99xx_power_down(const apds99xx_t *dev);
/**
* @brief Power up the sensor
*
* The sensor is woken up from sleep mode.
*
* @param[in] dev device descriptor of APDS99XX sensor
*
* @retval APDS99XX_OK on success
* @retval APDS99XX_ERROR_* a negative error code on error,
* see #apds99xx_error_codes_t
*/
int apds99xx_power_up(const apds99xx_t *dev);
#if MODULE_APDS99XX_FULL || DOXYGEN
/**
* @brief 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 @p 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.
*
* @param[in] dev device descriptor of APDS99XX sensor
* @param[in] cfg interrupt configuration, see #apds99xx_int_config_t
* @param[in] isr ISR called for all types of interrupts
* @param[in] isr_arg ISR argument, can be NULL
*
* @retval APDS99XX_OK on success
* @retval APDS99XX_ERROR_* negative error code on error,
* see #apds99xx_error_codes_t
*/
int apds99xx_int_config(apds99xx_t *dev, apds99xx_int_config_t* cfg,
apds99xx_isr_t isr, void *isr_arg);
/**
* @brief 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.
*
* @param[in] dev device descriptor of APDS99XX sensor
* @param[out] src interrupt source, see #apds99xx_int_source_t
*
* @retval APDS99XX_OK on success
* @retval APDS99XX_ERROR_* negative error code on error,
* see #apds99xx_error_codes_t
*/
int apds99xx_int_source(apds99xx_t *dev, apds99xx_int_source_t* src);
#endif /* MODULE_APDS99XX_FULL */
#ifdef __cplusplus
}
#endif
#endif /* APDS99XX_H */
/** @} */
View Git Blame Copy Permalink