Adafruit Color Sensors
Created by Bill Earl
https://learn.adafruit.com/adafruit-color-sensors
Last updated on 2021-11-15 06:00:50 PM EST
©Adafruit Industries
Page 1 of 21
Table of Contents
Overview
3
Assembly and Wiring
4
•
•
•
•
•
•
•
•
5
5
5
5
6
6
6
6
Assembly (breakout version only)
Position the header
Position the Breakout
And Solder!
Wiring
Flora Wiring:
Arduino Wiring:
To control the LED
Python & CircuitPython
7
•
•
•
•
•
•
7
7
8
9
9
10
CircuitPython Microcontroller Wiring
Python Computer Wiring
CircuitPython Installation of TCS34725 Library
Python Installation of TCS34725 Library
CircuitPython & Python Usage
Full Example Code
Python Docs
11
Arduino Code
11
•
•
•
•
•
11
12
13
13
13
Download Adafruit_TCS34725
Test the Sensor
ColorView!
ColorView Components
ColorView Wiring
Library Reference
14
•
•
•
•
14
15
15
16
Construction and Initialization:
Gain and Integration Time:
Light Readings and Calculations:
Interrupts and LED control:
Use it with Processing!
17
•
•
•
•
17
17
18
18
Load ColorView on the Arduino
Load ColorView.pde in Processing
Edit the Serial Port
And Run!
Identifying Colors
19
Downloads
19
• Files
• Breakout Board Version
• Flora Sewable Version
19
20
21
©Adafruit Industries
Page 2 of 21
Overview
Your electronics can now see in dazzling color with this lovely color light sensor. We
found the best color sensor on the market, the TCS34725, which has RGB and Clear
light sensing elements. An IR blocking filter, integrated on-chip and localized to the
color sensing photodiodes, minimizes the IR spectral component of the incoming light
and allows color measurements to be made accurately. The filter means you'll get
much truer color than most sensors, since humans don't see IR. The sensor also has
an incredible 3,800,000:1 dynamic range with adjustable integration time and gain so
it is suited for use behind darkened glass.
We add supporting circuitry as well, such as a 3.3V regulator so you can power the
breakout with 3-5VDC safely and level shifting for the I2C pins so they can be used
with 3.3V or 5V logic. Finally, we specified a nice neutral 4150°K temperature LED with
a MOSFET driver onboard to illuminate what you're trying to sense. The LED can be
easily turned on or off by any logic level output.
For more flexibility, we've made two different versions of this board: A breadboardfriendly breakout, and a wearable version designed to work with the Flora wearable
platform.
©Adafruit Industries
Page 3 of 21
Assembly and Wiring
Both color sensors come with all surface mount components pre-soldered. The
breakout-board version comes with an optional header for breadboard use. Soldering
the header is a simple process:
©Adafruit Industries
Page 4 of 21
Assembly (breakout version only)
Position the header
Trim the header to length if necessary
and insert it (long pins down) into your
breadboard.
Position the Breakout
Place the breakout over the exposed
short end of the header pins.
And Solder!
Solder all pins to ensure good electrical
contact.
©Adafruit Industries
Page 5 of 21
Wiring
These sensors communicate via a 2-wire I2C interface. To connect to the processor,
you need a total of just 4 wires.
Flora Wiring:
Connect from:
• 3.3v -> 3v (red wire)
• GND -> GND (black wire)
• SDA -> SDA (white wire)
• SCL -> SCL (green wire)
Arduino Wiring:
Connect jumpers from:
• 5v -> VIN (red wire)
• GND -> GND (black wire)
• SDA -> SDA (orange wire)
• SCL -> SCL (white wire)
Note: On older Arduinos such as the
Duemilanove and pre R3 UNOs, SDA is
on Analog 4 and SCL is on Analog 5.
On pre-R2 Megas, SDA is on Digtital 20
and SCL is on digital 21.
For the Leonardo, SDA is digital pin 2
and SCL is digital pin 3.
To control the LED
(Breakout version only) - The LED pin can be pulled low to turn off the LED. This can
be done in three ways:
1. Wire directly to ground to turn it off completely.
2. Wire to a spare digital pin and control it with digitalWrite().
3. Wire the LED pin to the INT pin and control with setInterrupt() (See Library
Reference for details).
©Adafruit Industries
Page 6 of 21
Python & CircuitPython
It's easy to use the TCS34725 sensor with Python and CircuitPython, and the Adafruit
CircuitPython TCS34725 (https://adafru.it/C5G) module. This module allows you to
easily write Python code that reads the color from the sensor.
You can use this sensor with any CircuitPython microcontroller board or with a
computer that has GPIO and Python thanks to Adafruit_Blinka, our CircuitPython-forPython compatibility library (https://adafru.it/BSN).
CircuitPython Microcontroller Wiring
First wire up a TCS34725 to your board exactly as shown on the previous pages for
Arduino. Here's an example of wiring a Feather M0 to the sensor with an I2C
connection:
• Board 3V to sensor VIN
• Board GND to sensor GND
• Board SCL to sensor SCL
• Board SDA to sensor SDA
Python Computer Wiring
Since there's dozens of Linux computers/boards you can use we will show wiring for
Raspberry Pi. For other platforms, please visit the guide for CircuitPython on Linux to
see whether your platform is supported (https://adafru.it/BSN).
Here's the Raspberry Pi wired with I2C:
©Adafruit Industries
Page 7 of 21
• Pi 3V3 to sensor VIN
• Pi GND to sensor GND
• Pi SCL to sensor SCL
• Pi SDA to sensor SDA
CircuitPython Installation of TCS34725
Library
You'll need to install the Adafruit CircuitPython TCS34725 (https://adafru.it/C5G) librar
y on your CircuitPython board.
First make sure you are running the latest version of Adafruit CircuitPython (https://
adafru.it/Amd) for your board.
Next you'll need to install the necessary libraries to use the hardware--carefully follow
the steps to find and install these libraries from Adafruit's CircuitPython library bundle
(https://adafru.it/zdx). Our introduction guide has a great page on how to install the
library bundle (https://adafru.it/ABU) for both express and non-express boards.
Remember for non-express boards like the, you'll need to manually install the
necessary libraries from the bundle:
• adafruit_tcs34725.mpy
• adafruit_bus_device
Before continuing make sure your board's lib folder or root filesystem has the adafrui
t_tcs34725.mpy, and adafruit_bus_device files and folders copied over.
Next connect to the board's serial REPL (https://adafru.it/Awz) so you are at the
CircuitPython >>> prompt.
©Adafruit Industries
Page 8 of 21
Python Installation of TCS34725 Library
You'll need to install the Adafruit_Blinka library that provides the CircuitPython
support in Python. This may also require enabling I2C on your platform and verifying
you are running Python 3. Since each platform is a little different, and Linux changes
often, please visit the CircuitPython on Linux guide to get your computer ready (https
://adafru.it/BSN)!
Once that's done, from your command line run the following command:
• sudo pip3 install adafruit-circuitpython-tcs34725
If your default Python is version 3 you may need to run 'pip' instead. Just make sure
you aren't trying to use CircuitPython on Python 2.x, it isn't supported!
CircuitPython & Python Usage
To demonstrate the usage of the sensor we'll initialize it and read the color and more
from the board's Python REPL.
Run the following code to import the necessary modules and initialize the I2C
connection with the sensor:
import board
import adafruit_tcs34725
i2c = board.I2C()
sensor = adafruit_tcs34725.TCS34725(i2c)
Now you're ready to read values from the sensor using any of these properties:
• color_rgb_bytes - A 3-tuple of the red, green, blue color values. These are
returned as bytes from 0 to 255 (0 is low intensity, 255 is maximum intensity).
• color_temperature - The color temperature in Kelvin detected by the sensor.
This is computed from the color and might not be super accurate!
• lux - The light intensity in lux detected by the sensor. This is computed from the
color and might not be super accurate!
print('Color: ({0}, {1}, {2})'.format(*sensor.color_rgb_bytes))
print('Temperature: {0}K'.format(sensor.color_temperature))
print('Lux: {0}'.format(sensor.lux))
©Adafruit Industries
Page 9 of 21
In addition there are some properties you can both read and write to change how the
sensor behaves:
• integration_time - The integration time of the sensor in milliseconds. Must be a
value between 2.4 and 614.4.
• gain - The gain of the sensor, must be a value of 1, 4, 16, 60.
sensor.integration_time = 200
sensor.gain = 60
See the simpletest.py example (https://adafru.it/C5I) for a complete demo of printing
the range every second. Save this as code.py on the board and examine the REPL
output to see the range printed every second.
That's all there is to using the TCS34725 with CircuitPython!
Full Example Code
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
# Simple demo of the TCS34725 color sensor.
# Will detect the color from the sensor and print it out every second.
import time
import board
import adafruit_tcs34725
# Create sensor object, communicating over the board's default I2C bus
i2c = board.I2C() # uses board.SCL and board.SDA
sensor = adafruit_tcs34725.TCS34725(i2c)
# Change sensor integration time to values between 2.4 and 614.4 milliseconds
# sensor.integration_time = 150
# Change sensor gain to 1, 4, 16, or 60
# sensor.gain = 4
# Main loop reading color and printing it every second.
while True:
©Adafruit Industries
Page 10 of 21
# Raw data from the sensor in a 4-tuple of red, green, blue, clear light
component values
# print(sensor.color_raw)
color = sensor.color
color_rgb = sensor.color_rgb_bytes
print(
"RGB color as 8 bits per channel int: #{0:02X} or as 3-tuple: {1}".format(
color, color_rgb
)
)
# Read the color temperature and lux of the sensor too.
temp = sensor.color_temperature
lux = sensor.lux
print("Temperature: {0}K Lux: {1}\n".format(temp, lux))
# Delay for a second and repeat.
time.sleep(1.0)
Python Docs
Python Docs (https://adafru.it/C5J)
Arduino Code
Download Adafruit_TCS34725
To begin reading sensor data, you will need to install the
(https://adafru.it/sDz)Adafruit_TCS34725 (https://adafru.it/cb1)
The easiest way to do that is to open up the Manage Libraries... menu in the Arduino
IDE
Then search for Adafruit TCS34725 and click Install
©Adafruit Industries
Page 11 of 21
We also have a great tutorial on Arduino library installation at:
http://learn.adafruit.com/adafruit-all-about-arduino-libraries-install-use (https://
adafru.it/aYM)
Test the Sensor
Run the TCS34725 test sketch to verify that your sensor is working properly.
Upload the sketch to your Aruduino or Flora and open the Serial Monitor to see the
output. The sketch should print out basic color measurement parameters as shown
below. Move the sensor around, cover it and/or expose it to different light sources to
see how it reacts.
Color parameters reported are:
• Color Temperature (https://adafru.it/cb3) - measured in Kelvin
• Lux (https://adafru.it/aKS) - or Lumens (https://adafru.it/cb4)per Square Meter
• R, G and B (filtered) values
• Clear (unfiltered) value
©Adafruit Industries
Page 12 of 21
ColorView!
The ColorView sketch demonstrates reflected-light measurement using the on-board
led. The white led is used to illuminate nearby objects and the sensor measures the
light reflected from the object. The ColorView sketch then uses the RGB outputs of
the sensor to drive an RGB led to match the color that is seen by the sensor!
ColorView Components
In addition to a processor and a color
sensor, you will need an RGB LED (http://
adafru.it/159) and some resistors:
• 1x 1K ohm resistor (Brown, Black
Red Gold)
• 2x 560 ohm resistor (Green Blue
Brown Gold)
ColorView Wiring
In addition to the basic power and I2C
wiring, you will need the following
connections:
• LED common anode (long pin) -> 5v.
• LED Red Pin -> 1K resistor ->
Arduino Pin 3
• LED Green Pin -> 560 ohm resistor > Arduino Pin 5
• LED Blue Pin -> 560 ohm resistor ->
Arduino Pin 6
Upload the ColorView sketch to your Arduino, then place different objects in front of
the sensor. The LED color should match the color of the sensed object!
©Adafruit Industries
Page 13 of 21
Library Reference
Construction and Initialization:
Adafruit_TCS34725(tcs34725IntegrationTime_t =
TCS34725_INTEGRATIONTIME_2_4MS,
tcs34725Gain_t = TCS34725_GAIN_1X);
Declare a TCS34725 sensor with optional integration time and gain values.
boolean Adafruit_TCS34725::begin(void)
Initialize the TCS34725 Color Sensor. Call this function before anything
else.
©Adafruit Industries
Page 14 of 21
Gain and Integration Time:
void Adafruit_TCS34725::setIntegrationTime(tcs34725IntegrationTime_t it)
Sets the integration time for color samples from the sensor. Longer
integration times can be used for increased sensitivity at low light levels.
Valid integration times are:
◦ TCS34725_INTEGRATIONTIME_2_4MS = 0xFF, /**< 2.4ms */
◦ TCS34725_INTEGRATIONTIME_24MS = 0xF6, /**< 24ms */
◦ TCS34725_INTEGRATIONTIME_50MS = 0xEB, /**< 50ms */
◦ TCS34725_INTEGRATIONTIME_101MS = 0xD5, /**< 101ms */
◦ TCS34725_INTEGRATIONTIME_154MS = 0xC0, /**< 154ms */
◦ TCS34725_INTEGRATIONTIME_700MS = 0x00 /**< 700ms */
void Adafruit_TCS34725::setGain(tcs34725Gain_t gain)
Sets the gain of the ADC to control the sensitivity of the sensor. Valid gain
settings are:
◦ TCS34725_GAIN_1X = 0x00, /**< No gain */
◦ TCS34725_GAIN_4X = 0x01, /**< 2x gain */
◦ TCS34725_GAIN_16X = 0x02, /**< 16x gain */
◦ TCS34725_GAIN_60X = 0x03 /**< 60x gain */
Light Readings and Calculations:
void Adafruit_TCS34725::getRawData (uint16_t *r, uint16_t *g, uint16_t *b, uint16_t *c)
Reads the raw sensor output for the Red, Green, Blue and Clear segments
of the sensor.
uint16_t Adafruit_TCS34725::calculateColorTemperature(uint16_t r, uint16_t g, uint16_t
©Adafruit Industries
Page 15 of 21
b)
Calculates the color temperature from the Red, Green and Blue
components.
uint16_t Adafruit_TCS34725::calculateLux(uint16_t r, uint16_t g, uint16_t b)
Calculates Lux from the Red, Green and Blue components.
Interrupts and LED control:
void Adafruit_TCS34725::setInterrupt(boolean i)
Sets the sensor interrupt to generate an interrupt when the detected level
is within the limits (see setIntLimits() below). The Int pin is only available on
the breakout version.
The boolean parameter can be used to control the LED. On the breakout
version, you must connect the LED pin to the INT pin for LED control.
• Passing "false" will enable the on-board led for reflected light
measurement.
• Passing "true" will turn the led off for incident light measurement.
void Adafruit_TCS34725::clearInterrupt(void)
Clears the sensor interrupt.
void Adafruit_TCS34725::setIntLimits(uint16_t low, uint16_t high)
Sets the high and low threshold levels for interrupts. For more detail on the
operation of interrupts, please refer to the data sheet (https://adafru.it/cb6).
©Adafruit Industries
Page 16 of 21
Use it with Processing!
The Adafruit_TCS34725 Library includes a processing sketch to communicate with
the ColorView Arduino sketch and display color on your computer screen in real time
The Processing Sketch only works with Processing 1.5.1. It is not compatible with
Processing version 2.0!
Load ColorView on the
Arduino
Open the ColorView example sketch and
upload it to your Arduino.
Make note of the serial port used by your
Arduino.
Load ColorView.pde in
Processing
Navigate to the "Processing" folder inside
the Adafruit_TCS34725 Library folder
and open "ColorView.pde".
©Adafruit Industries
Page 17 of 21
Edit the Serial Port
Find the line where the Serial port is
opened and edit it to use the same port
as your Arduino.
And Run!
When you run the processing sketch, it
will display the sensor text output and
pop up a window with a color patch
matching the color seen by your sensor.
©Adafruit Industries
Page 18 of 21
Identifying Colors
Identifying specific colors with a color sensor is not as simple as pointing the sensor
at a color patch and taking a reading. There are many factors such as distance, field
of view and ambient lighting conditions that can affect readings. Adafruit forum
member systembolaget has developed a system capable of quickly and reliably
identifying many different colors and has put together an excellent tutorial on the
subject.
See the video and github repository link below:
Colour Finder Github Repository
https://adafru.it/FCA
Downloads
Files
• Adafruit TCS34725 Arduino Library (https://adafru.it/cb1)
• TCS34725 Data Sheet (https://adafru.it/cb6)
• Fritzing objects in Adafruit Fritzing Library (https://adafru.it/aP3)
• EagleCAD PCB files for Breakout version (https://adafru.it/rCS)
• EagleCAD PCB files for Flora version (https://adafru.it/rCU)
©Adafruit Industries
Page 19 of 21
Breakout Board Version
Schematic and fabrication print
©Adafruit Industries
Page 20 of 21
Flora Sewable Version
Schematic and fabrication print
©Adafruit Industries
Page 21 of 21