跳转至

exs_aip650e 扩展库

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

一、概述

exs_aip650e 是中微爱芯 AiP650E 驱动芯片的 LuatOS 扩展库。AiP650E 是一款带键盘扫描接口的 LED 驱动控制专用 IC，内部集成 MCU 数字接口、数据锁存器、LED 驱动、键盘扫描、辉度调节等电路。

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

1.1 主要特性

  • 显示模式：8 段 ×4 位（支持 7 段/8 段模式切换）
  • 段驱动电流 ≥25mA，字驱动电流 ≥150mA
  • 8 级亮度控制（脉冲宽度调节）
  • 键盘扫描：7×4bit，最多 28 个独立按键 + 4 个组合按键（KI1+KI2）
  • 2 线串行接口（CLK + DIO，I²C 类协议），内置上拉电阻
  • 内置时钟振荡电路和上电复位电路
  • 支持 KP 中断引脚（DP/KP 脚），按键按下时产生中断信号
  • 支持 睡眠模式和唤醒
  • 工作电压 3V~5.5V
  • 工作温度 -40℃~+105℃（工业级）
  • 封装形式：DIP16 / SOP16 / SSOP16(0.635mm) / QFN16(3×3)

1.2 加载方式

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

1.3 注意事项

  • AiP650E 使用 CLK 和 DIO 两线通信（无 STB 片选脚），类似 I²C 协议。CLK 上升沿锁存数据，CLK=H 时 DIO 下降沿为起始条件、上升沿为停止条件
  • DIO 为内置上拉开漏模式，建议外接 4.7kΩ~10kΩ 上拉电阻到 VCC
  • VDD 端建议加 104 电容，且电容尽量靠近 AiP650E 的 VDD 端口（建议小于 2cm）
  • GRID 物理位置映射：如果 PCB 走线导致显示位置与预期不一致（如设置 "1234" 显示为 "4321"），通过 setup() 的 grid_map 参数适配
  • KP 中断引脚：DP/KP 脚为段/位复用输出，也用作键盘标志输出。使用中断模式可以替代轮询，降低 CPU 占用
  • 低功耗休眠前必须关闭按键回调：如果使用了 exs_aip650e.set_key_callback()，设备进入休眠前需调用 exs_aip650e.set_key_callback(nil) 停止内部轮询定时器，否则定时器会阻止系统进入低功耗模式
  • 如需驱动共阳数码管，在 exs_aip650e.setup() 时传入 common_anode = true
  • 上电后必须先对 RAM 进行数据写入，然后再开显示

1.4 硬件连接

  ┌──────────────┐                    ┌──────────────────┐
  │    主控      │                    │     AiP650E      │
  │  (AirXXX)    │                    │     驱动芯片     │
  │              │                    │                  │
  │ GPIO_CLK ────┼────────────────────┼──→ CLK           │
  │              │                    │                  │
  │ GPIO_DIO ←───┼────────────────────┼──→ DIO           │
  │              │                    │  （需外接上拉）   │
  │ GPIO_KP  ←───┼────────────────────┼──→ DP/KP         │
  │              │                    │  （可选中断输入） │
  │ VCC 3-5V ────┼────────────────────┼──→ VDD           │
  │              │                    │      +104电容    │
  │ GND      ────┼────────────────────┼──→ GND           │
  │              │                    │                  │
  │              │                    │ SEG A~G + DP  ───┼──→ 数码管段信号
  │              │                    │                  │
  │              │                    │ DIG1~DIG4────────┼──→ 数码管位选信号
  │              │                    │                  │
  │              │                    │ KI1~KI7 + DIG1~4─┼──→ 按键矩阵(7×4)
  └──────────────┘                    └──────────────────┘

二、核心示例

2.1 数码管显示示例

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

-- 应用主函数
local function aip650e_demo()
    -- 初始化 AiP650E，clk=27, dio=26, 初始亮度 3 级
    local result = exs_aip650e.setup({
        clk    = 27,
        dio    = 26,
        bright = 3,
    })
    if not result then
        log.error("exs_aip650e", "初始化失败")
        return
    end
    log.info("exs_aip650e", "初始化成功")

    -- 显示字符串
    exs_aip650e.set_display("1234")
    sys.wait(2000)

    -- 清空显示
    exs_aip650e.clear()

    -- 从第 3 位开始显示
    exs_aip650e.set_display("8888", 3)
    sys.wait(2000)
    exs_aip650e.clear()

    -- 温度显示
    exs_aip650e.set_display("25°C")
    sys.wait(3000)
end

sys.taskInit(aip650e_demo)

2.2 按键检测示例

local exs_aip650e = require "exs_aip650e"

-- 初始化
local result = exs_aip650e.setup({
    clk    = 27,
    dio    = 26,
    bright = 3,
})

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

-- 方式二：回调方式（推荐）
local function on_key(key_code)
    log.info("exs_aip650e", "按键回调，编码:", key_code)
    exs_aip650e.set_display(string.format("%02d", key_code))
end
exs_aip650e.set_key_callback(on_key)

2.3 亮度调节和模式切换示例

local exs_aip650e = require "exs_aip650e"

exs_aip650e.setup({clk = 27, dio = 26, bright = 3})

-- 从最暗到最亮逐级调节
for bright = 0, 7 do
    exs_aip650e.set_brightness(bright)
    exs_aip650e.set_display(string.format("%04d", bright))
    sys.wait(500)
end
exs_aip650e.clear()

-- 切换 7 段模式
exs_aip650e.set_mode(1)  -- 7 段模式
exs_aip650e.set_display("7SEG")
sys.wait(2000)

-- 切换回 8 段模式
exs_aip650e.set_mode(0)  -- 8 段模式
exs_aip650e.set_display("8SEG")
sys.wait(2000)

三、常量解释

扩展库常量，是由合宙 LuatOS 扩展库中定义的、不可重新赋值或修改的固定值。本扩展库没有对外暴露的常量。

四、函数详解

4.1 初始化与控制

4.1.1 exs_aip650e.setup(config)

功能

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

参数

config

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

    参数含义：DIO 数据引脚 GPIO 编号
    数据类型：number
    取值范围：有效的 GPIO 编号
    是否必选：是
    注意事项：该引脚连接 AiP650E 第 3 脚（DIO），需外接 4.7kΩ~10kΩ 上拉电阻到 VCC
    参数示例：26
    dio ,

    参数含义：KP 中断引脚 GPIO 编号
    数据类型：number
    取值范围：有效的 GPIO 编号
    是否必选：否
    注意事项：可选，连接 AiP650E 第 16 脚（DP/KP）。注册回调后优先使用中断读取按键
    参数示例：25
    kp ,

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

    参数含义：是否使用共阳数码管
    数据类型：boolean
    取值范围：true（共阳），false（共阴）
    是否必选：否
    注意事项：默认 false（共阴极）。设为 true 时库内部自动对段码取反
    参数示例：false
    common_anode ,

    参数含义：GRID 物理位置映射表
    数据类型：table
    取值范围：包含 4 个元素的数组，每个元素为 1~4 的 GRID 编号
    是否必选：否
    注意事项：默认 nil（不映射）。显示位置与预期不一致时使用。
              例如设置 "1234" 后实际显示 "4321"，则填入 {4,3,2,1}
    参数示例：{3, 4, 1, 2}
    grid_map ,

    参数含义：是否启用 7 段显示模式
    数据类型：boolean
    取值范围：true（7 段模式），false（8 段模式）
    是否必选：否
    注意事项：默认 false（8 段模式）。7 段模式下 DP 段不可用
    参数示例：false
    segment_7seg ,
}
是否必选：是
注意事项：必须包含 clk、dio 两个引脚配置，否则初始化失败。
库内部在初始化时自动清空 4 个显示地址（68H/6AH/6CH/6EH）并设置显示控制命令
参数示例：{clk = 27, dio = 26, bright = 3}

返回值

local init_result = exs_aip650e.setup(config)

init_result

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

示例

-- 基础初始化
local result = exs_aip650e.setup({clk = 27, dio = 26, bright = 3})

-- 共阳数码管
local result = exs_aip650e.setup({clk = 27, dio = 26, bright = 3, common_anode = true})

4.1.2 exs_aip650e.set_brightness(level)

功能

设置显示亮度，8 级亮度调节。调用此接口会自动开启显示并退出睡眠模式。

参数

level

参数含义：亮度等级
数据类型：number
取值范围：0~7（0 最暗，7 最亮）
是否必选：是
参数示例：7

返回值

无

示例

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

4.1.3 exs_aip650e.display_on()

功能

开启数码管显示（恢复显示）。

参数

无

返回值

无

示例

exs_aip650e.display_off()
sys.wait(1000)
exs_aip650e.display_on()

4.1.4 exs_aip650e.display_off()

功能

关闭数码管显示（熄灭，显存数据保留）。

参数

无

返回值

无

示例

exs_aip650e.display_off()

4.1.5 exs_aip650e.sleep()

功能

进入睡眠模式（低功耗）。睡眠模式关闭显示振荡器，显存数据保留。

参数

无

返回值

无

注意事项

进入低功耗休眠前，必须先调用 exs_aip650e.set_key_callback(nil) 停止内部轮询定时器。

示例

-- 低功耗前，先停止按键回调
exs_aip650e.set_key_callback(nil)
-- 进入睡眠
exs_aip650e.sleep()

4.1.6 exs_aip650e.wakeup()

功能

从睡眠模式唤醒，恢复数码管显示。

参数

无

返回值

无

示例

exs_aip650e.wakeup()

4.1.7 exs_aip650e.clear()

功能

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

参数

无

返回值

无

示例

exs_aip650e.set_display("1234")
sys.wait(1000)
exs_aip650e.clear()

4.2 数码管显示

4.2.1 exs_aip650e.set_display(str, offset)

功能

从指定起始位开始显示字符串，自动查段码表。

参数

str

参数含义：要显示的字符串
数据类型：string
取值范围：支持数字 0-9、大小写字母 A-Z/a-z、点号、减号、等于号、空格、度符号
是否必选：是
注意事项：点号 "." 作为小数点附加在前一个字符上，不占独立位置。
温度显示可用 "25°C" 表示 25℃。° 支持 UTF-8、GBK、Latin-1 三种编码自动识别。
不支持的字符显示为空格。
参数示例："1234"

offset

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

返回值

无

示例

exs_aip650e.set_display("1234")
exs_aip650e.set_display("88.8")
exs_aip650e.set_display("12", 3)   -- 从第 3 位开始显示
exs_aip650e.set_display("25°C")    -- 温度显示
exs_aip650e.set_display("77°F")    -- 华氏度显示

4.2.2 exs_aip650e.set_mode(mode)

功能

切换 7 段/8 段显示模式。

  • 8 段模式（默认）：a~g + DP，支持小数点
  • 7 段模式：a~g 七个段，DP 段不可用，适合纯数字显示

参数

mode

参数含义：显示模式
数据类型：number
取值范围：0（8 段模式），1（7 段模式）
是否必选：是
注意事项：切换模式后所有显示内容立即生效
参数示例：0

返回值

无

示例

exs_aip650e.set_mode(0)  -- 8 段模式（默认）
exs_aip650e.set_mode(1)  -- 7 段模式

4.3 按键扫描

AiP650E 内置 7×4 按键扫描矩阵，最多支持 28 个独立按键，外加 4 个组合按键（KI1+KI2）。

按键编码 1~32 的排列：

                DIG1  DIG2  DIG3  DIG4
          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
   组合键 KI1+KI2: 29    30    31    32

按键扫描由芯片自动完成（内部每 40ms 扫描一轮），结果存储在内部按键寄存器，主控只需通过两线总线读取即可。

组合按键说明：

AiP650E 支持 KI1 和 KI2 针对同一个 DIGX 引脚的组合键，组合键的优先级最优先。除此之外，如果多个键同时按下，按键代码较小的按键优先。在组合键应用中，应对 KI1 及 KI2 相互间进行阻隔处理（串联二极管）。

4.3.1 exs_aip650e.get_key()

功能

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

参数

无

返回值

local key = exs_aip650e.get_key()

key

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

示例

local function check_key_task()
    while true do
        local key = exs_aip650e.get_key()
        if key then
            log.info("exs_aip650e", "检测到按键:", key)
            exs_aip650e.set_display(string.format("%02d", key))
        end
        sys.wait(30)
    end
end
sys.taskInit(check_key_task)

4.3.2 exs_aip650e.set_key_callback(cbfunc)

功能

设置按键回调函数。注册后库内部自动轮询或使用 KP 中断读取按键。

中断 vs 轮询选择：

  • 如果 setup() 时配置了 kp 引脚：注册回调后将配置 KP 引脚为下降沿中断，按键按下时触发中断读取，CPU 占用更低
  • 如果未配置 kp 引脚：库内部每隔 50ms 自动轮询按键状态

低功耗注意事项：

设备进入低功耗休眠前，必须先调用 exs_aip650e.set_key_callback(nil) 停止内部轮询定时器。

参数

cbfunc

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

返回值

无

示例

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

-- 注册
exs_aip650e.set_key_callback(on_key)

-- 取消
exs_aip650e.set_key_callback(nil)

4.4 版本管理

4.4.1 exs_aip650e.version()

功能

获取 exs_aip650e 库的版本号。

参数

无

返回值

local ver = exs_aip650e.version()

ver

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

示例

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

五、版本更新说明

版本号：202607131200

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

  2. 更新内容：

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

  4. 支持数码管显示（8 段 ×4 位）
  5. 支持按键扫描（轮询 + 回调两种方式，支持 28 个独立按键 + 4 个组合按键）
  6. 支持 8 级亮度调节
  7. 支持共阴/共阳数码管切换
  8. 支持 7 段/8 段显示模式切换
  9. 支持睡眠模式和唤醒
  10. 支持 KP 中断引脚配置

六、产品支持说明

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

问一下 AI