跳转到内容
ESPHome - 智能家居，简单易用

TSL2591 环境光传感器

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

TSL2591 设备可从多家供应商的开发板上获得 （例如，Adafruit、CQRobot、Waveshare）。

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

该传感器声称具有 6 亿比 1 的动态范围，有效最大值为 88000 勒克斯。 它通过可配置的 gain（增益）值实现这一大范围。 对于许多应用，您可以使用 AUTO 增益，让 ESP 根据上一次测量选择合适的增益设置。 如果光照水平剧烈变化，这可能导致下一次读数饱和， 之后增益会下调，随后的读数将在范围内。 在测量较弱光源时使用较高的增益值。 另一方面，如果您发现任一物理传感器的 ADC 读数为 65,535， 您可能正在使该传感器饱和，需要降低增益。 维基百科的这篇文章有一个用于比较的勒克斯值表格。

该实现提供四个传感器。 其中只有 calculated_lux 是真正的 lux 值，即使这个值也有点主观。 （有关辐射测量和光度测量之间差异的信息，请参阅参考资料。） 其他传感器是设备板载 ADC 对物理传感器的无单位读数。 两个物理传感器分别测量”可见光和红外光”（通道 0）和”红外光”（通道 1）。 但是，此处的传感器读数还单独提供简单的”可见光”值。 可见光值是通过从结合可见光和红外光的物理传感器值（通道 0）中减去物理红外传感器的读数（通道 1）获得的。 由于这是两个不同的物理红外传感器读数，可能存在小的误差。

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

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

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

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

  • actual_gain: 用于报告值的实际增益值。每当 gain 更改时更新， 这在传感器设置为 gain: auto 时特别有用，可以在遇到亮度极端变化时帮助表示相对亮度。

报告的值据说是以 lux 为单位，但有一些事项需要了解。

  • 可以配置的增益乘数值只是近似值。 传感器会使用接近它的值，但确切值可能因设备而异。 没有办法询问设备它正在使用什么精确增益值。 请参阅 TSL2591 数据手册以了解特定的设备特性范围。

  • 测量任何勒克斯值都需要针对被测量的光频率进行仔细校准、特定设备的转换系数以及其他因素。 简而言之，要真正获得真实的勒克斯值测量，您应该针对您的具体用例进行实验室级校准。 如果您是那种可以进行实验室级校准的人，您可能已经知道所有这些了。

  • 即使考虑到上述几点，您仍然可以在不校准的情况下获得”差不多正确”的值。 这尤其适用于您只想区分”无光”、“有一点光”、“很多光”或类似情况时。

# 示例配置条目
i2c:
  # ...
sensor:
  - platform: tsl2591
    name: "我的小灯光"
    id: "my_tls2591"
    address: 0x29
    update_interval: 60s
    gain: auto
    device_factor: 53
    glass_attenuation_factor: 14.4
    visible:
      name: "TSL2591 可见光"
    infrared:
      name: "TSL2591 红外光"
    full_spectrum:
      name: "TSL2591 全光谱光"
    calculated_lux:
      id: i_lux
      name: "TSL2591 勒克斯"
    actual_gain:
      id: "actual_gain"
      name: "TSL2591 实际增益"

配置变量

Section titled “配置变量”

对于 TSL2591 设备：

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

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

  • address (可选, 整数): 手动指定设备的 I²C 地址。 默认为 0x29。 在没有额外硬件的情况下，无法更改此设备的此地址。 它还自动使用辅助地址 0x28（请参阅数据手册）， 使该地址无法用于同一 I²C 总线上的其他设备。

  • integration_time (可选, 时间): 设备用于每次测量的时间。时间越长意味着值越准确。 您不能指定任意时间量。它必须是以下之一：

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

  • gain (可选, 字符串): 设备将使用的增益。较高的值在弱光条件下更好。 此处的乘数是近似值。同一行上的值是别名。 您不能指定任意增益乘数。它必须是以下之一：

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

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

  • power_save_mode (可选, 布尔值): 设备是否应在更新间隔之间断电？ 默认为 True。

  • device_factor (可选, 浮点数): 默认为 53.0。 用作 calculated_lux 勒克斯方程一部分的设备因子。

  • glass_attenuation_factor (可选, 浮点数): 默认为 7.7。 用作 calculated_lux 勒克斯方程一部分的玻璃衰减因子。

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

您可以配置前面描述的所有传感器或任何子集。 每个配置的传感器在每个 update_interval 单独报告。

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

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

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

  • calculated_lux (可选): 计算勒克斯的值。

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

省电模式

Section titled “省电模式”

只有在设备指示 ADC 值有效时才进行传感器读数。 如果设备在两次读数之间断电， 在可靠读数可用之前，ADC 需要经过一个积分周期的延迟。 延迟大约是配置的积分时间。 该实现使用异步延迟来等待 ADC 读数变得可用。 这避免了减慢整体 ESPHome 更新循环， 但这意味着 TSL2591 的状态更新发布可能会稍晚一些。

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

由于延迟只有几分之一秒（最多 600-700 毫秒）， 而更新间隔通常是许多秒， 这些延迟通常不太重要。 要查看是否发生延迟，您可以启用调试日志记录。

另见

Section titled “另见”