Frank Vannieuwkerke / ISL29125

Library for ISL29125 - I2C RGB ambient light sensor

Dependents:   ISL29125_demo FinalProject Final_NSR 4180FinalProject_copy ... more

Device documentation

Detailed information is available at Intersil

Calling the constructor

The constructor can be instantiaded in 3 ways:

Information

The first two pins (SDA and SCL) always need to be declared.

ISR mode

void RGBsensor_irq(void)    // User ISR
{
    ....
}

ISL29125 RGBsensor(PTE0, PTE1, PTD7, &RGBsensor_irq);          // sda, scl, irq, user isr

The user ISR is called whenever the upper/lower threshold is reached and/or when a conversion cycle is finished. The threshold (Threshold function) and end of conversion (IRQonCnvDone function) interrupts can be enabled separately.
In this mode, PTD7 is an interrupt input.

Limitation!

Calling the Read function at a high rate will result in a I2C failure.
Use a Ticker to call the Read function at regular intervals. Example : ISL29125_demo

SYNC mode

ISL29125 RGBsensor(PTE0, PTE1, PTD7);                        // sda, scl, sync input

In this mode, PTD7 is a digital output. Initially, the sensor is idle (no conversions) and can be started by calling the Run function.

Polling mode

ISL29125 RGBsensor(PTE0, PTE1);                              // sda, scl

In this mode, user defined functions are needed to poll the sensor status, read the sensor data, ....

ISL29125.h@4:ae36914adb6d, 2014-05-28 (annotated)

Committer:
frankvnk
Date:
Wed May 28 20:15:39 2014 +0000
Revision:
4:ae36914adb6d
Parent:
3:400edaa74b7d 
Update doxygen

Who changed what in which revision?

UserRevisionLine numberNew contents of line
frankvnk 0:59ae5a71c902 1 /******************************************************************************************************************************
frankvnk 0:59ae5a71c902 2 ***** *****
frankvnk 0:59ae5a71c902 3 ***** Name: ISL29125.h *****
frankvnk 0:59ae5a71c902 4 ***** Date: 06/04/2014 *****
frankvnk 0:59ae5a71c902 5 ***** Auth: Frank Vannieuwkerke *****
frankvnk 0:59ae5a71c902 6 ***** Func: library for Intersil ISL29125 RGB Ambient light sensor with IR blocking filter *****
frankvnk 0:59ae5a71c902 7 ***** *****
frankvnk 0:59ae5a71c902 8 ***** Additional info is available at *****
frankvnk 0:59ae5a71c902 9 ***** http://www.intersil.com/en/products/optoelectronics/ambient-light-sensors/light-to-digital-sensors/ISL29125.html *****
frankvnk 0:59ae5a71c902 10 ***** *****
frankvnk 0:59ae5a71c902 11 ******************************************************************************************************************************/
frankvnk 0:59ae5a71c902 12
frankvnk 0:59ae5a71c902 13 #ifndef ISL29125_H
frankvnk 0:59ae5a71c902 14 #define ISL29125_H
frankvnk 0:59ae5a71c902 15
frankvnk 0:59ae5a71c902 16 #include "mbed.h"
frankvnk 0:59ae5a71c902 17
frankvnk 0:59ae5a71c902 18 // Common Controls Used with
frankvnk 0:59ae5a71c902 19 // Operating IRQ Status
frankvnk 0:59ae5a71c902 20 // Mode ADC assignment request
frankvnk 0:59ae5a71c902 21 #define ISL29125_G 0x01 // Green X X X
frankvnk 0:59ae5a71c902 22 #define ISL29125_R 0x02 // Red X X X
frankvnk 0:59ae5a71c902 23 #define ISL29125_B 0x03 // Blue X X X
frankvnk 0:59ae5a71c902 24 #define ISL29125_RG 0x06 // Red and Green X - -
frankvnk 0:59ae5a71c902 25 #define ISL29125_BG 0x07 // Blue and Green X - -
frankvnk 0:59ae5a71c902 26 #define ISL29125_RGB 0x05 // Red, Green and Blue X - X
frankvnk 0:59ae5a71c902 27 #define ISL29125_STBY 0x04 // Standby X - -
frankvnk 0:59ae5a71c902 28 #define ISL29125_OFF 0x00 // Switch OFF a control X X -
frankvnk 0:59ae5a71c902 29 // Unique Controls
frankvnk 0:59ae5a71c902 30 #define ISL29125_LTH_W 0x04 // Low interrupt threshold register
frankvnk 0:59ae5a71c902 31 #define ISL29125_HTH_W 0x06 // High interrupt threshold register
frankvnk 0:59ae5a71c902 32 #define ISL29125_LTH_R 0x02 // Low interrupt threshold register
frankvnk 0:59ae5a71c902 33 #define ISL29125_HTH_R 0x03 // High interrupt threshold register
frankvnk 0:59ae5a71c902 34 #define ISL29125_375LX 0x00 // Full scale range = 375 lux
frankvnk 0:59ae5a71c902 35 #define ISL29125_10KLX 0x08 // Full scale range = 10K lux
frankvnk 0:59ae5a71c902 36 #define ISL29125_16BIT 0x00 // ADC resolution = 16 bit
frankvnk 0:59ae5a71c902 37 #define ISL29125_12BIT 0x10 // ADC resolution = 12 bit
frankvnk 0:59ae5a71c902 38 #define ISL29125_PERS1 0x00 // IRQ when threshold is reached once
frankvnk 0:59ae5a71c902 39 #define ISL29125_PERS2 0x04 // IRQ when threshold is reached twice
frankvnk 0:59ae5a71c902 40 #define ISL29125_PERS4 0x08 // IRQ when threshold is reached 4 times
frankvnk 0:59ae5a71c902 41 #define ISL29125_PERS8 0x0C // IRQ when threshold is reached 8 times
frankvnk 0:59ae5a71c902 42
frankvnk 1:1c1ded8d719e 43 /** ISL29125 class.
frankvnk 1:1c1ded8d719e 44 */
frankvnk 1:1c1ded8d719e 45
frankvnk 0:59ae5a71c902 46 class ISL29125 {
frankvnk 0:59ae5a71c902 47 public:
frankvnk 0:59ae5a71c902 48 /**
frankvnk 2:f1b55929169a 49 * \brief Create a ISL29125 object connected to I2C bus, irq or sync pin and user-ISR pointer.\n
frankvnk 2:f1b55929169a 50 * \param sda SDA pin.\n
frankvnk 2:f1b55929169a 51 * \param scl SCL pin.\n
frankvnk 4:ae36914adb6d 52 * \param irqsync (Optional) Interrupt pin when fptr is also declared OR Sync output when fptr is not declared.\n
frankvnk 2:f1b55929169a 53 * \param fptr (Optional) Pointer to user-ISR (only used with Interrupt pin).\n
frankvnk 2:f1b55929169a 54 * \return none\n
frankvnk 0:59ae5a71c902 55 */
frankvnk 0:59ae5a71c902 56 ISL29125(PinName sda, PinName scl, PinName irqsync = NC, void (*fptr)(void) = NULL);
frankvnk 0:59ae5a71c902 57
frankvnk 0:59ae5a71c902 58 /**
frankvnk 2:f1b55929169a 59 * \brief Read status register.\n
frankvnk 2:f1b55929169a 60 * The interrupt status flag is cleared when the status register is read.\n
frankvnk 0:59ae5a71c902 61 * \param NONE
frankvnk 2:f1b55929169a 62 * \return Content of the entire status register.\n
frankvnk 4:ae36914adb6d 63 @verbatim
frankvnk 4:ae36914adb6d 64 bit Description
frankvnk 4:ae36914adb6d 65 --- ---------------------------------------------------------
frankvnk 4:ae36914adb6d 66 5,4 RGB conversion - 00: Inactive
frankvnk 4:ae36914adb6d 67 01: Green
frankvnk 4:ae36914adb6d 68 10: Red
frankvnk 4:ae36914adb6d 69 11: Blue
frankvnk 4:ae36914adb6d 70 2 Brownout status - 0: No brownout
frankvnk 4:ae36914adb6d 71 1: Power down or brownout occured
frankvnk 4:ae36914adb6d 72 1 Conversion status - 0: Conversion is pending or inactive
frankvnk 4:ae36914adb6d 73 1: Conversion is completed
frankvnk 4:ae36914adb6d 74 0 Interrupt status - 0: no interrupt occured
frankvnk 4:ae36914adb6d 75 1: interrupt occured
frankvnk 4:ae36914adb6d 76 @endverbatim
frankvnk 0:59ae5a71c902 77 */
frankvnk 0:59ae5a71c902 78 uint8_t Status(void);
frankvnk 0:59ae5a71c902 79
frankvnk 0:59ae5a71c902 80 /**
frankvnk 2:f1b55929169a 81 * \brief Read the device identifier.\n
frankvnk 4:ae36914adb6d 82 * \param none.
frankvnk 4:ae36914adb6d 83 * \return 0x7D on success.
frankvnk 0:59ae5a71c902 84 */
frankvnk 0:59ae5a71c902 85 uint8_t WhoAmI(void);
frankvnk 0:59ae5a71c902 86
frankvnk 0:59ae5a71c902 87 /**
frankvnk 2:f1b55929169a 88 * \brief Read the channel values (12 or 16-bit - depends on resolution).\n
frankvnk 4:ae36914adb6d 89 * \param color
frankvnk 4:ae36914adb6d 90 * ISL29125_R = Red channel.\n
frankvnk 4:ae36914adb6d 91 * ISL29125_G = Green channel.\n
frankvnk 4:ae36914adb6d 92 * ISL29125_B = Blue channel.\n
frankvnk 4:ae36914adb6d 93 * ISL29125_RGB = Red, Green and Blue channels.\n
frankvnk 4:ae36914adb6d 94 * \param data
frankvnk 3:400edaa74b7d 95 * Pointer to 16-bit array for storing the channel value(s).\n
frankvnk 3:400edaa74b7d 96 * Array size: 1 for a single color (Red, Green or Blue) or 3 for all colors.\n
frankvnk 2:f1b55929169a 97 * \return bool 1: new data available - 0: no new data available.\n
frankvnk 0:59ae5a71c902 98 */
frankvnk 0:59ae5a71c902 99 bool Read(uint8_t color, uint16_t * data);
frankvnk 0:59ae5a71c902 100
frankvnk 0:59ae5a71c902 101 /**
frankvnk 2:f1b55929169a 102 * \brief Read/Write the low/high interrupt threshold value.\n
frankvnk 2:f1b55929169a 103 * When setIRQonColor is activated, an interrupt will occur when the low or high threshold is exceeded.\n
frankvnk 4:ae36914adb6d 104 * \param reg
frankvnk 4:ae36914adb6d 105 * ISL29125_LTH_W = Write 16-bit low threshold.\n
frankvnk 4:ae36914adb6d 106 * ISL29125_HTH_W = Write 16-bit high threshold.\n
frankvnk 4:ae36914adb6d 107 * ISL29125_LTH_R = Read 16-bit low threshold.\n
frankvnk 4:ae36914adb6d 108 * ISL29125_HTH_R = Read 16-bit high threshold.\n
frankvnk 2:f1b55929169a 109 * \param thres 16-bit threshold value (only needed when _W parameter is used).\n
frankvnk 2:f1b55929169a 110 * \return Written threshold value when called with _W parameter.\n
frankvnk 2:f1b55929169a 111 * Stored threshold value when called with _R parameter only.\n
frankvnk 0:59ae5a71c902 112 */
frankvnk 0:59ae5a71c902 113 uint16_t Threshold(uint8_t reg, uint16_t thres=0);
frankvnk 0:59ae5a71c902 114
frankvnk 0:59ae5a71c902 115 /**
frankvnk 2:f1b55929169a 116 * \brief Read/Write the RGB operating mode value (active ADC channels).\n
frankvnk 4:ae36914adb6d 117 * \param mode
frankvnk 4:ae36914adb6d 118 * ISL29125_G = G channel only.\n
frankvnk 4:ae36914adb6d 119 * ISL29125_R = R channel only.\n
frankvnk 4:ae36914adb6d 120 * ISL29125_B = B channel only.\n
frankvnk 4:ae36914adb6d 121 * ISL29125_RG = R and G channel.\n
frankvnk 4:ae36914adb6d 122 * ISL29125_BG = B and G channel.\n
frankvnk 4:ae36914adb6d 123 * ISL29125_RGB = R, G and B channel.\n
frankvnk 4:ae36914adb6d 124 * ISL29125_STBY = Standby (No ADC conversion).\n
frankvnk 4:ae36914adb6d 125 * ISL29125_OFF = Power down ADC conversion.\n
frankvnk 2:f1b55929169a 126 * \return Written value is returned when called with valid parameter, otherwise 0xff is returned.\n
frankvnk 2:f1b55929169a 127 * Stored value is returned when called without parameter.\n
frankvnk 0:59ae5a71c902 128 */
frankvnk 0:59ae5a71c902 129 uint8_t RGBmode(uint8_t mode=0xff);
frankvnk 0:59ae5a71c902 130
frankvnk 0:59ae5a71c902 131 /**
frankvnk 2:f1b55929169a 132 * \brief Read/Write the sensing range parameter.\n
frankvnk 4:ae36914adb6d 133 * \param range
frankvnk 4:ae36914adb6d 134 * ISL29125_375LX = Max. value corresponds to 375 lux.\n
frankvnk 4:ae36914adb6d 135 * ISL29125_10KLX = Max. value corresponds to 10000 lux.\n
frankvnk 2:f1b55929169a 136 * \return Written value is returned when called with valid parameter, otherwise 0xff is returned.\n
frankvnk 2:f1b55929169a 137 * Stored value is returned when called without parameter.\n
frankvnk 0:59ae5a71c902 138 */
frankvnk 0:59ae5a71c902 139 uint8_t Range(uint8_t range=0xff);
frankvnk 0:59ae5a71c902 140
frankvnk 0:59ae5a71c902 141 /**
frankvnk 2:f1b55929169a 142 * \brief Read/Write the ADC resolution parameter.\n
frankvnk 4:ae36914adb6d 143 * \param range
frankvnk 4:ae36914adb6d 144 * ISL29125_16BIT = 16 bit ADC resolution.\n
frankvnk 4:ae36914adb6d 145 * ISL29125_12BIT = 12 bit ADC resolution.\n
frankvnk 2:f1b55929169a 146 * \return Written value is returned when called with valid parameter, otherwise 0xff is returned.\n
frankvnk 2:f1b55929169a 147 * Stored value is returned when called without parameter.\n
frankvnk 0:59ae5a71c902 148 */
frankvnk 0:59ae5a71c902 149 uint8_t Resolution(uint8_t resol=0xff);
frankvnk 0:59ae5a71c902 150
frankvnk 0:59ae5a71c902 151 /**
frankvnk 2:f1b55929169a 152 * \brief Read/Write the IRQ persistence parameter.\n
frankvnk 4:ae36914adb6d 153 * \param persist
frankvnk 4:ae36914adb6d 154 * ISL29125_PERS1 = IRQ occurs when threshold is exceeded once.\n
frankvnk 4:ae36914adb6d 155 * ISL29125_PERS2 = IRQ occurs when threshold is exceeded twice.\n
frankvnk 4:ae36914adb6d 156 * ISL29125_PERS4 = IRQ occurs when threshold is exceeded 4 times.\n
frankvnk 4:ae36914adb6d 157 * ISL29125_PERS8 = IRQ occurs when threshold is exceeded 8 times.\n
frankvnk 2:f1b55929169a 158 * \return Written value is returned when called with valid parameter, otherwise 0xff is returned.\n
frankvnk 2:f1b55929169a 159 * Stored value is returned when called without parameter.\n
frankvnk 0:59ae5a71c902 160 */
frankvnk 0:59ae5a71c902 161 uint8_t Persist(uint8_t persist=0xff);
frankvnk 0:59ae5a71c902 162
frankvnk 0:59ae5a71c902 163 /**
frankvnk 2:f1b55929169a 164 * \brief Read/Write the IRQ on conversion done parameter.\n
frankvnk 4:ae36914adb6d 165 * \param persist true (enabled).\n
frankvnk 4:ae36914adb6d 166 * false (disabled).\n
frankvnk 2:f1b55929169a 167 * \return Written value is returned when called with valid parameter, otherwise 0xff is returned.\n
frankvnk 2:f1b55929169a 168 * Stored value is returned when called without parameter.\n
frankvnk 0:59ae5a71c902 169 */
frankvnk 0:59ae5a71c902 170 uint8_t IRQonCnvDone(uint8_t irqen=0xff);
frankvnk 0:59ae5a71c902 171
frankvnk 0:59ae5a71c902 172 /**
frankvnk 2:f1b55929169a 173 * \brief Read/Write the IRQ threshold to color assignment parameter.\n
frankvnk 4:ae36914adb6d 174 * \param RGBmode ISL29125_OFF = No interrupt.\n
frankvnk 4:ae36914adb6d 175 * ISL29125_G = Green interrupt.\n
frankvnk 4:ae36914adb6d 176 * ISL29125_R = Red interrupt.\n
frankvnk 4:ae36914adb6d 177 * ISL29125_B = Blue interrupt.\n
frankvnk 2:f1b55929169a 178 * \return Written value is returned when called with valid parameter, otherwise 0xff is returned.\n
frankvnk 2:f1b55929169a 179 * Stored value is returned when called without parameter.\n
frankvnk 0:59ae5a71c902 180 */
frankvnk 0:59ae5a71c902 181 uint8_t IRQonColor(uint8_t RGBmode=0xff);
frankvnk 0:59ae5a71c902 182
frankvnk 0:59ae5a71c902 183 /**
frankvnk 2:f1b55929169a 184 * \brief Read/Write the active IR compensation parameter.\n
frankvnk 2:f1b55929169a 185 * \param ircomp valid range: between 0..63 or 128..191.\n
frankvnk 2:f1b55929169a 186 * \return Written value is returned when called with valid parameter, otherwise 0xff is returned.\n
frankvnk 2:f1b55929169a 187 * Stored value is returned when called without parameter.\n
frankvnk 0:59ae5a71c902 188 */
frankvnk 0:59ae5a71c902 189 uint8_t IRcomp(uint8_t ircomp=0xff);
frankvnk 0:59ae5a71c902 190
frankvnk 0:59ae5a71c902 191 /**
frankvnk 2:f1b55929169a 192 * \brief Start ADC conversion.\n
frankvnk 2:f1b55929169a 193 * Only possible when SyncMode is activated.\n
frankvnk 3:400edaa74b7d 194 * \param None.
frankvnk 3:400edaa74b7d 195 * \return bool 1: success - 0: fail.
frankvnk 0:59ae5a71c902 196 */
frankvnk 0:59ae5a71c902 197 bool Run(void);
frankvnk 0:59ae5a71c902 198
frankvnk 0:59ae5a71c902 199 private:
frankvnk 0:59ae5a71c902 200 I2C _i2c;
frankvnk 0:59ae5a71c902 201 FunctionPointer _fptr;
frankvnk 0:59ae5a71c902 202 uint8_t _ismode; // 0: no irq/sync mode - 1: irq mode - 2: sync mode
frankvnk 0:59ae5a71c902 203 void _alsISR(void);
frankvnk 0:59ae5a71c902 204 void i2cfail(void);
frankvnk 0:59ae5a71c902 205 void readRegs(uint8_t addr, uint8_t * data, uint8_t len);
frankvnk 0:59ae5a71c902 206 uint8_t readReg(uint8_t addr);
frankvnk 0:59ae5a71c902 207 void writeRegs(uint8_t * data, uint8_t len);
frankvnk 0:59ae5a71c902 208 };
frankvnk 0:59ae5a71c902 209
frankvnk 0:59ae5a71c902 210 #endif