ESP32-S3驱动TCS34725颜色传感器：I2C通信与RGB/HSL转换实战
ESP32-S3驱动TCS34725颜色传感器：I2C通信与RGB/HSL转换实战
最近在做一个智能家居项目，需要识别物体的颜色，比如判断水果的成熟度或者识别乐高积木的颜色。我选用了TCS34725这款数字颜色传感器，它精度高、使用简单，通过I2C接口就能读取RGB数据。今天我就来分享一下如何用ESP32-S3驱动它，并且把原始的RGB数据转换成更直观的HSL色彩空间。整个过程我会手把手带你走一遍，从硬件连接到代码编写，最后还会分享几个调试时容易踩的坑。
1. 认识TCS34725颜色传感器
TCS34725是一款非常流行的数字颜色传感器，它的核心是AMS公司的TCS3472XFN芯片。简单来说，它就像一个微型的“电子眼”，能感知环境中的红、绿、蓝（RGB）三原色以及环境光的强度（清晰光感应值）。
它内部集成了红外阻隔滤光片，这个设计很关键。因为环境光里含有大量人眼看不见的红外光，如果不过滤掉，就会干扰颜色识别的准确性。这个滤光片能最大程度地减少红外光谱成分，让我们得到更精确的颜色测量结果。
这款传感器有几个特点很适合我们玩嵌入式：
- 高灵敏度：在很宽的光照范围内都能工作。
- 通信简单：通过I2C接口通信，只需要两根线（SDA, SCL）。
- 功能丰富：自带环境光强检测和可屏蔽中断功能，可以做智能唤醒。
它的基本参数如下：
| 参数 | 规格 |
|---|---|
| 工作电压 | 3.3V - 5V |
| 工作电流 | 2.5μA - 330μA |
| 输出方式 | I2C |
| 引脚数量 | 7 Pin |
| I2C设备地址 | 0x29 (7位地址) |
注意：这里说的0x29是7位I2C设备地址。在8位地址格式下（读写位包含在内），写地址是0x52，读地址是0x53。我们编程时通常使用7位地址。
2. 硬件连接与引脚定义
TCS34725模块通常有7个引脚，我们只需要连接其中4个就能让它工作起来。下面以ESP32-S3开发板为例，说明如何连接。
首先，我们得知道ESP32-S3和TCS34725各自管脚的定义。
TCS34725模块引脚（常见）：
- VCC：电源正极，接3.3V或5V（ESP32-S3的3.3V）
- GND：电源地，接GND
- SDA：I2C数据线
- SCL：I2C时钟线
- INT：中断输出引脚（本例暂不使用，可悬空）
- LED：控制板载补光LED（本例暂不使用）
ESP32-S3引脚选择： ESP32-S3的几乎所有GPIO都可以配置为I2C功能。为了布线方便，我们可以选择一组空闲的GPIO。在提供的驱动代码中，作者使用了GPIO1和GPIO2。
根据代码中的宏定义：
#define TCS34725_SCL_PIN 1 #define TCS34725_SDA_PIN 2因此，连接方式非常简单：
| TCS34725引脚 | ESP32-S3引脚 | 连接线 |
|---|---|---|
| VCC | 3.3V | 红色杜邦线 |
| GND | GND | 黑色杜邦线 |
| SDA | GPIO2 | 蓝色杜邦线 |
| SCL | GPIO1 | 黄色杜邦线 |
提示：如果你使用的开发板GPIO1和GPIO2被占用了（比如用于串口下载），可以换成其他任意一组GPIO，比如GPIO8和GPIO9，只需要在代码中修改
TCS34725_SCL_PIN和TCS34725_SDA_PIN的定义即可。记得要接上拉电阻，通常模块上已经集成，如果没有，需要在SDA和SCL线上各接一个4.7kΩ电阻到3.3V。
3. 软件驱动编写：从零实现I2C通信
虽然ESP32-S3有硬件I2C外设，但为了让大家彻底理解I2C通信的时序，原始代码使用了“软件模拟I2C”（也叫GPIO模拟）的方式。这种方式代码更直观，便于学习和调试。我们分两部分来看：头文件定义和源文件实现。
3.1 头文件bsp_tcs34725.h解析
头文件主要做了三件事：包含必要的库、定义硬件引脚和寄存器地址、声明数据类型和函数。
首先是一堆ESP-IDF必要的头文件，比如操作GPIO的driver/gpio.h，提供延时功能的freertos/task.h等。
接着是硬件引脚定义，就是我们刚才看到的SCL和SDA引脚号。然后是一组宏定义，用来方便地控制引脚的电平和方向：
#define SDA_OUT() gpio_set_direction(TCS34725_SDA_PIN, GPIO_MODE_OUTPUT) #define SDA_IN() gpio_set_direction(TCS34725_SDA_PIN, GPIO_MODE_INPUT) #define SDA_GET() gpio_get_level(TCS34725_SDA_PIN) #define SDA(x) gpio_set_level(TCS34725_SDA_PIN, (x?1:0)) #define SCL(x) gpio_set_level(TCS34725_SCL_PIN, (x?1:0))SDA_OUT()和SDA_IN()用于切换SDA线是输出还是输入模式（I2C通信中SDA线方向会变化）。SDA(x)和SCL(x)用于设置引脚输出高电平(1)或低电平(0)。
核心寄存器地址定义： 这部分是驱动传感器的关键，所有对传感器的操作都归结为读写这些寄存器。代码里定义得非常全，我挑几个最常用的解释一下：
TCS34725_ADDRESS (0x29)：传感器的7位I2C地址。TCS34725_ENABLE (0x00)：使能寄存器。写PON位(0x01)上电，写AEN位(0x02)开启颜色转换。TCS34725_ATIME (0x01)：积分时间寄存器。设置传感器每次采样的时间，时间越长，精度越高，但速度越慢。代码中选择了TCS34725_INTEGRATIONTIME_24MS。TCS34725_CONTROL (0x0F)：增益控制寄存器。可以设置1x, 4x, 16x, 60x增益，放大信号。代码中选择了TCS34725_GAIN_1X。TCS34725_ID (0x12)：ID寄存器。读这个寄存器可以验证传感器是否连接成功，TCS34725的ID是0x44。TCS34725_STATUS (0x13)：状态寄存器。其中的AVALID位(0x01)为1时，表示一次颜色转换完成，可以读取数据了。CDATAL/RDATAL/GDATAL/BDATAL (0x14/0x16/0x18/0x1A)：这就是我们最终要读取的清晰光、红、绿、蓝通道的数据寄存器（低字节）。
最后，代码定义了两个结构体来存放数据：
typedef struct{ unsigned short c; // 清晰光通道值 [0-65535] unsigned short r; // 红色通道值 unsigned short g; // 绿色通道值 unsigned short b; // 蓝色通道值 }COLOR_RGBC; typedef struct{ unsigned short h; // 色相 [0, 360] unsigned char s; // 饱和度 [0, 100] unsigned char l; // 亮度 [0, 100] }COLOR_HSL;COLOR_RGBC存放传感器读出的原始数据，COLOR_HSL存放转换后的HSL值。
3.2 源文件bsp_tcs34725.c核心函数讲解
源文件代码较长，我们抓住主干，理解几个最核心的函数。
第一步：GPIO和I2C底层驱动TC34725_GPIO_Init()函数初始化ESP32-S3的GPIO引脚为输出模式，并启用内部上拉电阻。内部上拉对于I2C总线是必要的，可以保证总线在空闲时为高电平。
IIC_Start(),IIC_Stop(),Send_Byte(),Read_Byte()等函数实现了最基础的I2C通信时序。如果你刚开始学I2C，可以对照时序图慢慢看。简单说，Start是发起通信，Stop是结束通信，Send_Byte发送一个字节（8位数据），Read_Byte读取一个字节。
第二步：封装好的读写函数TCS34725_I2C_Write和TCS34725_I2C_Read函数在底层驱动之上，封装了完整的I2C帧的发送和接收过程，包括发送设备地址、等待应答、发送/接收数据等。
TCS34725_Write和TCS34725_Read是面向TCS34725寄存器的读写函数。这里有个细节：TCS34725的命令寄存器最高位（第7位）必须置1，这就是代码中subAddr | TCS34725_COMMAND_BIT的作用。
第三步：传感器初始化和数据读取这是应用层最关心的两个函数。
TCS34725_Init()是初始化函数，流程如下：
- 初始化GPIO。
- 读取传感器ID，验证连接是否成功（ID应为0x44或0x4D）。
- 设置积分时间为24ms。
- 设置增益为1倍。
- 先后使能传感器（上电
PON）和颜色转换器(AEN)。
uint8_t TCS34725_Init(void) { uint8_t id=0; TC34725_GPIO_Init(); TCS34725_Read(TCS34725_ID, &id, 1); if( (id==0x4D) | (id==0x44) ) { TCS34725_SetIntegrationTime(TCS34725_INTEGRATIONTIME_24MS); TCS34725_SetGain(TCS34725_GAIN_1X); TCS34725_Enable(); return 1; // 初始化成功 } return 0; // 初始化失败，检查接线 }TCS34725_GetRawData()是获取原始RGB数据的函数。它首先读取状态寄存器，检查AVALID位，只有该位为1（表示数据就绪）时，才会去读取四个通道的数据寄存器，并将16位数据组合起来存入COLOR_RGBC结构体。
uint8_t TCS34725_GetRawData(COLOR_RGBC *rgbc) { uint8_t status = TCS34725_STATUS_AVALID; TCS34725_Read(TCS34725_STATUS, &status, 1); if(status & TCS34725_STATUS_AVALID) { rgbc->c = TCS34725_GetChannelData(TCS34725_CDATAL); rgbc->r = TCS34725_GetChannelData(TCS34725_RDATAL); rgbc->g = TCS34725_GetChannelData(TCS34725_GDATAL); rgbc->b = TCS34725_GetChannelData(TCS34725_BDATAL); return 1; // 数据有效 } return 0; // 数据未就绪 }4. 核心算法：从RGB到HSL色彩空间转换
传感器直接给我们的r,g,b,c是原始计数值。c是清晰光总值，r,g,b分别是红、绿、蓝通道的计数值。为了得到更符合人眼感知的颜色信息，我们通常先将其归一化，再转换到HSL色彩空间。
HSL代表：
- H (Hue) 色相：是什么颜色？比如红、黄、绿、蓝。范围0-360度。
- S (Saturation) 饱和度：颜色的鲜艳程度。范围0-100%。
- L (Lightness) 亮度：颜色的明暗程度。范围0-100%。
代码中的RGBtoHSL函数完成了这个转换。我们来拆解一下它的步骤：
归一化：将
r,g,b分别除以c（清晰光总值），并映射到0-100的范围。这步是为了消除环境光强变化的影响，得到纯粹的颜色比例。uint8_t r = Rgb->r*100/Rgb->c; uint8_t g = Rgb->g*100/Rgb->c; uint8_t b = Rgb->b*100/Rgb->c;计算亮度(L)：亮度是
max(r,g,b)和min(r,g,b)的平均值。Hsl->l = (maxVal + minVal) / 2;计算饱和度(S)：饱和度取决于亮度。公式略有不同，但核心思想是颜色分量之间的差异(
difVal)相对于最大可能值的比例。if(Hsl->l <= 50) Hsl->s = difVal*100 / (maxVal + minVal); else Hsl->s = difVal*100 / (200 - (maxVal + minVal));计算色相(H)：这是最复杂的一步，需要判断哪个颜色分量最大，然后根据另外两个分量的比例来计算角度。代码中用
if-else分支处理了r、g、b分别为最大值的情况，并确保结果在0-360度之间。
这个转换算法是颜色科学中的标准方法，理解其原理后，你可以直接使用这个函数，得到更直观的HSL颜色值。
5. 实战应用与调试技巧
最后，我们看看如何在主函数app_main中调用这些驱动。
#include <stdio.h> #include "bsp_tcs34725.h" void app_main(void) { TCS34725_Init(); // 初始化传感器 printf("TCS34725 Color Sensor Start\r\n"); delay_1ms(1000); // 稍作延时，等待传感器稳定 while(1) { // 读取原始RGB数据 if(TCS34725_GetRawData(&rgb)) { // 将RGB转换为HSL RGBtoHSL(&rgb, &hsl); // 打印原始RGB和转换后的HSL值 printf("R=%d G=%d B=%d C=%d\r\n", rgb.r, rgb.g, rgb.b, rgb.c); printf("H=%d S=%d L=%d\r\n\r\n", hsl.h, hsl.s, hsl.l); } else { printf("Data not ready.\r\n"); } delay_1ms(1000); // 每秒读取一次 } }把代码编译下载到ESP32-S3，打开串口监视器（波特率115200），你应该能看到每秒输出一组的颜色数据。试着把不同颜色的物体放在传感器上方，观察R,G,B和H,S,L值的变化。
几个我踩过的坑和调试技巧：
- I2C地址不对：这是最常见的问题。务必确认地址是
0x29（7位）。如果读ID失败，首先用逻辑分析仪或示波器抓一下I2C波形，看起始信号、地址和数据对不对。也可以尝试扫描I2C总线上的设备。 - 数据总是零或不变：检查
TCS34725_Enable()函数是否被正确调用。确保PON和AEN位都被置1了。另外，检查一下TCS34725_GetRawData函数中读取状态寄存器的逻辑，确保是在数据有效(AVALID=1)时才去读数据。 - HSL转换结果异常：注意原始代码中
RGBtoHSL函数的第一步归一化：Rgb->r*100/Rgb->c。这里存在一个隐患，如果Rgb->c为0，会导致除以0的错误。在实际使用中，c值很少为0，但为了代码健壮性，最好加一个判断：if(Rgb->c != 0)。 - 响应速度慢：默认积分时间是24ms，如果你需要更快的采样率，可以修改
TCS34725_SetIntegrationTime的参数，比如换成TCS34725_INTEGRATIONTIME_2_4MS。但要注意，积分时间越短，进入传感器的光量越少，数值会变小，在暗环境下可能精度会下降，此时可以适当提高增益(TCS34725_SetGain)。
好了，关于ESP32-S3驱动TCS34725颜色传感器的全部内容就分享到这里。代码虽然看起来长，但结构清晰，从底层IO模拟到上层应用都涵盖了。你可以直接使用这些代码，也可以将其改造成使用ESP32-S3硬件I2C的方式，性能会更好。希望这篇教程能帮你顺利点亮你的颜色传感器。