Python颜色识别实战：基于行空板与TCS34725传感器的拾色游戏开发

1. 项目概述：当行空板遇见颜色传感器

如果你玩过一些创意编程或者图形化编程，对“颜色识别”这个功能应该不陌生。但当我们从图形化的“拖拽积木”进阶到用Python直接操控硬件时，那种感觉是完全不同的。今天要聊的这个“拾色游戏”项目，就是一个绝佳的切入点。它的核心很简单：用一块行空板，连接一个TCS34725颜色传感器，写一段Python代码，让硬件能“看见”并“说出”眼前物体的颜色。听起来像是电子版的“看图说话”，但背后串联起来的是I2C通信、传感器数据解析、RGB到HSV的色彩空间转换，以及如何将枯燥的数据转化为直观的交互反馈。

这个项目非常适合已经熟悉Python基础语法，想要迈入开源硬件和物联网领域的朋友。它不像复杂的机器人项目那样让人望而生畏，也不像单纯的软件脚本那样缺乏实感。通过它，你能亲手搭建一个物理世界与数字世界的桥梁，理解传感器如何成为程序的“眼睛”。无论是想做个自动分拣乐高积木的小装置，还是为你的艺术项目添加一个色彩捕捉的互动环节，这个项目提供的核心技能都能派上用场。接下来，我会带你从硬件连接到代码编写，再到游戏逻辑设计，完整地走一遍这个“拾色”之旅，并分享一些我调试过程中踩过的坑和总结的技巧。

2. 硬件选型与连接：为什么是TCS34725？

2.1 核心硬件解析：行空板与TCS34725的默契搭档

选择行空板作为主控，很大程度上是因为它极大地简化了开源硬件入门的环境配置。它本质上是一个高度集成、专为教育优化的微型Linux计算机，预装了Python和常用的库，自带屏幕和丰富的接口。这意味着你不需要像使用Arduino那样额外配置开发环境和烧录工具，插上USB线，打开网页IDE就能开始编程，对于从纯软件转向硬件的开发者来说，门槛降低了一大截。

而颜色传感器TCS34725，可以说是入门级颜色识别中的“明星器件”。它内部集成了RGB（红绿蓝）滤光片阵列和光电二极管，能够直接输出环境光中红、绿、蓝和透明光（Clear）四个通道的原始数据。相比于一些只能输出数字颜色编码的传感器，TCS34725提供原始数据的好处是，我们可以通过计算得到更丰富的色彩信息，比如色温、亮度，甚至进行更精确的白平衡校准。它的精度和灵敏度对于教学和大多数创意项目来说已经绰绰有余，并且它采用标准的I2C通信协议，与行空板的连接只需要两根信号线（SDA, SCL）和电源线，接线非常简洁。

注意：市面上有些更廉价的颜色传感器模块，输出的是模拟信号或自定义数字协议，需要额外的ADC（模数转换）或复杂的时序解析。TCS34725的I2C数字接口使其与行空板这类主控的集成变得异常简单和稳定，这是选型时一个关键的技术决策点。

2.2 物理连接与电路检查

接线是硬件项目的第一步，也是后续所有问题的根源所在，必须仔细。TCS34725模块通常有4到6个引脚，我们只需要关注其中四个：VCC（电源正极）、GND（电源负极）、SDA（数据线）、SCL（时钟线）。

1. 电源连接：将TCS34725模块的VCC引脚连接到行空板的任意一个3.3V电源引脚，GND连接到行空板的任意GND引脚。务必确认是3.3V，大多数行空板的GPIO电平是3.3V，如果误接5V，有可能损坏传感器。
2. I2C信号连接：将模块的SDA引脚连接到行空板的SDA引脚（通常是GPIO2），SCL引脚连接到行空板的SCL引脚（通常是GPIO3）。行空板的引脚定义可能会因版本略有不同，请以官方丝印或文档为准。
3. 上拉电阻：I2C总线需要上拉电阻才能稳定工作。幸运的是，行空板内部的I2C接口通常已经内置了上拉电阻。如果你使用的是完全裸露的TCS34725芯片而非模块，或者连接后通信不稳定，则需要在SDA和SCL线上各接一个4.7kΩ到10kΩ的电阻到3.3V。

连接好后，一个快速的检查方法是使用行空板系统自带的或通过pip安装的I2C检测工具。通过SSH或终端连接到行空板，运行i2cdetect -y 1命令（假设I2C总线编号为1）。如果一切正常，你应该能看到一个设备地址（通常是0x29）出现在输出列表中。如果看不到，请立即断电，检查接线是否正确、接触是否良好、电源电压是否匹配。

3. 软件环境与驱动准备

3.1 Python库的安装与选择

行空板默认的Python环境已经非常完善，但我们仍需要专门操作TCS34725的库。这里有两个主流选择：Adafruit_CircuitPython_TCS34725和tcs34725。我强烈推荐使用Adafruit_CircuitPython_TCS34725，因为它是Adafruit维护的，文档齐全，生态良好，并且是“CircuitPython”库系列的一部分，虽然行空板运行的是标准CPython，但这个库的兼容层做得很好，可以直接使用。

打开行空板的终端（通过Web SSH或直接连接显示器键盘），使用pip进行安装：

pip3 install adafruit-circuitpython-tcs34725

这个命令会自动安装该库及其依赖（比如adafruit-blinka，这是一个在非CircuitPython硬件上模拟CircuitPython硬件API的兼容层）。安装过程如果遇到网络问题，可以考虑使用国内镜像源，例如：

pip3 install adafruit-circuitpython-tcs34725 -i https://pypi.tuna.tsinghua.edu.cn/simple

3.2 初始化传感器与基础测试

安装好库之后，我们可以先写一个最简单的测试脚本，验证硬件和软件是否协同工作。创建一个名为color_test.py的文件。

import time import board import busio import adafruit_tcs34725 # 初始化I2C总线 i2c = busio.I2C(board.SCL, board.SDA) # 初始化TCS34725传感器 sensor = adafruit_tcs34725.TCS34725(i2c) # 修改传感器的积分时间和增益（可选，用于适应不同光照条件） # sensor.integration_time = 50 # 积分时间，单位毫秒，范围2.4ms - 614.4ms # sensor.gain = 4 # 增益，可选1, 4, 16, 60 print(“传感器初始化成功！芯片ID: 0x{:02X}”.format(sensor.chip_id)) while True: # 读取原始RGB和Clear值 raw_r, raw_g, raw_b, raw_c = sensor.color_raw # 读取计算后的RGB颜色值（0-255） r, g, b = sensor.color_rgb_bytes print(“原始值 -> R: {:4d}, G: {:4d}, B: {:4d}, C: {:4d}”.format(raw_r, raw_g, raw_b, raw_c)) print(“RGB字节 -> R: {:3d}, G: {:3d}, B: {:3d}”.format(r, g, b)) print(“-” * 30) time.sleep(1)

运行这个脚本，你应该能看到终端里每秒打印出一组数据。用手电筒照射传感器或放置不同颜色的物体在传感器上方，观察数值的变化。如果数值没有变化，或者提示I2C错误，请回到上一步检查硬件连接。

实操心得：color_raw返回的是传感器的原始计数，其最大值受integration_time（积分时间）影响。积分时间越长，计数越高，信噪比越好，但采样速度越慢。在光线较暗的环境下，可以适当增加积分时间和增益。color_rgb_bytes是库内部根据原始值和一些内置校准系数计算出的归一化RGB值，更适合直接用于颜色显示和比较。

4. 核心原理：从RGB数据到颜色识别

4.1 RGB色彩空间与它的局限性

传感器直接给我们的是RGB值，这是最基础的加色模型。但是，用RGB值来判断“这是什么颜色”并不直观。比如，深红色(150, 0, 0)和亮红色(255, 50, 50)在RGB空间里是两个点，计算它们的欧氏距离会比较大，但人眼都会认为它们是“红色”。此外，环境光强度的变化会同时影响R、G、B三个值，导致颜色判断不稳定。

因此，直接比较RGB值来做颜色匹配是非常脆弱和不准确的。我们需要一个对亮度变化不敏感的色彩空间。

4.2 转换至HSV色彩空间：色相是关键

HSV（色相、饱和度、明度）色彩空间更适合颜色识别。其中：

• 色相（Hue）：表示颜色的种类（如红、黄、绿、蓝），是一个0-360度的角度值。这是判断“是什么颜色”的核心指标。
• 饱和度（Saturation）：表示颜色的纯度或鲜艳程度，0%（灰色）到100%（纯色）。
• 明度（Value）：表示颜色的亮度，0%（黑色）到100%（白色）。

将RGB转换到HSV后，我们主要依据**色相（H）**来区分颜色。无论颜色是深是浅（明度V变化），是鲜艳还是暗淡（饱和度S变化），只要色相在一个范围内，我们就可以认为它是同一种颜色。这极大地提高了识别的鲁棒性。

Python的colorsys库提供了现成的转换函数。我们可以写一个辅助函数：

import colorsys def rgb_to_hsv(r, g, b): """将0-255范围的RGB转换为0-1范围的HSV""" r_norm, g_norm, b_norm = r / 255.0, g / 255.0, b / 255.0 h, s, v = colorsys.rgb_to_hsv(r_norm, g_norm, b_norm) # 将色相从0-1转换为0-360度 h_deg = h * 360.0 return h_deg, s, v def get_color_name(h, s, v): """根据HSV值返回颜色名称""" # 定义常见颜色的色相范围（单位：度） color_ranges = { ‘red’: [(0, 15), (345, 360)], ‘orange’: [(15, 45)], ‘yellow’: [(45, 75)], ‘green’: [(75, 165)], ‘cyan’: [(165, 195)], ‘blue’: [(195, 255)], ‘purple’: [(255, 285)], ‘pink’: [(285, 345)], } # 如果饱和度或明度太低，则认为是无色（黑、白、灰） if s < 0.2 or v < 0.2: return ‘white’ if v > 0.5 else ‘black’ if v < 0.1 else ‘gray’ # 遍历范围，判断色相落在哪个区间 for color_name, ranges in color_ranges.items(): for range_start, range_end in ranges: if range_start <= h < range_end: return color_name return ‘unknown’

这个get_color_name函数是一个基础版本。你可以通过调整color_ranges字典中的范围来微调颜色识别的准确度，这需要你根据实际传感器和测试环境进行校准。

5. 游戏逻辑设计与实现

5.1 “拾色游戏”的玩法设计

一个简单的游戏可以这样设计：程序随机在屏幕上显示一个颜色名称（如“红色”），玩家需要在规定时间内，找到一个该颜色的物体，并将其放到颜色传感器上。如果传感器识别出的颜色与目标颜色匹配，则得分，否则失败。游戏可以有多轮，难度可以随着轮次增加（如时间缩短、颜色区分度变小）。

这个设计包含了几个关键模块：

1. 目标生成器：随机从预定义的颜色列表中选取一个作为目标。
2. 游戏状态机：管理“准备”、“进行中”、“成功”、“失败”、“结束”等状态。
3. 计时器：控制每一轮的可用时间。
4. 反馈系统：通过屏幕显示、LED灯或声音给玩家即时反馈。

5.2 代码架构与核心循环

我们将使用行空板自带的unihiker库来进行图形化显示，它比Tkinter更轻量，对行空板优化更好。下面是一个简化但完整的游戏核心框架：

import time import random from unihiker import GUI from pinpong.board import Board from pinpong.extension.unihiker import * import adafruit_tcs34725 import busio import board import colorsys # 初始化行空板GUI和I2C Board().begin() gui = GUI() i2c = busio.I2C(board.SCL, board.SDA) sensor = adafruit_tcs34725.TCS34725(i2c) # 预定义游戏颜色（名称和对应的HSV色相范围中点） game_colors = { ‘red’: 0, ‘orange’: 30, ‘yellow’: 60, ‘green’: 120, ‘blue’: 240, ‘purple’: 270, } # 游戏参数 round_time = 10 # 每轮秒数 score = 0 round_num = 1 total_rounds = 5 # 创建UI组件 title_text = gui.draw_text(x=120, y=30, text=‘拾色游戏！’, font_size=20) target_color_text = gui.draw_text(x=120, y=80, text=‘目标颜色：’, font_size=16) countdown_text = gui.draw_text(x=120, y=120, text=‘时间：10s’, font_size=16) result_text = gui.draw_text(x=120, y=160, text=‘’, font_size=16, color=‘blue’) score_text = gui.draw_text(x=120, y=200, text=‘得分：0’, font_size=16) def get_current_color_name(): """读取传感器并返回判断的颜色名称""" r, g, b = sensor.color_rgb_bytes h, s, v = rgb_to_hsv(r, g, b) return get_color_name(h, s, v) # 使用前面定义的函数 def start_round(target_color): """开始一轮游戏""" start_time = time.time() remaining_time = round_time while remaining_time > 0: # 更新倒计时 countdown_text.config(text=‘时间：{}s’.format(int(remaining_time))) # 读取当前颜色 current_color = get_current_color_name() # 检查是否匹配 if current_color == target_color: return True, remaining_time # 成功，返回剩余时间 # 计算剩余时间 elapsed = time.time() - start_time remaining_time = round_time - elapsed time.sleep(0.1) # 短暂休眠，避免CPU占用过高 return False, 0 # 超时，失败 # 主游戏循环 for _ in range(total_rounds): # 随机选择目标颜色 target_color_name = random.choice(list(game_colors.keys())) target_color_text.config(text=‘目标颜色：’ + target_color_name, color=target_color_name) result_text.config(text=‘请将{}色物体放在传感器上！’.format(target_color_name)) # 开始本轮 success, time_left = start_round(target_color_name) # 处理结果 if success: score += int(time_left) # 剩余时间作为加分 result_text.config(text=‘成功！+{}分’.format(int(time_left)), color=‘green’) else: result_text.config(text=‘时间到！未找到正确颜色。’, color=‘red’) score_text.config(text=‘得分：{}’.format(score)) round_num += 1 time.sleep(2) # 结果展示2秒 # 游戏结束 gui.clear() gui.draw_text(x=120, y=100, text=‘游戏结束！’, font_size=24) gui.draw_text(x=120, y=140, text=‘最终得分：{}’.format(score), font_size=20) time.sleep(5)

这个代码框架实现了基本的游戏流程。你可以在此基础上增加更多功能，比如更丰富的颜色库、通过蜂鸣器播放提示音、用行空板上的RGB LED显示目标颜色、或者增加一个校准模式让玩家先“教”系统认识自己的色卡。

6. 性能优化与校准技巧

6.1 传感器参数的动态调整

TCS34725的integration_time和gain设置会显著影响性能。在默认设置下，传感器可能在某些光照条件下饱和（读数达到最大值）或信噪比太低（读数太小）。

• 高亮环境（如户外阳光下）：原始值raw_c可能接近65535（最大值）。此时应减少积分时间（如设为2.4或24毫秒），避免饱和，保证采样速度。
• 低亮环境（如室内夜晚）：原始值raw_c可能只有几百或几千。此时应增加积分时间（如设为154或700毫秒）和提高增益（如设为16x或60x），以提升信噪比，获得更稳定的颜色读数。

一个简单的自适应策略是在程序初始化后，先快速采样几次raw_c，根据其平均值来动态设置参数：

def auto_adjust_sensor(sensor): sensor.integration_time = 154 # 先设一个中等积分时间 sensor.gain = 4 time.sleep(0.1) # 等待设置生效 # 采样几次 samples = [] for _ in range(5): samples.append(sensor.color_raw[3]) # raw_c值 time.sleep(0.05) avg_clear = sum(samples) / len(samples) # 根据亮度调整 if avg_clear > 50000: sensor.integration_time = 24 # 很亮，用短积分 print(“环境很亮，积分时间设为24ms”) elif avg_clear < 1000: sensor.integration_time = 700 # 很暗，用长积分 sensor.gain = 16 print(“环境较暗，积分时间设为700ms，增益16x”) else: print(“环境光线适中，使用默认设置”)

6.2 颜色识别的校准与滤波

直接使用get_color_name函数可能会因为传感器噪声或环境光轻微变化导致识别结果在边界值附近跳动。两个实用的技巧是：

1. 均值滤波：连续读取多次颜色，取出现次数最多的结果作为最终判断，可以有效消除瞬时干扰。

   def get_stable_color_name(sample_times=5): color_counts = {} for _ in range(sample_times): name = get_current_color_name() # 单次读取 color_counts[name] = color_counts.get(name, 0) + 1 time.sleep(0.05) # 返回出现次数最多的颜色 return max(color_counts, key=color_counts.get)

2. 手动校准模式：为获得最准确的颜色范围，可以编写一个校准程序。让用户依次将红、绿、蓝等标准色卡放在传感器上，程序记录下每个颜色对应的HSV值（特别是色相H），并自动计算和保存该颜色的H值范围。之后游戏就使用这个校准后的范围字典，而不是预设的固定值。这能有效抵消不同传感器个体差异和环境光色温的影响。

7. 常见问题与故障排查实录

即使按照步骤操作，你也可能会遇到一些问题。下面是我在多次项目中遇到的典型情况及其解决方法。

避坑技巧：在编写主循环时，避免在同一个循环中既进行密集的传感器读取、复杂的颜色计算，又进行大量的屏幕绘制。可以考虑使用多线程，将传感器数据采集放在一个线程中，将UI更新放在主线程中，并通过线程安全的队列传递数据。对于行空板这样的资源有限设备，即使简单的多线程也能显著提升响应流畅度。