exs_tm1640 扩展库
作者：江访 | 最后修改：2026-07-13
一、概述
exs_tm1640 是天微电子 TM1640 驱动芯片的 LuatOS 扩展库。TM1640 是一款 LED 驱动控制专用 IC，内部集成 MCU 数字接口、数据锁存器、LED 驱动等电路。
TM1640 使用 2 线串行接口（CLK + DIN），用于 数码管显示，无按键扫描功能。适合需要大量数码管位数的纯显示场景。
1.1 主要特性
- 芯片最大支持 8 段 ×16 位 数码管显示
- 8 级亮度辉度调节（脉冲宽度 1/16 ~ 14/16）
- 2 线串行接口（CLK + DIN），最高时钟 1MHz
- 内置上电复位电路
- 工作电压 4.5V~5.5V
- 工作温度 -40℃~+85℃，工业级
1.2 加载方式
-- 扩展库需要 require 加载后才能调用
local exs_tm1640 = require "exs_tm1640"
1.3 注意事项
-
TM1640 使用 CLK、DIN 两线通信（无 STB 片选脚），支持自动地址递增和固定地址两种显存写入模式，通过
setup()的write_mode参数选择，默认自动递增 -
显存写入模式选择：exs_tm1640.setup(config) 的
write_mode参数可选两种模式：
| 模式 | 参数 | 写入方式 | 通信次数 | 速度 | 可靠性 | 适用场景 |
| 固定地址 | "fixed" | 固定地址，每字节独立帧 | 32 次（16 字节 × 2 次/字节） | 慢 | 高（逐帧独立，抗干扰） | 调试排查硬件接线 |
| 自动递增 | "auto" | 自动递增单帧一次写完 16 字节 | 2 次（1 次设置 + 1 次写入） | 快 | 较高 | 量产稳定运行 |
- CLK 和 DIN 需外接 4.7kΩ~10kΩ 上拉电阻到 VCC
- GRID 物理位置映射：若所购买的产品显示位置不一致（例如设置
"12345678ABCDEFGH"后实际显示"HGFEDCBA87654321"），则通过setup()的grid_map参数适配。配置方式：从左到右观察 16 位数码管，记录每个物理位置当前显示的 GRID 编号（1~16），填入数组
示例：设置
"12345678ABCDEFGH"后实际显示"HGFEDCBA87654321"，说明第 1 位显示的是 GRID16 的内容，第 16 位显示的是 GRID1 的内容。则grid_map = {16, 15, 14, 13, 12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1}- TM1640 无按键扫描功能（无 K 引脚），因此无 get_key、set_key_callback 等相关 API - TM1640 无 LED 指示灯独立控制功能
1.4 硬件连接
┌──────────────┐ ┌──────────────────┐
│ 主控 │ │ TM1640 │
│ (AirXXX) │ │ 驱动芯片 │
│ │ │ │
│ GPIO_CLK ────┼────────────────────┼──→ CLK │
│ │ │ │
│ GPIO_DIN ────┼────────────────────┼──→ DIN │
│ │ │ （需外接上拉电阻）│
│ │ │ │
│ VCC 5V ────┼────────────────────┼──→ VDD │
│ │ │ │
│ GND ────┼────────────────────┼──→ GND │
│ │ │ │
│ │ │ SEG1~SEG8 ───────┼──→ 数码管段信号
│ │ │ GRID1~GRID16 ────┼──→ 数码管位选信号
└──────────────┘ └──────────────────┘
二、核心示例
1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；
2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；
3、更加完整和详细的 demo，请参考 LuatOS 仓库 中各个产品目录下的 demo/sensor/tm1640
2.1 数码管显示示例
-- 加载扩展库
local exs_tm1640 = require "exs_tm1640"
-- 应用主函数
local function tm1640_demo()
-- 初始化 TM1640
-- clk=27, din=26, 初始亮度 3 级
local result = exs_tm1640.setup({
clk = 27,
din = 26,
bright = 3,
})
if not result then
log.error("exs_tm1640", "TM1640 初始化失败")
return
end
log.info("exs_tm1640", "TM1640 初始化成功")
-- 显示字符串
exs_tm1640.set_display("123456789ABCDEFG")
-- 延时 2 秒
sys.wait(2000)
-- 清空显示
exs_tm1640.clear()
-- 设置亮度为最亮（7 级）
exs_tm1640.set_brightness(7)
-- 从第 5 位开始显示
exs_tm1640.set_display("8888", 5)
end
-- 启动任务（sys.wait 只能在协程内使用，需要用 sys.taskInit 启动）
sys.taskInit(tm1640_demo)
三、常量解释
扩展库常量，顾名思义是由合宙 LuatOS 扩展库中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用，本扩展库没有常量。
四、函数详解
4.1 初始化与控制
4.1.1 exs_tm1640.setup(config)
功能
初始化 TM1640 驱动芯片，配置通信引脚和初始参数
参数
config
参数含义：初始化配置表
数据类型：table
取值范围：包含以下子参数：
{
参数含义：CLK 时钟引脚 GPIO 编号
数据类型：number
取值范围：有效的 GPIO 编号
是否必选：是
注意事项：该引脚连接 TM1640 的 CLK 管脚
参数示例：27
config.clk ,
参数含义：DIN 数据引脚 GPIO 编号
数据类型：number
取值范围：有效的 GPIO 编号
是否必选：是
注意事项：该引脚连接 TM1640 的 DIN 管脚，需外接 4.7kΩ~10kΩ 上拉电阻
参数示例：26
config.din ,
参数含义：显存写入模式
数据类型：string
取值范围："auto"（自动递增，默认）、"fixed"（固定地址）
是否必选：否
注意事项：自动递增模式在一帧内写完 16 字节，效率最高；固定地址模式每字节独立帧
参数示例："auto"
参数含义：初始显示亮度等级
数据类型：number
取值范围：0~7（0最暗，7最亮）
是否必选：否
注意事项：默认值为 3。设置 0 不会关闭显示
参数示例：3
config.bright ,
参数含义：是否开启显示
数据类型：boolean
取值范围：true（开启）, false（关闭）
是否必选：否
注意事项：默认值为 true。设为 false 时初始化后不点亮，之后可通过 set_brightness() 开启
参数示例：true
config.display_on ,
参数含义：GRID 物理位置映射表
数据类型：table
取值范围：包含 16 个元素的数组，每个元素为 1~16 的 GRID 编号
是否必选：否
注意事项：默认 nil（不映射）。显示位置与默认位置不一致时使用。
例如设置 "12345678ABCDEFGH" 后实际显示 "HGFEDCBA87654321"，说明顺序完全相反，
则 grid_map = {16,15,14,13,12,11,10,9,8,7,6,5,4,3,2,1}
参数示例：{16, 15, 14, 13, 12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1}
config.grid_map ,
}
是否必选：是
注意事项：必须包含 clk、din 两个引脚配置，否则初始化失败。库内部在初始化时自动清空全部 16 字节显存，无需手动调用
参数示例：{clk = 27, din = 26, bright = 3}
返回值
local init_result = exs_tm1640.setup(config)
init_result
含义说明：初始化是否成功
数据类型：boolean
取值范围：true（成功）, false（失败）
注意事项：失败时请检查接线和供电
返回示例：true
示例
-- 基础初始化
local result = exs_tm1640.setup({clk = 27, din = 26, bright = 3})
4.1.2 exs_tm1640.set_brightness(level)
功能
设置显示亮度，8 级亮度调节
参数
level
参数含义：亮度等级
数据类型：number
取值范围：0~7（0最暗，7最亮）
是否必选：是
注意事项：调用此接口会自动开启显示
参数示例：7
返回值
无
示例
exs_tm1640.set_brightness(7) -- 最亮
exs_tm1640.set_brightness(3) -- 中等
exs_tm1640.set_brightness(0) -- 最暗
4.1.3 exs_tm1640.clear()
功能
清空所有显示寄存器，熄灭所有数码管
参数
无
返回值
无
示例
exs_tm1640.set_display("123456789ABCDEFG")
sys.wait(1000)
exs_tm1640.clear()
4.2 数码管显示
4.2.1 exs_tm1640.set_display(str, offset)
功能
从指定起始位开始显示字符串
参数
str
参数含义：要显示的字符串
数据类型：string
取值范围：支持显示以下类型：
1、数字（0–9）
0, 1, 2, 3, 4, 5, 6, 7, 8, 9
2、大写字母（A–Z）
A, B, C, D, E, F, G, H, I, J, K(同H), L, M, N(同M), O(同0),
P, Q, R, S(同5), T(同R), U, V(同U), W, X(同H), Y, Z(同2)
3、小写字母（a–z）
a(同A), b(同B), c, d(同D), e(同E), f(同F), g(同9), h, i(同I),
j, k, l(同I), m, n(同m), o, p(同P), q(同Q), r, s(同S), t, u,
v(同u), w(同U), x(同H), y(同Y), z(同2)
4、其他符号
- , _ , = , °, .
是否必选：是
注意事项：点号"."作为小数点附加在前一个字符上，不占独立位置。温度显示可用 "25°C"、"77°F"表示 。° 支持 UTF-8、GBK、Latin-1 三种编码自动识别。
参数示例："123456789ABCDEFG"
offset
参数含义：起始位置
数据类型：number
取值范围：1~16（1 对应第 1 位数码管，16 对应第 16 位数码管）
是否必选：否
注意事项：默认 1。超出范围时超出部分不显示
参数示例：5
返回值
无
示例
exs_tm1640.set_display("123456789ABCDEFG")
exs_tm1640.set_display("88.88")
exs_tm1640.set_display("1234", 5) -- 从第 5 位开始显示
4.3 版本管理
4.3.1 exs_tm1640.version()
功能
获取 exs_tm1640 库的版本号
参数
无
返回值
local ver = exs_tm1640.version()
ver
含义说明：版本号字符串
数据类型：string
取值范围：格式 "yyyymmddhhmm"，表示 yyyy年mm月dd日hh时mm分发布的版本
注意事项：无
返回示例："202607131200"
示例
local ver = exs_tm1640.version()
log.info("exs_tm1640", "版本号:", ver)
五、版本更新说明
版本号：202607131200
- 更新时间：2026-07-13
-
更新内容：
-
首次发布，实现 TM1640 基础驱动功能
- 支持数码管显示（8 段 ×16 位）
- 支持 8 级亮度调节
六、产品支持说明
所有支持 luatos 二次开发的模块，具体可以查看选型手册。