esp-idf-lib/components/apds9930/apds9930.h

/**
 * @file    APDS-9930.h
 * @brief   Library for the SparkFun APDS-9930 breakout board
 * @author  Shawn Hymel (SparkFun Electronics)
 *
 * @copyright	This code is public domain but you buy me a beer if you use
 * this and we meet someday (Beerware license).
 *
 * This library interfaces the Avago APDS-9930 to ESP-IDF over I2C.
 * Ported from Arduino library by Davide Depau.
 *
 * MIT Licensed as described in the file LICENSE
 */

#ifndef __APDS9930_H__
#define __APDS9930_H__

#include <stdint.h>
#include <stdbool.h>
#include <esp_err.h>
#include <i2cdev.h>

#ifdef __cplusplus
extern "C" {
#endif

#define APDS9930_ID_1			0x12
#define APDS9930_ID_2			0x39
#define APDS9930_ID_3			0x30	// My chip gives this


/* LED Drive values */
#define APDS9930_LED_DRIVE_100MA	0
#define APDS9930_LED_DRIVE_50MA		1
#define APDS9930_LED_DRIVE_25MA		2
#define APDS9930_LED_DRIVE_12_5MA	3

/* Proximity Gain (PGAIN) values */
#define APDS9930_PGAIN_1X		0
#define APDS9930_PGAIN_2X		1
#define APDS9930_PGAIN_4X		2
#define APDS9930_PGAIN_8X		3

/* ALS Gain (AGAIN) values */
#define APDS9930_AGAIN_1X		0
#define APDS9930_AGAIN_8X		1
#define APDS9930_AGAIN_16X		2
#define APDS9930_AGAIN_120X		3

/**
 * Device descriptor
 */
typedef struct {
    i2c_dev_t	i2c_dev;
    uint8_t	id;
} apds9930_t;


/**
 * @brief Initialize device descriptor
 *
 * Default SCL frequency is 100kHz
 *
 * @param dev Pointer to I2C device descriptor
 * @param port I2C port number
 * @param addr I2C address (0x39 for APDS9930)
 * @param sda_gpio SDA GPIO
 * @param scl_gpio SCL GPIO
 * @return `ESP_OK` on success
 */
esp_err_t apds9930_init_desc(apds9930_t *dev, uint8_t addr, i2c_port_t port, gpio_num_t sda_gpio, gpio_num_t scl_gpio);

/**
 * @brief Free device descriptor
 * @param dev Pointer to I2C device descriptor
 * @return `ESP_OK` on success
 */
esp_err_t apds9930_free_desc(apds9930_t *dev);

/**
 * @brief Setup APDS9930 and initializes registers to defaults
 * @param dev Pointer to I2C device descriptor
 * @return `ESP_OK` on success
 */
esp_err_t apds9930_init(apds9930_t *dev);

/**
 * @brief Reads and returns the contents of the ENABLE register
 * @param dev Pointer to I2C device descriptor
 * @return Contents of the ENABLE register. 0xFF if error.
 */
uint8_t apds9930_getMode(apds9930_t *dev);

/**
 * @brief Enables or disables a feature in the APDS-9930
 * @param dev Pointer to I2C device descriptor
 * @param mode which feature to enable
 * @param enable ON (1) or OFF (0)
 * @return `ESP_OK` on success
 */
esp_err_t apds9930_setMode(apds9930_t *dev, uint8_t mode, uint8_t enable);

/**
 * @brief Turn the APDS-9930 on
 * @param dev Pointer to I2C device descriptor
 * @return ESP_OK if operation successful.
 */
esp_err_t apds9930_enablePower(apds9930_t *dev);

/**
 * @brief Turn the APDS-9930 off
 * @param dev Pointer to I2C device descriptor
 * @return ESP_OK if operation successful. False otherwise.
 */
esp_err_t apds9930_disablePower(apds9930_t *dev);

/**
 * @brief Starts the light (Ambient/IR) sensor on the APDS-9930
 * @param dev Pointer to I2C device descriptor
 * @param interrupts true to enable hardware interrupt on high or low light
 * @return ESP_OK if sensor enabled correctly.
 */
esp_err_t apds9930_enableLightSensor(apds9930_t *dev, bool interrupts);

/**
 * @brief Ends the light sensor on the APDS-9930
 * @param dev Pointer to I2C device descriptor
 * @return ESP_OK if sensor disabled correctly.
 */
esp_err_t apds9930_disableLightSensor(apds9930_t *dev);

/**
 * @brief Starts the proximity sensor on the APDS-9930
 * @param dev Pointer to I2C device descriptor
 * @param interrupts true to enable hardware external interrupt on proximity
 * @return ESP_OK if sensor enabled correctly.
 */
esp_err_t apds9930_enableProximitySensor(apds9930_t *dev, bool interrupts);

/**
 * @brief Ends the proximity sensor on the APDS-9930
 * @param dev Pointer to I2C device descriptor
 * @return ESP_OK if sensor disabled correctly.
 */
esp_err_t apds9930_disableProximitySensor(apds9930_t *dev);


/**
 * @brief Returns LED drive strength for proximity and ALS
 * @param dev Pointer to I2C device descriptor
 *
 * Value    LED Current
 *   0        100 mA
 *   1         50 mA
 *   2         25 mA
 *   3         12.5 mA
 *
 * @return the value of the LED drive strength. 0xFF on failure.
 */
uint8_t APDS9930_getLEDDrive(apds9930_t *dev);

/**
 * @brief Sets the LED drive strength for proximity and ALS
 * @param dev Pointer to I2C device descriptor
 *
 * Value    LED Current
 *   0        100 mA
 *   1         50 mA
 *   2         25 mA
 *   3         12.5 mA
 *
 * @param drive the value (0-3) for the LED drive strength
 * @return ESP_OK if operation successful.
 */
esp_err_t apds9930_setLEDDrive(apds9930_t *dev, uint8_t drive);

/**
 * @brief Gets the receiver ALS gain level for the ambient light sensor.
 *        When set the gain is extra scaled down with 0.16.
 * @param dev Pointer to I2C device descriptor
 * @return 1 if extra ALS gain level is enabled, 0 if not. 0xFF on error.
 */
uint8_t apds9930_getAmbientGainLevel(apds9930_t *dev);

/**
 * @brief Sets the receiver ALS gain level for the ambient light sensor
 * When asserted, the 1x and 8x gain modes are scaled by 0.16.
 * Otherwise AGAIN is scaled by 1. Do not use with AGAIN greater then 8x.
 * @param dev Pointer to I2C device descriptor
 * @param enable the value (0-1) for the gain level.
 * @return ESP_OK if operation successful.
 */
esp_err_t apds9930_setAmbientGainLevel(apds9930_t *dev, uint8_t enable);

/**
 * @brief Returns receiver gain for the ambient light sensor (ALS)
 * @param dev Pointer to I2C device descriptor
 *
 * Value    Gain
 *   0        1x
 *   1        4x
 *   2       16x
 *   3      120x
 *
 * @return the value of the ALS gain. 0xFF on failure.
 */
uint8_t apds9930_getAmbientLightGain(apds9930_t *dev);

/**
 * @brief Sets the receiver gain for the ambient light sensor (ALS)
 * @param dev Pointer to I2C device descriptor
 *
 * Value    Gain
 *   0        1x
 *   1        4x
 *   2       16x
 *   3      120x
 *
 * @param drive the value (0-3) for the gain
 * @return ESP_OK if operation successful. False otherwise.
 */
esp_err_t apds9930_setAmbientLightGain(apds9930_t *dev, uint8_t gain);

/**
 * @brief Returns receiver gain for proximity detection
 * @param dev Pointer to I2C device descriptor
 *
 * Value    Gain
 *   0       1x
 *   1       2x
 *   2       4x
 *   3       8x
 *
 * @return the value of the proximity gain. 0xFF on failure.
 */
uint8_t apds9930_getProximityGain(apds9930_t *dev);

/**
 * @brief Sets the receiver gain for proximity detection
 * @param dev Pointer to I2C device descriptor
 *
 * Value    Gain
 *   0       1x
 *   1       2x
 *   2       4x
 *   3       8x
 *
 * @param drive the value (0-3) for the gain
 * @return True if operation successful. False otherwise.
 */
esp_err_t apds9930_setProximityGain(apds9930_t *dev, uint8_t gain);

/**
 * @brief Selects the proximity diode
 * @param dev Pointer to I2C device descriptor
 *
 * Value    Diode selection
 *   0       Reserved
 *   1       Reserved
 *   2       Use Ch1 diode
 *   3       Reserved
 *
 * @param[in] drive the value (0-3) for the diode
 * @return True if operation successful. False otherwise.
 */
esp_err_t apds9930_setProximityDiode(apds9930_t *dev, uint8_t drive);

/**
 * @brief Returns the proximity diode
 * @param dev Pointer to I2C device descriptor
 *
 * Value    Diode selection
 *   0       Reserved
 *   1       Reserved
 *   2       Use Ch1 diode
 *   3       Reserved
 *
 * @return the selected diode. 0xFF on failure.
 */
uint8_t apds9930_getProximityDiode(apds9930_t *dev);

/**
 * @brief Gets the low threshold for ambient light interrupts
 * @param dev Pointer to I2C device descriptor
 * @param threshold current low threshold stored on the APDS-9930
 * @return ESP_OK if operation successful.
 */
esp_err_t apds9930_getLightIntLowThreshold(apds9930_t *dev, uint16_t *threshold);

/**
 * @brief Sets the low threshold for ambient light interrupts
 * @param dev Pointer to I2C device descriptor
 * @param threshold low threshold value for interrupt to trigger
 * @return ESP_OK if operation successful.
 */
esp_err_t apds9930_setLightIntLowThreshold(apds9930_t *dev, uint16_t threshold);

/**
 * @brief Gets the high threshold for ambient light interrupts
 * @param dev Pointer to I2C device descriptor
 * @param threshold current low threshold stored on the APDS-9930
 * @return ESP_OK if operation successful.
 */
esp_err_t apds9930_getLightIntHighThreshold(apds9930_t *dev, uint16_t *threshold);

/**
 * @brief Sets the high threshold for ambient light interrupts
 * @param dev Pointer to I2C device descriptor
 * @param threshold low threshold value for interrupt to trigger
 * @return ESP_OK if operation successful.
 */
esp_err_t apds9930_setLightIntHighThreshold(apds9930_t *dev, uint16_t threshold);

/**
 * @brief Gets if ambient light interrupts are enabled or not
 * @param dev Pointer to I2C device descriptor
 * @return 1 if interrupts are enabled, 0 if not. 0xFF on error.
 */
uint8_t apds9930_getAmbientLightIntEnable(apds9930_t *dev);

/**
 * @brief Turns ambient light interrupts on or off
 * @param dev Pointer to I2C device descriptor
 * @param[in] enable 1 to enable interrupts, 0 to turn them off
 * @return ESP_OK if operation successful.
 */
esp_err_t apds9930_setAmbientLightIntEnable(apds9930_t *dev, uint8_t enable);

/**
 * @brief Gets if proximity interrupts are enabled or not
 * @param dev Pointer to I2C device descriptor
 * @return 1 if interrupts are enabled, 0 if not. 0xFF on error.
 */
uint8_t apds9930_getProximityIntEnable(apds9930_t *dev);

/**
 * @brief Turns proximity interrupts on or off
 * @param dev Pointer to I2C device descriptor
 * @param[in] enable 1 to enable interrupts, 0 to turn them off
 * @return ESP_OK if operation successful.
 */
esp_err_t apds9930_setProximityIntEnable(apds9930_t *dev, uint8_t enable);

/**
 * @brief Clears the ambient light interrupt
 * @param dev Pointer to I2C device descriptor
 * @return ESP_OK if operation completed successfully.
 */
esp_err_t apds9930_clearAmbientLightInt(apds9930_t *dev);

/**
 * @brief Clears the proximity interrupt
 * @param dev Pointer to I2C device descriptor
 * @return ESP_OK if operation completed successfully.
 */
esp_err_t apds9930_clearProximityInt(apds9930_t *dev);

/**
 * @brief Clears all interrupts
 * @param dev Pointer to I2C device descriptor
 * @return ESP_OK if operation completed successfully.
 */
esp_err_t apds9930_clearAllInts(apds9930_t *dev);

/**
 * @brief Reads the proximity level as an 16-bit value
 * @param dev Pointer to I2C device descriptor
 * @param val value of the proximity sensor.
 * @return ESP_OK if operation successful.
 */
esp_err_t apds9930_readProximity(apds9930_t *dev, uint16_t *val);

/**
 * @brief Reads the ambient (clear) light level as a float value
 * @param dev Pointer to I2C device descriptor
 * @param val value of the light sensor.
 * @return ESP_OK if operation successful.
 */
esp_err_t apds9930_readAmbientLightLux(apds9930_t *dev, float *val);

/**
 * @brief Reads the ambient (clear) light level as a unsigned long value
 * @param dev Pointer to I2C device descriptor
 * @param val value of the light sensor.
 * @return ESP_OK if operation successful.
 */
esp_err_t apds9930_readulAmbientLightLux(apds9930_t *dev, unsigned long *val);

float apds9930_floatAmbientToLux(apds9930_t *dev, uint16_t Ch0, uint16_t Ch1);

unsigned long apds9930_ulongAmbientToLux(apds9930_t *dev, uint16_t Ch0, uint16_t Ch1);

/**
 * @brief Read the channel 0 light value from the APDS-9930
 * @param dev Pointer to I2C device descriptor
 * @param val The value read.
 * @return ESP_OK if read is correctly.
 */
esp_err_t apds9930_readCh0Light(apds9930_t *dev, uint16_t *val);

/**
 * @brief Read the channel 1 light value from the APDS-9930
 * @param dev Pointer to I2C device descriptor
 * @param val The value read.
 * @return ESP_OK if read is correctly.
 */
esp_err_t apds9930_readCh1Light(apds9930_t *dev, uint16_t *val);

/**
 * @brief Returns the lower threshold for proximity detection
 * @param dev Pointer to I2C device descriptor
 * @return lower threshold
 */
uint16_t apds9930_getProximityIntLowThreshold(apds9930_t *dev);

/**
 * @brief Sets the lower threshold for proximity detection
 * @param dev Pointer to I2C device descriptor
 * @param threshold the lower proximity threshold
 * @return ESP_OK if operation successful.
 */
esp_err_t apds9930_setProximityIntLowThreshold(apds9930_t *dev, uint16_t threshold);

/**
 * @brief Returns the high threshold for proximity detection
 * @param dev Pointer to I2C device descriptor
 * @return high threshold
 */
uint16_t apds9930_getProximityIntHighThreshold(apds9930_t *dev);

/**
 * @brief Sets the high threshold for proximity detection
 * @param dev Pointer to I2C device descriptor
 * @param threshold the high proximity threshold
 * @return ESP_OK if operation successful.
 */
esp_err_t apds9930_setProximityIntHighThreshold(apds9930_t *dev, uint16_t threshold);


#ifdef __cplusplus
}
#endif

#endif