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

Lite-On 环境光与接近传感器

LTR-329 和 LTR-303 环境光传感器。
Home Assistant UI 中的 LTR-303 传感器。

ltr_als_ps 传感器平台允许您在 ESPHome 中使用一系列 LiteOn 环境光和接近传感器。此传感器需要在您的配置中设置 I²C 总线 才能工作。

传感器系列包括：

  • 环境光传感器 LTR-303ALS 和 LTR-329ALS
  • 集成环境光和接近传感器 LTR-553ALS、LTR-556ALS、LTR-559ALS
  • 接近传感器 LTR-659ALS（带 PS 增益控制）

这些传感器非常相似，共享同一份数据手册。前两个的默认 I²C 地址为 0x29，其余为默认 I²C 地址 0x23。这些传感器可从多家供应商处获取 breakout 板，例如 Adafruit 或 Pimoroni。

接近传感器与手机和平板电脑中用于在您将设备贴近耳朵时关闭屏幕的传感器相同。它们可能有助于自动开启或关闭显示屏和控制面板。例如，M5Stack 的 CoreS3 板就在屏幕正下方集成了一个 LTR-559ALS 传感器。

环境光感知

Section titled “环境光感知”

传感器平台在 0.01 勒克斯到 64k 勒克斯的宽动态范围内提供线性响应，非常适合 高环境亮度下的应用。总共提供六种增益设置（1X、2X、4X、8X、48X 和 96X）， 可供用户配置。在较暗的区域使用较高增益。

设备由两个光电二极管组成：CH0 二极管对可见光和红外光均敏感， 而 CH1 二极管仅对红外光敏感。

CH0 和 CH1 典型光谱响应

环境光照度计算

Section titled “环境光照度计算”

摘自数据手册：

RATIO = CH1/(CH0+CH1)
IF (RATIO < 0.45)
    ALS_LUX = (1.7743 * CH0 + 1.1059 * CH1) / ALS_GAIN / ALS_INT
ELSEIF (RATIO < 0.64 && RATIO >= 0.45)
    ALS_LUX = (4.2785 * CH0 – 1.9548 * CH1) / ALS_GAIN / ALS_INT
ELSEIF (RATIO < 0.85 && RATIO >= 0.64)
    ALS_LUX = (0.5926 * CH0 + 0.1185 * CH1) / ALS_GAIN / ALS_INT
ELSE
    ALS_LUX = 0
END

其中：

  • CH0 和 CH1 分别是可见光+IR（Ch0）和仅 IR（Ch1）传感器的传感器值（测量计数）。
  • ALS_GAIN 是增益倍数
  • ALS_INT 是积分时间，单位为 ms/100

ALS 增益级别

Section titled “ALS 增益级别”

下表列出了增益值和对应的照度范围：

增益照度范围
1X1 勒克斯到 64k 勒克斯（默认）
2X0.5 勒克斯到 32k 勒克斯
4X0.25 勒克斯到 16k 勒克斯
8X0.125 勒克斯到 8k 勒克斯
48X0.02 勒克斯到 1.3k 勒克斯
96X0.01 勒克斯到 600 勒克斯

这篇维基百科文章有一个勒克斯值对照表。

接近感知

Section titled “接近感知”

接近传感器具有内置发射器和检测器。传感器检测从发射器反射的红外光， 并给出与距离成反指数关系的原始计数值。计数值减小意味着物体正在远离 传感器，反之亦然。数据手册均未提供任何将原始计数值转换为距离的信息。唯一的方法是自行测试传感器并根据您的需求和环境选择阈值 。确切数值将取决于物体的类型、颜色和 反射率。

示例配置

Section titled “示例配置”
sensor:
  - platform: ltr_als_ps
    address: 0x23
    update_interval: 60s
    type: ALS_PS  # or ALS or PS
    ambient_light: "Ambient light"
    # PS only section
    ps_cooldown: 5 s
    ps_high_threshold: 500
    on_ps_high_threshold:
      then:
        - .... # do something - light up the screen for example
    ps_counts: "Proximity counts"

配置变量

Section titled “配置变量”

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

  • address (可选，int): 手动指定传感器的 I²C 地址。默认为 0x29。

  • type (可选，string): 传感器类型。有效值为 ALS_PS （默认），用于 集成传感器；ALS 用于仅环境光；PS 用于仅接近设备。

  • auto_mode (可选，boolean): 自动增益和积分时间选择。默认为 True。

  • gain (可选，string): 设备将使用的增益。值越大在低光照条件下效果越好。 有效值为 1X （默认）、2X、4X、8X、48X、96X。

  • integration_time (可选，Time): 传感器曝光的时间量。时间越长值越准确。 有效值为：50ms （默认）、100ms、150ms、200ms、250ms、300ms、350ms、400ms。

  • glass_attenuation_factor (可选，float): 如果传感器后面有玻璃 或塑料面板，则为玻璃的衰减因子。默认为 1.0，表示 100% 透过率。2 表示 50% 透过率，以此类推。

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

  • ps_cooldown (可选，Time): 接近传感器被触发后的”冷却”期。 有助于避免多次调用。默认为 5s。

  • ps_gain (可选，string): 设备用于接近传感器的增益。值越大在低光照条件下效果越好。 有效值为 16X （默认）、32X、64X。仅限 LTR-659ALS。

  • ps_high_threshold (可选，int): 物体靠近时接近传感器触发的阈值。 默认为 65535，意味着永远不会被触发。

  • ps_low_threshold (可选，int): 物体远离时接近传感器触发的阈值。 默认为 0，意味着永远不会被触发。

  • on_ps_high_threshold (可选): 接近传感器因物体靠近而触发时要执行的操作。

  • on_ps_low_threshold (可选): 接近传感器因物体远离而触发时要执行的操作。

传感器

Section titled “传感器”

此组件为带 ALS 的设备提供五个传感器，为带 PS 的设备提供一个传感器。 您可以配置全部或其中任意子集。每个配置的传感器 会在每次 update_interval 时单独报告。每个都是 ESPHome 传感器，可以 相应配置；如果您不需要配置额外的 传感器 变量， 可以直接使用传感器的简写语法。例如：ambient_light: "Ambient light"

  • ambient_light (可选): 环境光照度，接近人眼光谱，lx。
  • infrared_counts (可选): IR 敏感传感器的传感器计数（CH1），计数。
  • full_spectrum_counts (可选): 对可见光和 IR 均敏感的传感器的传感器计数（CH0），计数。
  • actual_gain (可选): 用于测量数据的增益值，倍数。在选择”auto_mode”时特别有用。
  • actual_integration_time (可选): 用于测量数据的积分时间，ms。在选择”auto_mode”时特别有用。
  • ps_counts (可选): 来自接近传感器的原始 11 位读数，计数。

参见

Section titled “参见”