Skip to content

TCS34725

Works with

Any CircuitPython board with I2C

What it does

The TCS34725 measures red, green, blue, and clear light intensity through a built-in IR blocking filter. It returns calibrated RGB values and can calculate lux and color temperature automatically. Common uses include color detection, color matching, and automatic white balance in camera or display projects.

Installing the library

Download adafruit_tcs34725.mpy from the Adafruit CircuitPython Bundle and copy it to the lib/ folder on your board.

Quick start

import board
import busio
import adafruit_tcs34725

i2c = busio.I2C(board.SCL, board.SDA)
sensor = adafruit_tcs34725.TCS34725(i2c)

r, g, b = sensor.color_rgb_bytes
print(f"Red: {r}  Green: {g}  Blue: {b}")
print(f"Lux: {sensor.lux}")
print(f"Color temperature: {sensor.color_temperature} K")

Key things you can do

What you want How to do it
Read RGB values (0–255 each) sensor.color_rgb_bytes returns (r, g, b)
Read lux sensor.lux
Read color temperature sensor.color_temperature (Kelvin)
Read raw RGBC values sensor.color_raw returns (r, g, b, clear)
Adjust gain sensor.gain = 1 — options: 1, 4, 16, 60
Adjust integration time sensor.integration_time = 50 — 2.4ms to 614ms
Check if data is ready sensor.data_ready returns True when a cycle completes

Reading the official docs

Full API reference: https://docs.circuitpython.org/projects/tcs34725/en/latest/

Key things to look up:

  • color_raw vs color_rgb_bytes — raw values are 16-bit; bytes are normalized to 0–255
  • Gain and integration time interact — a longer integration time increases sensitivity but slows the read rate
  • The clear channel is used internally to normalize RGB readings; you can read it directly from color_raw

Projects using this library

  • Adafruit Color Sensors guide — wiring, setup, and usage examples
  • This wiki's Color Matcher project — uses TCS34725 readings to drive NeoPixel output