exs_tm1637 扩展库

作者：江访　|　最后修改：2026-07-13

一、概述

exs_tm1637 是天微电子 TM1637 驱动芯片的 LuatOS 扩展库。TM1637 是一款带键盘扫描接口的 LED 驱动控制专用 IC，内部集成 MCU 数字接口、数据锁存器、LED 驱动、键盘扫描等电路。

TM1637 使用 2 线串行接口（CLK + DIO），一颗芯片可以同时完成 数码管显示 + 按键检测 两项功能。

1.1 主要特性

• 芯片最大支持 8 段 ×6 位 数码管显示
• 芯片最大支持 8×2bit 共 16 个按键 扫描检测
• 8 级亮度辉度调节
• 2 线串行接口（CLK + DIO），最高时钟 500kHz
• 内置上电复位电路
• 工作电压 4.5V~5.5V
• 工作温度 -40℃~+85℃，工业级

1.2 加载方式

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

1.3 注意事项

• TM1637 使用 CLK、DIO 两线通信（无 STB 片选脚），支持自动地址递增和固定地址两种显存写入模式，通过 setup() 的 write_mode 参数选择，默认自动地址递增

• 显存写入模式选择：exs_tm1637.setup(config) 的 write_mode 参数可选两种模式：

模式	参数	写入方式	通信次数	速度	可靠性	适用场景
固定地址	"fixed"	固定地址，每字节独立帧	12 次（6 字节 × 2 次/字节）	慢	高（逐帧独立，抗干扰）	调试排查硬件接线
自动递增	"auto"	自动递增批量写 6 字节	2 次（1 次设置 + 1 次写入）	快	较高	量产稳定运行

• CLK 和 DIO 需外接 4.7kΩ~10kΩ 上拉电阻到 VCC
• GRID 物理位置映射：若所购买的产品显示位置不一致（例如设置 "123456" 实际显示 "654321"），则通过 setup() 的 grid_map 参数适配。配置方式：从左到右观察 6 位数码管，记录每个物理位置当前显示的 GRID 编号（1~6），填入数组
• TM1637 不支持独立 LED 指示灯控制，无 set_led 函数
• TM1637 无 KP 中断引脚，按键读取仅支持轮询方式

1.4 硬件连接

  ┌──────────────┐                    ┌──────────────────┐
  │    主控      │                    │     TM1637       │
  │  (AirXXX)    │                    │  驱动芯片         │
  │              │                    │                  │
  │ GPIO_CLK ────┼────────────────────┼──→ CLK           │
  │              │                    │                  │
  │ GPIO_DIO ←───┼────────────────────┼──→ DIO           │
  │              │                    │  （需外接上拉电阻）│
  │              │                    │                  │
  │ VCC 5V   ────┼────────────────────┼──→ VDD           │
  │              │                    │                  │
  │ GND      ────┼────────────────────┼──→ GND           │
  │              │                    │                  │
  │              │                    │ SEG1~SEG8 ───────┼──→ 数码管段信号
  │              │                    │ GRID1~GRID6 ─────┼──→ 数码管位选信号
  │              │                    │                  │
  │              │                    │ K1~K2 ──────────┼──→ 按键矩阵行输入
  │              │                    │ KS1~KS8 ────────┼──→ 按键矩阵列扫描
  └──────────────┘                    └──────────────────┘

---

二、核心示例

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

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

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

2.1 数码管显示示例

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

-- 应用主函数
local function tm1637_demo()
    -- 初始化 TM1637
    -- clk=18, dio=17, 初始亮度 3 级
    local result = exs_tm1637.setup({
        clk    = 18,
        dio    = 17,
        bright = 3,
    })

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

    -- 显示字符串
    exs_tm1637.set_display("123456")

    -- 延时 2 秒
    sys.wait(2000)

    -- 清空显示
    exs_tm1637.clear()

    -- 设置亮度为最亮（7 级）
    exs_tm1637.set_brightness(7)

    -- 从第 3 位开始显示
    exs_tm1637.set_display("8888", 3)
end

-- 启动任务（sys.wait 只能在协程内使用，需要用 sys.taskInit 启动）
sys.taskInit(tm1637_demo)

2.2 按键检测示例

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

-- 按键回调函数
local function on_key(key_code)
    log.info("exs_tm1637", "按键回调，编码:", key_code)
    exs_tm1637.set_display(string.format("KEY%02d", key_code))
end

-- 初始化
local result = exs_tm1637.setup({
    clk     = 18,
    dio     = 17,
    bright  = 3,
})

-- 方式一：轮询读取按键
local function key_scan_task()
    while true do
        local key = exs_tm1637.get_key()
        if key then
            log.info("exs_tm1637", "按键按下，编码:", key)
        end
        sys.wait(50)
    end
end
sys.taskInit(key_scan_task)

-- 方式二：回调方式（推荐）
exs_tm1637.set_key_callback(on_key)

---

三、常量解释

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

---

四、函数详解

4.1 初始化与控制

4.1.1 exs_tm1637.setup(config)

功能

初始化 TM1637 驱动芯片，配置通信引脚和初始参数

参数

config

参数含义：初始化配置表
数据类型：table
取值范围：包含以下子参数：
{
    参数含义：CLK 时钟引脚 GPIO 编号
    数据类型：number
    取值范围：有效的 GPIO 编号
    是否必选：是
    注意事项：该引脚连接 TM1637 的 CLK 管脚
    参数示例：18
    config.clk ,

    参数含义：DIO 数据引脚 GPIO 编号
    数据类型：number
    取值范围：有效的 GPIO 编号
    是否必选：是
    注意事项：该引脚连接 TM1637 的 DIO 管脚，需外接 4.7kΩ~10kΩ 上拉电阻
    参数示例：17
    config.dio ,

    参数含义：初始显示亮度等级
    数据类型：number
    取值范围：0~7（0最暗，7最亮）
    是否必选：否
    注意事项：默认值为 3。设置 0 不会关闭显示
    参数示例：3
    config.bright ,

    参数含义：是否开启显示
    数据类型：boolean
    取值范围：true（开启）, false（关闭）
    是否必选：否
    注意事项：默认值为 true。设为 false 时初始化后不点亮，之后可通过 set_brightness() 开启
    参数示例：true
    config.display_on ,

    参数含义：GRID 物理位置映射表
    数据类型：table
    取值范围：包含 6 个元素的数组，每个元素为 1~6 的 GRID 编号
    是否必选：否
    注意事项：默认 nil（不映射）。显示位置与默认位置不一致时使用。
             例如设置 "123456" 后实际显示 "654321"，则填入 {6,5,4,3,2,1}
    参数示例：{3, 4, 5, 6, 1, 2}
    config.grid_map ,
}
是否必选：是
注意事项：必须包含 clk、dio 两个引脚配置，否则初始化失败。库内部在初始化时自动清空全部显存，无需手动调用
参数示例：{clk = 18, dio = 17, bright = 3}

返回值

local init_result = exs_tm1637.setup(config)

init_result

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

示例

-- 基础初始化
local result = exs_tm1637.setup({clk = 18, dio = 17, bright = 3})

---

4.1.2 exs_tm1637.set_brightness(level)

功能

设置显示亮度，8 级亮度调节

参数

level

参数含义：亮度等级
数据类型：number
取值范围：0~7（0最暗，7最亮）
是否必选：是
注意事项：调用此接口会自动开启显示
参数示例：7

返回值

无

示例

exs_tm1637.set_brightness(7)  -- 最亮
exs_tm1637.set_brightness(3)  -- 中等
exs_tm1637.set_brightness(0)  -- 最暗

---

4.1.3 exs_tm1637.clear()

功能

清空所有显示寄存器，熄灭所有数码管

参数

无

返回值

无

示例

exs_tm1637.set_display("654321")
sys.wait(1000)
exs_tm1637.clear()

---

4.2 数码管显示

4.2.1 exs_tm1637.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 三种编码自动识别。
参数示例："123456"

offset

参数含义：起始位置
数据类型：number
取值范围：1~6（1 对应第 1 位数码管，6 对应第 6 位数码管）
是否必选：否
注意事项：默认 1。超出范围时超出部分不显示
参数示例：3

返回值

无

示例

exs_tm1637.set_display("123456")
exs_tm1637.set_display("88.88")
exs_tm1637.set_display("1234", 3)  -- 从第 3 位开始显示

---

4.3 按键扫描

TM1637 内置 8×2 按键扫描矩阵，最多支持 16 个按键。按键扫描由芯片自动完成（内部每 4.7ms 扫描一轮），结果存储在芯片内部的按键寄存器中，主控只需要通过通信总线读取即可。

TM1637 的按键读取只能用轮询方式，无 KP 中断引脚。支持中断的型号是 TM1650（有专用 KP 引脚）。

按键编码 1~16 的排列：

      KS1  KS2  KS3  KS4  KS5  KS6  KS7  KS8
K1 ──  1    2    3    4    5    6    7    8
K2 ──  9   10   11   12   13   14   15   16

4.3.1 exs_tm1637.get_key()

功能

轮询读取当前按下的按键编码，无按键按下时返回 nil

参数

无

返回值

local key = exs_tm1637.get_key()

key

含义说明：按键编码
数据类型：number 或 nil
取值范围：1~16（有按键按下），nil（无按键按下）
注意事项：多个键同时按下时返回编码最小的那个
返回示例：5

示例

local function check_key_task()
    while true do
        local key = exs_tm1637.get_key()
        if key then
            log.info("exs_tm1637", "检测到按键:", key)
        end
        sys.wait(30)
    end
end
sys.taskInit(check_key_task)

---

4.3.2 exs_tm1637.set_key_callback(cbfunc)

功能

设置按键回调函数。注册后库内部每隔 50ms 自动轮询，按键按下时调用回调。

设备进入低功耗休眠前，必须先调用 exs_tm1637.set_key_callback(nil) 停止内部轮询定时器，否则定时器会阻止休眠。唤醒后重新注册回调即可。

参数

cbfunc

参数含义：按键回调函数
数据类型：function
取值范围：有效的 Lua 函数
是否必选：是
注意事项：回调接收一个参数 key_code（number 类型 1~16）。传入 nil 取消回调。回调中避免长时间阻塞
参数示例：local function on_key(key_code) log.info("key", key_code) end

返回值

无

示例

-- 按键回调函数
local function on_key(key_code)
    log.info("exs_tm1637", "按键:", key_code)
end

-- 注册
exs_tm1637.set_key_callback(on_key)

-- 取消
exs_tm1637.set_key_callback(nil)

---

4.4 版本管理

4.4.1 exs_tm1637.version()

功能

获取 exs_tm1637 库的版本号

参数

无

返回值

local ver = exs_tm1637.version()

ver

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

示例

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

---

五、版本更新说明

版本号：202607131200

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

2. 更新内容：

3. 首次发布，实现 TM1637 基础驱动功能

4. 支持数码管显示（8 段 ×6 位）
5. 支持按键扫描（轮询 + 回调两种方式）
6. 支持 8 级亮度调节

---

六、产品支持说明

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