Wiki: TCS3430 XYZ Tristimulus Color Sensor Breakout Board

Introduction

Devices with True Tone technology like Apple iPad Pro, iPhone, and Macs usually feature sensors that measure the ambient light colour and brightness. The device then uses this information to automatically adjust its display, so it can correct white points and illumination based on your environmental lighting in order to render the right kinds of white under any conditions. And XYZ Tristimulus Color Sensor plays an important role in this technology.
TCS3430 features advanced digital ambient light sensing(ALS) and CIE 1931 tristimulus color sensing(XYZ). CIE1931 XYZ Tristimulus model is a kind of standard based on three different human cone cell types. The CIE XYZ color space encompasses all color sensations that are visible to a person with average eyesight. The spectral response of TCS3430 is almost the same as that of human eyes, which can realize the high-precision measurement of illumination and color temperature. What you see is what you measured! The TCS3430 Tristimulus Color Sensor is ideally suited for the use in smartphone applications to improve color measurement and intensity of ambient light conditions. Also, it can be used in scenarios requiring a true-color viewing experience like online shopping(product color matching, reducing the return rate caused by color difference of images and real product).

You can learn more about CIE 1931-XYZ system here: https://en.wikipedia.org/wiki/CIE_1931_color_space

Features

XYZ Tristimulus Filter
Capable of ±10% illuminance and correlated color temperature accuracy
Wide dynamic range and high sensitivity
Programmable gain and integration time

Application

Color Detection
Illuminance Detection
White-blance Detection
Color Temperature Detection

Specification

Power Supply: 3.3V~5V
Operating Current: <5mA
LED Operating Current: <15mA
I2C Address: 0x39
Operating Temperature Range: -30℃~85℃
Dimension: 22×15mm/0.87×0.59"

Dimension

Board Overview

Num	Label	Description
1	+	Power+
2	-	Power-
3	SCL	I2C Clock line
4	SDA	I2C Data line
5	LED	Drive LED
6	INT	Interrupt Output

Tutorial

Requirements

Hardware
- DFRduino UNO R3 (or similar) x 1
- TCS3430 Tristimulus Color Sensor Breakout Board x1
- Jumper wires

Software
- Arduino IDE
- Download and install the TCS3430 Library and Sample Code (About how to install the library?)
API Function List

  /**
   * @brief  Set the ALS gain 
   * @param  aGain  the value of gain
   */
  void setALSGain(uint8_t aGain);

  /**
   * @brief  Set the internal integration time of the  four-channel ADCs
   * @param  aTIme  integration time
   */
  void setIntegrationTime(uint8_t aTime);

    /**
   * @brief  get channel 0 value
   * @return  the z data
   */
  uint16_t getZData();

  /**
   * @brief  get channel 1 value
   * @return  the y data
   */
  uint16_t getYData();

  /**
   * @brief  get channel 2 value
   * @return  the IR1 data 
   */
  uint16_t getIR1Data();

  /**
   * @brief  get channel 3 value
   * @return  the x data
   */
  uint16_t getXData();

  /**
   * @brief  get channel 3 value
   * @return  the IR2 data
   */
  uint16_t getIR2Data();

Connection Diagram

Sample Code 1-Read Data

Read and print the values of XYZ, IR1 and IR2.

/*!
 * @file getXYZIRData.ino
 * @brief Detection of XYZ tristimulus and infrared data
 * @copyright  Copyright (c) 2010 DFRobot Co.Ltd (http://www.dfrobot.com)
 * @licence     The MIT License (MIT)
 * @author [yangfeng]<feng.yang@dfrobot.com>
 * @version  V1.0
 * @date  2021-01-26
 * @get from https://www.dfrobot.com
 * @url  https://github.com/DFRobot/DFRobot_TCS3430
 */
#include <DFRobot_TCS3430.h>

DFRobot_TCS3430 TCS3430;
void setup() {
  Serial.begin(115200);

  while(!TCS3430.begin()){
    Serial.println("Please check that the IIC device is properly connected");
    delay(1000);
  }
}

void loop() {
  uint16_t XData = TCS3430.getXData();
  uint16_t YData = TCS3430.getYData();
  uint16_t ZData = TCS3430.getZData();
  uint16_t IR1Data = TCS3430.getIR1Data();
  uint16_t IR2Data = TCS3430.getIR2Data();
  String str = "X : " + String(XData) + "    Y : " + String(YData) + "    Z : " +  String(ZData) + "    IR1 : "+String(IR1Data) + "    IR2 : "+String(IR2Data);
  Serial.println(str);
  delay(1000);
}

Expected Results

Result 1

Sample Code 2-Interrupt Threshold

Generate an interrupt when the Z-channel value exceeds the threshold for 10 consective times.

/*!
 * @file setALSInterrupt.ino
 * @brief Turn on the ambient light sense interrupt function to obtain the ambient light data within the specified range
 * @copyright  Copyright (c) 2010 DFRobot Co.Ltd (http://www.dfrobot.com)
 * @licence     The MIT License (MIT)
 * @author [yangfeng]<feng.yang@dfrobot.com>
 * @version  V1.0
 * @date  2021-01-26
 * @get from https://www.dfrobot.com
 * @url  https://github.com/DFRobot/DFRobot_TCS3430
 */
#include <DFRobot_TCS3430.h>


DFRobot_TCS3430 TCS3430;

int LEDpin = 12;
int interruptPin = 2;

volatile int state = 0;

void handleInterrupt(){

  Serial.println("WARNING:The data obtained exceeds the threshold");
  state = 1;
}

void setup() {
  Serial.begin(115200);

  pinMode(interruptPin, INPUT_PULLUP);

  while(!TCS3430.begin()){
    Serial.println("Please check that the IIC device is properly connected");
    delay(1000);
  }

// Configure the sensor's ADC integration time, device waiting time, and gain

  //TCS3430.setWaitTimer(true);
  //TCS3430.setWaitLong(false);
    /*
   * By asserting wlong, in register 0x8D the wait time is given in multiples of 33.4ms (12x).
   * ----------------------------------------
   * | wtime | Wait Cycles | Wait Time      |
   * ----------------------------------------
   * |  0x00 |      1      | 2.78ms/ 33.4ms |
   * ----------------------------------------
   * |  0x01 |      2      | 5.56ms/ 66.7ms |
   * ----------------------------------------
   * |  ...  |     ...     |      ...       |
   * ----------------------------------------
   * |  0x23 |     36      | 100ms/ 1.20s   |
   * ----------------------------------------
   * |  ...  |     ...     |       ...      |
   * ----------------------------------------
   * |  0xff |     256     |  711ms/ 8.53s  |
   * ----------------------------------------
   */
  //TCS3430.setWaitTime(/*wTime=*/0x00);
  /*
   * Maximum ALS Value=  min [CYCLES * 1024, 65535]
   * ---------------------------------------------------------------------
   * | aTime | Integration Cycles | Integration Time | Maximum ALS Value |
   * ---------------------------------------------------------------------
   * |  0x00 |         1          |       2.78ms     |        1023       |
   * ---------------------------------------------------------------------
   * |  0x01 |         2          |       5.56ms     |        2047       |
   * ---------------------------------------------------------------------
   * |  ...  |        ...         |       ...        |        ...        |
   * ---------------------------------------------------------------------
   * |  0x11 |         18         |       50ms       |        18431      |
   * ---------------------------------------------------------------------
   * |  0x40 |         65         |       181ms      |        65535      |
   * ---------------------------------------------------------------------
   * |  ...  |        ...         |       ...        |        ...        |
   * ---------------------------------------------------------------------
   * |  0xff |        256         |       711ms      |        65535      |
   * ---------------------------------------------------------------------
   */
  TCS3430.setIntegrationTime(/*aTime=*/0x23);
  /*
   * AGAIN: ALS Gain Control. Sets the gain of the ALS DAC.
   * ----------------------------------------------------------
   * | Field Value |            ALS GAIN VALUE                |
   * ----------------------------------------------------------
   * |     0       |               1X Gain                    |
   * ----------------------------------------------------------
   * |     1       |               4X Gain                    |
   * ----------------------------------------------------------
   * |     2       |               16X Gain                   |
   * ----------------------------------------------------------
   * |     3       |               64X Gain                   |
   * ----------------------------------------------------------
   */
  TCS3430.setALSGain(/*aGian=*/3);
  //128X high gain
  //TCS3430.setHighGAIN()

/* Turn on the ALS interrupt function of the device */

  //mode = true : enable ALS Interrupt
  TCS3430.setALSInterrupt(/*mode*/true);

  /*
   *                       APERS                              
   * ----------------------------------------------------------
   * | Field Value |            Persistence                   |
   * ----------------------------------------------------------
   * |     0x00    |   Every ALS cycle generates an interrupt |
   * ----------------------------------------------------------
   * |     0x01    |   Any value outside of threshold range   |
   * ----------------------------------------------------------
   * |     0x02    |   2 consecutive values out of range      |
   * ----------------------------------------------------------
   * |     0x03    |   3 consecutive values out of range      |
   * ----------------------------------------------------------
   * |     0x04    |   5 consecutive values out of range      |
   * ----------------------------------------------------------
   * |     0x05    |   10 consecutive values out of range     |
   * ----------------------------------------------------------
   * |     0x06    |   15 consecutive values out of range     |
   * ----------------------------------------------------------
   * |     0x07    |   20 consecutive values out of range     |
   * ----------------------------------------------------------
   * |     0x08    |   25 consecutive values out of range     |
   * ----------------------------------------------------------
   * |     0x09    |   30 consecutive values out of range     |
   * ----------------------------------------------------------
   * |     0x0A    |   35 consecutive values out of range     |
   * ----------------------------------------------------------
   * |     0x0B    |   40 consecutive values out of range     |
   * ----------------------------------------------------------
   * |     0x0C    |   45 consecutive values out of range     |
   * ----------------------------------------------------------
   * |     0x0D    |   50 consecutive values out of range     |
   * ----------------------------------------------------------
   * |     0x0E    |   55 consecutive values out of range     |
   * ----------------------------------------------------------
   * |     0x0F    |   60 consecutive values out of range     |
   * ----------------------------------------------------------
   */
  TCS3430.setInterruptPersistence(/*apers=*/0x05);

  // Set the threshold range(0-65535)
  TCS3430.setCH0IntThreshold(/*thresholdL=*/50,/*thresholdH=*/100);

  Serial.println("If the light data exceeds the threshold, an interrupt is triggered and a warning is printed.");

  attachInterrupt(digitalPinToInterrupt(interruptPin), handleInterrupt, FALLING);

}
void loop() {
  if (state == 1){
    state =0;
    TCS3430.getDeviceStatus(); 
  }else{
    Serial.println(TCS3430.getZData());
    delay(100);   //This delay only influences print speed, and does not affect the interrupt trigger
  }
}

Expected Result

Result 2

FAQ

For any questions, advice or cool ideas to share, please visit the DFRobot Forum.

Wiki: TCS3430 XYZ Tristimulus Color Sensor Breakout Board - DFRobot