exs_tsl2561 扩展库

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

一、概述

exs_tsl2561 是 TAOS（Texas Advanced Optoelectronic Solutions）TSL2561 光数字转换器的 LuatOS 扩展库。TSL2561 内部集成两个光电二极管（Channel 0 对可见光+红外敏感、Channel 1 仅对红外敏感）和两个 16 位积分式 ADC，通过 I2C 总线直接输出双通道数字量，配合分段经验公式即可得到接近人眼响应的照度 lux 值，广泛应用于手机/平板屏幕背光调节、键盘背光控制、路灯控制、数码相机曝光控制等场景。

TSL2561 提供 1,000,000:1 的宽动态范围，支持 1x/16x 可编程增益、13.7ms/101ms/402ms/手动四种积分时间、基于 Channel 0 的阈值中断、自动抑制 50/60Hz 灯光纹波等功能，断电模式功耗仅 3.2μA（典型），非常适合电池供电产品。

1.1 主要特性

• 双通道 16 位 ADC：CH0（可见光+红外）、CH1（仅红外），有效 20 位动态范围（1,000,000:1）
• 两种增益可选：低增益 1x（强光环境）、高增益 16x（低照度环境）
• 四种积分时间可选：13.7ms（满量程 5047）/ 101ms（满量程 37177）/ 402ms（满量程 65535）/ 手动积分
• 基于 Channel 0 的阈值中断（低阈值/高阈值 + 持久次数 PERSIST 0~15），电平中断保持直至清除
• 内置 50/60Hz 光噪声抑制电路，抗交流光源干扰
• 光谱响应接近人眼（双二极管红外补偿）
• I2C 接口速率可达 400kHz
• 3 个地址选择（ADDR SEL 引脚），支持 3 种 I2C 地址（0x29/0x39/0x49）
• 工作电压 2.7V~3.6V
• 工作温度 -30℃~+70℃

1.2 加载方式

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

1.3 注意事项

• I2C 接线：TSL2561 通过 I2C 总线与主控通信，SCL/SDA 需正确连接（Air780EHV I2C1：67=SCL、66=SDA，i2c_id=1）
• I2C 地址：由 ADDR SEL 引脚决定——接地 0x29、悬空 0x39（默认）、接 VDD 0x49；本工程配套 demo 使用 ADDR SEL 接地（地址 0x29），如模块地址不同请在 init 中指定
• I2C 上拉电阻：模块（如 GY-2561）通常已集成上拉电阻；若使用裸芯片，需在 SCL/SDA 上外接 4.7kΩ~10kΩ 上拉电阻到 3V3
• I2C 速率：TSL2561 最高支持 400kHz（Fast-Mode），本库 init 默认使用 i2c.FAST（400kHz）
• 字节序：TSL2561 字协议为低字节在前（与多数 I2C 传感器相反），本库已自动处理，调用者无需关心
• lux 自动归一化：get_lux 已按当前增益/积分时间自动归一化（以 16x + 402ms 为基准），切换增益或积分时间后读数应保持一致
• ADC 饱和：CH0 或 CH1 达到 0xFFFF 表示饱和，lux 记为 0；强光环境请改用低增益 1x 或缩短积分时间
• 手动积分：手动模式下 lux 计算无意义（积分时间未知），建议手动积分仅用于读取原始数据（get_data）
• INT 引脚：开漏输出（低有效），需上拉；本库通过 I2C 寄存器配置中断并清除，如需硬件中断通知可将 INT 连接主控 GPIO

1.4 硬件连接

  ┌──────────────┐                    ┌──────────────────┐
  │    主控       │                    │  TSL2561 光强模块 │
  │  (Airxxx)    │                    │   (GY-2561兼容)   │
  │              │                    │                  │
  │ PIN67/SCL ───┼────────────────────┼──→ SCL           │
  │              │                    │                  │
  │ PIN66/SDA ───┼────────────────────┼──→ SDA           │
  │              │                    │                  │
  │ 3V3      ────┼────────────────────┼──→ VCC（2.7~3.6V）│
  │              │                    │                  │
  │ GND      ────┼────────────────────┼──→ GND（共地）   │
  │              │                    │                  │
  │ 接地(GND) ────┼────────────────────┼──→ ADDR SEL（0x29）│
  │              │                    │                  │
  │ （可选）GPIO ─┼────────────────────┼──→ INT（开漏，上拉）│
  └──────────────┘                    └──────────────────┘

1.5 寄存器映射

TSL2561 通过命令字节访问寄存器，命令字节格式：bit7=CMD（必须为 1）、bit6=CLEAR（清中断）、bit5=WORD（字协议）、bit4=BLOCK（块协议）、bit3:0=寄存器地址。

寄存器	地址	位 7	位 6	位 5	位 4	位 3	位 2	位 1	位 0
CONTROL	0x00	-	-	-	-	-	-	POWER1	POWER0
TIMING	0x01	-	-	-	GAIN	Manual	-	INTEG1	INTEG0
THRESHLOWLOW/HIGH	0x02/0x03	-	-	-	-	低中断阈值 16 位（基于 CH0）	-	-	-
THRESHHIGHLOW/HIGH	0x04/0x05	-	-	-	-	高中断阈值 16 位（基于 CH0）	-	-	-
INTERRUPT	0x06	-	-	INTR1	INTR0	PERSIST3	PERSIST2	PERSIST1	PERSIST0
ID	0x0A	PARTNO3	PARTNO2	PARTNO1	PARTNO0	REVNO3	REVNO2	REVNO1	REVNO0
DATA0LOW/HIGH	0x0C/0x0D	-	-	-	-	ADC 通道 0 数据 16 位（低字节在前）	-	-	-
DATA1LOW/HIGH	0x0E/0x0F	-	-	-	-	ADC 通道 1 数据 16 位（低字节在前）	-	-	-

寄存器说明：

• CONTROL（0x00）：POWER=11 上电，POWER=00 断电
• TIMING（0x01）：GAIN=1 高增益 16x，GAIN=0 低增益 1x；INTEG=00 13.7ms、01 101ms、10 402ms、11 手动
• INTERRUPT（0x06）：INTR=00 中断禁用、01 电平中断；PERSIST=0 每次 ADC 周期都触发，N=连续 N 次超出阈值才触发
• ID（0x0A）：PARTNO=0001 表示 TSL2561，PARTNO=0000 表示 TSL2560
• 字协议数据均为低字节在前（先 DATAxLOW 后 DATAxHIGH），本库已自动解析

二、核心示例

核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码

核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单

更加完整和详细的 demo，请参考 LuatOS 仓库 中各个产品目录下的 demo/sensor/tsl2561

2.1 基础读取示例

-- 加载扩展库
local exs_tsl2561 = require "exs_tsl2561"

-- 应用主函数
local function tsl2561_basic_demo()
    -- 初始化 TSL2561（I2C1，默认地址 0x39；ADDR SEL 接地模块请传 0x29）
    local result = exs_tsl2561.init(1, exs_tsl2561.ADDR_GND)

    if not result then
        log.error("exs_tsl2561", "TSL2561 初始化失败")
        return
    end
    log.info("exs_tsl2561", "TSL2561 初始化成功")

    -- 每秒读取一次照度，共 5 次
    for i = 1, 5 do
        local lux = exs_tsl2561.get_lux()
        if lux then
            log.info("exs_tsl2561", string.format("照度: %.1f lux", lux))
        end
        sys.wait(1000)
    end
end

-- 启动任务
sys.taskInit(tsl2561_basic_demo)

2.2 双通道原始数据读取示例

-- 加载扩展库
local exs_tsl2561 = require "exs_tsl2561"

-- 应用主函数
local function tsl2561_raw_demo()
    -- 初始化 TSL2561（I2C1，地址 0x29，本工程模块 ADDR SEL 接地）
    local result = exs_tsl2561.init(1, exs_tsl2561.ADDR_GND)
    if not result then
        log.error("exs_tsl2561", "TSL2561 初始化失败")
        return
    end

    -- 读取 CH0/CH1 双通道原始数据
    local data = exs_tsl2561.get_data()
    if data then
        log.info("exs_tsl2561", string.format("CH0=%d（可见光+红外）, CH1=%d（仅红外）", data.ch0, data.ch1))
    end

    -- 读取 ID 寄存器（验证芯片型号）
    local id = exs_tsl2561.get_id()
    if id then
        log.info("exs_tsl2561", string.format("芯片 ID=0x%02X（PARTNO=0001 表示 TSL2561）", id))
    end
end

sys.taskInit(tsl2561_raw_demo)

2.3 低照度高灵敏度配置示例

-- 加载扩展库
local exs_tsl2561 = require "exs_tsl2561"

-- 应用主函数
local function tsl2561_lowlight_demo()
    -- 初始化 TSL2561（I2C1，地址 0x29，本工程模块 ADDR SEL 接地）
    local result = exs_tsl2561.init(1, exs_tsl2561.ADDR_GND)
    if not result then
        log.error("exs_tsl2561", "TSL2561 初始化失败")
        return
    end

    -- 切换到高增益 16x + 402ms（低照度环境最高灵敏度）
    exs_tsl2561.set_timing(exs_tsl2561.GAIN_16X, exs_tsl2561.INTEG_402MS)
    sys.wait(500)

    -- 读取照度
    local lux = exs_tsl2561.get_lux()
    log.info("exs_tsl2561", "低照度高灵敏度照度: ", lux and string.format("%.1f", lux) or "读取失败")

    -- 恢复默认配置（低增益 1x + 402ms）
    exs_tsl2561.set_timing(exs_tsl2561.GAIN_1X, exs_tsl2561.INTEG_402MS)
end

sys.taskInit(tsl2561_lowlight_demo)

2.4 阈值中断设置示例

-- 加载扩展库
local exs_tsl2561 = require "exs_tsl2561"

-- 应用主函数
local function tsl2561_int_demo()
    -- 初始化 TSL2561（I2C1，地址 0x29，本工程模块 ADDR SEL 接地）
    local result = exs_tsl2561.init(1, exs_tsl2561.ADDR_GND)
    if not result then
        log.error("exs_tsl2561", "TSL2561 初始化失败")
        return
    end

    -- 读取当前 CH0 作为阈值基准，设置 ±20% 阈值窗口
    local data = exs_tsl2561.get_data()
    if data then
        local low = data.ch0 * 0.8
        local high = data.ch0 * 1.2
        -- 设置阈值中断：电平中断模式，PERSIST=1（超出阈值 1 次触发）
        if exs_tsl2561.set_interrupt(low, high, exs_tsl2561.PERSIST_ONCE) then
            log.info("exs_tsl2561", "阈值中断设置成功, low=", low, "high=", high)
        end
    end

    -- 中断处理完成后清除中断
    exs_tsl2561.clear_interrupt()
end

sys.taskInit(tsl2561_int_demo)

三、常量解释

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

每个常量对应的常量取值仅做日志打印时查询使用，不要将这个常量取值用做具体的 业务逻辑判断，因为扩展库可能会变更每个常量对应的常量取值；

如果用做具体的业务逻辑判断，一旦常量取值发生改变，业务逻辑就会出错；

3.1 exs_tsl2561.ADDR_GND

常量含义：TSL2561 从机地址（ADDR SEL 引脚接地时，地址 0x29）
数据类型：number
注意事项：需与硬件 ADDR SEL 引脚实际接法一致，本工程 demo 使用此地址
示例代码：log.info("exs_tsl2561", exs_tsl2561.ADDR_GND)

3.2 exs_tsl2561.ADDR_FLOAT

常量含义：TSL2561 从机地址（ADDR SEL 引脚悬空时，地址 0x39）
数据类型：number
注意事项：ADDR SEL 悬空时的默认地址，也是 init 函数的默认从机地址
示例代码：log.info("exs_tsl2561", exs_tsl2561.ADDR_FLOAT)

3.3 exs_tsl2561.ADDR_VDD

常量含义：TSL2561 从机地址（ADDR SEL 引脚接 VDD 时，地址 0x49）
数据类型：number
注意事项：需与硬件 ADDR SEL 引脚实际接法一致
示例代码：log.info("exs_tsl2561", exs_tsl2561.ADDR_VDD)

3.4 exs_tsl2561.GAIN_1X

常量含义：低增益 1x（默认，适合明亮环境）
数据类型：number
注意事项：强光环境推荐使用，避免 ADC 饱和；lux 计算已自动归一化增益
示例代码：exs_tsl2561.set_timing(exs_tsl2561.GAIN_1X, exs_tsl2561.INTEG_402MS)

3.5 exs_tsl2561.GAIN_16X

常量含义：高增益 16x（适合低照度环境）
数据类型：number
注意事项：低照度环境推荐使用，灵敏度提高 16 倍；强光下可能饱和（lux 记为 0）
示例代码：exs_tsl2561.set_timing(exs_tsl2561.GAIN_16X, exs_tsl2561.INTEG_402MS)

3.6 exs_tsl2561.INTEG_13MS

常量含义：13.7ms 积分时间（满量程 5047，快速采样）
数据类型：number
注意事项：适合快速采样场景；lux 计算已自动按 (402/积分时间) 归一化
示例代码：exs_tsl2561.set_timing(exs_tsl2561.GAIN_1X, exs_tsl2561.INTEG_13MS)

3.7 exs_tsl2561.INTEG_101MS

常量含义：101ms 积分时间（满量程 37177，均衡）
数据类型：number
注意事项：兼顾采样速度与精度
示例代码：exs_tsl2561.set_timing(exs_tsl2561.GAIN_1X, exs_tsl2561.INTEG_101MS)

3.8 exs_tsl2561.INTEG_402MS

常量含义：402ms 积分时间（满量程 65535，高精度，默认）
数据类型：number
注意事项：精度最高，为默认积分时间，也是 lux 归一化基准
示例代码：exs_tsl2561.set_timing(exs_tsl2561.GAIN_1X, exs_tsl2561.INTEG_402MS)

3.9 exs_tsl2561.INTEG_MANUAL

常量含义：手动积分（Manual 位控制启停）
数据类型：number
注意事项：需配合 manual_start/manual_stop 使用；手动模式下 lux 计算无意义，建议仅读取原始数据
示例代码：exs_tsl2561.set_timing(exs_tsl2561.GAIN_1X, exs_tsl2561.INTEG_MANUAL)

3.10 exs_tsl2561.PERSIST_EVERY

常量含义：中断持久次数 0，每次 ADC 积分周期都产生中断
数据类型：number
注意事项：无需等待超出阈值次数，每次积分结束即判断并触发
示例代码：exs_tsl2561.set_interrupt(low, high, exs_tsl2561.PERSIST_EVERY)

3.11 exs_tsl2561.PERSIST_ONCE

常量含义：中断持久次数 1，超出阈值 1 次即产生中断（默认）
数据类型：number
注意事项：set_interrupt 未传 persist 参数时的默认值
示例代码：exs_tsl2561.set_interrupt(low, high, exs_tsl2561.PERSIST_ONCE)

3.12 exs_tsl2561.PERSIST_3

常量含义：中断持久次数 3，连续 3 次超出阈值才产生中断
数据类型：number
注意事项：用于滤除瞬态干扰，减少误触发
示例代码：exs_tsl2561.set_interrupt(low, high, exs_tsl2561.PERSIST_3)

四、函数详解

4.1 初始化与控制

4.1.1 exs_tsl2561.init(i2c_id, slave_address)

功能

初始化 TSL2561，配置 I2C 通信参数（400kHz 快速模式），上电后读取 ID 寄存器自动验证芯片型号（PARTNO=0001 表示 TSL2561），并设置默认时序（低增益 1x + 402ms 积分）

参数

i2c_id

参数含义：主机使用的 I2C 总线 ID，用来控制 TSL2561
数据类型：number
取值范围：平台有效的 I2C 总线编号（如 0 或 1）
是否必选：否
注意事项：可选，默认 1
参数示例：1

slave_address

参数含义：TSL2561 从机地址（由 ADDR SEL 引脚决定）
数据类型：number
取值范围：0x29（接地）/ 0x39（悬空）/ 0x49（接 VDD）
是否必选：否
注意事项：可选，默认 0x39（ADDR SEL 悬空）；GY-2561 模块默认悬空，地址为 0x39
参数示例：0x39

返回值

local init_result = exs_tsl2561.init(i2c_id, slave_address)

init_result

含义说明：初始化是否成功
数据类型：boolean
取值范围：true（成功）, false（失败）
注意事项：初始化失败时请检查接线、供电和 I2C 地址配置（ADDR SEL 引脚与代码地址是否一致）
返回示例：true

示例

-- 基础初始化（I2C1、地址 0x39）
local result = exs_tsl2561.init()

-- 自定义地址（ADDR SEL 接地，地址 0x29）
local result = exs_tsl2561.init(1, 0x29)

-- 自定义地址（ADDR SEL 接 VDD，地址 0x49）
local result = exs_tsl2561.init(1, 0x49)

4.1.2 exs_tsl2561.deinit()

功能

关闭 TSL2561 通信，释放 I2C 总线资源。关闭前先发送断电指令使传感器进入低功耗状态

参数

无

返回值

local result = exs_tsl2561.deinit()

result

含义说明：释放是否成功
数据类型：boolean
取值范围：true（成功）, false（失败）
注意事项：释放后传感器进入断电状态，如需使用需重新 init
返回示例：true

示例

exs_tsl2561.deinit()

4.2 数据读取

4.2.1 exs_tsl2561.get_lux()

功能

读取环境光照度 lux 值。自动完成"读取 CH0/CH1 双通道原始数据 → 按当前增益/积分时间归一化 → 分段公式计算"，调用者无需关心归一化细节

参数

无

返回值

local lux = exs_tsl2561.get_lux()

lux

含义说明：环境光照度 lux 值
数据类型：number（浮点数）
取值范围：0 ~ 约 100000（与增益/积分时间组合相关，强光 16x 增益饱和时返回 0）
注意事项：读取失败返回 nil；CH0/CH1 饱和（0xFFFF）时返回 0；需设备处于上电状态
返回示例：491.6

示例

-- 读取照度
local lux = exs_tsl2561.get_lux()
if lux then
    log.info("exs_tsl2561", string.format("照度: %.1f lux", lux))
end

4.2.2 exs_tsl2561.get_data()

功能

读取 CH0/CH1 双通道 16 位原始测量数据。CH0 对可见光+红外敏感，CH1 仅对红外敏感，两者比值可用于判断光源类型（如白炽灯红外占比高）

参数

无

返回值

local data = exs_tsl2561.get_data()

data

含义说明：双通道原始数据表
数据类型：table
取值范围：{ch0 = 0~65535, ch1 = 0~65535}
注意事项：读取失败返回 nil；需设备处于上电状态
返回示例：{ch0 = 1125, ch1 = 124}

示例

-- 读取双通道原始数据
local data = exs_tsl2561.get_data()
if data then
    log.info("exs_tsl2561", string.format("CH0=%d, CH1=%d", data.ch0, data.ch1))
end

4.2.3 exs_tsl2561.get_id()

功能

读取 ID 寄存器值。bit7:4 为 PARTNO（0001=TSL2561，0000=TSL2560），bit3:0 为 REVNO 版本号

参数

无

返回值

local id = exs_tsl2561.get_id()

id

含义说明：ID 寄存器值
数据类型：number
取值范围：0x00 ~ 0xFF（TSL2561 的 PARTNO 应为 0001，即高 4 位为 1）
注意事项：读取失败返回 nil
返回示例：0x13

示例

-- 读取 ID
local id = exs_tsl2561.get_id()
if id then
    log.info("exs_tsl2561", string.format("芯片 ID=0x%02X", id))
end

4.3 测量配置

4.3.1 exs_tsl2561.set_timing(gain, integ)

功能

设置增益和积分时间。gain 选择低增益 1x（强光）或高增益 16x（低照度）；integ 选择 13.7ms（快速）/ 101ms（均衡）/ 402ms（高精度）/ 手动。lux 计算已自动按 (402/积分时间) 和增益归一化，切换后读数应保持一致

参数

gain

参数含义：增益常量（exs_tsl2561.GAIN_1X / GAIN_16X）
数据类型：number
取值范围：0（1x）或 1（16x）
是否必选：是
注意事项：传入无效值返回 false
参数示例：exs_tsl2561.GAIN_16X

integ

参数含义：积分时间常量（exs_tsl2561.INTEG_13MS / INTEG_101MS / INTEG_402MS / INTEG_MANUAL）
数据类型：number
取值范围：0 ~ 3
是否必选：是
注意事项：传入无效值返回 false；INTEG_MANUAL 需配合 manual_start/manual_stop 使用
参数示例：exs_tsl2561.INTEG_402MS

返回值

local result = exs_tsl2561.set_timing(gain, integ)

result

含义说明：设置是否成功
数据类型：boolean
取值范围：true（成功）, false（失败）
注意事项：切换积分时间后建议等待对应积分时间后再读取数据
返回示例：true

示例

-- 低照度高灵敏度配置（16x 增益 + 402ms）
exs_tsl2561.set_timing(exs_tsl2561.GAIN_16X, exs_tsl2561.INTEG_402MS)

-- 快速采样配置（1x 增益 + 13.7ms）
exs_tsl2561.set_timing(exs_tsl2561.GAIN_1X, exs_tsl2561.INTEG_13MS)

4.3.2 exs_tsl2561.manual_start()

功能

开始手动积分。将 INTEG 字段置为 11（手动积分模式），并置 Manual 位为 1 启动积分。手动积分可精确控制积分时长，适合与外部光源同步（如 LED 脉冲同步）

参数

无

返回值

local result = exs_tsl2561.manual_start()

result

含义说明：启动是否成功
数据类型：boolean
取值范围：true（成功）, false（失败）
注意事项：需先 set_timing(GAIN_x, INTEG_MANUAL)；启动后需等待所需积分时间再 manual_stop
返回示例：true

示例

-- 手动积分 100ms
exs_tsl2561.set_timing(exs_tsl2561.GAIN_1X, exs_tsl2561.INTEG_MANUAL)
exs_tsl2561.manual_start()
sys.wait(100)
exs_tsl2561.manual_stop()
local data = exs_tsl2561.get_data()

4.3.3 exs_tsl2561.manual_stop()

功能

停止手动积分。清除 Manual 位，积分结果保留在 DATA0/DATA1 寄存器中，可通过 get_data 读取

参数

无

返回值

local result = exs_tsl2561.manual_stop()

result

含义说明：停止是否成功
数据类型：boolean
取值范围：true（成功）, false（失败）
注意事项：停止后建议等待 50ms 再读取数据，确保寄存器更新完成
返回示例：true

示例

exs_tsl2561.manual_stop()

4.4 中断功能

4.4.1 exs_tsl2561.set_interrupt(low, high, persist)

功能

设置阈值中断（电平中断模式）。中断基于 Channel 0（CH0）的值：CH0 低于低阈值或高于高阈值时触发，INT 引脚拉低并保持，直到写入 CLEAR 位清除。persist 控制触发条件（0=每次 ADC 周期都触发，N=连续 N 次超出阈值）

参数

low

参数含义：低阈值（基于 CH0 原始值）
数据类型：number
取值范围：0 ~ 65535
是否必选：是
注意事项：建议基于当前 CH0 实测值计算，如 CH0 × 0.8
参数示例：900

high

参数含义：高阈值（基于 CH0 原始值）
数据类型：number
取值范围：0 ~ 65535
是否必选：是
注意事项：建议基于当前 CH0 实测值计算，如 CH0 × 1.2
参数示例：1350

persist

参数含义：中断持久次数
数据类型：number
取值范围：0 ~ 15（0=每次 ADC 周期都触发；N=连续 N 次超出阈值才触发）
是否必选：否
注意事项：可选，默认 1；可用 exs_tsl2561.PERSIST_EVERY / PERSIST_ONCE / PERSIST_3 常量
参数示例：1

返回值

local result = exs_tsl2561.set_interrupt(low, high, persist)

result

含义说明：设置是否成功
数据类型：boolean
取值范围：true（成功）, false（失败）
注意事项：若当前 CH0 值已在阈值窗口外，INT 引脚会立即拉低，需调用 clear_interrupt 清除
返回示例：true

示例

-- 读取当前 CH0 并设置 ±20% 阈值窗口，PERSIST=1（超出 1 次触发）
local data = exs_tsl2561.get_data()
if data then
    local low = data.ch0 * 0.8
    local high = data.ch0 * 1.2
    exs_tsl2561.set_interrupt(low, high, exs_tsl2561.PERSIST_ONCE)
end

4.4.2 exs_tsl2561.clear_interrupt()

功能

清除挂起的电平中断。向命令字节写入 CLEAR 位（0xC0），INT 引脚释放（恢复高电平）

参数

无

返回值

local result = exs_tsl2561.clear_interrupt()

result

含义说明：清除是否成功
数据类型：boolean
取值范围：true（成功）, false（失败）
注意事项：电平中断保持直到清除，中断服务程序处理完应尽快清除
返回示例：true

示例

-- 中断处理完成后清除中断
exs_tsl2561.clear_interrupt()

4.5 电源管理

4.5.1 exs_tsl2561.power_up()

功能

发送上电指令（写 CONTROL=0x03），设备上电后开始 ADC 积分转换。init 内部已自动上电，通常无需手动调用

参数

无

返回值

local result = exs_tsl2561.power_up()

result

含义说明：上电是否成功
数据类型：boolean
取值范围：true（成功）, false（失败）
注意事项：断电后需上电并重新 set_timing 才能恢复测量
返回示例：true

示例

exs_tsl2561.power_up()
exs_tsl2561.set_timing(exs_tsl2561.GAIN_1X, exs_tsl2561.INTEG_402MS)

4.5.2 exs_tsl2561.power_down()

功能

发送断电指令（写 CONTROL=0x00），设备进入低功耗状态（功耗 3.2~15μA）。断电后 ADC 停止转换，get_data/get_lux 将返回 nil

参数

无

返回值

local result = exs_tsl2561.power_down()

result

含义说明：断电是否成功
数据类型：boolean
取值范围：true（成功）, false（失败）
注意事项：断电后 get_lux 读取会失败（返回 nil），属正常现象
返回示例：true

示例

-- 测量完成后断电，进入低功耗
exs_tsl2561.power_down()

4.5.3 exs_tsl2561.reset()

功能

复位，恢复默认配置。TSL2561 无硬件复位指令，通过"断电 → 上电 → 恢复默认时序（低增益 1x + 402ms）"实现，同时清除中断配置

参数

无

返回值

local result = exs_tsl2561.reset()

result

含义说明：复位是否成功
数据类型：boolean
取值范围：true（成功）, false（失败）
注意事项：复位后恢复默认配置（增益 1x、积分 402ms），中断配置被清除
返回示例：true

示例

-- 复位并确认读数恢复正常
exs_tsl2561.reset()
sys.wait(500)
local lux = exs_tsl2561.get_lux()

4.6 版本管理

4.6.1 exs_tsl2561.version()

功能

获取 exs_tsl2561 库的版本号

参数

无

返回值

local ver = exs_tsl2561.version()

ver

含义说明：版本号字符串
数据类型：string
取值范围：格式 "yyyymmddhhmm"，表示 yyyy年mm月dd日hh时mm分发布的版本
注意事项：无
返回示例："202608262000"

示例

local ver = exs_tsl2561.version()
log.info("exs_tsl2561", "版本号:", ver)

五、版本更新说明

版本号：202608262000

更新时间：2026-08-26

更新内容：

第一版，实现 TSL2561 基础驱动功能

• 初始化 TSL2561，自动验证芯片型号（读取 ID 寄存器 PARTNO=0001）
• 支持 CH0/CH1 双通道 16 位原始数据读取
• 支持 1x/16x 增益配置
• 支持 13.7ms/101ms/402ms/手动四种积分时间配置
• 支持 lux 照度计算（T/FN/CL 封装分段公式）
• 支持阈值中断设置与清除
• 支持手动积分
• 支持上电/断电/复位电源管理

六、产品支持说明

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