跳转到内容
ESPHome - 让智能家居更简单2026.7.0

TSL2591 环境光传感器

tsl2591 传感器平台允许您在 ESPHome 中使用 AMS TSL2591 环境光传感器。与设备的通信通过 I²C 进行，必须在配置中存在该总线。

TSL2591 设备可通过几家供应商的评估板获得（例如，Adafruit、CQRobot、Waveshare）。

评估板上的 TSL2591 环境光传感器。
Home Assistant 界面中的 TSL2591 传感器。

该传感器号称具有 6 亿比 1 的动态范围，有效最大值约为 88000 lux。它通过配置 gain（增益）值来实现如此大的范围。对于许多应用，您可以使用 AUTO 增益，让 ESP 根据上一次测量值选择合适的前置增益设置。如果光线水平变化剧烈，这可能会导致下一次读数饱和，随后增益将下调，后续读数则会回到量程内。在测量较弱光源时使用较高的增益值。另一方面，如果任一物理传感器得到 65,535 的 ADC 读数，您可能已经使该传感器饱和，需要降低增益。这篇 Wikipedia 文章 提供了一些 lux 值以供比较。

该实现提供了四个传感器。其中只有 calculated_lux 是真正的 lux 值，即便如此也具有一定主观性。（有关辐射度测量与光度测量的区别，请参阅参考资料。）其他传感器来自设备板载 ADC 对物理传感器的无量纲读数。两个物理传感器分别测量”可见光与红外线”（通道 0）和”红外线”（通道 1）。不过，这里提供的传感器读数还单独给出了简单的”可见光”值。可见光值是通过从”可见光与红外线”物理传感器的读数（通道 0）中减去红外物理传感器（通道 1）的读数得到的。由于这两个是不同的物理红外传感器读数，因此可能存在轻微的误差。

  • full_spectrum: 来自板载 ADC 的原始 16 位读数，用于可见光与红外线物理传感器（通道 0）。

  • infrared: 来自板载 ADC 的原始 16 位读数，用于红外线物理传感器（通道 1）。

  • visible: 为方便起见，通过取两个物理传感器之间的差值得到的值（通道 0 减去通道 1）。

  • calculated_lux: 这是基于物理传感器读数、配置的增益和配置的积分时间计算出的 lux 值。 有关实际计算（可能取决于其他物理属性）的详细信息，请参阅 API 参考中的方法 get_calculated_lux()。 lux 方程中包含用于设备因子和玻璃衰减因子的配置项。 如果您不满意内置计算，可以使用所需原始数据进行自行计算。 制造商 AMS 提供了若干讨论该主题的应用笔记。请参阅参考资料。

  • actual_gain: 实际用于报告数值的增益值。每当 gain 更改时都会更新，当传感器设置为 gain: auto 时，特别是在遇到亮度剧烈变化时，这对指示相对亮度非常有用。

报告的数值单位为 lux，但需要注意以下几点。

  • 可配置的增益乘数仅为近似值。 传感器会使用接近它的值，但确切值可能因设备而异。 无法询问设备它正在使用什么精确的增益值。 有关特定设备特征范围，请参阅 TSL2591 数据手册。

  • 测量任何 lux 值都需要针对被测量的光频率（或多个频率）、特定设备的转换系数以及其他因素进行仔细校准。 简而言之，要真正获得真正的 lux 值测量，您应针对自己的使用场景进行实验室级校准。 如果您能进行实验室级校准，您可能已经知道所有这些信息了。

  • 即使考虑上述要点，您仍然可以获得”大致正确”的数值，无需校准。 如果您只是想区分”无光”、“有一点光”、“很多光”或类似情况，就更是如此。

# 示例配置条目
i2c:
  # ...
sensor:
  - platform: tsl2591
    name: "This little light of mine"
    id: "my_tls2591"
    address: 0x29
    update_interval: 60s
    gain: auto
    device_factor: 53
    glass_attenuation_factor: 14.4
    visible:
      name: "TSL2591 visible light"
    infrared:
      name: "TSL2591 infrared light"
    full_spectrum:
      name: "TSL2591 full spectrum light"
    calculated_lux:
      id: i_lux
      name: "TSL2591 Lux"
    actual_gain:
      id: "actual_gain"
      name: "TSL2591 actual gain"

配置变量

Section titled “配置变量”

对于 TSL2591 设备：

  • id (可选, ID): 手动指定代码生成中使用的 ID。

  • name (可选, string): 此 TSL2591 设备的用户友好名称。

  • address (可选, int): 手动指定设备的 I²C 地址。默认为 0x29。如果不借助额外的硬件，该设备的地址无法更改。它还会自动使用备用地址 0x28（参见数据手册），因此同一 I²C 总线上其他设备无法使用该地址。

  • integration_time (可选, Time): 设备用于每次测量的时间。时间越长，数值越准确。您不能随意指定时间长度。它必须是以下某一项的等效值：

    • 100ms （默认）
    • 200ms
    • 300ms
    • 400ms
    • 500ms
    • 600ms

  • gain (可选, string): 设备将使用的增益。在低光条件下较高的值效果更好。 此处的乘数为近似值。同一行中的下方值为别名。您不能随意指定增益乘数。它必须是以下某一项：

    • low、1x
    • medium、med、25x
    • high、400x
    • maximum、max、9500x
    • auto （默认）

  • update_interval (可选, Time): 检查传感器的间隔。默认为 60s。

  • power_save_mode (可选, boolean): 是否应在两次更新间隔之间关闭设备电源？默认为 True。

  • device_factor (可选, float): 默认为 53.0。用于 calculated_lux 的 lux 方程中的设备因子。

  • glass_attenuation_factor (可选, float): 默认为 7.7。用于 calculated_lux 的 lux 方程中的玻璃衰减因子。

  • I²C 总线 中描述的 I²C 设备的所有其他选项。

您可以配置前面描述的所有传感器或其任意子集。 每个配置的传感器都会在每次 update_interval 时分别报告。

  • full_spectrum (可选): 全光谱传感器的读数。

  • infrared (可选): 红外传感器的读数。

  • visible (可选): 可见光的读数。

  • calculated_lux (可选): 计算得出的 lux 值。

  • actual_gain (可选): 用于报告数值的增益值。当增益设置为 “auto” 时特别有用。

省电模式

Section titled “省电模式”

仅当设备指示 ADC 值有效时才会采集传感器读数。 如果设备在两次读数之间被关机， 则 ADC 需要经历一个积分周期后才能获得可靠的读数。 延迟时间大约为配置的积分时间。 实现使用异步延迟来等待 ADC 读数变为可用。 这避免了拖慢 ESPHome 的整体更新循环， 但也意味着 TSL2591 的状态更新发布可能会稍晚一些。

如果使用 TSL2591 API 更改增益或积分时间值， 设备会在内部被禁用并重新启用。 否则，下一组 ADC 读数将不可靠， 因为当前的 ADC 积分周期是以混合的增益值完成的。 （ADC 不会自动”感知”到增益或积分时间已更改。） 即使未启用省电模式，如果在更换后不幸恰好在某个时间点进行第一次传感器读取， 也可能出现类似的轻微延迟。

由于延迟仅为几分之一秒（最长 600–700 ms）， 而更新间隔通常为多秒， 因此延迟通常不是特别值得关注。 如需查看是否发生延迟，可以开启调试日志。

参见

Section titled “参见”