简介：这是一份面向Arduino开发者和电子爱好者的TCS34725颜色识别传感器模块资料包，聚焦颜色检测、环境光感应等应用，帮助用户快速解决传感器驱动、数据读取与颜色计算等入门难题。压缩包共14个文件，以ino、PDE示例程序、C++驱动库、Markdown/PDF说明文档以及JPG格式原理图和实物图为代表，整体约450KB，内容精炼且目录清晰。已有620人学习下载，尤其适合正在开展颜色识别课设或智能车、机器人项目的初学者参考。借助其中的电路原理图可梳理模块接线，PDF数据手册能了解芯片引脚、寄存器与I²C通信时序，配套Arduino库和示例代码则涵盖初始化配置、RGB/IR数据读取、颜色空间换算及环境光滤波等关键步骤。整套资料围绕“驱动—读取—计算—抗干扰”链路展开，可帮助读者避开设坑点，快速搭建起可用的颜色识别系统。
1. 从一块 TCS34725 颜色识别传感器模块的命名说起
标题里那串“YX65496”和“190517”是典型的产品 SKU 加 PCB 版本号，后面的“tcs34725程序”则暴露了用户真正想要的东西：寄存器怎么配、数据怎么读、颜色怎么算。TCS34725 颜色识别传感器模块是 AMS 的 RGBC 数字传感器，模块上自带 LDO 和 I2C 上拉，MCU 只需要两组线就能拿到 16 位四通道原始数据。它和 MQ-2 烟雾气敏传感器模块那种纯模拟输出完全不同，属于“给程序做眼睛”的传感器：屏幕校色、色卡比对、产品分拣、智能照明反馈都能用到它。下面我会先把内部光电二极管阵列和寄存器语义讲清楚，再给出不依赖任何厂商库的最小驱动，最后把白平衡和参数调优的坑填平。
2. TCS34725 颜色识别传感器的原理、寄存器映射与动态范围
2.1 四通道光电二极管阵列为什么适合做颜色识别
TCS34725 内部有一个 3×4 的光电二极管阵列，阵列上覆盖着 R、G、B 三组彩色滤光片，以及一组没有任何滤光片的 Clear（透明）通道。当环境光照射到芯片表面时，四个通道同时产生光电流，经过积分型 ADC 量化后，输出 16 位计数。注意“同时”这个细节很重要：如果是分时扫描三色滤光片，运动物体的颜色就会被撕裂，而 TCS34725 是同步采样的，所以它能用来识别传送带上的小零件。
芯片封装上还集成了红外阻断滤波器。这跟 BH1750 这类照度计的差别是本质性的——BH1750 只告诉你“光有多亮”，TCS34725 能告诉你“光是什么颜色”。如果去掉红外阻断，白炽灯下所有颜色都会被红外成分推成偏粉，这也是很多人买回模块后觉得“颜色不准”的第一个隐藏原因。Clear 通道也不是多余的：它吸收的是整个可见光波段的能量，在后面做白平衡归一化和照度估算时，它是抵消光源强度波动的锚点。
2.2 COMMAND 字节与核心寄存器地址表
TCS34725 走的是标准 I2C，7 位从机地址默认 0x29。它内部所有寄存器都是 8 位宽度，颜色数据寄存器则分布在一对 8 位低字节和高字节上。访问任何寄存器之前，必须先发一个 COMMAND 字节，这个字节的高位固定为 1，低 7 位里包含寄存器地址和可选的自增标志。忘了在寄存器地址上 OR 0x80，是新手读回全 0xFF 的第一大原因。
下面是我日常调试最常用的一张寄存器速查表：
| 寄存器 | 地址 | 作用 | 关键位/说明 |
|---|---|---|---|
| ENABLE | 0x00 | 使能控制 | bit0=PON，bit1=AEN，写 0x01 后延时再写 0x03 |
| ATIME | 0x01 | 积分时间 | (256 - ATIME) × 2.4ms |
| WTIME | 0x03 | 等待时间 | 需要 WEN 位配合 |
| AILTL/AILTH | 0x04/0x05 | 低阈值中断 | 16位阈值低字节和高字节 |
| AIHTL/AIHTH | 0x06/0x07 | 高阈值中断 | 16位阈值低字节和高字节 |
| PERS | 0x0C | 中断持久化 | 连续几次超阈值才触发 |
| CONTROL | 0x0F | 增益 | 低2位: 00=1x, 01=4x, 10=16x, 11=60x |
| ID | 0x12 | 芯片ID | TCS34725 应读到 0x44 |
| STATUS | 0x13 | 状态 | bit0=AVALID，表示 ADC 数据可读 |
| CDATAL/H | 0x14/0x15 | Clear 计数 | 16位小端 |
| RDATAL/H | 0x16/0x17 | Red 计数 | 16位小端 |
| GDATAL/H | 0x18/0x19 | Green 计数 | 16位小端 |
| BDATAL/H | 0x1A/0x1B | Blue 计数 | 16位小端 |
表中 0x00 到 0x1B 之间的寄存器地址在写的时候都要加上 COMMAND 位，所以实际发送的第一个字节是 0x80|addr。需要一次性把 C、R、G、B 四个通道都读出来时，可以从 0x14 开始，在 COMMAND 字节里再置位 auto-increment 位 0x20，然后连续读 8 个字节。这里有个容易忽视的细节：TCS34725 的地址是 8 位寄存器地址，auto-increment 只对寄存器地址生效，读取跨过 0x1B 到 0x1C 后会进入中断阈值寄存器，而不是绕回 0x00。所以连续读的时候严格按 8 字节一次，不要贪多。
2.3 积分时间和增益怎么搭配
先把公式记牢：积分时间 = (256 - ATIME) × 2.4ms。ATIME=0xFF 时只有 2.4ms，适合强光；ATIME=0x00 时约 614ms，适合暗光。增益通过 CONTROL 寄存器低 2 位配置，可选 1x、4x、16x、60x。两者共同决定满量程范围和信噪比：增益越高，噪声被放大的比例也越高；积分时间越长，受环境光频闪（比如 50Hz 灯光）影响越大。
| 场景示例 | ATIME | 实际积分 | GAIN | 数据特点 |
|---|---|---|---|---|
| 显示屏校色、强反射面 | 0xF6 | 24ms | 1x | 接近真实色度，亮度足够 |
| 室内正常光照、色卡比对 | 0xD5 | 101ms | 4x | 最常用的起点 |
| 暗色物体、低照度环境 | 0xC0 | 154ms | 16x | 噪声开始增加，需要滤波 |
| 接近黑暗 | 0x00 | 614ms | 60x | 计数很低，只能做趋势判断 |
我一般从 0xD5 加 4x 增益开始，先读一次 STATUS 看 AVALID 置没置位，再判断是否饱和。饱和的判断标准不是 ADC 达到 65535，而是 Clear 通道计数超过 50000 就已经可能让 R/G/B 通道的线性度变差，这个时候往下调积分时间比调增益更有效。反过来，如果 Clear 计数不到 1000，先加积分时间，积分时间到头再加增益。
3. TCS34725 传感器模块的硬件接线与寄存器级最小程序
3.1 模块引脚、电平匹配与 I2C 上拉检查
模块上最常见的丝印是 VIN、GND、SCL、SDA，少数版本多留一个 INT 中断脚。VIN 通常直接进板载 LDO，允许 3~5V 供电，而 I2C 电平由内部稳压输出决定，一般在 3.3V 附近。所以同一块模块接 5V 的 Arduino Uno 和 3.3V 的 ESP32 都可以，真正要确认的只有上拉电阻。
| 平台 | 供电 | I2C 电平 | 注意事项 |
|---|---|---|---|
| Arduino Uno | VIN=5V | 3.3V 模块可兼容 | SDA/SCL 不需要额外分压 |
| ESP32 | VIN=3.3V | 3.3V | 检查模块上拉是否已到 VIN |
| 树莓派 | VIN=3.3V | 3.3V | 使用 /dev/i2c-1，先 sudo i2cdetect -y 1 |
| STM32 | VIN=3.3V | 3.3V | 固件里确认开外部上拉 |
如果模块的 SCL/SDA 上拉电阻是焊在板上的 2.2kΩ 到 VIN，而 VIN 接了 5V，那么总线高电平会被拉到 5V，接 3.3V 的 MCU 就要小心。我一般首选用 3.3V 给模块供电，让整条总线都是 3.3V 电平。
提示：模块的丝印 VCC 和 VIN 有时混用，接 5V 前先确认板载 LDO 型号，耐压不够的板子会直接烧稳压器。
3.2 Arduino 寄存器级最小驱动
下面这段不依赖 Adafruit 库，能直接跑在 Uno、Mega 或 ESP32 上。核心动作只有三个：写寄存器、读寄存器、读 16 位通道。
#include <Wire.h> #define TCS34725_ADDR 0x29 #define CMD_BIT 0x80 void writeReg(uint8_t reg, uint8_t val) { Wire.beginTransmission(TCS34725_ADDR); Wire.write(CMD_BIT | reg); Wire.write(val); Wire.endTransmission(); } uint8_t readReg(uint8_t reg) { Wire.beginTransmission(TCS34725_ADDR); Wire.write(CMD_BIT | reg); Wire.endTransmission(false); Wire.requestFrom((uint8_t)TCS34725_ADDR, (uint8_t)1); return Wire.read(); } uint16_t readChannel(uint8_t regLo) { uint8_t lo = readReg(regLo); uint8_t hi = readReg(regLo + 1); return (uint16_t)hi << 8 | lo; }读取通道时，先读低字节再读高字节。TCS34725 的 16 位寄存器并不是锁存的，如果两次读取之间发生了一次 ADC 更新，低字节和高字节可能来自不同帧。这个问题在连续高速读取时会出现，表现为颜色数据偶发跳变。稳妥做法是先读 STATUS，只有 AVALID=1 时再读通道数据，读完一组后立即丢弃缓冲区里的旧状态，不满足就等下一周期。
按这个逻辑，初始化函数可以这么写：
void initTCS34725() { writeReg(0x00, 0x01); // PON=1，打开内部振荡器 delay(3); writeReg(0x00, 0x03); // PON | AEN，启动 ADC 采样 writeReg(0x01, 0xD5); // ATIME: 101ms writeReg(0x0F, 0x01); // CONTROL: 增益 4x（低2位=01） delay(150); // 等第一次积分完成 } bool readRGBC(uint16_t &c, uint16_t &r, uint16_t &g, uint16_t &b) { uint8_t status = readReg(0x13); if (!(status & 0x01)) return false; c = readChannel(0x14); r = readChannel(0x16); g = readChannel(0x18); b = readChannel(0x1A); return true; }注意初始化时 PON 和 AEN 要分开写，PON 之后至少等 2.4ms 再开 AEN，否则芯片的模拟状态机还没起来，第一次采样可能落入未知状态。读 STATUS 这一步看似多余，但能挡掉一半以上的偶发跳动，我在实际项目里从不让主循环无条件读取。
3.3 树莓派上用 smbus2 复现同一套流程
Python 里最直接的移植版本如下：
import smbus2 import time ADDR = 0x29 CMD = 0x80 bus = smbus2.SMBus(1) def write_reg(reg, val): bus.write_byte_data(ADDR, CMD | reg, val) def read_reg(reg): return bus.read_byte_data(ADDR, CMD | reg) def read_u16(reg): lo = read_reg(reg) hi = read_reg(reg + 1) return (hi << 8) | lo write_reg(0x00, 0x01) time.sleep(0.01) write_reg(0x00, 0x03) write_reg(0x01, 0xD5) write_reg(0x0F, 0x01) time.sleep(0.15) while True: if read_reg(0x13) & 0x01: c = read_u16(0x14) r = read_u16(0x16) g = read_u16(0x18) b = read_u16(0x1A) print(f"R={r} G={g} B={b} C={c}") time.sleep(0.3)这里没用 block-read 自动递增读 8 字节，原因跟树莓派内核 i2c 驱动的实现有关：单字节加自动递增的复合事务在部分内核版本上会因为时钟延展被从机 NACK，而逐字节读虽然多花几十微秒，但每次事务都干净利落。实际跑下来单次读取四个通道大概 1ms 左右，对颜色识别来说没有任何压力。如果后续要做高速在线分拣，建议直接上 STM32 这类硬 I2C 外设，并且用 DMA，在裸机程序里才能压到 100Hz 以上的稳定采样率。
4. 颜色识别数据处理：白平衡、色温与照度换算
4.1 raw 数据为什么不能直接用
从 TCS34725 读回的 C、R、G、B 是 ADC 计数，它同时受光源强度、积分时间、增益、颜色反射率四个因素影响。同一块绿色积木，在窗边自然光和 LED 台灯下读出的 RGB 比例完全不一样；同一光源下，把积分时间加倍，所有通道数值也跟着翻倍。所以直接用 raw 值去判断颜色，换一个光照条件就失效，必须做归一化处理。
最常见的归一化是除以 Clear 通道：r' = R/C，g' = G/C，b' = B/C。这个做法能补偿光源强度波动，但补偿不了光源色温变化。在暖黄光下看白纸，R/C 会明显大于 B/C，如果不做白平衡，白纸也会被判断成淡橙色。这也是“颜色识别传感器模块”在真实项目里必须带一套标定流程的原因。
4.2 白点标定的具体实现
先在目标光源下放一块标准白板（没有就用打印纸叠三层，尽量选喷墨高光相纸），采样 20 次取中位数作为参考值。之后所有新样本都除以这个基准，再映射到 0~255。
def take_sample(n=10): vals = [] while len(vals) < n: if read_reg(0x13) & 0x01: c = read_u16(0x14) r = read_u16(0x16) g = read_u16(0x18) b = read_u16(0x1A) vals.append((r, g, b, c)) time.sleep(0.02) return vals def median(vals, idx): col = sorted(sample[idx] for sample in vals) return col[len(col) // 2] def calibrate_white(): s = take_sample(20) return [median(s, idx) for idx in range(4)] # r, g, b, c def to_rgb(sample, ref): r, g, b, c = sample rr, gg, bb, cc = ref out = [ (r / c) / (rr / cc) * 255, (g / c) / (gg / cc) * 255, (b / c) / (bb / cc) * 255 ] return [max(0, min(255, int(x))) for x in out]注意这里除法全部保留浮点，最后再截断到 0~255。如果在 MCU 上用整数除法先算比例再缩放，暗色区域会直接归零，亮色区域饱和，动态范围白白丢了一半。中位数而不是平均数的原因也很简单：翻盖动作引起的机械振动会造成个别帧毛刺，平均数会被一两个坏点拉偏，中位数稳健得多。标定结果可以存到 EEPROM，换光源时只重算 ref 那一组数据，算法代码不用动。
注意：白板采样时手不要悬在传感器上方，阴影本身就会改变白平衡参考值。
4.3 色温和照度的经验换算
有了白平衡后的 RGB，就能估算光源色温。最实用的做法不是套多项式，而是用 R/B 比值做分段线性插值。暖白光源 R/B 高，冷白光源 R/B 低，这个关系在 TCS34725 的响应范围内近似单调。我常用的锚点数据是：R/B=2.4 对应 2800K，R/B=1.4 对应 4000K，R/B=0.9 对应 6000K，R/B=0.75 对应 7500K，中间值直接按比例拉直线。验证方法很简单：手机屏幕开一张纯白图，把屏幕色温切到 4000K、6500K 各读几次，插值结果和预设值之间的偏差能控制在 300K 上下，足够做光源类型判断。
照度估算则不要迷信手册系数。TCS34725 的 Clear 通道没有标准的余弦视场校正，加上模块外壳开窗和透镜遮挡差异，不同批次的换算系数可能差 30%。我一般用照度计在 500 lux 和 2000 lux 两个点标定一个线性系数：lux = K × C_std，其中 C_std 是先把积分时间统一折算到 2.4ms、增益统一折算到 1x 后的 Clear 计数。标定时让传感器平面正对光源，因为光电二极管的响应会随入射角余弦衰减，斜着放会让系数失真。
| 光源 | 典型 R/B 比 | 估算色温 | 是否需要白平衡 |
|---|---|---|---|
| 白炽灯 | 2.1~2.5 | 2700K 左右 | 必须 |
| 暖白 LED | 1.2~1.5 | 4000K 左右 | 建议 |
| 正白 LED | 0.9~1.1 | 5500~6500K | 建议 |
| 阴天自然光 | 0.8~0.9 | 6500K 以上 | 可选 |
这套流程跑下来，颜色识别就从一个“读寄存器”问题变成一个“标定参数”问题：模块 API 基本不动，换场景只需要重采白点、重设积分时间和增益。
5. 传感器模块参数调优与三种常见故障定位
5.1 三个可直接套用的参数模板
| 场景 | ATIME | GAIN | 采样次数 | 关键设置 |
|---|---|---|---|---|
| 屏幕校色/发光体 | 0xF6 (24ms) | 1x | 连续 5 次取平均 | 传感器贴近屏幕，避免环境杂散光 |
| 物体颜色分类 | 0xD5 (101ms) | 4x | 10 次取中值 | 加乳白扩散片减弱方向性 |
| 微弱环境光监控 | 0xC0 (154ms) | 16x | 20 次取中值 | 避开 50Hz 灯光频闪下读取 |
“加乳白扩散片”是很多成品颜色传感器上不难见到的做法。把半透明白色塑料片盖在传感器窗口前，能让光线在进入光电二极管前先混匀，减少镜面反射带来的高光过曝。但不建议把扩散片直接紧贴芯片，留 1~2mm 空气间隙能显著降低暗角误差。
5.2 数据跳变和颜色偏粉偏绿时先查什么
先看 STATUS 的 AVALID 位，再决定是否丢弃数据。ADC 没有更新完就读，拿到的一定是上一帧混着下一帧的半截数据。其次看 Clear 通道是否接近饱和。此时虽然颜色数据看上去也在变化，但 R/G/B 比例的斜率已经不对，偏粉偏绿多半是饱和后非线性导致。第三，检查供电纹波。模块的 LDO 在低噪声场景下够用，但跟电机共用电源时，Clear 通道计数会周期性地整体抬高，我遇到过的跳变项目里这一步占了 80%。
5.3 地址冲突和库函数失效的兜底方法
多个 I2C 设备共存时，先用i2cdetect -y 1（Linux）或 I2C 扫描代码看看 0x29 是否被其他设备占用。如果冲突，多数模块预留了 ADDR 跳线，可以改成其他地址；没留跳线的，只能换总线或者用 I2C 多路复用器。厂商库读不到数据时，回到寄存器级代码打印 ID、ENABLE、STATUS 三个值，十有八九能定位到是上拉问题还是初始化顺序问题。把写寄存器、读寄存器、取样本这三个原子函数固定下来，后续换平台就能直接平移。
本文还有配套的精品资源，点击获取
