LuatOS扩展库API——【exlcd】显示屏控制

一、概述

exlcd 扩展库是基于 lcd 核心库的二次封装，提供了更简化的屏幕管理功能，包括屏幕初始化、背光亮度等级控制、当前背光亮度等级查询、休眠/唤醒控制、休眠状态查询功能。该库旨在丰富 lcd 屏幕功能，简化合宙量产功能板、合宙 LCD 配件板的使用，减少用户代码。

1.1 主要特性

简化初始化：使用合宙量产功能板、合宙 LCD 配件板加上配套开发板，只需要填 lcd_model 参数即可自动配置
自动参数配置：支持 Air780EHM_LCD_4、AirLCD_1000、AirLCD_1010、AirLCD_1020 型号的自动参数配置
参数覆盖：对于合宙 LCD 配件板 AirLCD_1000、AirLCD_1010、AirLCD_1020 等型号在非配套开发板上使用，可以传入的参数覆盖默认配置
背光/休眠管理：一个背光引脚在配置了背光引脚对应得 GPIO 号和对应得 PWM 端口号情况下，可以同时支持 PWM 背光 0-100 级亮度控制和休眠/唤醒功能，无需手动切换背光引脚工作模式、无需在屏幕休眠后手动设置恢复休眠前的亮度
错误处理：内置参数检查和错误提示

1.2 注意事项

exlcd 为扩展库，没有内置到 LuatOS 内核固件中，真实设备使用时需要 require("exlcd")加载后才能正常调用 exlcd 的功能。
背光引脚选择同时支持 PWM 功能和 GPIO 功能的引脚，正确配置好参数后可同时实现背光亮度 0-100 级调节和屏幕休眠/唤醒功能。
例 1：Air780EHM PIN22 引脚默认为 PWM0 功能，同时又能复用为 GPIO1，如果使用该引脚作为背光引脚。在 exlcd.init(param)初始化接口的 param 参数内，填入参数 pin_pwm = 0 ，pin_pwr = 1 即可实现同时支持背光亮度调节和屏幕休眠/唤醒功能。
例 2：Air780EHM PIN106 引脚默认为 CAN_RXD 功能，同时又能复用为 PWM2 和 GPIO25，此时可以使用 LuatIO 引脚复用配置工具，引脚配置为 PWM2，然后在 exlcd.init(param)初始化接口的 param 参数内，填入参数 pin_pwm = 2 ，pin_pwr = 25 即可实现同时支持背光亮度调节和屏幕休眠/唤醒功能。
pin_vcc 为屏幕电源开关 GPIO 号参数，填入后执行初始化会先拉高对应的 GPIO 引脚电平，再拉高背光引脚 pin_pwr 对应 GPIO 电平，如果有特殊需求可选择不填手动控制

二、核心示例

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

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

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

2.1 核心代码

lua 复制代码

-- 导入exlcd库
exlcd = require("exlcd")

-- 应用主函数
local function exlcd_main()
    -- 初始化lcd屏幕
    local init_result = exlcd.init({lcd_model = "Air780EHM_lcd_4"})

    if init_result then
        log.info("exlcd", "屏幕初始化成功")
    end
    -- 设置中等亮度
    exlcd.set_bl(60)

    -- 设置颜色，白底黑字，背景色:白色(0xFFFF), 前景色:黑色(0x0000)
    lcd.setColor(0xFFFF, 0x0000)

    -- 在屏幕左上角(0,0)显示一张图片
    -- 图片路径为/luadb/logo.jpg
    lcd.showImage(0, 0, "/luadb/logo.jpg")

    -- 在位置(0,82)绘制一个16x16的位图，内容依次为""上""，""海""，""合""，""宙""
    -- 位图数据使用字符串格式表示
    lcd.drawXbm(0, 82, 16, 16, string.char(
        0x00, 0x00, 0x80, 0x00, 0x80, 0x00, 0x80, 0x00, 0x80, 0x00, 0x80, 0x00, 0x80, 0x3F, 0x80, 0x00,
        0x80, 0x00, 0x80, 0x00, 0x80, 0x00, 0x80, 0x00, 0x80, 0x00, 0x80, 0x00, 0xFE, 0x7F, 0x00, 0x00))

    lcd.drawXbm(18, 82, 16, 16, string.char(
        0x00, 0x00, 0x80, 0x00, 0xC4, 0x7F, 0x28, 0x00, 0x10, 0x00, 0xD0, 0x3F, 0x42, 0x20, 0x44, 0x22,
        0x40, 0x24, 0xF0, 0xFF, 0x24, 0x20, 0x24, 0x22, 0x24, 0x20, 0xE2, 0x7F, 0x02, 0x20, 0x02, 0x1E))

    lcd.drawXbm(36, 82, 16, 16, string.char(
        0x00, 0x00, 0x00, 0x01, 0x80, 0x01, 0x40, 0x02, 0x20, 0x04, 0x18, 0x18, 0xF4, 0x6F, 0x02, 0x00,
        0x00, 0x00, 0xF8, 0x1F, 0x08, 0x10, 0x08, 0x10, 0x08, 0x10, 0x08, 0x10, 0xF8, 0x1F, 0x08, 0x10))

    lcd.drawXbm(54, 82, 16, 16, string.char(
        0x00, 0x00, 0x80, 0x00, 0x00, 0x01, 0xFE, 0x7F, 0x02, 0x40, 0x02, 0x40, 0x00, 0x01, 0xFC, 0x3F,
        0x04, 0x21, 0x04, 0x21, 0xFC, 0x3F, 0x04, 0x21, 0x04, 0x21, 0x04, 0x21, 0xFC, 0x3F, 0x04, 0x20))

    -- 在位置(120,40)绘制一个蓝色点
    lcd.drawPoint(120, 40, 0x001F)

    -- 以(120,40)为圆心，40为半径绘制一个蓝色圆
    lcd.drawCircle(120, 40, 40, 0x001F)

    -- 从(170,40)到(280,40)绘制一条蓝色水平线
    lcd.drawLine(170, 40, 280, 40, 0x001F)

    -- 从(170,50)到(280,80)绘制一个蓝色矩形框
    lcd.drawRectangle(170, 50, 280, 80, 0x001F)

    -- 在位置(200,170)绘制一个100x100的二维码，内容为指定URL
    lcd.drawQrcode(200, 170, "https://docs.openluat.com/air8000/", 100)

    lcd.setFont(lcd.font_opposansm12)
    lcd.drawStr(20, 172, "hello hezhou") --显示字符
    lcd.setFont(lcd.font_opposansm16)
    lcd.drawStr(20, 189, "hello hezhou") --显示字符
    lcd.setFont(lcd.font_opposansm18)
    lcd.drawStr(20, 210, "hello hezhou") --显示字符
    lcd.setFont(lcd.font_opposansm20)
    lcd.drawStr(20, 233, "hello hezhou") --显示字符
    lcd.setFont(lcd.font_opposansm22)
    lcd.drawStr(20, 258, "hello hezhou") --显示字符
    lcd.setFont(lcd.font_opposansm24)
    lcd.drawStr(20, 285, "hello hezhou") --显示字符
    lcd.setFont(lcd.font_opposansm32)
    lcd.drawStr(20, 316, "hello hezhou") --显示字符

    lcd.fill(10, 380, 150, 460, 0xF800)  -- 绘制红色矩形区域(0xF800是红色)
    lcd.fill(170, 380, 310, 460, 0x07E0) -- 绘制绿色矩形区域(0x07E0是绿色)

    -- 设置字体为font_open_iconic_weather_6x_t天气字体，Air780EPM不支持
    lcd.setFont(lcd.font_open_iconic_weather_6x_t)
    lcd.setColor(0xFFFF, 0x0000) -- 白底黑字
    lcd.drawStr(1, 155, "A")     --注意字体是左下角显示在设置坐标位置
    lcd.drawStr(60, 155, "B")
    lcd.drawStr(120, 155, "C")
    lcd.drawStr(180, 155, "D")
    lcd.drawStr(240, 155, "E")

    -----------------------------以下为显示中文设置----------------------------
    -- Air780EPM不支持中文显示
    -- Air780EHM/EGH/EHV/Air8000支持12号中文字体
    -- 中文以左下角为坐标显示与位图左上角方式不同

    -- 设置字体为opposansm12中文字体，从英文显示切换到中文前一定要设置
    lcd.setFont(lcd.font_opposansm12_chinese)

    -- 显示重拍按钮（左侧）
    lcd.drawStr(70, 420, "重拍", 0xFFFF) -- 在按钮上绘制白色文字"重拍"

    -- 显示返回按钮（右侧）
    lcd.drawStr(230, 420, "返回", 0xFFFF) -- 在按钮上绘制白色文字"返回"

    -- 在位置(160,155)绘制文本
    -- 不设置字体颜色，默认会使用lcd.setColor所设置的字体颜色
    lcd.drawStr(160, 168, "扫码进入Air8000资料站", 0x0000)

    -- 主动刷新数据到屏幕
    lcd.flush()

    -- 背光引脚使用PWM引脚控制，且pwm_id正确配置后可以实现背光控制
    -- 参数 level: 亮度级别(0-100)
    exlcd.set_bl(0)   -- 设置背光为0%
    sys.wait(5000)
    exlcd.set_bl(10)  -- 设置背光为10%
    sys.wait(5000)
    exlcd.set_bl(20)  -- 设置背光为20%
    sys.wait(5000)
    exlcd.set_bl(30)  -- 设置背光为30%
    sys.wait(5000)
    exlcd.set_bl(40)  -- 设置背光为40%
    sys.wait(5000)
    exlcd.set_bl(50)  -- 设置背光为50%
    sys.wait(5000)
    exlcd.set_bl(60)  -- 设置背光为60%
    sys.wait(5000)
    exlcd.set_bl(70)  -- 设置背光为70%
    sys.wait(5000)
    exlcd.set_bl(80)  -- 设置背光为80%
    sys.wait(5000)
    exlcd.set_bl(90)  -- 设置背光为90%
    sys.wait(5000)
    exlcd.set_bl(100) -- 设置背光为100%

    -- 进入休眠，功耗13ma
    exlcd.sleep() -- 进入休眠状态
    sys.wait(10000)

    exlcd.wakeup() -- 唤醒屏幕，自动恢复之前的背光亮度设置
end

-- 启动应用
__sys.taskInit(exlcd_main)_

2.2 效果演示

lua 复制代码

[2025-10-13 18:32:49.403][000000001.041] I/user.exlcd 背光设置为 0 %
[2025-10-13 18:32:53.252][000000006.042] I/user.exlcd 背光设置为 10 %
[2025-10-13 18:32:58.243][000000011.041] I/user.exlcd 背光设置为 20 %
[2025-10-13 18:33:03.253][000000016.041] I/user.exlcd 背光设置为 30 %
[2025-10-13 18:33:08.253][000000021.041] I/user.exlcd 背光设置为 40 %
[2025-10-13 18:33:13.253][000000026.041] I/user.exlcd 背光设置为 50 %
[2025-10-13 18:33:18.248][000000031.041] I/user.exlcd 背光设置为 60 %
[2025-10-13 18:33:23.247][000000036.041] I/user.exlcd 背光设置为 70 %
[2025-10-13 18:33:28.239][000000041.041] I/user.exlcd 背光设置为 80 %
[2025-10-13 18:33:33.245][000000046.041] I/user.exlcd 背光设置为 90 %
[2025-10-13 18:33:38.249][000000051.041] I/user.exlcd 背光设置为 100 %
[2025-10-13 18:33:38.258][000000051.046] I/user.exlcd lcd进入休眠状态
[2025-10-13 18:33:48.363][000000061.151] I/user.exlcd lcd唤醒

三、常量详解

exlcd 显示扩展库没有常量。

四、函数详解

3.1 exlcd.init(param)

功能

初始化 lcd 显示屏，配置硬件参数和屏幕属性。

注意事项

本函数参考示例 2 和示例 3 中的参数为合宙 LCD 配件板和量产功能板在 exlcd 内置的默认参数，在非配套开发板上使用可根据实际接线进行修改，初始化时会优先使用传入参数，没有传入参数再使用默认参数；

参数

param

lua 复制代码

> 参数含义：lcd配置参数表；  
> 数据类型：table；  
> 取值范围：table中包含多个配置字段，各字段说明如下：  
> {  
> 参数含义：lcd型号标识；  
> 数据类型：string；  
> 取值范围：分为四大类,当lcd\_model是配件板且搭配配套的开发板使用或者量产功能板时，  
> 只需要传入lcd\_model参数  
> 1、合宙LCD配件板  
> "AirLCD\_1000"(对应Air780EPM/EHM/EGH/EHV整机开发板上配套的的显示屏)  
> "AirLCD\_1010"(对应Air8000整机开发板上配套的的显示屏)  
> "AirLCD\_1020"(对应Air8101核心板上配套的的显示屏)  
> 2、合宙量产功能板  
> "Air780EHM\_LCD\_4"(自带3.5寸480\*320触摸屏，矢量字库，tf卡槽)  
> 3、支持显示IC型号  
> "st7796"、"st7789"、"st7735"、"st7735v"、"st7735s"  
> "gc9a01"、"gc9106l"、"gc9306x"、"ili9486"、"ili9341"  
> "nv3037"、"h050iwv"、"co5300"、"jd9261t"、"sh8601z"  
> 4、自定义显示IC型号  
> "custom"；  
> 是否必选：必须传入此参数；  
> 注意事项：根据实际使用的lcd屏幕型号填写对应的参数；  
> 参数示例：lcd\_model = "Air780EHM\_LCD\_4"  
> 参数名称： param.lcd\_model
> 
> 参数含义：lcd供电开启GPIO端口号，设置后初始化时会拉高所设置GPIO；  
> 数据类型：number；  
> 取值范围：有效的GPIO端口号；  
> 是否必选：可选传入此参数；如果没有传入，根据自己的硬件设计需要自行控制；  
> 注意事项：暂无；  
> 参数示例：pin\_vcc = 1  
> 参数名称： param.pin\_vcc
> 
> 参数含义：lcd背光引脚GPIO端口号，设置可通过该引脚控制屏幕背光开启和关闭；  
> 数据类型：number；  
> 取值范围：有效的GPIO端口号；  
> 是否必选：可选传入此参数；如果没有传入，无法使用休眠唤醒指令控制休眠和唤醒，  
> 且需要根据自己的硬件设计需要自行控制背光；  
> 注意事项：具体步骤可以按【1.2章节注意事项】来操作；  
> 参数示例：pin\_pwr = 1
> 
> 参数名称： param.pin\_pwr
> 
> 参数含义：lcd背光引脚PWM端口号，设置可通过该引脚控制屏幕背光亮度；  
> 数据类型：number；  
> 取值范围：有效的PWM端口号；  
> 是否必选：可选传入此参数；如果没有传入，根据自己的硬件设计需要自行控制背光；  
> 注意事项：具体步骤可以按【1.2章节注意事项】来操作；  
> 参数示例：pin\_pwm = 0  
> 参数名称： param.pin\_pwm
> 
> 参数含义：lcd硬件驱动端口类型；  
> 数据类型：number或者string；  
> 取值范围：  
> 1、lcd.HWID\_0表示专用lcd SPI接口；  
> 2、lcd.RGB表示RGB端口；  
> 3、0,1,2表示具体的标准SPI硬件端口ID；  
> 4、lcd.QSPI\_MODE标识QSPI端口；  
> 5、"device"表示具体的标准SPI硬件端口对象；  
> device的方式是通过spi.deviceSetup()先将SPI接口设置为SPI对象，  
> 并赋值给一个全局变量，然后再将全局变量放到lcd.init()第三个参数spi\_dev，  
> 在此需要赋值port = "device"，  
> 是否必选：合宙量产功能板和合宙LCD配件板可选，其他必须传入此参数；  
> 注意事项：根据实际硬件连接选择对应的端口类型；  
> 参数示例：port = lcd.HWID\_0  
> 参数名称： param.port
> 
> 参数含义：lcd数据/命令选择引脚GPIO号；  
> 数据类型：number；  
> 取值范围：有效的GPIO端口号；  
> 是否必选：可选传入此参数，默认nil，  
> 注意事项：1、当参数port = lcd.HWID\_0时，pin\_dc参数保持为空；  
> 2、当参数port = lcd.RGB时，pin\_dc参数保持为空；  
> 3、当参数port = 0、1、2等标准SPI接口时，pin\_dc需要赋值；  
> 4、当参数port = lcd.QSPI\_MODE时，pin\_dc参数保持为空；  
> 5、当参数port = "device"时，pin\_dc需要赋值；  
> 参数示例：pin\_dc = 31  
> 参数名称： param.pin\_dc
> 
> 参数含义：lcd复位引脚GPIO号；  
> 数据类型：number；  
> 取值范围：有效的GPIO端口号；  
> 是否必选：可选传入此参数；  
> 注意事项：1、当参数port = lcd.RGB时，pin\_rst参数保持为空；  
> 2、当参数port = 其他类型时，pin\_rst参数根据实际情况填写；  
> 参数示例：pin\_rst = 10  
> 参数名称： param.pin\_rst
> 
> 参数含义：lcd屏幕方向；  
> 数据类型：number；  
> 取值范围：lcd.direction\_0表示显示方向为0°；  
> lcd.direction\_90表示显示方向为90°；  
> lcd.direction\_180表示显示方向为180°；  
> lcd.direction\_270表示显示方向为270°；  
> 是否必选：可选传入此参数；不传入此参数，默认是0度方向；  
> 注意事项：设置屏幕的显示方向；  
> 参数示例：direction = lcd.direction\_0  
> 参数名称： param.direction
> 
> 参数含义：lcd水平分辨率；  
> 数据类型：number；  
> 取值范围：正整数；  
> 是否必选：合宙量产功能板和合宙LCD配件板可选，其他必须传入此参数；  
> 注意事项：设置屏幕的宽度像素值；  
> 参数示例：w = 240  
> 参数名称： param.w
> 
> 参数含义：lcd竖直分辨率；  
> 数据类型：number；  
> 取值范围：正整数；  
> 是否必选：合宙量产功能板和合宙LCD配件板可选，其他必须传入此参数；  
> 注意事项：设置屏幕的高度像素值；  
> 参数示例：h = 320  
> 参数名称： param.h
> 
> 参数含义：X偏移；  
> 数据类型：number；  
> 取值范围：整数；  
> 是否必选：可选传入此参数，省略此参数则偏移量默认为0；  
> 注意事项：不同屏幕IC和不同屏幕方向会有差异；  
> 参数示例：xoffset = 0  
> 参数名称： param.xoffset
> 
> 参数含义：Y偏移；  
> 数据类型：number；  
> 取值范围：整数；  
> 是否必选：可选传入此参数，省略此参数则偏移量默认为0；  
> 注意事项：不同屏幕IC和不同屏幕方向会有差异；  
> 参数示例：yoffset = 0  
> 参数名称： param.yoffset
> 
> 参数含义：睡眠命令；  
> 数据类型：number；  
> 取值范围：十六进制命令值；  
> 是否必选：可选传入此参数，默认0x10；  
> 注意事项：使用lcd.sleep()时发送配置的命令；  
> 参数示例：sleepcmd = 0x10  
> 参数名称： param.sleepcmd
> 
> 参数含义：唤醒命令；  
> 数据类型：number；  
> 取值范围：十六进制命令值；  
> 是否必选：可选传入此参数，默认0x11；  
> 注意事项：使用lcd.wakeup()时发送配置的命令；  
> 参数示例：wakecmd = 0x11  
> 参数名称： param.wakecmd
> 
> 参数含义：0°方向的命令；  
> 数据类型：number；  
> 取值范围：十六进制命令值；  
> 是否必选：可选传入此参数，省略此参数时默认为0x00；  
> 注意事项：不同屏幕IC会有差异；  
> 参数示例：direction0 = 0x00  
> 参数名称： param.direction0
> 
> 参数含义：90°方向的命令；  
> 数据类型：number；  
> 取值范围：十六进制命令值；  
> 是否必选：可选传入此参数，省略此参数时默认为0x60；  
> 注意事项：不同屏幕IC会有差异；  
> 参数示例：direction90 = 0x01  
> 参数名称： param.direction90
> 
> 参数含义：180°方向的命令；  
> 数据类型：number；  
> 取值范围：十六进制命令值；  
> 是否必选：可选传入此参数，省略此参数时默认为0xC0；  
> 注意事项：不同屏幕IC会有差异；  
> 参数示例：direction180 = 0x02  
> 参数名称： param.direction180
> 
> 参数含义：270°方向的命令；  
> 数据类型：number；  
> 取值范围：十六进制命令值；  
> 是否必选：可选传入此参数，省略此参数时默认为0xA0；  
> 注意事项：不同屏幕IC会有差异；  
> 参数示例：direction270 = 0x03  
> 参数名称： param.direction270
> 
> 参数含义：lcd接口软件驱动类型；  
> 数据类型：string；  
> 取值范围：lcd.QSPI\_MODE；  
> 是否必选：可选传入此参数，  
> 注意事项：interface\_mode参数是port参数的进一步细分  
> 1、当参数port = lcd.QSPI\_MODE时，interface\_mode参数赋值为lcd.QSPI\_MODE；  
> 2、当参数port = lcd.HWID\_0且所接屏幕接口为QSPI时，  
> interface\_mode参数赋值为lcd.QSPI\_MODE；  
> 3、当参数port = 其他类型时，interface\_mode参数保持为空；  
> 参数示例：interface\_mode = lcd.QSPI\_MODE  
> 参数名称： param.interface\_mode
> 
> 参数含义：QSPI/RGB总线速率，单位为Hz；  
> 数据类型：number；  
> 取值范围：正整数；  
> 是否必选：可选传入此参数；  
> 注意事项：目前lcd核心库设置速率上限是80MHz，目前lcd库支持的型号  
> 显示IC型号:jd9261t, QSPI接口，bus\_speed = 70000000  
> 显示IC型号:co5300, QSPI接口，bus\_speed = 60000000  
> 显示IC型号:h050iwv, RGB接口， bus\_speed = 30000000
> 
> 其他QSPI/RGB接口显示IC，根据芯片手册要求填此参数  
> 参数示例：bus\_speed = 70000000  
> 参数名称： param.bus\_speed
> 
> 参数含义：水平后廊，用于生成水平扫描时序，控制有效数据传输前的延迟周期；  
> 数据类型：number；  
> 取值范围：正整数；  
> 是否必选：可选传入此参数；  
> 注意事项：此参数为校准调试参数，lcd.init()中driver\_ic支持的型号不需要填写，  
> 其他非driver\_ic支持的型号，如果出现不显示或显示不正确的情况，  
> 优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；  
> 参数示例：hbp = 10  
> 参数名称： param.hbp
> 
> 参数含义：水平同步脉冲宽度，初始化时参与水平同步信号的时序计算，  
> 决定水平同步脉冲的持续周期；  
> 数据类型：number；  
> 取值范围：正整数；  
> 是否必选：可选传入此参数，无默认值；  
> 注意事项：此参数为校准调试参数，lcd.init()中driver\_ic支持的型号不需要填写，  
> 其他非driver\_ic支持的型号，如果出现不显示或显示不正确的情况，  
> 优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；  
> 参数示例：hspw = 5  
> 参数名称： param.hspw
> 
> 参数含义：水平前廊，用于水平扫描时序配置，控制有效数据传输后的延迟周期；  
> 数据类型：number；  
> 取值范围：正整数；  
> 是否必选：可选传入此参数，无默认值；  
> 注意事项：此参数为校准调试参数，lcd.init()中driver\_ic支持的型号不需要填写，  
> 其他非driver\_ic支持的型号，如果出现不显示或显示不正确的情况，  
> 优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；  
> 参数示例：hfp = 10  
> 参数名称： param.hfp
> 
> 参数含义：垂直后廊，在垂直扫描时序配置中生效，控制帧数据传输前的垂直延迟周期；  
> 数据类型：number；  
> 取值范围：正整数；  
> 是否必选：可选传入此参数，无默认值；  
> 注意事项：此参数为校准调试参数，lcd.init()中driver\_ic支持的型号不需要填写，  
> 其他非driver\_ic支持的型号，如果出现不显示或显示不正确的情况，  
> 优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；  
> 参数示例：vbp = 10  
> 参数名称： param.vbp
> 
> 参数含义：垂直同步脉冲宽度，初始化时参与垂直同步信号的时序计算，  
> 决定垂直同步脉冲的持续周期；  
> 数据类型：number；  
> 取值范围：正整数；  
> 是否必选：可选传入此参数，无默认值；  
> 注意事项：此参数为校准调试参数，lcd.init()中driver\_ic支持的型号不需要填写，  
> 其他非driver\_ic支持的型号，如果出现不显示或显示不正确的情况，  
> 优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；  
> 参数示例：vspw = 5  
> 参数名称： param.vspw
> 
> 参数含义：垂直前廊，用于垂直扫描时序配置，控制帧数据传输后的垂直延迟周期；  
> 数据类型：number；  
> 取值范围：正整数；  
> 是否必选：可选传入此参数，无默认值；  
> 注意事项：此参数为校准调试参数，lcd.init()中driver\_ic支持的型号不需要填写，  
> 其他非driver\_ic支持的型号，如果出现不显示或显示不正确的情况，  
> 优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；  
> 参数示例：vfp = 10  
> 参数名称： param.vfp
> 
> 参数含义：垂直同步，用于控制垂直同步信号的使能或参数，  
> 具体作用依赖屏幕驱动 IC 的时序要求；  
> 数据类型：number；  
> 取值范围：正整数；  
> 是否必选：可选传入此参数，无默认值；  
> 注意事项：此参数为校准调试参数，lcd.init()中driver\_ic支持的型号不需要填写，  
> 其他非driver\_ic支持的型号，如果出现不显示或显示不正确的情况，  
> 优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；  
> 参数示例：vs = 1  
> 参数名称： param.vs
> 
> 参数含义：刷新率，用于控制屏幕扫描时的帧刷新频率，驱动会根据该值调整数据传输的周期；  
> 数据类型：number；  
> 取值范围：正整数，单位0.1Hz；  
> 是否必选：可选传入此参数，无默认值；  
> 注意事项：屏幕选型时建议询问厂家对应的型号是否带RAM，若不带则根据芯片手册建议进行设置；  
> 参数示例：flush\_rate = 600  
> 参数名称： param.flush\_rate
> 
> 参数含义：调换x方向（默认为水平方向）和y方向判定（默认为竖直方向）；  
> 数据类型：boolean；  
> 取值范围：true或false；  
> 是否必选：可选传入此参数，不填则默认值为false，一般不需要使用；  
> 注意事项：false（默认）：x 为水平方向，y 为竖直方向；  
> true：交换 x 和 y 的方向判定，适用于特殊屏幕布局需求  
> 参数示例：rb\_swap = false  
> 参数名称： param.rb\_swap
> 
> 参数含义：自定义屏幕初始化命令表，在lcd.init()内部执行初始化后，  
> 会自动调用lcd.cmd按顺序执行initcmd表内的命令；  
> 数据类型：table；  
> 取值范围：包含初始化命令序列的table；  
> 是否必选：可选传入此参数；  
> 注意事项：用于自定义屏幕初始化流程，driver\_ic为"custom"时才使用，命令格式如下；  
> 1、0x01xxxx: 表示延时，xxxx为延时ms时间  
> 2、0x02xxxx: 表示命令，xxxx为命令码  
> 3、0x03xxxx: 表示参数，xxxx为参数值  
> 参数示例：initcmd = {0x0200FE, 0x030000}  
> 参数名称： param.initcmd
> 
> 参数含义：SPI设备对象；  
> 数据类型：userdata；  
> 取值范围：SPI设备对象；  
> 是否必选：可选传入此参数；  
> 注意事项：当port = "device"时有效，当port ≠ "device"时可省略该参数或者填nil；  
> 参数示例：spi\_dev = device  
> 参数名称： param.spi\_dev
> 
> 参数含义：是否允许在后台初始化lcd；  
> 数据类型：boolean；  
> 取值范围：true或false；  
> 是否必选：可选传入此参数，默认值为false；  
> 注意事项：支持的型号推荐使用，不支持的型号省略此参数；  
> 参数示例：init\_in\_service = false  
> 参数名称： param.init\_in\_service  
> }
> 
> 注意事项：table内可选参数如果不需要就整个都不需要填，如果有下标就必须赋值，  
> 只写下标例如param={pin\_pwr = ，pin\_rst = }会报语法错误，  
> 正确的形式是param={pin\_pwr =25 ，pin\_rst = 36}  
> 参数示例：exlcd.init({lcd\_model = "Air780EHM\_LCD\_4"})

返回值

local init_result = exlcd.init(param)

init_result

lua 复制代码

参数含义：初始化是否成功；
数据类型：boolean；
取值范围：true表示成功，false表示失败；
注意事项：初始化失败可能是参数错误或硬件连接问题；
返回示例：true

示例 1 LCD 配件板 + 默认参数

lua 复制代码

-- AirLCD_1000搭配Air780EPM整机开发板初始化
exlcd.init({lcd_model = "AirLCD_1000"})

-- AirLCD_1000搭配Air780EHM整机开发板初始化
exlcd.init({lcd_model = "AirLCD_1000",pin_pwr = 16})

-- AirLCD_1010搭配Air8000整机开发板初始化
exlcd.init({lcd_model = "AirLCD_1010"})

-- AirLCD_1020搭配Air8101核心板初始化
exlcd.init({lcd_model = "AirLCD_1020"})

--也可以只传型号，或部分覆盖参数
exlcd.init({lcd_model = "AirLCD_1020", direction = 3, w = 480, h = 320}) -- 覆盖方向参数

示例 2 LCD 配件板 + 自定义参数，示例为 exlcd 扩展库内默认参数

lua 复制代码

-- AirLCD_1000自定义参数初始化
exlcd.init(
    {
        lcd_model = "AirLCD_1000", -- LCD型号
        pin_vcc = 29,         -- 供电引脚，使用GPIO控制屏幕供电可配置
        pin_rst = 36,         -- 复位引脚
        pin_pwr = 30,          -- 背光控制引脚GPIO端口号
        pin_pwm = 1,          -- 背光控制引脚PWM端口号
        port = lcd.HWID_0,    -- 驱动端口
        direction = 0,        -- lcd屏幕方向 0:0° 1:90° 2:180° 3:270°，屏幕方向和分辨率保存一致
        w = 320,              -- lcd 水平分辨率
        h = 480,              -- lcd 竖直分辨率
        xoffset = 0,          -- x偏移(不同屏幕ic 不同屏幕方向会有差异)
        yoffset = 0,          -- y偏移(不同屏幕ic 不同屏幕方向会有差异)
        sleepcmd = 0X10,      -- 睡眠命令，默认0X10
        wakecmd = 0X11,       -- 唤醒命令，默认0X11
  }
)

-- AirLCD_1010自定义参数初始化
exlcd.init(
    {
        lcd_model = "AirLCD_1010", -- LCD型号
        pin_vcc = 141,         -- 供电引脚，使用GPIO控制屏幕供电可配置
        pin_rst = 36,         -- 复位引脚
        pin_pwr = 1,          -- 背光控制引脚GPIO端口号
        pin_pwm = 0,          -- 背光控制引脚PWM端口号
        port = lcd.HWID_0,    -- 驱动端口
        direction = 0,        -- lcd屏幕方向 0:0° 1:90° 2:180° 3:270°，屏幕方向和分辨率保存一致
        w = 320,              -- lcd 水平分辨率
        h = 480,              -- lcd 竖直分辨率
        xoffset = 0,          -- x偏移(不同屏幕ic 不同屏幕方向会有差异)
        yoffset = 0,          -- y偏移(不同屏幕ic 不同屏幕方向会有差异)
        sleepcmd = 0X10,      -- 睡眠命令，默认0X10
        wakecmd = 0X11,       -- 唤醒命令，默认0X11
  }
)

-- AirLCD_1020自定义参数初始化
exlcd.init(
    {
        lcd_model = "AirLCD_1020",    -- LCD型号
        pin_pwr = 8,                  -- 背光控制引脚GPIO端口号
        pin_pwm = 0,                  -- 背光控制引脚PWM端口号
        port = lcd.RGB,               -- 驱动端口
        direction = 0,                -- lcd屏幕方向 0:0° 1:90° 2:180° 3:270°，屏幕方向和分辨率保存一致
        w = 800,                      -- lcd 水平分辨率
        h = 480,                      -- lcd 竖直分辨率
        xoffset = 0,                  -- x偏移(不同屏幕ic 不同屏幕方向会有差异)
        yoffset = 0,                  -- y偏移(不同屏幕ic 不同屏幕方向会有差异)
        bus_speed = 30 * 1000 * 1000, -- SPI总线速度,不填默认50M，若速率要求更高需要进行设置
        hbp = 8,                      -- 水平后廊
        hspw = 4,                     -- 水平同步脉冲宽度
        hfp = 8,                      -- 水平前廊
        vbp = 16,                     -- 垂直后廊
        vspw = 4,                     -- 垂直同步脉冲宽度
        vfp = 16,                     -- 垂直前廊
  }
)

示例 3 LCD 量产功能板，不支持修改默认参数

lua 复制代码

-- Air780EHM_LCD_4量产功能板初始化
exlcd.init({lcd_model = "Air780EHM_LCD_4"})

-- 以下为exlcd扩展库内默认参数
        lcd_model = "Air780EHM_LCD_4", -- LCD型号
        pin_vcc = 24,         -- 供电引脚，使用GPIO控制屏幕供电可配置
        pin_rst = 36,         -- 复位引脚
        pin_pwr = 25,         -- 背光控制引脚GPIO端口号
        pin_pwm = 2,          -- 背光控制引脚PWM端口号
        port = lcd.HWID_0,    -- 驱动端口
        direction = 3,        -- lcd屏幕方向 0:0° 1:90° 2:180° 3:270°，屏幕方向和分辨率保存一致
        w = 480,              -- lcd 水平分辨率
        h = 320,              -- lcd 竖直分辨率
        xoffset = 0,          -- x偏移(不同屏幕ic 不同屏幕方向会有差异)
        yoffset = 0,          -- y偏移(不同屏幕ic 不同屏幕方向会有差异)
        sleepcmd = 0X10,      -- 睡眠命令，默认0X10
        wakecmd = 0X11,       -- 唤醒命令，默认0X11

示例 4 驱动 ic 型号

lua 复制代码

-- st7796自定义参数初始化
exlcd.init(
    {
        lcd_model = "st7796", -- LCD型号
        pin_vcc = 24,         -- 供电引脚，使用GPIO控制屏幕供电可配置
        pin_rst = 36,         -- 复位引脚
        pin_pwr = 1,          -- 背光控制引脚GPIO端口号
        pin_pwm = 0,          -- 背光控制引脚PWM端口号
        port = lcd.HWID_0,    -- 驱动端口
        direction = 0,        -- lcd屏幕方向 0:0° 1:90° 2:180° 3:270°，屏幕方向和分辨率保存一致
        w = 320,              -- lcd 水平分辨率
        h = 480,              -- lcd 竖直分辨率
        xoffset = 0,          -- x偏移(不同屏幕ic 不同屏幕方向会有差异)
        yoffset = 0,          -- y偏移(不同屏幕ic 不同屏幕方向会有差异)
        sleepcmd = 0X10,      -- 睡眠命令，默认0X10
        wakecmd = 0X11,       -- 唤醒命令，默认0X11
  }
)

示例 5 custom

lua 复制代码

-- st7796custom方式初始化
exlcd.init(
    {
        lcd_model = "st7796", -- LCD型号
        pin_vcc = 24,         -- 供电引脚，使用GPIO控制屏幕供电可配置
        pin_rst = 36,         -- 复位引脚
        pin_pwr = 1,          -- 背光控制引脚GPIO端口号
        pin_pwm = 0,          -- 背光控制引脚PWM端口号
        port = lcd.HWID_0,    -- 驱动端口
        direction = 0,        -- lcd屏幕方向 0:0° 1:90° 2:180° 3:270°，屏幕方向和分辨率保存一致
        w = 320,              -- lcd 水平分辨率
        h = 480,              -- lcd 竖直分辨率
        xoffset = 0,          -- x偏移(不同屏幕ic 不同屏幕方向会有差异)
        yoffset = 0,          -- y偏移(不同屏幕ic 不同屏幕方向会有差异)
        sleepcmd = 0X10,      -- 睡眠命令，默认0X10
        wakecmd = 0X11,       -- 唤醒命令，默认0X11
        -- ST7796S专用初始化命令序列
        initcmd = {
            -- 命令格式说明：
            -- 0x01xxxx: 延时，xxxx为延时ms时间
            -- 0x02xxxx: 命令，xxxx为命令码
            -- 0x03xxxx: 数据，xxxx为参数值

            -- 1. 设置接口像素格式
            0x02003A, 0x030005,
            -- 命令0x3A: 设置像素格式为16位RGB565 (参数0x05)

            -- 2. 帧率控制2 - 空闲模式
            0x0200B2, 0x03000C, 0x03000C, 0x030000, 0x030033, 0x030033,
            -- 设置空闲模式下的帧率参数

            -- 3. 门控制
            0x0200B7, 0x030035,
            -- 设置门控参数，控制扫描行数

            -- 4. VCOM设置
            0x0200BB, 0x030032,
            -- 设置VCOM电压值，影响对比度

            -- 5. 电源控制3
            0x0200C2, 0x030001,
            -- 设置电源控制参数3

            -- 6. 电源控制4
            0x0200C3, 0x030015,
            -- 设置VCOMH电压

            -- 7. 电源控制5
            0x0200C4, 0x030020,
            -- 设置VCOML电压

            -- 8. VCOM偏移控制
            0x0200C6, 0x03000F,
            -- 设置VCOM偏移量

            -- 9. 电源控制1
            0x0200D0, 0x0300A4, 0x0300A1,
            -- 设置主要的电源控制参数

            -- 10. 正伽马校正
            0x0200E0, 0x0300D0, 0x030008, 0x03000E, 0x030009, 0x030009, 
            0x030005, 0x030031, 0x030033, 0x030048, 0x030017, 0x030014, 
            0x030015, 0x030031, 0x030034,
            -- 15个参数点，校正亮部色彩曲线

            -- 11. 负伽马校正
            0x0200E1, 0x0300D0, 0x030008, 0x03000E, 0x030009, 0x030009, 
            0x030015, 0x030031, 0x030033, 0x030048, 0x030017, 0x030014, 
            0x030015, 0x030031, 0x030034,
            -- 15个参数点，校正暗部色彩曲线
        }
    }
  )

3.2 exlcd.set_bl(level)

功能

设置 lcd 背光亮度，背光引脚选择同时支持 PWM 功能和 GPIO 功能的引脚，在 exlcd.init(param)接口 param 参数内，通过背光引脚的 GPIO 功能可以实现屏幕的休眠和唤醒，通过背光引脚的 PWM 功能可以实现亮度从 0-100 级调光；

注意事项

正常情况下，0 为亮度最低，100 为亮度最高。在 Air780EPM/EHM/EGH/EHV 整机开发板上，模组背光引脚输出高电平，经过开发板上的三极管转换会输出低电平到屏幕背光引脚，所以在 Air780EPM/EHM/EGH/EHV 整机开发板上 100 为亮度为亮度最低，0 为亮度最高。

参数

level

lua 复制代码

参数含义：背光亮度级别；
数据类型：number；
取值范围：0-100，0表示关闭背光，100表示最大亮度；
是否必选：可选传入此参数；
注意事项：如果不传入参数，则使用上次设置的亮度值；
参数示例：75

返回值

local set_result = exlcd.set_bl(level)

set_result

lua 复制代码

参数含义：设置背光是否成功；
数据类型：boolean；
取值范围：true表示成功，false表示失败；
注意事项：在屏幕休眠状态下设置背光会失败，或者没有配置PWM引脚也会失败；
返回示例：true

示例

lua 复制代码

-- 设置背光为最大亮度
local result = exlcd.set_bl(100)
if result then
    log.info("背光设置成功")
else
    log.error("背光设置失败")
end

-- 设置中等亮度
exlcd.set_bl(60)

-- 关闭背光
exlcd.set_bl(0)

-- 使用上次亮度（在休眠唤醒后恢复亮度）
exlcd.set_bl()

3.3 exlcd.get_bl()

功能

获取当前背光亮度值。

参数

无

返回值

local brightness = exlcd.get_bl()

brightness

lua 复制代码

参数含义：当前背光亮度值；
数据类型：number；
取值范围：0-100；
注意事项：返回的是上次设置的亮度值，如果是休眠状态，返回的是休眠前设置的亮度值；
返回示例：80

示例

lua 复制代码

-- 获取当前亮度
local current_brightness = exlcd.get_bl()
log.info("当前背光亮度:", current_brightness, "%")

-- 在状态显示中使用
local function display_status()
    local brightness = exlcd.get_bl()
    lcd.drawStr(10, 10, "亮度: "..brightness.."%", 0x0000)
end

-- 亮度调节逻辑
local function adjust_brightness()
    local current = exlcd.get_bl()
    if current < 50 then
        exlcd.set_bl(current + 10)
    else
        exlcd.set_bl(current - 10)
    end
end

3.4 exlcd.sleep()

功能

使 lcd 屏幕进入休眠状态，发送休眠命令并拉低背光引脚。

注意事项

正常情况下，调用 exlcd.sleep()显示 IC 会进入休眠并拉低背光引脚。在 Air780EPM/EHM/EGH/EHV 整机开发板上，模组背光引脚输出低电平，经过开发板上的三极管转换会输出高电平到屏幕背光引脚，所以在 Air780EPM/EHM/EGH/EHV 整机开发板上执行完 exlcd.sleep()后，如果屏幕亮屏还需要手动拉高背光引脚 GPIO；
休眠后会保存当前亮度设置，唤醒时自动恢复；
如果屏幕处于已休眠状态，调用此函数不会产生效果；
屏幕休眠期间支持将显示数据先保存到主控缓冲区，屏幕唤醒后再刷新缓冲区数据到屏幕；

参数

无

返回值

无

示例

lua 复制代码

-- 使屏幕进入休眠
exlcd.sleep()
log.info("屏幕已进入休眠状态")

3.5 exlcd.wakeup()

功能

从休眠状态唤醒 lcd 屏幕，发送唤醒命令并拉高背光引脚。

注意事项

正常情况下，调用 exlcd.wakeup()显示 IC 会唤醒并拉高背光引脚。在 Air780EPM/EHM/EGH/EHV 整机开发板上，模组背光引脚输出高电平，经过开发板上的三极管转换会输出低电平到屏幕背光引脚，所以在 Air780EPM/EHM/EGH/EHV 整机开发板上执行完 exlcd.wakeup()后，如果屏幕黑屏还需要手动拉低背光引脚 GPIO
如果屏幕已经处于唤醒状态，调用此函数不会产生效果
唤醒后会恢复休眠前设置的背光亮度

参数

无

返回值

无

示例

lua 复制代码

-- 唤醒屏幕
exlcd.wakeup()
log.info("屏幕已唤醒")

3.6 exlcd.get_sleep()

功能

获取当前屏幕的休眠状态。

参数

无

返回值

local sleep_state = exlcd.get_sleep()

sleep_state

lua 复制代码

参数含义：当前屏幕休眠状态；
数据类型：boolean；
取值范围：true表示屏幕处于休眠状态，false表示屏幕处于唤醒状态；
注意事项：休眠状态下背光关闭，但显示内容仍然保存在缓冲区；
返回示例：true

示例

lua 复制代码

-- 检查屏幕状态
local function check_screen_status()
    if exlcd.get_sleep() then
        log.info("屏幕处于休眠状态")
        -- 执行唤醒操作
        exlcd.wakeup()
    else
        log.info("屏幕处于唤醒状态")
    end
end

-- 节能模式控制
local function power_saving_mode()
    if exlcd.get_sleep() then
        -- 屏幕已休眠，无需操作
        return
    end

    -- 检查是否需要进入休眠
    if should_enter_sleep() then
        exlcd.sleep()
        log.info("进入节能模式，休眠状态:", exlcd.get_sleep())
    end
end

-- 状态显示
local function show_system_status()
    local sleep_status = exlcd.get_sleep() and "休眠" or "唤醒"
    lcd.drawStr(10, 30, "屏幕状态: "..sleep_status, 0x0000)
end

五、模组支持说明

exlcd 需要硬件支持, 请确认你的设备有 lcd 屏幕接口，所有支持lcd库型号的模组都支持exlcd扩展库。

今天就分享到这里啦~~~