Labs / Electronic modules

GraftSense - TCS34725-based Color Recognition Module (Open Version)

Author: Li Zisheng · Source: FreakStudio open documentation, v1.3 · License: CC BY 4.0 · Driver code (sensors/tcs34725_color_driver): MIT License

Contents
GraftSense - TCS34725-based Color Recognition Module (Open Version)
GraftSense - TCS34725-based Color Recognition Module (Open Version)

I. Module Introduction

Color recognition module based on TCS34725 takes the TCS34725FN chip as the core, and integrates a color sensor with four channels: red (R), green (G), blue (B) and clear (Clear). It realizes color recognition by detecting light and converting it into digital signals. The module is equipped with a supplementary light control circuit to reduce ambient light interference and improve color measurement accuracy. This module is suitable for scenarios requiring accurate color discrimination such as intelligent recognition and industrial inspection, and provides a reliable hardware solution for color perception applications.

II. Introduction to Major Chips

TCS34725 is a high-precision RGB full-color color sensor with a built-in infrared filter and 16-bit ADC. It can accurately detect four light signals including red, green, blue and clear light (Clear), supports the visible light spectrum of 400~700nm, and can output digital color data. Equipped with programmable gain and integration time adjustment functions to adapt to different lighting environments, it communicates with the main controller via the I²C interface, operates on 3.3V power supply with low power consumption (only 0.3μA in standby), features a compact size (2.4mm×2.4mm×0.55mm), complies with the RoHS standard, and is widely used in color recognition, ambient light detection, display calibration, intelligent lighting and other scenarios.

2.1 Chip Overview

GraftSense - TCS34725-based Color Recognition Module (Open Version)

2.2 Pin Definition

GraftSense - TCS34725-based Color Recognition Module (Open Version)

2.3 Functional Block Diagram

GraftSense - TCS34725-based Color Recognition Module (Open Version)

TCS34725 The functional block diagram is described as follows:

Typical Scenarios for Color Inspection:

2.4 Performance Parameters

TCS34725 Absolute Maximum Ratings:

GraftSense - TCS34725-based Color Recognition Module (Open Version)

TCS34725 DC Electrical Characteristics Description:

GraftSense - TCS34725-based Color Recognition Module (Open Version)
GraftSense - TCS34725-based Color Recognition Module (Open Version)

AC Electrical Characteristics (V DD= 3V, T A= 25℃)

GraftSense - TCS34725-based Color Recognition Module (Open Version)
ParameterDescriptionMinTypMaxUnit
f(SCL)Clock frequency (I²C only)0400kHz
t(BUF)Bus free time between start and stop conditions1.3μs
t(HDSTA)Hold time after a (repeated) start condition. After this period, the first clock is generated.0.6μs
t(SUSTA)Setup time for a repeated start condition0.6μs
t(SUSTO)Setup time for a stop condition0.6μs
t(HDDAT)Data hold time00.9μs
t(SUDAT)Data setup time100ns
t(LOW)SCL clock low period1.3μs
t(HIGH)SCL clock high period0.6μs
tFClock/data fall time300ns
tRClock/data rise time300ns
CiInput pin capacitance10pF

The spectral responsivity plot is shown as follows:

GraftSense - TCS34725-based Color Recognition Module (Open Version)

This is the TCS34725 RGBC photodiode spectral response characteristic curve, which illustrates the relative responsivity of its four channels, namely Clear (full transmission), Red (red light), Green (green light), and Blue (blue light), to light with wavelengths ranging from 300 nm to 1100 nm at an ambient temperature of 25°C (normalized with reference to the response of the Clear channel at 755 nm).

The response characteristics of different channels have their own focuses: Clear channel has a wide wavelength coverage in response, while the Red, Green, and Blue channels have more significant responses to the optical bands of their corresponding colors (red, green, and blue bands) respectively. This feature enables the TCS34725 to distinguish light of different wavelengths, thus realizing functions such as color detection and ambient light intensity sensing.

The normalized responsivity and angular displacement diagrams are shown as follows:

GraftSense - TCS34725-based Color Recognition Module (Open Version)

This graph illustrates TCS34725 's response characteristics to light incident angles: when light is incident normally along the sensor' s optical axis (angular displacement of 0°), its normalized responsivness reaches the maximum (close to 1.0); as the incident angle shifts towards ±90°, the responsivness gradually decreases, and drops to 0 at ±90°. This characteristic indicates that TCS34725 has the optimal detection sensitivity for normally incident light, and the greater the deviation of the incident angle, the lower the detection sensitivity. In practical applications, the light should be kept as close to normal incidence as possible to ensure the accuracy of color and light intensity detection.

2.5 Reference Circuit

None.

2.6 Chip Configuration

None.

2.7.1 IIC Communication Protocol

GraftSense - TCS34725-based Color Recognition Module (Open Version)
GraftSense - TCS34725-based Color Recognition Module (Open Version)

This section describes the TCS34725 I²C Communication Protocol function: it controls registers via an interface compatible with I²C (Standard / Fast Mode) to achieve device control and data output, and supports 7-bit I²C addresses.

I²C includes three types of bus transactions: write protocol, read protocol, and combined protocol.

The command byte can carry control information or a 5-bit register address; control commands can also clear interrupts. For read operations, the register address corresponding to the previous command is reused, and if no address is set, the register address of the last valid command is used.

2.7.2 Register Description

2.7.2.1 Command Register
GraftSense - TCS34725-based Color Recognition Module (Open Version)

This is an 8-bit command register that is used to control the transaction type and function selection for subsequent data transmission, and it is divided into 3 fields:

  1. CMD (Bit 7): Used to select the command register; this bit must be set to 1 when accessing this register.
  2. TYPE (bits 6-5): Specifies the transaction type for subsequent data transmission, including "Repeat Byte Protocol Transfer (00)" and "Auto-increment Protocol Transfer (01)"; 10 is reserved, and 11 corresponds to a special function.
  3. ADDR/SF (Bits 4-0): Functions as an address field or a special function field depending on the transaction type; for special functions, only "00110" corresponds to the "clear channel interrupt" function, and all other values are reserved.

The core function of this register is to coordinate the interaction mode of subsequent read and write transactions, and it also supports special functions such as interrupt clearing.

2.7.2.2 Enable Register
GraftSense - TCS34725-based Color Recognition Module (Open Version)

The TCS3472's enable register (address 0x00) is primarily used to control the device's power supply, function activation, and interrupt switch:

2.7.2.3 RGBC Timing Register
GraftSense - TCS34725-based Color Recognition Module (Open Version)

The TCS3472 RGBC Timing Register (address 0x01) is primarily used to control the integration time of the RGBC and IR channel ADCs (in steps of 2.4ms):

2.7.2.4 Wait Time Register
GraftSense - TCS34725-based Color Recognition Module (Open Version)

The TCS3472 Wait Time Register (address 0x03) is primarily used to configure the waiting duration of the device:

2.7.2.5 RGBC Interrupt Threshold Register Bank
GraftSense - TCS34725-based Color Recognition Module (Open Version)

The TCS3472's RGBC interrupt threshold register bank (addresses 0x04–0x07) is primarily used to set the high and low trigger thresholds for interrupts:

2.7.2.6 Persistent Register
GraftSense - TCS34725-based Color Recognition Module (Open Version)
GraftSense - TCS34725-based Color Recognition Module (Open Version)

The Persistent Register (address 0x0C) of the TCS3472 is primarily used to control the filter trigger conditions for interrupts so as to reduce spurious interrupts:

2.7.2.7 Configuration Register
GraftSense - TCS34725-based Color Recognition Module (Open Version)

The configuration register of the TCS3472 (address 0x0D) has the core function of controlling the amplification factor of the waiting duration:

2.7.2.8 Control Register
GraftSense - TCS34725-based Color Recognition Module (Open Version)

The TCS3472 control register (address 0x0F) is primarily used to configure the analog gain of the RGBC channels:

2.7.2.9 ID Register
GraftSense - TCS34725-based Color Recognition Module (Open Version)

The TCS3472 ID register (address 0x12) is a read-only register that is primarily used to identify the device model:

2.7.2.10 Status Register

The TCS3472's status register (address 0x13) is a read-only register used to report the internal operating status of the device:

2.7.2.11 RGBC Channel Data Register Bank
GraftSense - TCS34725-based Color Recognition Module (Open Version)

The TCS3472's RGBC channel data register set (addresses 0x14–0x1B) is primarily used to store 16-bit light detection data:

2.8 PCB Routing Precautions

GraftSense - TCS34725-based Color Recognition Module (Open Version)

This is the PCB pad layout guide in the hardware application information for TCS3472 (FN package), which provides the recommended PCB pad design scheme for the dual no-lead flat (FN) surface-mount package:

  1. Layout and Dimensions: The unit of measurement for dimensions is micrometer. The pads are divided into two groups on the left and right, with a total width of 2500μm and an overall height of 1700μm; the pads feature various shapes (such as structures with a semicircular end), and parameters including the spacing between individual pads (e. g., 650μm) and partial lengths (e. g., 1000μm) have been marked.
  2. Practical Instructions: If manual soldering is adopted, the solder pads can be further extended to facilitate the operation.
  3. Notes: All linear dimensions are in micrometers, and this drawing is subject to change without notice.

This layout serves as a reference design for the surface-mount assembly of FN packaged devices on PCBs, ensuring the soldering reliability and compatibility of the devices.

III. Circuit Engineering

3.1 Circuit Source Engineering

To obtain the source project of the circuit, please follow the official account [Freak Embedded]

3.2 Module Usage Instructions

SCH_Schematic1_TCS34725-Based Color Recognition Module-V1.1.0_2025-11-12.pdf 2.1 MB

GraftSense - TCS34725-based Color Recognition Module (Open Version)

This module provides an I2C communication interface: it supports standard I2C communication rate, with a default I2C address of 0x29, is compatible with 3.3V/5V logic levels, and can stably transmit the four-channel digital color data of the TCS34725 RGBC sensor. Meanwhile, it can send fill light control commands through this interface to reduce ambient light interference. It is suitable for scenarios such as color recognition in maker projects, color perception of smart devices, and color identification in industrial inspection, providing accurate digital signal interaction capabilities for color perception applications.

If the detection environment is relatively dark, you can toggle the following DIP switch to turn on the fill light circuit to improve the detection effect.

GraftSense - TCS34725-based Color Recognition Module (Open Version)

3.3 Application Experiment

Here, we use the GraftPort-RP2040 development board for testing, and connect the TCS34725-based color recognition module to communicate with the main controller via the I2C interface.

Here, we first use the HY2.0-4P cable to connect the module to the GraftPort-RP2040 development board's I2C0 interface:

GraftSense - TCS34725-based Color Recognition Module (Open Version)

The module connections are shown in the following table:

Development Board Pins

Module Pins

Description

Pin 4

SDA

I2C data transmission line, corresponding to I2C0 's SDA

Pin 5

SCL

I2C clock signal line, corresponding to the I2C0 SCL

Here, we need to search for the relevant driver packages on uPyPI: https://upypi.net/zh/

GraftSense - TCS34725-based Color Recognition Module (Open Version)

Enter tcs34725_color_driver to search, and the following will be displayed:

GraftSense - TCS34725-based Color Recognition Module (Open Version)

Click to copy the local installation command:

GraftSense - TCS34725-based Color Recognition Module (Open Version)

Here, we can use the mip tool to import module driver library code. The following are the usage commands for the mpremote tool:

mpremote mip install github:FreakStudioCN/GraftSense-Drivers-MicroPython/sensors/tcs34725_color_driver

Import the TCS34725-based color recognition module - MicroPython driver code, then copy the following main.py code into our project:

# Python env   : MicroPython v1.23.0
# -*- coding: utf-8 -*-        
# @Time    : 2024/9/1 2:10 PM
# @Author  : Li Qingshui
# @File    : main.py       
# @Description : DAC experiment, using an external DAC chip to generate a sine waveform

# ======================================== Import Modules ========================================

# Import the hardware module
from machine import ADC, Timer, Pin, I2C, UART
# Import time-related modules
import time
# Import the module for accessing and controlling MicroPython internals
import micropython
# Import the math library for calculating the sine wave
import math
# Import the mcp4725 module to control the DAC chip
from mcp4725 import MCP4725

# ======================================== Global Variables ============================================

# mcp4725 chip address
DAC_ADDRESS = 0x00
# Voltage conversion factor
adc_conversion_factor = 3.3 / (65535)

# ======================================== Functions ============================================

# Timer callback function
def timer_callback(timer: Timer) -> None:
    """
    Timer callback function, used to read ADC data periodically and call the user-defined callback function.

    Args:
        timer (machine.Timer): Timer instance.

    Returns:
        None
    """

    # Declare global variables
    global adc,adc_conversion_factor

    # Read ADC data
    value = adc.read_u16() * adc_conversion_factor
    # Call the user-defined callback function
    micropython.schedule(user_callback, (value))

# User-defined callback function
def user_callback(value: float) -> None:
    """
    User-defined callback function, used to process the voltage value sampled by the ADC and send it over the serial port.

    Args:
        value (float): Voltage value sampled by the ADC.

    Returns:
        None
    """
    # Declare global variables
    global uart

    # Get the floating-point number and round it to two decimal places
    formatted_value = "{:.2f}".format(value)
    # Send the sampled voltage data over the serial port
    uart.write(str(formatted_value) + '\r\n')
    # Print the sampled voltage data to the terminal
    print('dac generated voltage: ' + str(formatted_value))

# ======================================== Custom Classes ============================================

# ======================================== Initialization ==========================================

# Delay 3 s to wait for the device to finish powering up
time.sleep(3)
# Print debug information
print("FreakStudio : Using DAC to generate sine wave")

# Create a hardware I2C instance using the I2C1 peripheral, with a clock frequency of 400KHz, SDA pin 4, and SCL pin 5
i2c = I2C(id=0, sda=Pin(4), scl=Pin(5), freq=400000)

# Start scanning for devices on the I2C bus and return a list of slave addresses
devices_list = i2c.scan()
print('START I2C SCANNER')

# If devices_list is empty, no device is connected to the I2C bus
if len(devices_list) == 0:
    print("No i2c device !")
# If not empty, print the slave device addresses
else:
    print('i2c devices found:', len(devices_list))
    # Iterate over the slave device address list
    for device in devices_list:
        # If the device address is between 0x60 and 0x61, it is a DAC chip
        if 0x60 <= device <= 0x61:
            print("I2C hexadecimal address: ", hex(device))
            DAC_ADDRESS = device

# Create the DAC object, using the I2C0 peripheral, with address DAC_ADDRESS
dac = MCP4725(i2c, DAC_ADDRESS)
# Read the DAC configuration information
eeprom_write_busy, power_down, value, eeprom_power_down, eeprom_value = dac.read()
print(eeprom_write_busy, power_down, value, eeprom_power_down, eeprom_value)
# Configure the DAC: cancel power-down mode, output voltage 0V, write to EEPROM
dac.config(power_down='Off',value=0,eeprom=True)
# Delay 50ms; reading immediately after configuration causes an error
time.sleep_ms(50)
# Read the DAC configuration information
eeprom_write_busy, power_down, value, eeprom_power_down, eeprom_value = dac.read()
print(eeprom_write_busy, power_down, value, eeprom_power_down, eeprom_value)

# Create the ADC instance: ADC1-GP27
adc = ADC(1)
# Create a software timer object
timer = Timer(-1)
# Start the timer, triggering the timer_callback function every 5ms to sample voltage with the ADC
timer.init(period=5, mode=Timer.PERIODIC, callback=timer_callback)

# Create the serial port object, set the baud rate to 115200
uart = UART(0, 115200)
# Initialize the uart object with a baud rate of 115200, 8 data bits, no parity bit, and 1 stop bit
# Set the serial port timeout to 100ms
uart.init(baudrate  = 115200,
          bits      = 8,
          parity    = None,
          stop      = 1,
          tx        = 0,
          rx        = 1,
          timeout   = 100)

# ========================================  Main Program  ===========================================

# Generate the sine wave
for i in range(10000):
    # Calculate the voltage value of the sine wave
    value = 3.3 * math.sin(2 * math.pi * i / 100) + 3.3
    # Convert the voltage value of the sine wave to an integer
    value = int(value * 4095 / 6.6)
    # Write the analog value to the DAC
    dac.write(value)
    # Delay 10ms
    time.sleep_ms(10)

# Stop ADC sampling
timer.deinit()

Burn the code, open the terminal, and use the mpremote tool to connect to the main controller. The output is as follows:

GraftSense - TCS34725-based Color Recognition Module (Open Version)

It can be seen that when we move color blocks of different colors such as red, green, blue and yellow close to the module, the terminal will output the corresponding different color component values and the corresponding color codes:

IV. Drivers

tcs34725_color_driver.zip 14 KB

None.

VI. Revision History

Document Version

Date of Modification

Modifier

Modified Content

v1.0

2025-11-12

Ling Gaoxing

Initialize the document

v1.1

2025-12-29

Li Zisheng

Added application experiments and production files

v1.2

2025-12-31

Xin Ruili

Create an open version of the document based on the internal document version v1.1.

v1.3

2026-03-29

Xin Ruili

Modified the application experiment section

VII. Relevant Materials

7.1 Chip Datasheet

TCS34725FN Datasheet.pdf 1.5 MB

7.2 Unique Icons for PCB Silkscreen

GraftSense - TCS34725-based Color Recognition Module (Open Version)