CircuitPython I2C总线扫描与TSL2591传感器数据读取实战指南

1. 项目概述与I2C协议基础

在嵌入式开发领域，尤其是使用像Adafruit的CircuitPython系列开发板时，I2C总线是连接各种传感器和执行器最常用、最便捷的通信方式之一。它就像一条简易的“数据高速公路”，仅用两根线就能串联起多个设备，极大地节省了宝贵的GPIO引脚资源。我最近在做一个环境监测的小项目，需要读取光照强度数据，于是选择了集成度高、性能稳定的TSL2591传感器。但在实际动手前，我发现很多新手朋友，甚至一些有经验的开发者，在面对I2C设备时，第一步——确认设备是否被正确识别——就卡住了。要么是代码跑不通，要么是串口输出一片空白，让人摸不着头脑。

这篇文章，我就以“CircuitPython I2C总线扫描与TSL2591传感器数据读取”这个具体任务为线索，把我从硬件连接到软件调试，再到稳定读取数据的完整过程，以及中间踩过的坑、总结的技巧，毫无保留地分享出来。无论你是刚接触CircuitPython的新手，还是想更深入了解I2C通信细节的开发者，相信都能从中找到有用的信息。我们的目标很简单：让你手里的传感器“开口说话”，把数据稳稳当当地读出来。

2. I2C协议核心原理与在CircuitPython中的实现机制

在动手接线和写代码之前，我们有必要花几分钟搞清楚I2C到底是怎么工作的。这能帮你从根本上理解后续的每一个操作步骤，遇到问题时也能自己分析，而不是盲目地照抄代码。

2.1 I2C通信的基本框架

I2C协议的精髓在于“两线制”和“主从模式”。想象一下一个老师（主设备）和多个学生（从设备）在教室里。老师手里有一个点名册（地址列表），每次想和某个学生交流时，就先喊出他的名字（发送设备地址）。只有被叫到名字的学生才会起立应答，其他学生则保持安静。在硬件上，这体现为两根共享的总线：

• SCL（Serial Clock Line）：时钟线，由主设备产生，像节拍器一样同步所有设备的通信节奏。
• SDA（Serial Data Line）：数据线，用于双向传输地址和数据信息。

所有设备都并联在这两根线上，每个设备都需要一个唯一的“学号”，也就是7位I2C设备地址。TSL2591的默认地址是0x29（十六进制），这就是它在I2C总线上的“名字”。通信开始时，主设备（我们的开发板）会先发送一个起始信号，然后广播这个7位地址外加1位读写指示位。总线上所有设备都会“听”这个地址，只有地址匹配的从设备（TSL2591）会回复一个应答信号，之后主从双方才开始正式的数据交换。

注意：I2C总线需要上拉电阻。你可以把SDA和SCL线想象成弹簧，默认被电阻“拉”到高电平（3.3V）。当任何设备想要输出低电平时，它需要“按下”这根弹簧。如果没有上拉电阻，这根线就会处于悬空状态（电平不确定），通信必然失败。绝大多数Adafruit的传感器分线板（Breakout Board）都贴心地内置了这些上拉电阻，但如果你是自己用裸芯片搭建电路，千万别忘了在SDA和SCL线上各接一个2.2K到10K欧姆的电阻到3.3V。

2.2 CircuitPython中的I2C对象：单例模式的应用

在CircuitPython中操作I2C，最常用的方法是使用board.I2C()。这里涉及一个重要的软件设计模式——单例模式。简单来说，无论你在代码里调用多少次board.I2C()，它返回的都是同一个I2C总线对象。这保证了整个程序中对硬件的访问是统一且一致的，避免了资源冲突。

import board import busio # 方法一：使用便捷的单例函数（推荐） i2c = board.I2C() # 自动使用板子默认的SCL和SDA引脚 # 方法二：手动指定引脚创建（用于非默认引脚或多个I2C总线） i2c2 = busio.I2C(board.SCL1, board.SDA1, frequency=100000) # 频率单位是Hz，100000即100kHz

第一种方式最简单，适用于大多数标准板型（如Feather M4、ItsyBitsy等），它们都有明确标注的SDA和SCL引脚。第二种方式更灵活，允许你使用其他引脚组合来创建额外的I2C总线实例，这在引脚资源紧张或需要隔离不同速率设备时非常有用。创建对象时，你还可以通过frequency参数调整时钟速度，标准模式是100kHz，快速模式是400kHz，一些高速设备支持更高的速率。

3. 硬件连接详解与避坑指南

理论清楚了，接下来就是动手连接。这一步看似简单，但却是问题的高发区。我结合TSL2591和几种主流Adafruit板型，把接线方法和容易出错的地方都列出来。

3.1 通用接线逻辑与STEMMA QT/QWIIC接口

现代传感器模块，包括TSL2591，越来越多地采用STEMMA QT（或兼容的QWIIC）接口。这是一个4针的防反插连接器，大大简化了接线。其线序颜色是标准化的：

• 黑色（Black）：GND，接地。
• 红色（Red）：VIN或3Vo，接电源（通常是3.3V，部分模块支持5V）。
• 蓝色（Blue）：SDA，数据线。
• 黄色（Yellow）：SCL，时钟线。

如果你的开发板也有STEMMA QT接口（如QT Py、部分Feather型号），那么直接用一根4芯电缆对接即可，连颜色都不用记，因为接口是防反插的。这是最省心、最可靠的连接方式。

3.2 各型号开发板具体接线表

对于没有STEMMA QT接口的板子，或者你需要使用面包板进行原型搭建，就需要手动连接了。下面这个表格汇总了常见板型的连接方法：

实操心得：电源选择：TSL2591的VIN引脚支持3-5V宽电压输入。我个人的习惯是，如果开发板有USB供电（5V），优先接USB引脚，这样电压更稳定。如果使用电池供电或担心功耗，可以接3.3V。务必确保开发板和传感器共地（GND连接在一起），这是电路正常工作的基础。

3.3 连接后的初步检查

线接好后先别急着写代码，做两个简单的物理检查：

1. 接触检查：用手轻轻晃动杜邦线或连接器，确保没有虚接。面包板上的插孔用久了容易松动，最好用新的或确保插紧。
2. 发热检查：通电后，快速用手指触摸传感器芯片和开发板的主要芯片。如果有任何部件异常发热（烫手），立即断电！这通常是电源接反或短路的标志。

4. I2C总线扫描：诊断连接的第一步

硬件连接确认无误后，第一段要跑的代码永远是I2C总线扫描。这个脚本就像是一个“设备探测器”，它能告诉你总线上有哪些设备在响应，并列出它们的地址。这是验证物理连接和软件配置是否正确的黄金标准。

4.1 扫描代码逐行解析

我们把官方的扫描脚本拿过来，加上详细的注释，让你理解每一行的作用：

# SPDX-FileCopyrightText: 2017 Limor Fried for Adafruit Industries # SPDX-License-Identifier: MIT """CircuitPython I2C Device Address Scan""" import time import board # 使用板载默认I2C引脚创建I2C对象（单例模式） i2c = board.I2C() # 对于大多数板子，这等同于 busio.I2C(board.SCL, board.SDA) # 注意：如果你的板子有STEMMA QT接口，并且想用它，可以取消下面这行的注释 # i2c = board.STEMMA_I2C() # 尝试锁定I2C总线。在多任务或中断环境中，防止其他代码同时访问总线。 # 这里用while循环等待，直到锁定成功。 while not i2c.try_lock(): pass try: while True: # i2c.scan() 返回一个包含所有发现设备地址的列表（整数形式） # 用列表推导式将整数地址转换为更易读的十六进制字符串 found_addresses = [hex(addr) for addr in i2c.scan()] print("I2C addresses found:", found_addresses) time.sleep(2) # 每2秒扫描一次 finally: # 无论是否发生异常（比如你用Ctrl+C中断程序），都确保解锁总线。 # 这是一个良好的编程习惯，避免总线被永久锁死导致需要复位。 i2c.unlock()

将这段代码保存为code.py并上传到你的CIRCUITPY驱动器。然后打开串行监视器（如Mu编辑器、Thonny或VS Code的串行终端）。如果一切顺利，你应该会看到类似这样的输出：

I2C addresses found: ['0x29']

这个0x29就是TSL2591的默认地址。恭喜你，硬件连接和基础通信已经通了！

4.2 扫描失败问题排查手册

如果输出是I2C addresses found: []（空列表），或者程序似乎卡住了，别慌，按照以下步骤排查：

踩过的坑：我曾经遇到过扫描时好时坏的情况，最后发现是杜邦线接触不良。对于需要移动的原型，强烈建议使用焊接、螺丝端子或STEMMA QT这种可靠的连接方式，杜邦线只适合临时静态测试。

5. TSL2591传感器数据读取实战

总线扫描成功，意味着通信链路已经建立。现在，我们可以和TSL2591“对话”，让它告诉我们光照数据了。这里我们需要借助Adafruit提供的专用库，它封装了与传感器通信的复杂细节。

5.1 库文件安装与项目结构

CircuitPython通过lib文件夹管理第三方库。我们需要两个库文件：

1. adafruit_tsl2591.mpy：TSL2591传感器的驱动库。
2. adafruit_bus_device：一个通用的总线设备支持库，为许多传感器库所依赖。

获取它们最方便的方法是访问 Adafruit的CircuitPython库包 ，下载与你CircuitPython版本匹配的完整库包。解压后，在lib文件夹中找到上述两个文件，将它们复制到你的CIRCUITPY驱动器的lib文件夹内。如果你的lib文件夹不存在，就新建一个。

正确的项目文件结构应该如下所示：

CIRCUITPY/ ├── lib/ │ ├── adafruit_tsl2591.mpy │ └── adafruit_bus_device/ │ ├── __init__.mpy │ └── i2c_device.mpy └── code.py

5.2 数据读取代码深度剖析

下面是我们读取光照数据的核心代码，我加入了比官方示例更详细的注释和错误处理：

# SPDX-FileCopyrightText: 2017 Limor Fried for Adafruit Industries # SPDX-License-Identifier: MIT """CircuitPython Essentials I2C sensor example using TSL2591""" import time import board import adafruit_tsl2591 # 初始化I2C总线 i2c = board.I2C() # 可选：在正式创建传感器对象前，再做一次快速扫描确认（调试用） while not i2c.try_lock(): pass print("I2C addresses found:", [hex(addr) for addr in i2c.scan()]) i2c.unlock() # 创建TSL2591传感器对象 # 驱动库会通过I2C总线与地址0x29的设备进行通信 try: tsl = adafruit_tsl2591.TSL2591(i2c) print("TSL2591 sensor initialized successfully!") except ValueError as e: # 如果初始化失败，可能是地址不对或根本不是TSL2591 print("Failed to initialize TSL2591:", e) # 此处可以加入更复杂的错误处理，如尝试其他可能地址 raise # 配置传感器增益和积分时间（可选，但很重要！） # 增益（Gain）控制灵敏度：LOW (1x), MEDIUM (25x), HIGH (428x), MAX (9876x) # 环境光弱时用高增益，强时用低增益，防止饱和。 tsl.gain = adafruit_tsl2591.GAIN_MEDIUM # 室内环境常用MEDIUM # 积分时间（Integration Time）控制每次测量的时长：100MS, 200MS, 300MS, 400MS, 500MS, 600MS # 时间越长，信噪比越好，但采样率越低。 tsl.integration_time = adafruit_tsl2591.INTEGRATIONTIME_200MS print(f"Current gain: {tsl.gain}") print(f"Current integration time: {tsl.integration_time}ms") # 主循环：持续读取并打印数据 while True: try: # 读取并打印可见光+红外光的综合照度值（单位：勒克斯 Lux） lux = tsl.lux print(f"Lux: {lux:.2f}") # 进阶：还可以读取原始通道数据，用于更复杂的计算 # visible_raw = tsl.visible # infrared_raw = tsl.infrared # full_spectrum_raw = tsl.full_spectrum # print(f"Visible: {visible_raw}, IR: {infrared_raw}") except OSError as e: # I2C通信错误，通常是物理连接中断 print("I2C communication error:", e) time.sleep(1) # 等待后重试 except Exception as e: # 捕获其他未知错误 print("An unexpected error occurred:", e) break # 严重错误，退出循环 time.sleep(1.0) # 每秒读取一次

5.3 增益与积分时间的调优策略

TSL2591的强大之处在于其可配置性。gain（增益）和integration_time（积分时间）是两个关键参数，直接影响测量范围和精度。不合理的配置会导致读数溢出（显示为None）或噪声过大。

我制作了一个参数选择参考表，帮助你根据环境快速配置：

调优技巧：在代码中动态调整这些参数是高级用法。你可以先读取原始通道值（full_spectrum_raw），如果它接近最大值（65535），说明快要饱和了，应降低增益或积分时间；如果值非常小（比如几十），则可以尝试提高增益以获得更精确的读数。

6. 进阶技巧：探索其他I2C引脚与多总线应用

大多数Adafruit的SAMD21、SAMD51和nRF52840芯片的开发板，其I2C引脚并非固定死的。除了标有SDA/SCL的引脚，很多其他引脚也能复用为I2C功能。当你需要连接多个同地址设备，或者默认引脚被其他功能占用时，这个技巧就非常有用。

6.1 硬件I2C引脚扫描脚本

Adafruit提供了一个非常实用的脚本，可以自动检测板子上哪些引脚对可以用于硬件I2C。运行这个脚本，它会列出所有可能的SCL和SDA引脚组合。

# SPDX-FileCopyrightText: 2018 Kattni Rembor for Adafruit Industries # SPDX-License-Identifier: MIT """CircuitPython Essentials I2C possible pin-pair identifying script""" import board import busio from microcontroller import Pin def is_hardware_I2C(scl_pin, sda_pin): """测试一对引脚是否支持硬件I2C""" try: # 尝试用这对引脚创建I2C对象 i2c = busio.I2C(scl_pin, sda_pin) i2c.deinit() # 创建成功后立即释放资源 return True except ValueError: # 引脚不支持I2C return False except RuntimeError: # 引脚支持I2C但可能被占用，也算作支持 return True def get_unique_pins(): """获取板子上所有唯一的、可用的Pin对象""" exclude = ['NEOPIXEL', 'APA102_MOSI', 'APA102_SCK'] # 排除一些特殊功能引脚 pins = [ pin for pin in [ getattr(board, attr_name) for attr_name in dir(board) if attr_name not in exclude ] if isinstance(pin, Pin) # 确保是Pin对象 ] # 去重（因为有些引脚可能有多个别名） unique_pins = [] for pin in pins: if pin not in unique_pins: unique_pins.append(pin) return unique_pins # 主程序：遍历所有可能的引脚组合并测试 print("Scanning for hardware I2C pin pairs...") for scl in get_unique_pins(): for sda in get_unique_pins(): if scl is sda: # SCL和SDA不能是同一个引脚 continue if is_hardware_I2C(scl, sda): print(f"SCL: {scl} \t SDA: {sda}") print("Scan complete.")

在你的板子上运行这个脚本，可能会得到一个很长的列表。例如，在ItsyBitsy M4 Express上，除了默认的SCL/SDA，你可能还会发现board.SCL1/board.SDA1等其他可用的硬件I2C接口。

6.2 创建第二个I2C总线实例

假设扫描脚本告诉你board.D13和board.D12可以作为一组I2C引脚，你想用它们连接第二个TSL2591（注意：两个相同地址的设备不能挂在同一总线上，除非使用I2C多路复用器。这里仅为演示多总线创建）。

import board import busio import adafruit_tsl2591 # 第一个I2C总线，使用默认引脚 i2c_bus0 = board.I2C() # 或 busio.I2C(board.SCL, board.SDA) sensor0 = adafruit_tsl2591.TSL2591(i2c_bus0) # 第二个I2C总线，使用自定义引脚（例如D13和D12） i2c_bus1 = busio.I2C(board.D13, board.D12) sensor1 = adafruit_tsl2591.TSL2591(i2c_bus1) print("Two I2C buses initialized.")

重要提醒：使用非默认引脚创建I2C时，务必确保这些引脚没有被其他功能（如PWM、UART、LED）占用，否则会发生冲突。busio.I2C()在创建时会进行一些检查，但并非万能。

7. 项目扩展与数据应用思路

成功读取到光照数据只是第一步。如何让这些数据产生价值？这里分享几个我实践过的扩展方向。

1. 数据记录与可视化将读取到的Lux值连同时间戳一起保存到CIRCUITPY驱动器上的一个文本文件或CSV文件中。你可以插入一个SD卡模块，实现更长时间的数据记录。然后，将数据导入到电脑，用Python的Matplotlib或Excel生成光照变化曲线图，分析一天中不同时段的光照规律。

2. 阈值触发与自动化根据光照强度控制其他设备。例如，当Lux值低于某个阈值（如50）时，自动打开LED灯；当高于某个阈值（如500）时，自动关闭。这可以用于智能台灯、植物补光系统等。

import digitalio import board led = digitalio.DigitalInOut(board.LED) led.direction = digitalio.Direction.OUTPUT while True: lux = tsl.lux if lux is not None: if lux < 50: led.value = True # 开灯 elif lux > 500: led.value = False # 关灯 time.sleep(10) # 每10秒检查一次

3. 无线传输与物联网集成结合Wi-Fi或蓝牙模块（如ESP32-S2/S3，或搭配AirLift协处理器），将光照数据实时发送到物联网平台（如Adafruit IO、Blynk、Home Assistant），实现远程环境监测和智能家居联动。

4. 多传感器融合TSL2591测量的是可见光和红外光。你可以结合温湿度传感器（如AHT20）、气压传感器（如BMP280）等，通过I2C总线将它们全部连接起来（地址不同即可），构建一个功能全面的微型气象站。I2C总线支持多设备的特性在这里大放异彩。

从连接线缆到代码调试，从读取一个简单的数值到规划一个完整的项目，I2C通信是贯穿嵌入式开发的核心技能。TSL2591作为一个优秀的实践案例，其清晰的通信逻辑和强大的库支持，使得上手过程非常平滑。我最深刻的体会是，嵌入式开发中，耐心和系统性排查往往比高深的代码技巧更重要。当传感器没有响应时，按照“电源->接地->信号线->地址->代码”的顺序一步步检查，绝大多数问题都能迎刃而解。希望这篇详细的实践记录，能帮你扫清I2C学习路上的障碍，更自信地探索更多传感器的世界。