exs_tm1650 扩展库
作者：江访 | 最后修改：2026-07-13
一、概述
exs_tm1650 是天微电子 TM1650 驱动芯片的 LuatOS 扩展库。TM1650 是一款带键盘扫描接口的 LED 驱动控制专用 IC，内部集成 MCU 数字接口、数据锁存器、LED 驱动、键盘扫描等电路。
TM1650 使用 2 线串行接口（CLK + DIO），一颗芯片可以同时完成 数码管显示 + 按键检测 两项功能，并支持 KP 中断引脚，按键按下时产生中断信号，无需轮询。
1.1 主要特性
- 芯片最大支持 8/7 段 ×4 位 数码管显示（支持 7 段/8 段模式切换）
- 芯片最大支持 7×4bit 共 28 个按键 扫描检测
- 8 级亮度辉度调节
- 2 线串行接口（CLK + DIO），最高时钟 500KHz
- 支持 KP 中断引脚（INTN 脚），按键按下时输出下降沿中断信号
- 内置上电复位电路
- 工作电压 4.5V~5.5V
- 工作温度 -40℃~+85℃，工业级
1.2 加载方式
-- 扩展库需要 require 加载后才能调用
local exs_tm1650 = require "exs_tm1650"
1.3 注意事项
- TM1650 使用 CLK、DIO 两线通信（无 STB 片选脚），通信协议与 TM1637 类似
- CLK 和 DIO 需外接 4.7kΩ~10kΩ 上拉电阻到 VCC
- GRID 物理位置映射：若所购买的产品显示位置不一致（例如设置
"1234"实际显示"4321"），则通过setup()的grid_map参数适配。配置方式：从左到右观察 4 位数码管，记录每个物理位置当前显示的 GRID 编号（1~4），填入数组 - KP 中断引脚：TM1650 的第 7 脚为 KP/SEG8/DP 复用引脚。当配置 KP 中断检测按键时，该引脚被用作中断输出，数码管的 DP（小数点）段无法使用，必须用
set_mode(1)切换到 7 段模式（a~g 七个段）。如需使用小数点显示（8 段模式），请勿连接 KP 引脚，改用轮询方式（50ms 间隔）读取按键。库内部自动根据是否传入kp参数选择中断或轮询方式 - 低功耗休眠前必须关闭按键回调：如果使用了
exs_tm1650.set_key_callback()，设备进入休眠前需调用exs_tm1650.set_key_callback(nil)停止内部轮询定时器，否则定时器会阻止系统进入低功耗模式 - TM1650 无独立 LED 指示灯控制功能，无 set_led 函数
1.4 硬件连接
┌──────────────┐ ┌──────────────────┐
│ 主控 │ │ TM1650 │
│ (AirXXX) │ │ 驱动芯片 │
│ │ │ │
│ GPIO_CLK ────┼────────────────────┼──→ CLK │
│ │ │ │
│ GPIO_DIO ←───┼────────────────────┼──→ DIO │
│ │ │ （需外接上拉电阻）│
│ GPIO_KP ←───┼────────────────────┼──→ INTN/KP │
│ │ │ （可选中断输入） │
│ │ │ │
│ VCC 5V ────┼────────────────────┼──→ VDD │
│ │ │ │
│ GND ────┼────────────────────┼──→ GND │
│ │ │ │
│ │ │ SEG A~G + DP ────┼──→ 数码管段信号
│ │ │ GRID1~GRID4 ─────┼──→ 数码管位选信号
│ │ │ │
│ │ │ KI1~KI7 ────────┼──→ 按键矩阵行输入
│ │ │ GRID1~GRID4 ────┼──→ 按键矩阵列扫描
└──────────────┘ └──────────────────┘
二、核心示例
1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；
2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；
3、更加完整和详细的 demo，请参考 LuatOS 仓库 中各个产品目录下的 demo/sensor/tm1650
2.1 数码管显示示例
-- 加载扩展库
local exs_tm1650 = require "exs_tm1650"
-- 应用主函数
local function tm1650_demo()
-- 初始化 TM1650
-- clk=18, dio=17, 初始亮度 3 级
local result = exs_tm1650.setup({
clk = 18,
dio = 17,
bright = 3,
})
if not result then
log.error("exs_tm1650", "TM1650 初始化失败")
return
end
log.info("exs_tm1650", "TM1650 初始化成功")
-- 显示字符串
exs_tm1650.set_display("1234")
-- 延时 2 秒
sys.wait(2000)
-- 清空显示
exs_tm1650.clear()
-- 设置亮度为最亮（7 级）
exs_tm1650.set_brightness(7)
-- 从第 3 位开始显示
exs_tm1650.set_display("8888", 3)
end
-- 启动任务（sys.wait 只能在协程内使用，需要用 sys.taskInit 启动）
sys.taskInit(tm1650_demo)
2.2 按键检测示例
-- 加载扩展库
local exs_tm1650 = require "exs_tm1650"
-- 按键回调函数
local function on_key(key_code)
log.info("exs_tm1650", "按键回调，编码:", key_code)
exs_tm1650.set_display(string.format("KEY%02d", key_code))
end
-- 初始化（配置 KP 中断引脚）
local result = exs_tm1650.setup({
clk = 18,
dio = 17,
kp = 16, -- KP 中断引脚（可选，使用后需 set_mode(1) 切换到 7 段模式，DP 段不可用）
bright = 3,
})
-- 方式一：轮询读取按键
local function key_scan_task()
while true do
local key = exs_tm1650.get_key()
if key then
log.info("exs_tm1650", "按键按下，编码:", key)
end
sys.wait(50)
end
end
sys.taskInit(key_scan_task)
-- 方式二：回调方式（推荐，配置 kp 引脚时将自动使用中断）
exs_tm1650.set_key_callback(on_key)
2.3 模式切换示例
local exs_tm1650 = require "exs_tm1650"
exs_tm1650.setup({clk = 18, dio = 17, bright = 3})
-- 切换 7 段模式
exs_tm1650.set_mode(1) -- 7 段模式
exs_tm1650.set_display("7SEG")
sys.wait(2000)
-- 切换回 8 段模式
exs_tm1650.set_mode(0) -- 8 段模式
exs_tm1650.set_display("8SEG")
sys.wait(2000)
三、常量解释
扩展库常量，顾名思义是由合宙 LuatOS 扩展库中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用，本扩展库没有常量。
四、函数详解
4.1 初始化与控制
4.1.1 exs_tm1650.setup(config)
功能
初始化 TM1650 驱动芯片，配置通信引脚和初始参数
参数
config
参数含义：初始化配置表
数据类型：table
取值范围：包含以下子参数：
{
参数含义：CLK 时钟引脚 GPIO 编号
数据类型：number
取值范围：有效的 GPIO 编号
是否必选：是
注意事项：该引脚连接 TM1650 的 CLK 管脚
参数示例：18
config.clk ,
参数含义：DIO 数据引脚 GPIO 编号
数据类型：number
取值范围：有效的 GPIO 编号
是否必选：是
注意事项：该引脚连接 TM1650 的 DIO 管脚，需外接 4.7kΩ~10kΩ 上拉电阻
参数示例：17
config.dio ,
参数含义：KP 中断引脚 GPIO 编号
数据类型：number
取值范围：有效的 GPIO 编号
是否必选：否
注意事项：可选，连接 TM1650 的 INTN/KP 管脚（第 7 脚）。该引脚与 SEG8/DP 硬件复用，配置 kp 后 DP 段被用作中断输出，必须使用 7 段模式（set_mode(1)），此时小数点不显示。如需显示小数点（8 段模式），请勿连接 KP 引脚，改用轮询方式读取按键。配置后注册按键回调时将使用中断方式，而非轮询
参数示例：16
config.kp ,
参数含义：初始显示亮度等级
数据类型：number
取值范围：0~7（0最暗，7最亮）
是否必选：否
注意事项：默认值为 3。设置 0 不会关闭显示
参数示例：3
config.bright ,
参数含义：是否开启显示
数据类型：boolean
取值范围：true（开启）, false（关闭）
是否必选：否
注意事项：默认值为 true。设为 false 时初始化后不点亮，之后可通过 set_brightness() 开启
参数示例：true
config.display_on ,
参数含义：GRID 物理位置映射表
数据类型：table
取值范围：包含 4 个元素的数组，每个元素为 1~4 的 GRID 编号
是否必选：否
注意事项：默认 nil（不映射）。显示位置与默认位置不一致时使用。
例如设置 "1234" 后实际显示 "4321"，则填入 {4,3,2,1}
参数示例：{3, 4, 1, 2}
config.grid_map ,
}
是否必选：是
注意事项：必须包含 clk、dio 两个引脚配置，否则初始化失败。库内部在初始化时自动清空全部显存并设置显示模式，无需手动调用
参数示例：{clk = 18, dio = 17, bright = 3}
返回值
local init_result = exs_tm1650.setup(config)
init_result
含义说明：初始化是否成功
数据类型：boolean
取值范围：true（成功）, false（失败）
注意事项：失败时请检查接线和供电
返回示例：true
示例
-- 基础初始化
local result = exs_tm1650.setup({clk = 18, dio = 17, bright = 3})
-- 带 KP 中断引脚
local result = exs_tm1650.setup({clk = 18, dio = 17, kp = 16, bright = 3})
4.1.2 exs_tm1650.set_brightness(level)
功能
设置显示亮度，8 级亮度调节
参数
level
参数含义：亮度等级
数据类型：number
取值范围：0~7（0最暗，7最亮）
是否必选：是
注意事项：调用此接口会自动开启显示
参数示例：7
返回值
无
示例
exs_tm1650.set_brightness(7) -- 最亮
exs_tm1650.set_brightness(3) -- 中等
exs_tm1650.set_brightness(0) -- 最暗
4.1.3 exs_tm1650.clear()
功能
清空所有显示寄存器，熄灭所有数码管
参数
无
返回值
无
示例
exs_tm1650.set_display("4321")
sys.wait(1000)
exs_tm1650.clear()
4.2 数码管显示
4.2.1 exs_tm1650.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 三种编码自动识别。
参数示例："1234"
offset
参数含义：起始位置
数据类型：number
取值范围：1~4（1 对应第 1 位数码管，4 对应第 4 位数码管）
是否必选：否
注意事项：默认 1。超出范围时超出部分不显示
参数示例：3
返回值
无
示例
exs_tm1650.set_display("1234")
exs_tm1650.set_display("88.8")
exs_tm1650.set_display("12", 3) -- 从第 3 位开始显示
4.2.2 exs_tm1650.set_mode(mode)
功能
切换 7 段/8 段显示模式
- 8 段模式（默认）：a~g + DP，支持小数点
- 7 段模式：a~g 七个段，DP 段不可用，适合纯数字显示
参数
mode
参数含义：显示模式
数据类型：number
取值范围：0（8 段模式），1（7 段模式）
是否必选：是
注意事项：切换模式后所有显示内容立即生效
参数示例：0
返回值
无
示例
exs_tm1650.set_mode(0) -- 8 段模式（默认）
exs_tm1650.set_mode(1) -- 7 段模式
4.3 按键扫描
TM1650 内置 7×4 按键扫描矩阵，最多支持 28 个按键。按键扫描由芯片自动完成（内部定时扫描），结果存储在芯片内部的按键寄存器中，主控只需要通过通信总线读取即可。
TM1650 支持 KP 中断引脚（INTN 脚），按键按下时输出下降沿中断信号。在 setup() 时配置 kp 引脚后，注册按键回调将自动使用中断方式，无需轮询。
⚠ KP/SEG8/DP 复用说明：第 7 脚同时用作 KP 中断输出和小数点（DP）段驱动。使用 KP 中断时，必须切换到 7 段模式（set_mode(1)），此时 DP 段不可用，无法显示小数点。如需显示小数点（8 段模式），请勿连接 KP 引脚，使用轮询方式读取按键。
按键编码 1~28 的排列：
GRID1 GRID2 GRID3 GRID4
KI1: 1 2 3 4
KI2: 5 6 7 8
KI3: 9 10 11 12
KI4: 13 14 15 16
KI5: 17 18 19 20
KI6: 21 22 23 24
KI7: 25 26 27 28
4.3.1 exs_tm1650.get_key()
功能
轮询读取当前按下的按键编码，无按键按下时返回 nil
参数
无
返回值
local key = exs_tm1650.get_key()
key
含义说明：按键编码
数据类型：number 或 nil
取值范围：1~28（有按键按下），nil（无按键按下）
注意事项：多个键同时按下时返回编码最小的那个
返回示例：5
示例
local function check_key_task()
while true do
local key = exs_tm1650.get_key()
if key then
log.info("exs_tm1650", "检测到按键:", key)
end
sys.wait(30)
end
end
sys.taskInit(check_key_task)
4.3.2 exs_tm1650.set_key_callback(cbfunc)
功能
设置按键回调函数。注册后库内部自动轮询或使用 KP 中断读取按键。
中断 vs 轮询选择：
- 如果
setup()时配置了kp引脚：注册回调后将配置 KP 引脚为下降沿中断，按键按下时触发中断读取，CPU 占用更低 - 使用 KP 中断前提：KP/SEG8/DP 为复用引脚，配置 kp 后必须用
set_mode(1)切换到 7 段模式（DP 段不可用），否则小数点无法显示。如需使用小数点（8 段模式），请勿连接 KP 引脚 - 如果未配置
kp引脚：库内部每隔 50ms 自动轮询按键状态
设备进入低功耗休眠前，必须先调用 exs_tm1650.set_key_callback(nil) 停止内部轮询定时器，否则定时器会阻止休眠。唤醒后重新注册回调即可。
参数
cbfunc
参数含义：按键回调函数
数据类型：function
取值范围：有效的 Lua 函数
是否必选：是
注意事项：回调接收一个参数 key_code（number 类型 1~28）。传入 nil 取消回调。回调中避免长时间阻塞
参数示例：local function on_key(key_code) log.info("key", key_code) end
返回值
无
示例
-- 按键回调函数
local function on_key(key_code)
log.info("exs_tm1650", "按键:", key_code)
end
-- 注册
exs_tm1650.set_key_callback(on_key)
-- 取消
exs_tm1650.set_key_callback(nil)
4.4 版本管理
4.4.1 exs_tm1650.version()
功能
获取 exs_tm1650 库的版本号
参数
无
返回值
local ver = exs_tm1650.version()
ver
含义说明：版本号字符串
数据类型：string
取值范围：格式 "yyyymmddhhmm"，表示 yyyy年mm月dd日hh时mm分发布的版本
注意事项：无
返回示例："202607131200"
示例
local ver = exs_tm1650.version()
log.info("exs_tm1650", "版本号:", ver)
五、版本更新说明
版本号：202607131200
- 更新时间：2026-07-13
-
更新内容：
-
首次发布，实现 TM1650 基础驱动功能
- 支持数码管显示（8/7 段 ×4 位，支持 7 段/8 段模式切换）
- 支持按键扫描（轮询 + 回调两种方式，支持 KP 中断）
- 支持 8 级亮度调节
六、产品支持说明
所有支持 luatos 二次开发的模块，具体可以查看选型手册。