APDS9960.h 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561
  1. /**************************************************************************/
  2. /*!
  3. @file APDS9960.h
  4. @author Ladyada, Dean Miller (Adafruit Industries)
  5. @section LICENSE
  6. Software License Agreement (BSD License)
  7. Copyright (c) 2017, Adafruit Industries
  8. All rights reserved.
  9. Redistribution and use in source and binary forms, with or without
  10. modification, are permitted provided that the following conditions are met:
  11. 1. Redistributions of source code must retain the above copyright
  12. notice, this list of conditions and the following disclaimer.
  13. 2. Redistributions in binary form must reproduce the above copyright
  14. notice, this list of conditions and the following disclaimer in the
  15. documentation and/or other materials provided with the distribution.
  16. 3. Neither the name of the copyright holders nor the
  17. names of its contributors may be used to endorse or promote products
  18. derived from this software without specific prior written permission.
  19. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ''AS IS'' AND ANY
  20. EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  21. WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  22. DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY
  23. DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  24. (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  25. LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  26. ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27. (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  28. SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29. */
  30. /**************************************************************************/
  31. #ifndef _APDS9960_H_
  32. #define _APDS9960_H_
  33. #include <Arduino.h>
  34. #include <Wire.h>
  35. #define I2CDEBUG
  36. /*=========================================================================
  37. I2C ADDRESS/BITS
  38. -----------------------------------------------------------------------*/
  39. #define APDS9960_ADDRESS (0x39)
  40. /*=========================================================================*/
  41. /*=========================================================================
  42. REGISTERS
  43. -----------------------------------------------------------------------*/
  44. enum
  45. {
  46. APDS9960_RAM = 0x00,
  47. APDS9960_ENABLE = 0x80,
  48. APDS9960_ATIME = 0x81,
  49. APDS9960_WTIME = 0x83,
  50. APDS9960_AILTIL = 0x84,
  51. APDS9960_AILTH = 0x85,
  52. APDS9960_AIHTL = 0x86,
  53. APDS9960_AIHTH = 0x87,
  54. APDS9960_PILT = 0x89,
  55. APDS9960_PIHT = 0x8B,
  56. APDS9960_PERS = 0x8C,
  57. APDS9960_CONFIG1 = 0x8D,
  58. APDS9960_PPULSE = 0x8E,
  59. APDS9960_CONTROL = 0x8F,
  60. APDS9960_CONFIG2 = 0x90,
  61. APDS9960_ID = 0x92,
  62. APDS9960_STATUS = 0x93,
  63. APDS9960_CDATAL = 0x94,
  64. APDS9960_CDATAH = 0x95,
  65. APDS9960_RDATAL = 0x96,
  66. APDS9960_RDATAH = 0x97,
  67. APDS9960_GDATAL = 0x98,
  68. APDS9960_GDATAH = 0x99,
  69. APDS9960_BDATAL = 0x9A,
  70. APDS9960_BDATAH = 0x9B,
  71. APDS9960_PDATA = 0x9C,
  72. APDS9960_POFFSET_UR = 0x9D,
  73. APDS9960_POFFSET_DL = 0x9E,
  74. APDS9960_CONFIG3 = 0x9F,
  75. APDS9960_GPENTH = 0xA0,
  76. APDS9960_GEXTH = 0xA1,
  77. APDS9960_GCONF1 = 0xA2,
  78. APDS9960_GCONF2 = 0xA3,
  79. APDS9960_GOFFSET_U = 0xA4,
  80. APDS9960_GOFFSET_D = 0xA5,
  81. APDS9960_GOFFSET_L = 0xA7,
  82. APDS9960_GOFFSET_R = 0xA9,
  83. APDS9960_GPULSE = 0xA6,
  84. APDS9960_GCONF3 = 0xAA,
  85. APDS9960_GCONF4 = 0xAB,
  86. APDS9960_GFLVL = 0xAE,
  87. APDS9960_GSTATUS = 0xAF,
  88. APDS9960_IFORCE = 0xE4,
  89. APDS9960_PICLEAR = 0xE5,
  90. APDS9960_CICLEAR = 0xE6,
  91. APDS9960_AICLEAR = 0xE7,
  92. APDS9960_GFIFO_U = 0xFC,
  93. APDS9960_GFIFO_D = 0xFD,
  94. APDS9960_GFIFO_L = 0xFE,
  95. APDS9960_GFIFO_R = 0xFF,
  96. };
  97. /*=========================================================================*/
  98. typedef enum
  99. {
  100. APDS9960_AGAIN_1X = 0x00, /**< No gain */
  101. APDS9960_AGAIN_4X = 0x01, /**< 2x gain */
  102. APDS9960_AGAIN_16X = 0x02, /**< 16x gain */
  103. APDS9960_AGAIN_64X = 0x03 /**< 64x gain */
  104. }
  105. apds9960AGain_t;
  106. typedef enum
  107. {
  108. APDS9960_PGAIN_1X = 0x00, /**< 1x gain */
  109. APDS9960_PGAIN_2X = 0x04, /**< 2x gain */
  110. APDS9960_PGAIN_4X = 0x08, /**< 4x gain */
  111. APDS9960_PGAIN_8X = 0x0C /**< 8x gain */
  112. }
  113. apds9960PGain_t;
  114. typedef enum
  115. {
  116. APDS9960_PPULSELEN_4US = 0x00, /**< 4uS */
  117. APDS9960_PPULSELEN_8US = 0x40, /**< 8uS */
  118. APDS9960_PPULSELEN_16US = 0x80, /**< 16uS */
  119. APDS9960_PPULSELEN_32US = 0xC0 /**< 32uS */
  120. }
  121. apds9960PPulseLen_t;
  122. typedef enum
  123. {
  124. APDS9960_LEDDRIVE_100MA = 0x00, /**< 100mA */
  125. APDS9960_LEDDRIVE_50MA = 0x40, /**< 50mA */
  126. APDS9960_LEDDRIVE_25MA = 0x80, /**< 25mA */
  127. APDS9960_LEDDRIVE_12MA = 0xC0 /**< 12.5mA */
  128. }
  129. apds9960LedDrive_t;
  130. typedef enum
  131. {
  132. APDS9960_LEDBOOST_100PCNT = 0x00, /**< 100% */
  133. APDS9960_LEDBOOST_150PCNT = 0x10, /**< 150% */
  134. APDS9960_LEDBOOST_200PCNT = 0x20, /**< 200% */
  135. APDS9960_LEDBOOST_300PCNT = 0x30 /**< 300% */
  136. }
  137. apds9960LedBoost_t;
  138. enum
  139. {
  140. APDS9960_DIMENSIONS_ALL = 0x00,
  141. APDS9960_DIMENSIONS_UP_DOWM = 0x01,
  142. APGS9960_DIMENSIONS_LEFT_RIGHT = 0x02,
  143. };
  144. enum
  145. {
  146. APDS9960_GFIFO_1 = 0x00,
  147. APDS9960_GFIFO_4 = 0x01,
  148. APDS9960_GFIFO_8 = 0x02,
  149. APDS9960_GFIFO_16 = 0x03,
  150. };
  151. enum
  152. {
  153. APDS9960_GGAIN_1 = 0x00,
  154. APDS9960_GGAIN_2 = 0x01,
  155. APDS9960_GGAIN_4 = 0x02,
  156. APDS9960_GGAIN_8 = 0x03,
  157. };
  158. enum
  159. {
  160. APDS9960_GPULSE_4US = 0x00,
  161. APDS9960_GPULSE_8US = 0x01,
  162. APDS9960_GPULSE_16US = 0x02,
  163. APDS9960_GPULSE_32US = 0x03,
  164. };
  165. #define APDS9960_TIME_MULT 2.78 //millisec
  166. #define APDS9960_UP 0x01
  167. #define APDS9960_DOWN 0x02
  168. #define APDS9960_LEFT 0x03
  169. #define APDS9960_RIGHT 0x04
  170. class APDS9960 {
  171. public:
  172. APDS9960(void) {};
  173. ~APDS9960(void) {};
  174. boolean begin(uint16_t iTimeMS = 10, apds9960AGain_t = APDS9960_AGAIN_4X, uint8_t addr = APDS9960_ADDRESS);
  175. void setADCIntegrationTime(uint16_t iTimeMS);
  176. float getADCIntegrationTime(void);
  177. void setADCGain(apds9960AGain_t gain);
  178. apds9960AGain_t getADCGain(void);
  179. void setLED(apds9960LedDrive_t drive, apds9960LedBoost_t boost);
  180. // proximity
  181. void enableProximity(boolean en = true);
  182. void setProxGain(apds9960PGain_t gain);
  183. apds9960PGain_t getProxGain(void);
  184. void setProxPulse(apds9960PPulseLen_t pLen, uint8_t pulses);
  185. void enableProximityInterrupt();
  186. void disableProximityInterrupt();
  187. uint8_t readProximity(void);
  188. void setProximityInterruptThreshold(uint8_t low, uint8_t high, uint8_t persistance = 4);
  189. bool getProximityInterrupt();
  190. // gesture
  191. void enableGesture(boolean en = true);
  192. bool gestureValid();
  193. void setGestureDimensions(uint8_t dims, uint8_t pcmp_en = 0);
  194. void setGestureFIFOThreshold(uint8_t thresh);
  195. void setGestureGain(uint8_t gain);
  196. void setGestureProximityThreshold(uint8_t thresh);
  197. void setGestureOffset(uint8_t offset_up, uint8_t offset_down, uint8_t offset_left, uint8_t offset_right);
  198. uint8_t readGesture(void);
  199. void resetCounts();
  200. // light & color
  201. void enableColor(boolean en = true);
  202. bool colorDataReady();
  203. void getColorData(uint16_t *r, uint16_t *g, uint16_t *b, uint16_t *c);
  204. uint16_t calculateColorTemperature(uint16_t r, uint16_t g, uint16_t b);
  205. uint16_t calculateLux(uint16_t r, uint16_t g, uint16_t b);
  206. void enableColorInterrupt();
  207. void disableColorInterrupt();
  208. void clearInterrupt(void);
  209. void setIntLimits(uint16_t l, uint16_t h);
  210. // turn on/off elements
  211. void enable(boolean en = true);
  212. private:
  213. uint8_t _i2caddr;
  214. uint32_t read32(uint8_t reg);
  215. uint16_t read16(uint8_t reg);
  216. uint16_t read16R(uint8_t reg);
  217. void write8(byte reg, byte value);
  218. uint8_t read8(byte reg);
  219. uint8_t gestCnt;
  220. uint8_t UCount;
  221. uint8_t DCount;
  222. uint8_t LCount;
  223. uint8_t RCount;
  224. uint8_t read(uint8_t reg, uint8_t *buf, uint8_t num);
  225. void write(uint8_t reg, uint8_t *buf, uint8_t num);
  226. void _i2c_init();
  227. struct enable {
  228. //power on
  229. uint8_t PON : 1;
  230. //ALS enable
  231. uint8_t AEN : 1;
  232. //Proximity detect enable
  233. uint8_t PEN : 1;
  234. //wait timer enable
  235. uint8_t WEN : 1;
  236. //ALS interrupt enable
  237. uint8_t AIEN : 1;
  238. //proximity interrupt enable
  239. uint8_t PIEN : 1;
  240. //gesture enable
  241. uint8_t GEN : 1;
  242. uint8_t get() {
  243. return (GEN << 6) | (PIEN << 5) | (AIEN << 4) | (WEN << 3) | (PEN << 2) | (AEN << 1) | PON;
  244. };
  245. };
  246. struct enable _enable;
  247. struct pers {
  248. //ALS Interrupt Persistence. Controls rate of Clear channel interrupt to the host processor
  249. uint8_t APERS : 4;
  250. //proximity interrupt persistence, controls rate of prox interrupt to host processor
  251. uint8_t PPERS : 4;
  252. uint8_t get(){
  253. return (PPERS << 4) | APERS;
  254. };
  255. };
  256. pers _pers;
  257. struct config1 {
  258. uint8_t WLONG : 1;
  259. uint8_t get(){
  260. return WLONG << 1;
  261. };
  262. };
  263. config1 _config1;
  264. struct ppulse {
  265. /*Proximity Pulse Count. Specifies the number of proximity pulses to be generated on LDR.
  266. Number of pulses is set by PPULSE value plus 1.
  267. */
  268. uint8_t PPULSE : 6;
  269. //Proximity Pulse Length. Sets the LED-ON pulse width during a proximity LDR pulse.
  270. uint8_t PPLEN : 2;
  271. uint8_t get(){
  272. return (PPLEN << 6) | PPULSE;
  273. }
  274. };
  275. ppulse _ppulse;
  276. struct control {
  277. //ALS and Color gain control
  278. uint8_t AGAIN : 2;
  279. //proximity gain control
  280. uint8_t PGAIN : 2;
  281. //led drive strength
  282. uint8_t LDRIVE : 2;
  283. uint8_t get(){
  284. return (LDRIVE << 6) | (PGAIN << 2) | AGAIN;
  285. }
  286. };
  287. control _control;
  288. struct config2 {
  289. /* Additional LDR current during proximity and gesture LED pulses. Current value, set by LDRIVE,
  290. is increased by the percentage of LED_BOOST.
  291. */
  292. uint8_t LED_BOOST : 2;
  293. //clear photodiode saturation int enable
  294. uint8_t CPSIEN : 1;
  295. //proximity saturation interrupt enable
  296. uint8_t PSIEN : 1;
  297. uint8_t get(){
  298. return (PSIEN << 7) | (CPSIEN << 6) | (LED_BOOST << 4) | 1;
  299. }
  300. };
  301. config2 _config2;
  302. struct status {
  303. /* ALS Valid. Indicates that an ALS cycle has completed since AEN was asserted or since a read
  304. from any of the ALS/Color data registers.
  305. */
  306. uint8_t AVALID : 1;
  307. /* Proximity Valid. Indicates that a proximity cycle has completed since PEN was asserted or since
  308. PDATA was last read. A read of PDATA automatically clears PVALID.
  309. */
  310. uint8_t PVALID : 1;
  311. /* Gesture Interrupt. GINT is asserted when GFVLV becomes greater than GFIFOTH or if GVALID
  312. has become asserted when GMODE transitioned to zero. The bit is reset when FIFO is
  313. completely emptied (read).
  314. */
  315. uint8_t GINT : 1;
  316. //ALS Interrupt. This bit triggers an interrupt if AIEN in ENABLE is set.
  317. uint8_t AINT : 1;
  318. //Proximity Interrupt. This bit triggers an interrupt if PIEN in ENABLE is set.
  319. uint8_t PINT : 1;
  320. /* Indicates that an analog saturation event occurred during a previous proximity or gesture
  321. cycle. Once set, this bit remains set until cleared by clear proximity interrupt special function
  322. command (0xE5 PICLEAR) or by disabling Prox (PEN=0). This bit triggers an interrupt if PSIEN
  323. is set.
  324. */
  325. uint8_t PGSAT : 1;
  326. /* Clear Photodiode Saturation. When asserted, the analog sensor was at the upper end of its
  327. dynamic range. The bit can be de-asserted by sending a Clear channel interrupt command
  328. (0xE6 CICLEAR) or by disabling the ADC (AEN=0). This bit triggers an interrupt if CPSIEN is set.
  329. */
  330. uint8_t CPSAT : 1;
  331. void set(uint8_t data){
  332. AVALID = data & 0x01;
  333. PVALID = (data >> 1) & 0x01;
  334. GINT = (data >> 2) & 0x01;
  335. AINT = (data >> 4) & 0x01;
  336. PINT = (data >> 5) & 0x01;
  337. PGSAT = (data >> 6) & 0x01;
  338. CPSAT = (data >> 7) & 0x01;
  339. }
  340. };
  341. status _status;
  342. struct config3 {
  343. //proximity mask
  344. uint8_t PMASK_R : 1;
  345. uint8_t PMASK_L : 1;
  346. uint8_t PMASK_D : 1;
  347. uint8_t PMASK_U : 1;
  348. /* Sleep After Interrupt. When enabled, the device will automatically enter low power mode
  349. when the INT pin is asserted and the state machine has progressed to the SAI decision block.
  350. Normal operation is resumed when INT pin is cleared over I2C.
  351. */
  352. uint8_t SAI : 1;
  353. /* Proximity Gain Compensation Enable. This bit provides gain compensation when proximity
  354. photodiode signal is reduced as a result of sensor masking. If only one diode of the diode pair
  355. is contributing, then only half of the signal is available at the ADC; this results in a maximum
  356. ADC value of 127. Enabling PCMP enables an additional gain of 2X, resulting in a maximum
  357. ADC value of 255.
  358. */
  359. uint8_t PCMP : 1;
  360. uint8_t get(){
  361. return (PCMP << 5) | (SAI << 4) | (PMASK_U << 3) | (PMASK_D << 2) | (PMASK_L << 1) | PMASK_R;
  362. }
  363. };
  364. config3 _config3;
  365. struct gconf1 {
  366. /* Gesture Exit Persistence. When a number of consecutive �gesture end� occurrences become
  367. equal or greater to the GEPERS value, the Gesture state machine is exited.
  368. */
  369. uint8_t GEXPERS : 2;
  370. /* Gesture Exit Mask. Controls which of the gesture detector photodiodes (UDLR) will be included
  371. to determine a �gesture end� and subsequent exit of the gesture state machine. Unmasked
  372. UDLR data will be compared with the value in GTHR_OUT. Field value bits correspond to UDLR
  373. detectors.
  374. */
  375. uint8_t GEXMSK : 4;
  376. /* Gesture FIFO Threshold. This value is compared with the FIFO Level (i.e. the number of UDLR
  377. datasets) to generate an interrupt (if enabled).
  378. */
  379. uint8_t GFIFOTH : 2;
  380. uint8_t get(){
  381. return (GFIFOTH << 6) | (GEXMSK << 2) | GEXPERS;
  382. }
  383. };
  384. gconf1 _gconf1;
  385. struct gconf2 {
  386. /* Gesture Wait Time. The GWTIME controls the amount of time in a low power mode between
  387. gesture detection cycles.
  388. */
  389. uint8_t GWTIME : 3;
  390. //Gesture LED Drive Strength. Sets LED Drive Strength in gesture mode.
  391. uint8_t GLDRIVE : 2;
  392. //Gesture Gain Control. Sets the gain of the proximity receiver in gesture mode.
  393. uint8_t GGAIN : 2;
  394. uint8_t get(){
  395. return (GGAIN << 5) | (GLDRIVE << 3) | GWTIME;
  396. }
  397. };
  398. gconf2 _gconf2;
  399. struct gpulse {
  400. /* Number of Gesture Pulses. Specifies the number of pulses to be generated on LDR.
  401. Number of pulses is set by GPULSE value plus 1.
  402. */
  403. uint8_t GPULSE : 6;
  404. //Gesture Pulse Length. Sets the LED_ON pulse width during a Gesture LDR Pulse.
  405. uint8_t GPLEN : 2;
  406. uint8_t get(){
  407. return (GPLEN << 6) | GPULSE;
  408. }
  409. };
  410. gpulse _gpulse;
  411. struct gconf3 {
  412. uint8_t PCMP : 1;
  413. /* Gesture Dimension Select. Selects which gesture photodiode pairs are enabled to gather
  414. results during gesture.
  415. */
  416. uint8_t GDIMS : 4;
  417. uint8_t get(){
  418. return (PCMP << 5) | GDIMS;
  419. }
  420. };
  421. gconf3 _gconf3;
  422. struct gconf4 {
  423. /* Gesture Mode. Reading this bit reports if the gesture state machine is actively running, 1
  424. = Gesture, 0= ALS, Proximity, Color. Writing a 1 to this bit causes immediate entry in to the
  425. gesture state machine (as if GPENTH had been exceeded). Writing a 0 to this bit causes exit of
  426. gesture when current analog conversion has finished (as if GEXTH had been exceeded).
  427. */
  428. uint8_t GMODE : 1;
  429. /* Gesture interrupt enable. Gesture Interrupt Enable. When asserted, all gesture related
  430. interrupts are unmasked.
  431. */
  432. uint8_t GIEN : 2;
  433. uint8_t get(){
  434. return (GIEN << 1) | GMODE;
  435. }
  436. void set(uint8_t data){
  437. GIEN = (data >> 1) & 0x01;
  438. GMODE = data & 0x01;
  439. }
  440. };
  441. gconf4 _gconf4;
  442. struct gstatus {
  443. /* Gesture FIFO Data. GVALID bit is sent when GFLVL becomes greater than GFIFOTH (i.e. FIFO has
  444. enough data to set GINT). GFIFOD is reset when GMODE = 0 and the GFLVL=0 (i.e. All FIFO data
  445. has been read).
  446. */
  447. uint8_t GVALID : 1;
  448. /* Gesture FIFO Overflow. A setting of 1 indicates that the FIFO has filled to capacity and that new
  449. gesture detector data has been lost.
  450. */
  451. uint8_t GFOV : 1;
  452. void set(uint8_t data){
  453. GFOV = (data >> 1) & 0x01;
  454. GVALID = data & 0x01;
  455. }
  456. };
  457. gstatus _gstatus;
  458. };
  459. #endif