exs_opt3001 扩展库

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

一、概述

1.1 主要特性

• 宽量程环境光测量：支持 0.01 ~ 83865 lux 宽量程范围，自动/手动选择 12 档量程

• 高精度照度测量：12 位模数转换，分辨率 0.01 lux，适用于自动调光、光强监测等场景

• 灵活的测量模式：支持连续测量和单次测量两种模式，转换时间可选 100ms 或 800ms

• 阈值中断功能：支持上限/下限阈值设置，通过 INT 引脚输出中断信号，可配置锁存/透明模式和中断极性

• I2C 通信接口：支持硬件 I2C 和软件 I2C 两种通信方式，I2C 地址可通过 ADDR 引脚配置

• 低功耗设计：关断模式下电流低至 0.1μA，适合电池供电应用

1.2 注意事项

• INT 引脚为开漏输出：需外部上拉电阻（通常 10kΩ），默认低有效（POL=0）

• 单次测量模式需主动触发：调用 get_data() 时会自动触发新的转换并等待完成

• 量程自动切换：默认自动量程模式，可通过 set_config() 切换为固定量程

• 照度计算公式：lux = 0.01 × 2^E × R（E=指数 0~11，R=尾数 1~4095）

• I2C 地址配置：ADDR 引脚接地时地址为 0x44，接 VDD 时地址为 0x45

1.3 硬件连接

主控与 OPT3001 模块接线

主控	OPT3001	说明
3.3V	VDD	电源
GND	GND	地线
SDA	SDA	I2C 数据线
SCL	SCL	I2C 时钟线
GND	ADDR	地址选择（接地=0x44）
GPIO（可选）	INT	中断输出

接线示意图

主控                      OPT3001 模块
┌─────────────┐          ┌─────────────┐
│  3.3V ──────┼──────────┤VDD          │
│             │          │             │
│   GND ──────┼──────────┤GND          │
│             │          │             │
│   SDA ──────┼──────────┤SDA          │
│             │          │             │
│   SCL ──────┼──────────┤SCL          │
│             │          │             │
│   GND ──────┼──────────┤ADDR         │
│             │          │             │
│   GPIO ─────┼──────────┤INT          │
└─────────────┘          └─────────────┘

1.4 加载方式

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

---

二、核心示例

2.1 连续读取照度（自动量程）

local exs_opt3001 = require "exs_opt3001"

local function main_task()
    -- 初始化
    local ok = exs_opt3001.setup({i2c_id = 1})
    if not ok then return end

    -- 连续读取 10 次（800ms 转换时间）
    for i = 1, 10 do
        local data = exs_opt3001.get_data()
        if data then
            log.info("opt3001", string.format("照度: %.2f lux", data.lux))
        end
        sys.wait(800)   -- 匹配 800ms 转换时间
    end

    exs_opt3001.close()
end

sys.taskInit(main_task)

2.2 单次测量 + 阈值中断

local exs_opt3001 = require "exs_opt3001"

-- 中断消息监听
local function int_listener()
    while true do
        local ret = sys.waitUntil("exs_opt3001_INT", 5000)
        if ret then
            local cfg = exs_opt3001.get_config()
            if cfg then
                if cfg.flag_high then
                    log.info("opt3001", "照度超过上限阈值")
                end
                if cfg.flag_low then
                    log.info("opt3001", "照度低于下限阈值")
                end
            end
        end
    end
end

local function main_task()
    -- 初始化（带中断 GPIO）
    local ok = exs_opt3001.setup({
        i2c_id = 1,
        int_gpio = 2,        -- GPIO2 作为中断引脚
    })
    if not ok then return end

    -- 设置阈值（10~1000 lux）
    exs_opt3001.set_threshold(10, 1000)

    -- 启动中断监听
    sys.taskInit(int_listener)

    -- 单次测量
    exs_opt3001.set_config({mode = "single", ct = 100})
    for i = 1, 5 do
        local data = exs_opt3001.get_data()
        if data then
            log.info("opt3001", string.format("单次测量: %.2f lux", data.lux))
        end
        sys.wait(200)       -- 间隔 200ms
    end

    exs_opt3001.close()
end

sys.taskInit(main_task)

---

三、常量解释

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

---

四、函数详解

4.1 初始化

4.1.1 exs_opt3001.setup(config)

功能

初始化 OPT3001 传感器，配置 I2C 通信、校验设备 ID、加载默认配置。

参数

config

参数含义：初始化配置表
数据类型：table
取值范围：
{
    参数含义：I2C 总线 ID（硬件 I2C 必选）
    数据类型：number
    取值范围：0 ~ 1，具体取决于硬件支持
    是否必选：否
    注意事项：仅传 i2c_id 时使用硬件 I2C
    参数示例：1
    config.i2c_id ,

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

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

    参数含义：I2C 从设备地址
    数据类型：number
    取值范围：0x44（ADDR 接地）/ 0x45（ADDR 接 VDD）
    是否必选：否
    注意事项：默认 0x44，需与硬件接线一致
    参数示例：0x44
    config.addr ,

    参数含义：中断 GPIO ID（用于接收 INT 信号）
    数据类型：number
    取值范围：根据芯片 GPIO 编号，如 2
    是否必选：可选
    注意事项：启用阈值中断功能时需要；GPIO 配置为下降沿触发
    参数示例：2
    config.int_gpio ,

    参数含义：初始工作模式
    数据类型：string
    取值范围："continuous"（连续测量，默认，适合常规监测）
             "single"（单次测量，适合低功耗场景）
             "shutdown"（关断模式，最低功耗）
    是否必选：否
    注意事项：默认 "continuous"
    参数示例："continuous"
    config.mode ,

    参数含义：转换时间
    数据类型：number
    取值范围：100（快速模式，精度较低）/ 800（精确模式，默认，精度高）
    是否必选：否
    注意事项：800ms 模式下分辨率更高；仅接受 100 或 800
    参数示例：800
    config.ct ,

    参数含义：量程配置
    数据类型：string 或 number
    取值范围："auto"（自动量程，默认，适合大多数场景）
             具体量程值：0.40 / 0.80 / 1.60 / 3.20 / 6.40 / 12.80 / 25.60 / 51.20 / 102 / 204 / 408 / 819（单位 lux，固定量程模式）
    是否必选：否
    注意事项：自动量程会在测量时自动选择合适的量程；固定量程适合已知光强范围的场景
    参数示例："auto"
    config.range ,

    参数含义：锁存模式（阈值中断行为）
    数据类型：boolean
    取值范围：true（锁存模式，默认，中断后需手动清除）/ false（透明模式，条件恢复后自动清除）
    是否必选：否
    注意事项：锁存模式下，触发中断后即使光强回到正常范围，INT 引脚仍保持有效，直到读取配置寄存器
    参数示例：true
    config.latch ,

    参数含义：中断极性
    数据类型：number
    取值范围：0（低有效，默认）/ 1（高有效）
    是否必选：否
    注意事项：OPT3001 INT 为开漏输出，默认低有效；若使用外部上拉并需要高有效，设为 1
    参数示例：0
    config.polarity ,

    参数含义：故障计数（触发中断所需的连续超限次数）
    数据类型：number
    取值范围：1（首次超限即触发，默认，适合快速响应）/ 2 / 4 / 8（多次确认后触发，适合抗干扰场景）
    是否必选：否
    注意事项：值越大抗干扰能力越强，但响应越慢
    参数示例：1
    config.fault_count ,
}
是否必选：是
参数示例：
    -- 硬件 I2C + 中断
    exs_opt3001.setup({i2c_id = 1, int_gpio = 2})

    -- 软件 I2C + 自定义参数
    exs_opt3001.setup({scl = 67, sda = 66, mode = "continuous", ct = 800})

返回值

local result = exs_opt3001.setup(config)

result

含义说明：初始化是否成功
数据类型：boolean
取值范围：true（成功），false（失败）
注意事项：失败时请检查接线、I2C 地址和供电；常见失败原因：I2C 地址错误、接线松动、电压不足
返回示例：true

示例

-- 硬件 I2C 初始化（Air780EHV I2C1）
local ok = exs_opt3001.setup({
    i2c_id = 1,
    int_gpio = 2,        -- 可选：GPIO2 中断引脚
})
if not ok then
    log.error("opt3001", "初始化失败！检查接线: VCC=3.3V GND SCL SDA")
    return
end

---

4.2 数据读取

4.2.1 exs_opt3001.get_data()

功能

读取当前照度值。连续模式下直接读取最新转换结果，单次模式下自动触发新转换并等待完成。

参数

无

返回值

local data = exs_opt3001.get_data()

data

含义说明：传感器测量数据
数据类型：table 或 nil
取值范围：
    data.lux      - 照度值，单位 lux，范围 0.01 ~ 83865
    data.raw      - 原始寄存器值（16 位）
    data.overflow - 是否溢出（boolean），溢出时需缩小量程
注意事项：单次模式下此函数会等待转换完成（最长 800ms + 50ms 超时）；溢出标志为 true 时表示当前量程不足，建议切换自动或更大量程
返回示例：{lux = 256.78, raw = 0x4235, overflow = false}

示例

local data = exs_opt3001.get_data()
if data then
    log.info("opt3001", string.format("照度: %.2f lux", data.lux))
    if data.overflow then
        log.warn("opt3001", "量程溢出，建议切换自动或更大量程")
    end
else
    log.warn("opt3001", "读取失败")
end

⚠️ 协程限制：必须在 sys.taskInit 创建的协程中调用 原因：单次测量模式下内部使用轮询等待转换完成，需要 sys.wait 让出 CPU 最长等待：800ms + 50ms 超时（单次模式）

---

4.3 阈值中断

4.3.1 exs_opt3001.set_threshold(low, high)

功能

设置照度阈值，当测量值低于 low 或高于 high 时触发 INT 中断信号。

参数

low

参数含义：低限阈值
数据类型：number
取值范围：0.01 ~ 83865，单位 lux，精确度 0.01 lux
是否必选：是
注意事项：必须小于 high；建议设置在常用光照条件附近，如室内照明 10~100 lux
参数示例：10

high

参数含义：高限阈值
数据类型：number
取值范围：0.01 ~ 83865，单位 lux，精确度 0.01 lux
是否必选：是
注意事项：必须大于 low；建议设置在需要报警的光强水平，如强光报警 1000 lux
参数示例：1000

返回值

local result = exs_opt3001.set_threshold(low, high)

result

含义说明：阈值设置是否成功
数据类型：boolean
取值范围：true（成功），false（失败）
注意事项：阈值转换为寄存器值时会自动选择最佳量程；low >= high 时会返回 false
返回示例：true

示例

-- 设置阈值：低于 10 lux 或高于 1000 lux 时触发中断
local ok = exs_opt3001.set_threshold(10, 1000)
if ok then
    log.info("opt3001", "阈值已设置")
end

4.3.2 exs_opt3001.get_threshold()

功能

读取当前设置的照度阈值。

参数

无

返回值

local th = exs_opt3001.get_threshold()

th

含义说明：当前阈值配置
数据类型：table 或 nil
取值范围：
    th.low  - 低限阈值，单位 lux
    th.high - 高限阈值，单位 lux
注意事项：返回的阈值为寄存器转换值，可能与设置时有微小差异（分辨率 0.01 lux）
返回示例：{low = 10.00, high = 1002.02}

示例

local th = exs_opt3001.get_threshold()
if th then
    log.info("opt3001", string.format("阈值: 低限=%.2f, 高限=%.2f", th.low, th.high))
end

---

4.4 参数配置

4.4.1 exs_opt3001.set_config(cfg)

功能

动态修改传感器配置参数，包括测量模式、转换时间、量程等。

参数

cfg

参数含义：配置参数表
数据类型：table
取值范围：
{
    参数含义：工作模式
    数据类型：string
    取值范围："continuous"（连续测量）/ "single"（单次测量）/ "shutdown"（关断）
    是否必选：否
    注意事项：切换为 shutdown 后传感器停止工作，需重新配置或初始化恢复
    参数示例："single"
    cfg.mode ,

    参数含义：转换时间
    数据类型：number
    取值范围：100（快速）/ 800（精确）
    是否必选：否
    注意事项：仅接受 100 或 800；其他值会自动使用默认 800
    参数示例：100
    cfg.ct ,

    参数含义：量程
    数据类型：string 或 number
    取值范围："auto"（自动）/ 具体量程值（如 0.40, 12.80, 102 等）
    是否必选：否
    注意事项：仅接受标准量程值；不识别的值会回退到 "auto"
    参数示例："auto"
    cfg.range ,

    参数含义：锁存模式
    数据类型：boolean
    取值范围：true（锁存）/ false（透明）
    是否必选：否
    参数示例：true
    cfg.latch ,

    参数含义：中断极性
    数据类型：number
    取值范围：0（低有效）/ 1（高有效）
    是否必选：否
    参数示例：0
    cfg.polarity ,

    参数含义：故障计数
    数据类型：number
    取值范围：1 / 2 / 4 / 8
    是否必选：否
    参数示例：1
    cfg.fault_count ,
}
是否必选：是
参数示例：
    -- 切换为单次 + 100ms 快速模式
    exs_opt3001.set_config({mode = "single", ct = 100})

    -- 切换为自动量程
    exs_opt3001.set_config({range = "auto"})

返回值

local result = exs_opt3001.set_config(cfg)

result

含义说明：配置更新是否成功
数据类型：boolean
取值范围：true（成功），false（失败）
注意事项：无效参数会被警告并使用默认值，但函数可能返回 true
返回示例：true

示例

-- 切换为单次测量 + 快速转换
exs_opt3001.set_config({mode = "single", ct = 100})

-- 之后的 get_data() 会自动触发新转换
local data = exs_opt3001.get_data()

4.4.2 exs_opt3001.get_config()

功能

读取当前配置寄存器并解析为结构化数据。

参数

无

返回值

local cfg = exs_opt3001.get_config()

cfg

含义说明：当前配置与状态
数据类型：table 或 nil
取值范围：
    cfg.mode        - 工作模式："continuous" / "single" / "shutdown"
    cfg.ct          - 转换时间：100 / 800，单位 ms
    cfg.range       - 量程："auto" 或具体值（如 25.60）
    cfg.conv_ready  - 转换完成标志：boolean
    cfg.flag_high   - 超限标志（高于高限）：boolean
    cfg.flag_low    - 低限标志（低于低限）：boolean
    cfg.overflow    - 溢出标志：boolean
    cfg.latch       - 锁存模式：boolean
    cfg.polarity    - 中断极性：0 / 1
    cfg.fault_count - 故障计数：1 / 2 / 4 / 8
    cfg.raw         - 原始寄存器值：number
注意事项：flag_high 和 flag_low 在锁存模式下读取后会自动清除；overflow 表示当前量程不够
返回示例：{mode="continuous", ct=800, range="auto", conv_ready=true, ...}

示例

local cfg = exs_opt3001.get_config()
if cfg then
    log.info("opt3001", string.format("模式: %s, 转换时间: %dms", cfg.mode, cfg.ct))
    if cfg.flag_high then
        log.warn("opt3001", "照度超过高限阈值")
    end
end

---

4.5 资源释放

4.5.1 exs_opt3001.close()

功能

释放 I2C 资源和中断 GPIO，将传感器置于关断模式。

参数

无

返回值

无

示例

-- 完成测量后释放资源
exs_opt3001.close()

---

4.6 版本信息

4.6.1 exs_opt3001.version()

功能

获取扩展库版本号。

参数

无

返回值

local ver = exs_opt3001.version()

ver

含义说明：扩展库版本号
数据类型：string
取值范围：格式为 YYYYMMDDHHmm，如 "202608052000"
注意事项：版本号在代码和文档中保持一致
返回示例："202608052000"

示例

log.info("opt3001", "版本: " .. exs_opt3001.version())

---

4.7 软件复位

4.7.1 exs_opt3001.soft_reset()

功能

通过关断后重新配置的方式实现软件复位，恢复默认配置。

参数

无

返回值

local result = exs_opt3001.soft_reset()

result

含义说明：复位是否成功
数据类型：boolean
取值范围：true（成功），false（失败）
注意事项：OPT3001 无硬件复位寄存器，此函数通过关断→延时→重配实现；复位后阈值会被清零，配置恢复默认值
返回示例：true

示例

-- 软件复位（恢复默认配置）
local ok = exs_opt3001.soft_reset()
if ok then
    log.info("opt3001", "复位成功")
end

⚠️ 协程限制：必须在 sys.taskInit 创建的协程中调用 原因：内部使用 sys.wait(10ms) 等待关断生效 最长等待：10ms

---

五、版本更新说明

版本号：202608061000

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

2. 更新内容：

   • 正式发布版本

   • 支持硬件 I2C 和软件 I2C

   • 支持单次/连续测量模式

   • 支持自动/手动量程选择（12 档）

   • 支持阈值中断功能（锁存/透明模式）

   • 支持配置管理和软件复位

   • 支持 I2C 总线恢复（9 时钟脉冲 + SDA 释放检测）

   • 支持 9 个对外接口

---

六、产品支持说明

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