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

VEML7700 与 VEML6030 环境光传感器

veml7700 传感器平台允许您在 ESPHome 中使用 Vishay VEML7700 和 VEML6030 环境光传感器。与设备的通信通过 I²C 进行，必须在配置中存在该总线。VEML7700 和 VEML6030 基本相同，只是封装不同。VEML7700 使用固定地址 0x10，而较小的 VEML6030 可以配置为使用 0x10 或 0x48。

VEML 7700/6030 设备可通过多家供应商的评估板获得，包括 Adafruit、SparkFun、DFRobot 等。

板载与独立的 VEML7700 环境光传感器。
Home Assistant 界面中的 VEML 传感器。

该传感器是一款高精度的环境光数字 16 位分辨率传感器，动态范围从 0 lux 到约 120,000 lux。其宽测量范围通过四个可配置的 增益 级别和六个不同的 积分时间 选项来实现。较高的增益值通常用于较低的光线条件。

该传感器有两个具有不同光谱响应的光电二极管，分别对应两个通道：ALS 通道和 WHITE 通道。ALS（环境光）通道非常接近人眼曲线。WHITE 通道覆盖更广的波长/光谱，能捕获相当多的近红外辐射。

ALS 和 WHITE 通道的光谱响应

建议使用该组件的自动测量模式；在此模式下，组件在多次测量后会自动选择合适的 增益 和 积分时间。为此，它遵循制造商推荐的过程。

如果您希望手动控制这些参数——请注意：

  • 在大多数情况下应使用 1/8 和 1/4 的增益级别。
  • 1 和 2 的增益级别仅用于 < 100 lux 的低光条件。在非常高的照度下会出现高度的非线性。
  • 在 0 lux – 1000 lux 范围内，当增益为 1/4 和 1/8 时，传感器测量严格呈线性；超过 1000 lux 后会出现非线性。

使用 lux 补偿公式可以在明亮条件下获得更好的读数。 不过，在非常明亮的直射阳光下，它会给出较高的误差（可能给出 150-200k+ 而不是 100-120 kilolux）。

这篇 Wikipedia 文章 提供了一些 lux 值以供比较。

自动测量模式

Section titled “自动测量模式”

在自动测量模式下，组件从增益 1/8 和 100 ms（默认）开始。

  • 如果照度高于 46 lx（100 counts），会逐渐减少积分时间以获得好的读数（最佳范围为 100 - 10,000 counts）。
  • 如果照度较低（低于 46 lx），会尝试逐渐增加增益，然后再增加积分时间。

请注意，在低光条件下，由于曝光时间较长和传感器重新配置，测量过程可能需要几秒。

通过设置 gain 和 integration_time 参数可以覆盖起始值。增益值会在可能的情况下先被调整。

Lux 补偿

Section titled “Lux 补偿”

Lux 补偿按制造商的推荐进行，但可以通过在设备配置中设置 lux_compensation: false 来关闭。

lux = counts × resolution(time, gain)
lux_comp = 6.0135e-13 × lux⁴ - 9.3924e-9 × lux³ + 8.1488e-5 × lux² + 1.0023 × lux

其中：

  • counts - 传感器读数，counts
  • resolution - 给定积分时间和增益的传感器分辨率，lx/counts
  • lux - 计算得到的照度，lx
  • lux_comp - 补偿后的照度，lx

可用数据

Section titled “可用数据”

该实现提供了七个传感器：

  • 两个提供 lux 值，

  • 两个来自设备的无量纲数据测量值，

  • 两个用于测量的实际 增益 和 积分时间 值（在自动模式下很有用），以及

  • 一个完全人工的、一定程度上代表近红外光谱部分的值。

  • ambient_light: 代表人眼的 ALS 通道的照度值，lx

  • full_spectrum: 宽光谱 WHITE 通道的照度值，lx

  • infrared: 计算得到的照度值（WHITE 减去 ALS），代表近红外光谱，lx

  • ambient_light_counts: ALS 通道的原始 16 位读数，counts

  • full_spectrum_counts: WHITE 通道的原始 16 位读数，counts

  • actual_gain: 实际用于报告数值的增益值，乘数

  • actual_integration_time: 实际用于报告数值的积分时间，ms

配置示例

Section titled “配置示例”
# 示例配置条目
sensor:
  - platform: veml7700
    address: 0x10
    update_interval: 60s


    # 传感器定义的简写形式：
    ambient_light: "Ambient light"
    # 传感器定义的长格式形式：
    actual_gain:
      name: "Actual gain"

配置变量

Section titled “配置变量”

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

  • integration_time (可选, Time): 传感器曝光的时间长度。有效值为 25ms、50ms、100ms（默认）、200ms、400ms、800ms。在自动模式下，它设置起始值。

  • gain (可选, string): 设备内部 ADC 将使用的增益。有效值为 1/8x（默认）、1/4x、1x、2x。在低光条件下较高的值效果更好。在自动模式下，它设置起始增益值。

  • lux_compensation (可选, boolean): 按制造商要求使用 lux 补偿公式。默认为 True。

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

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

  • I²C 总线 中描述的 I²C 设备的所有其他选项。该传感器支持”标准”和”快速”总线模式：10 kHz 到 400 kHz。

传感器

Section titled “传感器”

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

不过，如果您不需要其他任何选项，可以直接使用像 ambient_light: Ambient light 这样的简写形式。

  • ambient_light (可选): 可见光的照度（ALS 通道），lx。
  • full_spectrum (可选): 全光谱传感器的照度（WHITE 通道），lx。
  • infrared (可选): 近红外光谱的计算照度（WHITE 减去 ALS），lx。
  • ambient_light_counts (可选): 可见光的读数（ALS 通道），counts。
  • full_spectrum_counts (可选): 全光谱传感器的读数（WHITE 通道），counts。
  • actual_gain (可选): 用于报告数值的增益值。当选择”auto_mode”时特别有用。
  • actual_integration_time (可选): 用于报告数值的积分时间，ms。当选择”auto_mode”时特别有用。

参见

Section titled “参见”