跳转至

exs_veml3328 扩展库

作者：沈园园　|　最后修改：2026-08-07

一、概述

1.1 主要特性

  • 高性能 RGBW 颜色检测：支持 Red、Green、Blue、Clear、IR 五个通道的同步测量
  • 16 位分辨率：每个通道均可获得 0~65535 的原始数据，精确捕捉颜色变化
  • 灵活的增益配置：支持 Gain（0.5x/1x/2x/4x/12x）和 DG（1x/2x/4x）双增益控制
  • 多档集成时间：50ms/100ms/200ms/400ms 可选，平衡速度与精度
  • 双灵敏度模式：高灵敏度模式适合低光场景，低灵敏度模式适合强光场景
  • 低功耗设计：支持睡眠模式（SD0/SD1），待机功耗极低
  • I2C 通信：标准 I2C 接口，支持硬件/软件 I2C

1.2 注意事项

  • I2C 上拉电阻：SDA 和 SCL 需外接 4.7kΩ~10kΩ 上拉电阻到 VCC
  • 供电电压：传感器工作电压为 2.7V~3.6V，典型值 3.3V
  • 增益与噪声：增益越高灵敏度越高，但噪声也越大；建议在满足测量需求的前提下使用最低增益
  • 集成时间：集成时间过长会增加测量延迟，实时性要求高的场景建议使用 100ms 或 50ms
  • 环境光干扰：测量时应尽量避免环境光直射传感器窗口，建议加遮光罩
  • 预热时间：传感器上电后建议预热 30 秒以上再进行精确测量
  • I2C 地址：VEML3328 固定地址为 0x10，不可改变

1.3 硬件连接

主控（Air780EHM）        VEML3328 传感器
─────────────           ─────────────
VCC (3.3V)  ──────────→ VCC
GND         ──────────→ GND
SCL (GPIO1) ──────────→ SCL
SDA (GPIO2) ──────────→ SDA
                              └──→ 4.7kΩ 上拉到 VCC
                              └──→ 4.7kΩ 上拉到 VCC

1.4 加载方式

-- 扩展库需要 require 加载后才能调用
local exs_veml3328 = require "exs_veml3328"

二、核心示例

2.1 场景一：基础颜色检测

local exs_veml3328 = require "exs_veml3328"

local function color_detect_task()
    -- 初始化传感器
    local ok = exs_veml3328.setup({i2c_id = 1})
    if not ok then
        log.error("veml3328", "初始化失败")
        return
    end

    -- 循环读取颜色数据
    while true do
        local data = exs_veml3328.get_data()
        if data then
            log.info("veml3328", string.format(
                "R=%d G=%d B=%d C=%d IR=%d",
                data.red, data.green, data.blue, data.clear, data.ir
            ))
        end
        sys.wait(500)  -- 每 500ms 读取一次
    end
end

sys.taskInit(color_detect_task)

2.2 场景二：高级配置与低光检测

local exs_veml3328 = require "exs_veml3328"

local function low_light_detect_task()
    -- 高灵敏度配置：Gain 12x + DG 4x + 集成时间 400ms
    local ok = exs_veml3328.setup({
        i2c_id = 1,
        gain = 12,        -- 最高增益
        dg = 4,           -- DG 增益
        it = 400,         -- 最长集成时间
        sensitivity = "high"  -- 高灵敏度模式
    })
    if not ok then
        log.error("veml3328", "初始化失败")
        return
    end

    -- 检测低光颜色
    for i = 1, 10 do
        local data = exs_veml3328.get_data()
        if data then
            -- 计算颜色比例用于色温判断
            local total = data.red + data.green + data.blue
            if total > 0 then
                local r_ratio = data.red / total
                local g_ratio = data.green / total
                local b_ratio = data.blue / total
                log.info("veml3328", string.format(
                    "R=%.1f%% G=%.1f%% B=%.1f%%",
                    r_ratio * 100, g_ratio * 100, b_ratio * 100
                ))
            end
        end
        sys.wait(1000)  -- 等待 1 秒
    end

    -- 使用完毕释放资源
    exs_veml3328.close()
end

sys.taskInit(low_light_detect_task)

三、常量解释

扩展库常量，顾名思义是由 exs_veml3328 扩展库中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用，本扩展库没有常量。

四、函数详解

4.1 初始化

4.1.1 exs_veml3328.setup(config)

功能

初始化 VEML3328 传感器，包括 I2C 通信配置、设备探测、参数设置和就绪等待

参数

config

参数含义：配置参数表
数据类型：table
取值范围：
    {
        参数含义：I2C 总线 id（硬件 I2C 模式）
        数据类型：number
        取值范围：0 ~ 1，具体取决于硬件支持
        是否必选：否
        注意事项：仅传 i2c_id 时不具总线自动恢复能力
        参数示例：1
        config.i2c_id ,

        参数含义：软件 I2C SCL 引脚（传 scl+sda 时自动使用软件 I2C）
        数据类型：number
        取值范围：根据芯片 GPIO 引脚定义
        是否必选：否
        注意事项：与 sda 需同时传入
        参数示例：31
        config.scl ,

        参数含义：软件 I2C SDA 引脚
        数据类型：number
        取值范围：根据芯片 GPIO 引脚定义
        是否必选：否
        注意事项：与 scl 需同时传入
        参数示例：30
        config.sda ,

        参数含义：初始增益（Gain）
        数据类型：number
        取值范围：0.5（最低灵敏度，适合强光）
                 / 1（默认，适合大多数场景）
                 / 2（中等灵敏度）
                 / 4（高灵敏度）
                 / 12（最高灵敏度，适合低光）
        是否必选：否
        注意事项：增益越高测量范围越大但噪声也越大；建议默认使用 1x
        参数示例：1
        config.gain ,

        参数含义：初始 DG 增益
        数据类型：number
        取值范围：1（默认）
                 / 2（中等增益）
                 / 4（高增益）
        是否必选：否
        注意事项：与 gain 叠加作用，总增益 = gain × dg
        参数示例：1
        config.dg ,

        参数含义：初始集成时间
        数据类型：number
        取值范围：50（最快，低精度）
                 / 100（默认，平衡速度与精度）
                 / 200（高精度）
                 / 400（最慢，最高精度）
        是否必选：否
        注意事项：集成时间越长精度越高但响应越慢
        参数示例：100
        config.it ,

        参数含义：初始灵敏度模式
        数据类型：string
        取值范围："high"（高灵敏度模式，适合低光）
                 / "low"（低灵敏度模式，适合强光）
        是否必选：否
        注意事项：默认 "high"
        参数示例："high"
        config.sensitivity ,
    }
是否必选：是
参数示例：
    -- 硬件 I2C 模式
    exs_veml3328.setup({i2c_id = 1})

    -- 软件 I2C 模式
    exs_veml3328.setup({scl = 31, sda = 30})

返回值

local result = exs_veml3328.setup(config)

result

含义说明：初始化是否成功
数据类型：boolean
取值范围：true（成功），false（失败）
注意事项：失败时请检查接线和通信参数
返回示例：true

示例

local function init_func()
    -- 使用硬件 I2C（id=1）
    local ok = exs_veml3328.setup({i2c_id = 1})
    if not ok then
        log.error("veml3328", "初始化失败")
        log.error("veml3328", "检查接线: VCC=3.3V GND SCL SDA")
        return false
    end
    log.info("veml3328", "初始化成功，版本:", exs_veml3328.version())
    return true
end

4.2 数据读取

4.2.1 exs_veml3328.get_data()

功能

读取 VEML3328 五个通道（Red/Green/Blue/Clear/IR）的原始测量数据

参数

无

返回值

local data = exs_veml3328.get_data()

data

含义说明：传感器测量数据
数据类型：table 或 nil
取值范围：
    data.red    - 红色通道原始值，范围 0~65535（16位分辨率）
    data.green  - 绿色通道原始值，范围 0~65535（16位分辨率）
    data.blue   - 蓝色通道原始值，范围 0~65535（16位分辨率）
    data.clear  - 清光通道原始值，范围 0~65535（16位分辨率）
    data.ir     - 红外通道原始值，范围 0~65535（16位分辨率）
注意事项：返回 nil 表示读取失败；各通道值为线性关系，可直接用于颜色比例计算
返回示例：{red = 1234, green = 2345, blue = 3456, clear = 4567, ir = 567}

示例

local function read_data_func()
    local data = exs_veml3328.get_data()
    if data then
        log.info("veml3328", string.format(
            "R=%d G=%d B=%d C=%d IR=%d",
            data.red, data.green, data.blue, data.clear, data.ir
        ))
    else
        log.error("veml3328", "读取数据失败")
    end
end

4.3 参数配置

4.3.1 exs_veml3328.set_gain(gain)

功能

设置传感器增益（Gain），增益越高灵敏度越高但噪声也越大

参数

gain

参数含义：增益倍数
数据类型：number
取值范围：0.5（最低灵敏度，适合强光场景）
         / 1（默认，适合大多数场景）
         / 2（中等灵敏度）
         / 4（高灵敏度）
         / 12（最高灵敏度，适合低光场景）
是否必选：是
注意事项：增益改变后需要等待新的集成周期完成（最长 400ms）
参数示例：2

返回值

local result = exs_veml3328.set_gain(gain)

result

含义说明：设置是否成功
数据类型：boolean
取值范围：true（成功），false（失败）
返回示例：true

示例

-- 设置增益为 2x
local ok = exs_veml3328.set_gain(2)
if ok then
    log.info("veml3328", "增益设置成功")
end

4.3.2 exs_veml3328.set_dg(dg)

功能

设置 DG 增益，与 Gain 叠加作用，总增益 = gain × dg

参数

dg

参数含义：DG 增益倍数
数据类型：number
取值范围：1（默认）
         / 2（中等增益）
         / 4（高增益）
是否必选：是
注意事项：DG 增益与 Gain 增益叠加，总增益过高可能导致饱和
参数示例：2

返回值

local result = exs_veml3328.set_dg(dg)

result

含义说明：设置是否成功
数据类型：boolean
取值范围：true（成功），false（失败）
返回示例：true

示例

-- 设置 DG 增益为 2x
exs_veml3328.set_dg(2)

4.3.3 exs_veml3328.set_it(it)

功能

设置集成时间，决定测量的速度与精度

参数

it

参数含义：集成时间，单位 ms
数据类型：number
取值范围：50（最快，低精度，适合快速响应场景）
         / 100（默认，平衡速度与精度）
         / 200（高精度）
         / 400（最慢，最高精度，适合精确测量）
是否必选：是
注意事项：集成时间越长精度越高但响应越慢；实时性要求高的场景建议使用 100ms
参数示例：200

返回值

local result = exs_veml3328.set_it(it)

result

含义说明：设置是否成功
数据类型：boolean
取值范围：true（成功），false（失败）
返回示例：true

示例

-- 设置集成时间为 200ms
exs_veml3328.set_it(200)

4.3.4 exs_veml3328.set_sensitivity(sens)

功能

设置灵敏度模式，高灵敏度模式适合低光场景，低灵敏度模式适合强光场景

参数

sens

参数含义：灵敏度模式
数据类型：string
取值范围："high"（高灵敏度模式，适合低光检测）
         / "low"（低灵敏度模式，适合强光检测）
是否必选：是
注意事项：切换灵敏度模式后建议等待一个集成周期再读取数据
参数示例："low"

返回值

local result = exs_veml3328.set_sensitivity(sens)

result

含义说明：设置是否成功
数据类型：boolean
取值范围：true（成功），false（失败）
返回示例：true

示例

-- 切换到低灵敏度模式（强光场景）
exs_veml3328.set_sensitivity("low")

4.3.5 exs_veml3328.get_config()

功能

读取当前配置寄存器值，用于验证配置或调试

参数

无

返回值

local config = exs_veml3328.get_config()

config

含义说明：配置寄存器值
数据类型：number
取值范围：0x0000 ~ 0xFFFF（16位）
注意事项：返回 nil 表示读取失败
返回示例：0x1000

示例

local config = exs_veml3328.get_config()
if config then
    log.info("veml3328", string.format("配置寄存器: 0x%04X", config))
end

4.4 电源管理

4.4.1 exs_veml3328.enable()

功能

使能传感器，退出关机模式开始测量

参数

无

返回值

local result = exs_veml3328.enable()

result

含义说明：使能是否成功
数据类型：boolean
取值范围：true（成功），false（失败）
返回示例：true

示例

-- 从关机模式唤醒传感器
exs_veml3328.enable()
sys.wait(500)  -- 等待传感器完成初始化，500ms

4.4.2 exs_veml3328.disable()

功能

禁用传感器，进入关机模式降低功耗

参数

无

返回值

local result = exs_veml3328.disable()

result

含义说明：禁用是否成功
数据类型：boolean
取值范围：true（成功），false（失败）
返回示例：true

示例

-- 进入关机模式（降低功耗）
exs_veml3328.disable()

4.5 资源释放

4.5.1 exs_veml3328.close()

功能

释放传感器占用的资源，包括 I2C 总线等

参数

无

返回值

无

示例

-- 完成使用后释放资源
exs_veml3328.close()
log.info("veml3328", "资源已释放")

4.6 版本信息

4.6.1 exs_veml3328.version()

功能

获取扩展库版本号，用于版本兼容检查和日志标识

参数

无

返回值

local ver = exs_veml3328.version()

ver

含义说明：扩展库版本号
数据类型：string
取值范围："yyyymmddhhmm" 格式
返回示例："202608062000"

示例

log.info("veml3328", "扩展库版本:", exs_veml3328.version())

五、版本更新说明

版本号：202608071000

  1. 更新时间：2026-08-07

  2. 更新内容：

    • 正式发布版本

六、产品支持说明

所有支持 luatos 二次开发的模块，具体可以查看选型手册。

搜索
AirMaster 实时解答