SparkFun_APDS9960.h

00001 /**
00002  * @file    SparkFun_APDS-9960.h
00003  * @brief   Library for the SparkFun APDS-9960 breakout board
00004  * @author  Shawn Hymel (SparkFun Electronics)
00005  *
00006  * @copyright   This code is public domain but you buy me a beer if you use
00007  * this and we meet someday (Beerware license).
00008  *
00009  * Adapted for mbed by Nenad Milosevic (synvox.ch) in April 2015.
00010  *
00011  * This library interfaces the Avago APDS-9960 to mbed over I2C. The library
00012  * relies on the mbed I2C-library. To use the library, instantiate an
00013  * APDS9960 object, call init(), and call the appropriate functions.
00014  */
00015  
00016 #ifndef SparkFun_APDS9960_H
00017 #define SparkFun_APDS9960_H
00018 
00019 #include "mbed.h"
00020 
00021 /* APDS-9960 I2C address */
00022 #define APDS9960_I2C_ADDR       0x39
00023 #define APDS9960_I2C_ADDR8      (APDS9960_I2C_ADDR << 1)
00024 
00025 /* Gesture parameters */
00026 #define GESTURE_THRESHOLD_OUT   10
00027 #define GESTURE_SENSITIVITY_1   50
00028 #define GESTURE_SENSITIVITY_2   20
00029 
00030 /* Error code for returned values */
00031 #define ERROR                   0xFF
00032 
00033 /* Acceptable device IDs */
00034 #define APDS9960_ID_1           0xAB
00035 #define APDS9960_ID_2           0x9C 
00036 
00037 /* Misc parameters */
00038 #define FIFO_PAUSE_TIME         30      // Wait period (ms) between FIFO reads
00039 
00040 /* APDS-9960 register addresses */
00041 #define APDS9960_ENABLE         0x80
00042 #define APDS9960_ATIME          0x81
00043 #define APDS9960_WTIME          0x83
00044 #define APDS9960_AILTL          0x84
00045 #define APDS9960_AILTH          0x85
00046 #define APDS9960_AIHTL          0x86
00047 #define APDS9960_AIHTH          0x87
00048 #define APDS9960_PILT           0x89
00049 #define APDS9960_PIHT           0x8B
00050 #define APDS9960_PERS           0x8C
00051 #define APDS9960_CONFIG1        0x8D
00052 #define APDS9960_PPULSE         0x8E
00053 #define APDS9960_CONTROL        0x8F
00054 #define APDS9960_CONFIG2        0x90
00055 #define APDS9960_ID             0x92
00056 #define APDS9960_STATUS         0x93
00057 #define APDS9960_CDATAL         0x94
00058 #define APDS9960_CDATAH         0x95
00059 #define APDS9960_RDATAL         0x96
00060 #define APDS9960_RDATAH         0x97
00061 #define APDS9960_GDATAL         0x98
00062 #define APDS9960_GDATAH         0x99
00063 #define APDS9960_BDATAL         0x9A
00064 #define APDS9960_BDATAH         0x9B
00065 #define APDS9960_PDATA          0x9C
00066 #define APDS9960_POFFSET_UR     0x9D
00067 #define APDS9960_POFFSET_DL     0x9E
00068 #define APDS9960_CONFIG3        0x9F
00069 #define APDS9960_GPENTH         0xA0
00070 #define APDS9960_GEXTH          0xA1
00071 #define APDS9960_GCONF1         0xA2
00072 #define APDS9960_GCONF2         0xA3
00073 #define APDS9960_GOFFSET_U      0xA4
00074 #define APDS9960_GOFFSET_D      0xA5
00075 #define APDS9960_GOFFSET_L      0xA7
00076 #define APDS9960_GOFFSET_R      0xA9
00077 #define APDS9960_GPULSE         0xA6
00078 #define APDS9960_GCONF3         0xAA
00079 #define APDS9960_GCONF4         0xAB
00080 #define APDS9960_GFLVL          0xAE
00081 #define APDS9960_GSTATUS        0xAF
00082 #define APDS9960_IFORCE         0xE4
00083 #define APDS9960_PICLEAR        0xE5
00084 #define APDS9960_CICLEAR        0xE6
00085 #define APDS9960_AICLEAR        0xE7
00086 #define APDS9960_GFIFO_U        0xFC
00087 #define APDS9960_GFIFO_D        0xFD
00088 #define APDS9960_GFIFO_L        0xFE
00089 #define APDS9960_GFIFO_R        0xFF
00090 
00091 /* Bit fields */
00092 #define APDS9960_PON            0x01 //0b00000001
00093 #define APDS9960_AEN            0x02 //0b00000010
00094 #define APDS9960_PEN            0x04 //0b00000100
00095 #define APDS9960_WEN            0x08 //0b00001000
00096 #define APSD9960_AIEN           0x10 //0b00010000
00097 #define APDS9960_PIEN           0x20 //0b00100000
00098 #define APDS9960_GEN            0x40 //0b01000000
00099 #define APDS9960_GVALID         0x01 //0b00000001
00100 
00101 /* On/Off definitions */
00102 #define OFF                     0
00103 #define ON                      1
00104 
00105 /* Acceptable parameters for setMode */
00106 #define POWER                   0
00107 #define AMBIENT_LIGHT           1
00108 #define PROXIMITY               2
00109 #define WAIT                    3
00110 #define AMBIENT_LIGHT_INT       4
00111 #define PROXIMITY_INT           5
00112 #define GESTURE                 6
00113 #define ALL_MODES               7
00114 
00115 /* LED Drive values */
00116 #define LED_DRIVE_100MA         0
00117 #define LED_DRIVE_50MA          1
00118 #define LED_DRIVE_25MA          2
00119 #define LED_DRIVE_12_5MA        3
00120 
00121 /* Proximity Gain (PGAIN) values */
00122 #define PGAIN_1X                0
00123 #define PGAIN_2X                1
00124 #define PGAIN_4X                2
00125 #define PGAIN_8X                3
00126 
00127 /* ALS Gain (AGAIN) values */
00128 #define AGAIN_1X                0
00129 #define AGAIN_4X                1
00130 #define AGAIN_16X               2
00131 #define AGAIN_64X               3
00132 
00133 /* Gesture Gain (GGAIN) values */
00134 #define GGAIN_1X                0
00135 #define GGAIN_2X                1
00136 #define GGAIN_4X                2
00137 #define GGAIN_8X                3
00138 
00139 /* LED Boost values */
00140 #define LED_BOOST_100           0
00141 #define LED_BOOST_150           1
00142 #define LED_BOOST_200           2
00143 #define LED_BOOST_300           3    
00144 
00145 /* Gesture wait time values */
00146 #define GWTIME_0MS              0
00147 #define GWTIME_2_8MS            1
00148 #define GWTIME_5_6MS            2
00149 #define GWTIME_8_4MS            3
00150 #define GWTIME_14_0MS           4
00151 #define GWTIME_22_4MS           5
00152 #define GWTIME_30_8MS           6
00153 #define GWTIME_39_2MS           7
00154 
00155 /* Default values */
00156 #define DEFAULT_ATIME           219     // 103ms
00157 #define DEFAULT_WTIME           246     // 27ms
00158 #define DEFAULT_PROX_PPULSE     0x87    // 16us, 8 pulses
00159 #define DEFAULT_GESTURE_PPULSE  0x89    // 16us, 10 pulses
00160 #define DEFAULT_POFFSET_UR      0       // 0 offset
00161 #define DEFAULT_POFFSET_DL      0       // 0 offset      
00162 #define DEFAULT_CONFIG1         0x60    // No 12x wait (WTIME) factor
00163 #define DEFAULT_LDRIVE          LED_DRIVE_100MA
00164 #define DEFAULT_PGAIN           PGAIN_4X
00165 #define DEFAULT_AGAIN           AGAIN_4X
00166 #define DEFAULT_PILT            0       // Low proximity threshold
00167 #define DEFAULT_PIHT            50      // High proximity threshold
00168 #define DEFAULT_AILT            0xFFFF  // Force interrupt for calibration
00169 #define DEFAULT_AIHT            0
00170 #define DEFAULT_PERS            0x11    // 2 consecutive prox or ALS for int.
00171 #define DEFAULT_CONFIG2         0x01    // No saturation interrupts or LED boost  
00172 #define DEFAULT_CONFIG3         0       // Enable all photodiodes, no SAI
00173 #define DEFAULT_GPENTH          40      // Threshold for entering gesture mode
00174 #define DEFAULT_GEXTH           30      // Threshold for exiting gesture mode    
00175 #define DEFAULT_GCONF1          0x40    // 4 gesture events for int., 1 for exit
00176 #define DEFAULT_GGAIN           GGAIN_4X
00177 #define DEFAULT_GLDRIVE         LED_DRIVE_100MA
00178 #define DEFAULT_GWTIME          GWTIME_2_8MS
00179 #define DEFAULT_GOFFSET         0       // No offset scaling for gesture mode
00180 #define DEFAULT_GPULSE          0xC9    // 32us, 10 pulses
00181 #define DEFAULT_GCONF3          0       // All photodiodes active during gesture
00182 #define DEFAULT_GIEN            0       // Disable gesture interrupts
00183 
00184 /* Direction definitions */
00185 enum {
00186   DIR_NONE,
00187   DIR_LEFT,
00188   DIR_RIGHT,
00189   DIR_UP,
00190   DIR_DOWN,
00191   DIR_NEAR,
00192   DIR_FAR,
00193   DIR_ALL
00194 };
00195 
00196 /* State definitions */
00197 enum {
00198   NA_STATE,
00199   NEAR_STATE,
00200   FAR_STATE,
00201   ALL_STATE
00202 };
00203 
00204 /* Container for gesture data */
00205 typedef struct gesture_data_type {
00206     uint8_t u_data[32];
00207     uint8_t d_data[32];
00208     uint8_t l_data[32];
00209     uint8_t r_data[32];
00210     uint8_t index;
00211     uint8_t total_gestures;
00212     uint8_t in_threshold;
00213     uint8_t out_threshold;
00214 } gesture_data_type;
00215 
00216 /* APDS9960 Class */
00217 class SparkFun_APDS9960 {
00218 public:
00219 
00220     /* Initialization methods */
00221     SparkFun_APDS9960(I2C &i2c);
00222     ~SparkFun_APDS9960();
00223     bool init(int apds_i2c_freq);
00224     uint8_t getMode();
00225     bool setMode(uint8_t mode, uint8_t enable);
00226     
00227     /* Turn the APDS-9960 on and off */
00228     bool enablePower();
00229     bool disablePower();
00230     
00231     /* Enable or disable specific sensors */
00232     bool enableLightSensor(bool interrupts = false);
00233     bool disableLightSensor();
00234     bool enableProximitySensor(bool interrupts = false);
00235     bool disableProximitySensor();
00236     bool enableGestureSensor(bool interrupts = true);
00237     bool disableGestureSensor();
00238     
00239     /* LED drive strength control */
00240     uint8_t getLEDDrive();
00241     bool setLEDDrive(uint8_t drive);
00242     uint8_t getGestureLEDDrive();
00243     bool setGestureLEDDrive(uint8_t drive);
00244     
00245     /* Gain control */
00246     uint8_t getAmbientLightGain();
00247     bool setAmbientLightGain(uint8_t gain);
00248     uint8_t getProximityGain();
00249     bool setProximityGain(uint8_t gain);
00250     uint8_t getGestureGain();
00251     bool setGestureGain(uint8_t gain);
00252     
00253     /* Get and set light interrupt thresholds */
00254     bool getLightIntLowThreshold(uint16_t &threshold);
00255     bool setLightIntLowThreshold(uint16_t threshold);
00256     bool getLightIntHighThreshold(uint16_t &threshold);
00257     bool setLightIntHighThreshold(uint16_t threshold);
00258     
00259     /* Get and set proximity interrupt thresholds */
00260     bool getProximityIntLowThreshold(uint8_t &threshold);
00261     bool setProximityIntLowThreshold(uint8_t threshold);
00262     bool getProximityIntHighThreshold(uint8_t &threshold);
00263     bool setProximityIntHighThreshold(uint8_t threshold);
00264     
00265     /* Get and set interrupt enables */
00266     uint8_t getAmbientLightIntEnable();
00267     bool setAmbientLightIntEnable(uint8_t enable);
00268     uint8_t getProximityIntEnable();
00269     bool setProximityIntEnable(uint8_t enable);
00270     uint8_t getGestureIntEnable();
00271     bool setGestureIntEnable(uint8_t enable);
00272     
00273     /* Clear interrupts */
00274     bool clearAmbientLightInt();
00275     bool clearProximityInt();
00276     
00277     /* Ambient light methods */
00278     bool readAmbientLight(uint16_t &val);
00279     bool readRedLight(uint16_t &val);
00280     bool readGreenLight(uint16_t &val);
00281     bool readBlueLight(uint16_t &val);
00282     
00283     /* Proximity methods */
00284     bool readProximity(uint8_t &val);
00285     
00286     /* Gesture methods */
00287     bool isGestureAvailable();
00288     int readGesture();
00289     
00290 private:
00291 
00292     /* Gesture processing */
00293     void resetGestureParameters();
00294     bool processGestureData();
00295     bool decodeGesture();
00296 
00297     /* Proximity Interrupt Threshold */
00298     uint8_t getProxIntLowThresh();
00299     bool setProxIntLowThresh(uint8_t threshold);
00300     uint8_t getProxIntHighThresh();
00301     bool setProxIntHighThresh(uint8_t threshold);
00302     
00303     /* LED Boost Control */
00304     uint8_t getLEDBoost();
00305     bool setLEDBoost(uint8_t boost);
00306     
00307     /* Proximity photodiode select */
00308     uint8_t getProxGainCompEnable();
00309     bool setProxGainCompEnable(uint8_t enable);
00310     uint8_t getProxPhotoMask();
00311     bool setProxPhotoMask(uint8_t mask);
00312     
00313     /* Gesture threshold control */
00314     uint8_t getGestureEnterThresh();
00315     bool setGestureEnterThresh(uint8_t threshold);
00316     uint8_t getGestureExitThresh();
00317     bool setGestureExitThresh(uint8_t threshold);
00318     
00319     /* Gesture LED, gain, and time control */
00320     uint8_t getGestureWaitTime();
00321     bool setGestureWaitTime(uint8_t time);
00322     
00323     /* Gesture mode */
00324     uint8_t getGestureMode();
00325     bool setGestureMode(uint8_t mode);
00326 
00327     /* Raw I2C Commands */
00328     bool wireWriteByte(uint8_t val);
00329     bool wireWriteDataByte(uint8_t reg, uint8_t val);
00330     //bool wireWriteDataBlock(uint8_t reg, uint8_t *val, unsigned int len);
00331     bool wireReadDataByte(uint8_t reg, uint8_t &val);
00332     int wireReadDataBlock(uint8_t reg, uint8_t *val, unsigned int len);
00333 
00334     /* Members */
00335     I2C &apds_i2c;
00336     gesture_data_type gesture_data_;
00337     int gesture_ud_delta_;
00338     int gesture_lr_delta_;
00339     int gesture_ud_count_;
00340     int gesture_lr_count_;
00341     int gesture_near_count_;
00342     int gesture_far_count_;
00343     int gesture_state_;
00344     int gesture_motion_;
00345 };
00346 
00347 #endif