Implemented DN40 CCT algorithm for more accurate results

Author: Kevin Townsend

Adafruit_TCS34725.cpp

@@ -119,9 +119,9 @@ void Adafruit_TCS34725::enable(void)
 {
   write8(TCS34725_ENABLE, TCS34725_ENABLE_PON);
   delay(3);
-  write8(TCS34725_ENABLE, TCS34725_ENABLE_PON | TCS34725_ENABLE_AEN);  
+  write8(TCS34725_ENABLE, TCS34725_ENABLE_PON | TCS34725_ENABLE_AEN);
     /* Set a delay for the integration time.
-      This is only necessary in the case where enabling and then 
+      This is only necessary in the case where enabling and then
       immediately trying to read values back. This is because setting
       AEN triggers an automatic integration, so if a read RGBC is
       performed too quickly, the data is not yet valid and all 0's are
@@ -171,7 +171,7 @@ void Adafruit_TCS34725::disable(void)
     Constructor
 */
 /**************************************************************************/
-Adafruit_TCS34725::Adafruit_TCS34725(tcs34725IntegrationTime_t it, tcs34725Gain_t gain) 
+Adafruit_TCS34725::Adafruit_TCS34725(tcs34725IntegrationTime_t it, tcs34725Gain_t gain)
 {
   _tcs34725Initialised = false;
   _tcs34725IntegrationTime = it;
@@ -188,10 +188,10 @@ Adafruit_TCS34725::Adafruit_TCS34725(tcs34725IntegrationTime_t it, tcs34725Gain_
     doing anything else)
 */
 /**************************************************************************/
-boolean Adafruit_TCS34725::begin(void) 
+boolean Adafruit_TCS34725::begin(void)
 {
   Wire.begin();
-  
+
   /* Make sure we're actually connected */
   uint8_t x = read8(TCS34725_ID);
   if ((x != 0x44) && (x != 0x10))
@@ -209,7 +209,7 @@ boolean Adafruit_TCS34725::begin(void)
 
   return true;
 }
-  
+
 /**************************************************************************/
 /*!
     Sets the integration time for the TC34725
@@ -255,7 +255,7 @@ void Adafruit_TCS34725::getRawData (uint16_t *r, uint16_t *g, uint16_t *b, uint1
   *r = read16(TCS34725_RDATAL);
   *g = read16(TCS34725_GDATAL);
   *b = read16(TCS34725_BDATAL);
-  
+
   /* Set a delay for the integration time */
   switch (_tcs34725IntegrationTime)
   {
@@ -330,6 +330,136 @@ uint16_t Adafruit_TCS34725::calculateColorTemperature(uint16_t r, uint16_t g, ui
   return (uint16_t)cct;
 }
 
+/**************************************************************************/
+/*!
+    @brief  Converts the raw R/G/B values to color temperature in degrees
+            Kelvin using the algorithm described in DN40 from Taos (now AMS).
+*/
+/**************************************************************************/
+uint16_t Adafruit_TCS34725::calculateColorTemperature_dn40(uint16_t r, uint16_t g, uint16_t b, uint16_t c)
+{
+    int rc;                     /* Error return code */
+    uint16_t r2, g2, b2;        /* RGB values minus IR component */
+    int gl;                     /* Results of the initial lux conversion */
+    uint8_t gain_int;           /* Gain multiplier as a normal integer */
+    uint16_t sat;               /* Digital saturation level */
+    uint16_t ir;                /* Inferred IR content */
+
+    /* Analog/Digital saturation:
+     *
+     * (a) As light becomes brighter, the clear channel will tend to
+     *     saturate first since R+G+B is approximately equal to C.
+     * (b) The TCS34725 accumulates 1024 counts per 2.4ms of integration
+     *     time, up to a maximum values of 65535. This means analog
+     *     saturation can occur up to an integration time of 153.6ms
+     *     (64*2.4ms=153.6ms).
+     * (c) If the integration time is > 153.6ms, digital saturation will
+     *     occur before analog saturation. Digital saturation occurs when
+     *     the count reaches 65535.
+     */
+    if ((256 - _tcs34725IntegrationTime) > 63) {
+        /* Track digital saturation */
+        sat = 65535;
+    } else {
+        /* Track analog saturation */
+        sat = 1024 * (256 - _tcs34725IntegrationTime);
+    }
+
+    /* Ripple rejection:
+     *
+     * (a) An integration time of 50ms or multiples of 50ms are required to
+     *     reject both 50Hz and 60Hz ripple.
+     * (b) If an integration time faster than 50ms is required, you may need
+     *     to average a number of samples over a 50ms period to reject ripple
+     *     from fluorescent and incandescent light sources.
+     *
+     * Ripple saturation notes:
+     *
+     * (a) If there is ripple in the received signal, the value read from C
+     *     will be less than the max, but still have some effects of being
+     *     saturated. This means that you can be below the 'sat' value, but
+     *     still be saturating. At integration times >150ms this can be
+     *     ignored, but <= 150ms you should calculate the 75% saturation
+     *     level to avoid this problem.
+     */
+    if ((256 - _tcs34725IntegrationTime) <= 63) {
+        /* Adjust sat to 75% to avoid analog saturation if atime < 153.6ms */
+        sat -= sat/4;
+    }
+
+    /* Check for saturation and mark the sample as invalid if true */
+    if (c >= sat) {
+        return 0;
+    }
+
+    /* AMS RGB sensors have no IR channel, so the IR content must be */
+    /* calculated indirectly. */
+    ir = (r + g + b > c) ? (r + g + b - c) / 2 : 0;
+
+    /* Remove the IR component from the raw RGB values */
+    r2 = r - ir;
+    g2 = g - ir;
+    b2 = b - ir;
+
+    /* Convert gain to a usable integer value */
+    switch(_tcs34725Gain) {
+        case TCS34725_GAIN_4X: /* GAIN 4X */
+            gain_int = 4;
+            break;
+        case TCS34725_GAIN_16X: /* GAIN 16X */
+            gain_int = 16;
+            break;
+        case TCS34725_GAIN_60X: /* GAIN 60X */
+            gain_int = 60;
+            break;
+        case TCS34725_GAIN_1X: /* GAIN 1X */
+        default:
+            gain_int = 1;
+            break;
+    }
+
+    /* Calculate the counts per lux (CPL), taking into account the optional
+     * arguments for Glass Attenuation (GA) and Device Factor (DF).
+     *
+     * GA = 1/T where T is glass transmissivity, meaning if glass is 50%
+     * transmissive, the GA is 2 (1/0.5=2), and if the glass attenuates light
+     * 95% the GA is 20 (1/0.05). A GA of 1.0 assumes perfect transmission.
+     *
+     * NOTE: It is recommended to have a CPL > 5 to have a lux accuracy
+     *       < +/- 0.5 lux, where the digitization error can be calculated via:
+     *       'DER = (+/-2) / CPL'.
+     */
+    float cpl = (((256-_tcs34725IntegrationTime)*2.4f) * gain_int) /
+        (1.0f * 310.0f);
+
+    /* Determine lux accuracy (+/- lux) */
+    float der = 2.0f / cpl;
+
+    /* Determine the maximum lux value */
+    float max_lux = 65535.0 / (cpl * 3);
+
+    /* Lux is a function of the IR-compensated RGB channels and the associated
+     * color coefficients, with G having a particularly heavy influence to
+     * match the nature of the human eye.
+     *
+     * NOTE: The green value should be > 10 to ensure the accuracy of the lux
+     *       conversions. If it is below 10, the gain should be increased, but
+     *       the clear<100 check earlier should cover this edge case.
+     */
+    gl =  0.136f * (float)r2 +                   /** Red coefficient. */
+          1.000f * (float)g2 +                   /** Green coefficient. */
+         -0.444f * (float)b2;                    /** Blue coefficient. */
+
+    float lux = gl / cpl;
+
+    /* A simple method of measuring color temp is to use the ratio of blue */
+    /* to red light, taking IR cancellation into account. */
+    uint16_t cct = (3810 * (uint32_t)b2) /      /** Color temp coefficient. */
+                   (uint32_t)r2 + 1391;         /** Color temp offset. */
+
+    return cct;
+}
+
 /**************************************************************************/
 /*!
     @brief  Converts the raw R/G/B values to lux

Adafruit_TCS34725.h

@@ -1,5 +1,5 @@
 /**************************************************************************/
-/*! 
+/*!
     @file     Adafruit_TCS34725.h
     @author   KTOWN (Adafruit Industries)
 
@@ -118,13 +118,14 @@ tcs34725Gain_t;
 class Adafruit_TCS34725 {
  public:
   Adafruit_TCS34725(tcs34725IntegrationTime_t = TCS34725_INTEGRATIONTIME_2_4MS, tcs34725Gain_t = TCS34725_GAIN_1X);
-  
+
   boolean  begin(void);
   void     setIntegrationTime(tcs34725IntegrationTime_t it);
   void     setGain(tcs34725Gain_t gain);
   void     getRawData(uint16_t *r, uint16_t *g, uint16_t *b, uint16_t *c);
   void     getRawDataOneShot(uint16_t *r, uint16_t *g, uint16_t *b, uint16_t *c);
   uint16_t calculateColorTemperature(uint16_t r, uint16_t g, uint16_t b);
+  uint16_t calculateColorTemperature_dn40(uint16_t r, uint16_t g, uint16_t b, uint16_t c);
   uint16_t calculateLux(uint16_t r, uint16_t g, uint16_t b);
   void     write8 (uint8_t reg, uint32_t value);
   uint8_t  read8 (uint8_t reg);
@@ -138,8 +139,8 @@ class Adafruit_TCS34725 {
  private:
   boolean _tcs34725Initialised;
   tcs34725Gain_t _tcs34725Gain;
-  tcs34725IntegrationTime_t _tcs34725IntegrationTime; 
-  
+  tcs34725IntegrationTime_t _tcs34725IntegrationTime;
+
 };
 
 #endif

examples/tcs34725/tcs34725.pde

@@ -7,7 +7,7 @@
    Connect SDA    to analog 4
    Connect VDD    to 3.3V DC
    Connect GROUND to common ground */
-   
+
 /* Initialise with default values (int time = 2.4ms, gain = 1x) */
 // Adafruit_TCS34725 tcs = Adafruit_TCS34725();
 
@@ -16,24 +16,25 @@ Adafruit_TCS34725 tcs = Adafruit_TCS34725(TCS34725_INTEGRATIONTIME_700MS, TCS347
 
 void setup(void) {
   Serial.begin(9600);
-  
+
   if (tcs.begin()) {
     Serial.println("Found sensor");
   } else {
     Serial.println("No TCS34725 found ... check your connections");
     while (1);
   }
-  
+
   // Now we're ready to get readings!
 }
 
 void loop(void) {
   uint16_t r, g, b, c, colorTemp, lux;
-  
+
   tcs.getRawData(&r, &g, &b, &c);
-  colorTemp = tcs.calculateColorTemperature(r, g, b);
+  // colorTemp = tcs.calculateColorTemperature(r, g, b);
+  colorTemp = tcs.calculateColorTemperature_dn40(r, g, b, c);
   lux = tcs.calculateLux(r, g, b);
-  
+
   Serial.print("Color Temp: "); Serial.print(colorTemp, DEC); Serial.print(" K - ");
   Serial.print("Lux: "); Serial.print(lux, DEC); Serial.print(" - ");
   Serial.print("R: "); Serial.print(r, DEC); Serial.print(" ");

library.properties

@@ -1,5 +1,5 @@
 name=Adafruit TCS34725
-version=1.1.0
+version=1.2.0
 author=Adafruit
 maintainer=Adafruit <[email protected]>
 sentence=Driver for Adafruit's TCS34725 RGB Color Sensor Breakout