13 display-显示核心库（仅Air1601/1602的102号固件）
作者：江访 | 最后修改：2026-10-12
一、概述
display 是 LuatOS 新一代显示核心库，采用面板（Panel）与物理接口（Interface）分离架构，支持 RGB、MIPI-DSI、MIPI-DBI、SPI、LVDS 等多种接口类型的屏幕。该模块提供显示屏初始化、显示开关与休眠唤醒、屏幕旋转、纯色填充、命令发送、FrameBuffer 管理等功能，为上层 UI 框架（AirUI、LVGL）提供统一的显示底层。
固件支持说明：目前仅 Air1601/Air1602 的 102 号固件支持 display 核心库，其他型号和固件版本暂不支持；
选择哪个显示库开发：
1、新项目 UI 开发推荐使用 AirUI 核心库，AirUI 基于 display 核心库实现复杂界面渲染；
2、需要直接控制显存、多屏幕管理、自定义面板初始化、或为 UI 框架提供底层支持时，使用 display 核心库；
3、简单图形绘制且使用旧一代 lcd 核心库的存量项目，可继续使用 lcd 核心库，新项目不推荐；
4、display 核心库暂不支持 QSPI 接口屏幕，QSPI 屏幕请使用 lcd 核心库。
1.1 支持的面板型号和接口组合
display.init(panel_name, config) 的 panel_name 和 config.interface 必须填下表中支持的组合，其他组合会初始化失败：
| panel_name | 支持的 interface | 说明 |
|---|---|---|
| "custom" | "rgb"、"dsi"、"lvds" | 自定义面板，需要自行配置分辨率、时序和初始化命令 |
| "st7789" | "spi" | 内置 SPI 面板，芯片参数已适配 |
| "st7796" | "spi" | 内置 SPI 面板，芯片参数已适配 |
| "ili9341" | "spi" | 内置 SPI 面板，芯片参数已适配 |
| "st7701s" | "rgb"、"dsi" | 内置面板，芯片参数已适配 |
| "nv3052c" | "rgb" | 内置面板，芯片参数已适配 |
说明：
1、内置面板型号底层已完成芯片参数适配，只需填写分辨率、时序、引脚等基本信息即可正常显示；
2、未内置的面板型号使用 "custom"，需要按屏幕数据手册填写时序参数和 custom_cmds 初始化命令序列；
3、SPI 接口屏幕的 IC 未在内置型号中时（如 GC9A01），可选用内置 SPI 型号名（如 "st7789"）并传入 custom_cmds 覆盖内置初始化序列，同样可以完成初始化；
4、"sdl" 接口是 PC 模拟器专用接口，在 PC 模拟器上运行时接口会自动强制为 "sdl"，无需手动填写。
1.2 custom 面板的初始化命令序列 custom_cmds
"custom" 面板和内置面板都支持通过 config.custom_cmds 传入芯片初始化命令序列。命令序列为 table，每一行是一条命令，格式为：
{命令, 数据1, 数据2, ..., delay = 延时毫秒}
每一行的第一个元素是命令字节，后续元素是该命令携带的数据字节；delay 字段是可选的，表示发送完该行命令后延时的毫秒数，用于等待屏幕电源或寄存器生效。
-- 示例：屏幕芯片初始化命令序列
custom_cmds = {
{0xFF, 0x77, 0x01, 0x00, 0x00, 0x10}, -- 命令0xFF，携带5个数据字节，用于解锁寄存器页
{0xC0, 0x3B, 0x00}, -- 命令0xC0，携带2个数据字节，设置扫描方向
{0x11, delay = 120}, -- 退出休眠命令，延时120ms等待屏幕电源稳定
}
1.3 屏幕方向和旋转
display 核心库通过 display.setRotation(rotation) 设置屏幕旋转，支持 0°、90°、180°、270° 四个方向，对应 display.ROTATE_0、display.ROTATE_90、display.ROTATE_180、display.ROTATE_270 常量。90° 为逆时针旋转 90°。
注意事项：
1、旋转 90°/270° 时 display.getSize() 返回的宽高互换（如 1024×600 的屏幕变为 600×1024），display.getPhySize() 的返回值不随旋转改变；上层代码按 display.getSize() 返回的宽高绘制即可铺满全屏；
1.4 从 lcd 核心库迁移对照表
| lcd 核心库 | display 核心库 |
|---|---|
| lcd.init("custom", {port = lcd.RGB, bus_speed = 30000000, ...}) | display.init("custom", {interface = "rgb", pclk_hz = 30000000, ...}) |
| lcd.init("custom", {port = lcd.HWID_0, ...}) | display.init("st7789", {interface = "spi", ...}) |
| param.direction = lcd.direction_90 | display.setRotation(display.ROTATE_90) |
| lcd.setupBuff(nil, true)、lcd.autoFlush(false) | 无需调用，FrameBuffer 由 display 核心库分配管理 |
| lcd.getSize() | display.getSize() |
| lcd.clear(color) | display.fill(0, 0, width - 1, height - 1, color) |
| lcd.flush() | display.flush() |
| lcd.cmd(cmd)、lcd.data(data) | display.sendSeq({cmd, data1, data2}) |
| lcd.on()、lcd.off()、lcd.sleep()、lcd.wakeup() | display.on()、display.off()、display.sleep()、display.wakeup() |
二、核心示例
1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；
2、示例以 RGB 接口屏幕为例，屏幕分辨率 1024×600，初始化命令序列和时序参数按屏幕数据手册填写；
3、更加完整和详细的 demo，请参考 LuatOS 仓库 中各个产品目录下的 demo。
2.1 核心代码
-- RGB接口屏幕初始化，初始化完成后进入绘图演示
local function ui_main()
-- 初始化display，panel_name填"custom"，接口填"rgb"，时序参数按屏幕数据手册填写
local result, err = display.init("custom", {
interface = "rgb", -- RGB接口
w = 1024, -- 屏幕水平分辨率
h = 600, -- 屏幕竖直分辨率
hbp = 120, -- 水平后廊，按屏幕数据手册填写
hspw = 40, -- 水平同步脉宽，按屏幕数据手册填写
hfp = 150, -- 水平前廊，按屏幕数据手册填写
vbp = 23, -- 垂直后廊，按屏幕数据手册填写
vspw = 10, -- 垂直同步脉宽，按屏幕数据手册填写
vfp = 12, -- 垂直前廊，按屏幕数据手册填写
pclk_hz = 51 * 1000 * 1000, -- 像素时钟51MHz，按屏幕数据手册填写
pin_pwr = 42, -- 屏幕供电引脚，初始化完成自动拉高供电
pin_rst = 15, -- 屏幕复位引脚，初始化时自动输出复位时序
})
if not result then
log.error("display", "init fail", err)
return
end
-- 获取屏幕尺寸，后续按实际分辨率绘制
local width, height = display.getSize()
log.info("display", "size", width, height)
-- 全屏填充白色背景
display.fill(0, 0, width - 1, height - 1, 0xFFFF)
-- 在屏幕左上角区域填充一个红色矩形
display.fill(20, 20, 300, 200, 0xF800)
-- 在屏幕中央填充一个绿色圆形
display.fillCircle(width / 2, height / 2, 100, 0x07E0)
-- 发送寄存器命令，命令0x35开启TEAR效果同步（按屏幕数据手册支持的命令填写）
display.sendSeq({0x35, 0x00})
-- 刷新显示缓冲区内容到屏幕，RGB接口屏幕写入即显示，SPI/DBI接口必须调用
display.flush()
end
sys.taskInit(ui_main)
2.2 代码说明
1：display.init("custom", {...}) 初始化 RGB 接口屏幕，配置表中 interface 填 "rgb"，w/h 填屏幕分辨率，hbp/hspw/hfp/vbp/vspw/vfp/pclk_hz 按屏幕数据手册的 RGB 时序参数填写；
2：初始化返回两个值，第一个值为 boolean 表示是否成功，第二个值为失败时的错误信息字符串；
3：display.getSize() 获取屏幕宽高，后续绘制按实际分辨率计算坐标；
4：display.fill(0, 0, width - 1, height - 1, 0xFFFF) 用白色填充整个屏幕，颜色为16位RGB565值；
5：display.fill(20, 20, 300, 200, 0xF800) 填充以(20,20)为左上角、(300,200)为右下角的红色矩形；
6：display.fillCircle(width / 2, height / 2, 100, 0x07E0) 以屏幕中心为圆心填充半径100的绿色实心圆；
7：display.sendSeq({0x35, 0x00}) 向屏幕芯片发送命令0x35，携带1个数据字节0x00；
8：display.flush() 将显示缓冲区内容刷新到屏幕。
三、常量详解
核心库常量，顾名思义是由合宙 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用，包含以下常量；
| 常量名 | 取值 | 说明 |
| display.ROTATE_0 | 0 | 屏幕旋转 0°，正常方向 |
| display.ROTATE_90 | 1 | 屏幕逆时针旋转 90° |
| display.ROTATE_180 | 2 | 屏幕旋转 180° |
| display.ROTATE_270 | 3 | 屏幕逆时针旋转 270°（顺时针 90°） |
四、函数详解
4.1 display.init(panel_name, config)
功能
display 显示屏初始化，配置面板型号、接口类型、分辨率、时序参数、引脚和初始化命令序列；初始化完成自动开启显示；
参数
panel_name
参数含义：面板型号；
数据类型：string；
取值范围：
- "custom"：自定义面板，配合 config 中的时序参数和 custom_cmds 使用，适合未内置的
面板型号，支持 "rgb"、"dsi"、"lvds" 接口；
- "st7789"、"st7796"、"ili9341"：内置 SPI 面板型号，芯片参数已适配，适合对应
芯片的 SPI 接口屏幕，不需要配置 custom_cmds；
- "st7701s"：内置面板型号，支持 "rgb"、"dsi" 接口；
- "nv3052c"：内置面板型号，支持 "rgb" 接口；
如果不确定填哪个：使用的屏幕 IC 是以上内置型号就填对应型号，否则填 "custom"；
是否必选：必须传入此参数；
注意事项：panel_name 与 config.interface 必须是 1.1 节表格中支持的组合，否则初始化失败；
参数示例："custom"
config
参数含义：屏幕初始化配置表；
数据类型：table；
取值范围：包含以下字段：
{
参数含义：接口类型；
数据类型：string；
取值范围："rgb"（RGB接口）、"dsi"（MIPI-DSI接口）、"spi"（SPI接口）、
"lvds"（LVDS接口）、"sdl"（PC模拟器专用，真机无需填写）；
按屏幕与主板实际连接的接口类型选择；
是否必选：必须传入此参数；
注意事项：必须与 panel_name 匹配，支持的组合见 1.1 节表格；
参数示例："rgb"
config.interface ,
参数含义：显示组件 ID，多屏场景用于区分不同屏幕；
数据类型：number；
取值范围：0~4；
是否必选：可选传入此参数；不传则自动分配一个空闲 ID；
注意事项：单屏场景不需要填写；多屏场景给每块屏填不同的 ID，后续接口可用该 ID 指定操作哪块屏；
参数示例：0
config.id ,
参数含义：屏幕水平分辨率；
数据类型：number；
取值范围：正整数；
是否必选：必须传入此参数；
注意事项：填屏幕的像素宽度；
参数示例：1024
config.w ,
参数含义：屏幕竖直分辨率；
数据类型：number；
取值范围：正整数；
是否必选：必须传入此参数；
注意事项：填屏幕的像素高度；
参数示例：600
config.h ,
参数含义：每像素位数；
数据类型：number；
取值范围：16；
是否必选：可选传入此参数；不传默认 16；
注意事项：当前版本固定 16 位（RGB565），不需要修改，不传即可；
参数示例：16
config.bpp ,
参数含义：RGB 时序的水平后廊；
数据类型：number；
取值范围：非负整数；
是否必选："rgb"/"lvds" 接口必须传入此参数，"spi"/"dsi" 接口不需要填写；
注意事项：HSYNC 脉冲结束到第一个有效像素之间的像素时钟数，按屏幕数据手册的 RGB 时序参数填写；
参数示例：120
config.hbp ,
参数含义：RGB 时序的水平同步脉宽；
数据类型：number；
取值范围：正整数；
是否必选："rgb"/"lvds" 接口必须传入此参数，"spi"/"dsi" 接口不需要填写；
注意事项：HSYNC 脉冲的宽度，单位像素时钟数，按屏幕数据手册的 RGB 时序参数填写；
参数示例：40
config.hspw ,
参数含义：RGB 时序的水平前廊；
数据类型：number；
取值范围：非负整数；
是否必选："rgb"/"lvds" 接口必须传入此参数，"spi"/"dsi" 接口不需要填写；
注意事项：最后一个有效像素到下一个 HSYNC 脉冲开始之间的像素时钟数，按屏幕数据手册的 RGB 时序参数填写；
参数示例：150
config.hfp ,
参数含义：RGB 时序的垂直后廊；
数据类型：number；
取值范围：非负整数；
是否必选："rgb"/"lvds" 接口必须传入此参数，"spi"/"dsi" 接口不需要填写；
注意事项：VSYNC 脉冲结束到第一个有效显示行之间的行数，按屏幕数据手册的 RGB 时序参数填写；
参数示例：23
config.vbp ,
参数含义：RGB 时序的垂直同步脉宽；
数据类型：number；
取值范围：正整数；
是否必选："rgb"/"lvds" 接口必须传入此参数，"spi"/"dsi" 接口不需要填写；
注意事项：VSYNC 脉冲的宽度，单位行数，按屏幕数据手册的 RGB 时序参数填写；
参数示例：10
config.vspw ,
参数含义：RGB 时序的垂直前廊；
数据类型：number；
取值范围：非负整数；
是否必选："rgb"/"lvds" 接口必须传入此参数，"spi"/"dsi" 接口不需要填写；
注意事项：最后一个有效显示行到下一个 VSYNC 脉冲开始之间的行数，按屏幕数据手册的 RGB 时序参数填写；
参数示例：12
config.vfp ,
参数含义：像素时钟频率；
数据类型：number；
取值范围：正整数，单位 Hz；
是否必选："rgb"/"lvds" 接口必须传入此参数，"spi"/"dsi" 接口不需要填写；
注意事项：按屏幕数据手册填写，示例 51MHz 填 51 * 1000 * 1000；像素时钟决定屏幕刷新率，
填写过低会导致画面显示不全或闪屏；
参数示例：51 * 1000 * 1000
config.pclk_hz ,
参数含义：HSYNC 同步信号极性；
数据类型：number；
取值范围：0（低电平有效）、1（高电平有效）；
是否必选：可选传入此参数；不传默认 0；
注意事项：按屏幕数据手册的 RGB 时序参数填写；"custom" 面板不传默认全部低电平有效；
参数示例：0
config.hs_polarity ,
参数含义：VSYNC 同步信号极性；
数据类型：number；
取值范围：0（低电平有效）、1（高电平有效）；
是否必选：可选传入此参数；不传默认 0；
注意事项：按屏幕数据手册的 RGB 时序参数填写；
参数示例：0
config.vs_polarity ,
参数含义：DE 数据有效信号极性；
数据类型：number；
取值范围：0（低电平有效）、1（高电平有效）；
是否必选：可选传入此参数；不传默认 0；
注意事项：按屏幕数据手册的 RGB 时序参数填写；
参数示例：0
config.de_polarity ,
参数含义：PCLK 像素时钟极性；
数据类型：number；
取值范围：0（低电平有效）、1（高电平有效）；
是否必选：可选传入此参数；不传默认 0；
注意事项：按屏幕数据手册的 RGB 时序参数填写；
参数示例：0
config.pclk_polarity ,
参数含义：裁剪窗口的起始 X 坐标；
数据类型：number；
取值范围：非负整数；
是否必选：可选传入此参数；不传默认 0；
注意事项：只显示屏幕窗口内的内容时使用，单屏全屏显示不需要填写；
参数示例：0
config.crop_x ,
参数含义：裁剪窗口的起始 Y 坐标；
数据类型：number；
取值范围：非负整数；
是否必选：可选传入此参数；不传默认 0；
注意事项：单屏全屏显示不需要填写；
参数示例：0
config.crop_y ,
参数含义：裁剪窗口的宽度；
数据类型：number；
取值范围：正整数；
是否必选：可选传入此参数；不传默认屏幕宽度；
注意事项：单屏全屏显示不需要填写；
参数示例：1024
config.crop_w ,
参数含义：裁剪窗口的高度；
数据类型：number；
取值范围：正整数；
是否必选：可选传入此参数；不传默认屏幕高度；
注意事项：单屏全屏显示不需要填写；
参数示例：600
config.crop_h ,
参数含义：屏幕复位引脚 GPIO 端口号；
数据类型：number；
取值范围：有效的 GPIO 端口号；
是否必选：可选传入此参数；不传则不输出复位时序；
注意事项：传入后初始化时自动输出复位时序，业务代码不需要再手动复位；
参数示例：15
config.pin_rst ,
参数含义：屏幕供电使能引脚 GPIO 端口号；
数据类型：number；
取值范围：有效的 GPIO 端口号；
是否必选：可选传入此参数；不传则不控制供电引脚；
注意事项：传入后初始化完成自动拉高供电；需要延后供电的场景不传此参数，由业务代码自行控制；
参数示例：42
config.pin_pwr ,
参数含义：屏幕背光引脚 GPIO 端口号；
数据类型：number；
取值范围：有效的 GPIO 端口号；
是否必选：可选传入此参数；不传则不控制背光引脚；
注意事项：传入后初始化完成自动点亮背光；需要延后点亮背光的场景（如避免开机残影）
不传此参数，由业务代码自行控制背光；
参数示例：42
config.pin_bl ,
参数含义：SPI 片选引脚 GPIO 端口号；
数据类型：number；
取值范围：有效的 GPIO 端口号；
是否必选：使用 custom_cmds 发送初始化命令时必须传入此参数，其他情况不需要填写；
注意事项：仅用于初始化期间发送 custom_cmds 命令序列；
参数示例：10
config.pin_cs ,
参数含义：SPI 时钟引脚 GPIO 端口号；
数据类型：number；
取值范围：有效的 GPIO 端口号；
是否必选：使用 custom_cmds 发送初始化命令时必须传入此参数，其他情况不需要填写；
注意事项：仅用于初始化期间发送 custom_cmds 命令序列；
参数示例：12
config.pin_scl ,
参数含义：SPI 数据引脚 GPIO 端口号；
数据类型：number；
取值范围：有效的 GPIO 端口号；
是否必选：使用 custom_cmds 发送初始化命令时必须传入此参数，其他情况不需要填写；
注意事项：仅用于初始化期间发送 custom_cmds 命令序列；
参数示例：11
config.pin_sdi ,
参数含义：SPI 数据/命令选择引脚 GPIO 端口号；
数据类型：number；
取值范围：有效的 GPIO 端口号；
是否必选：可选传入此参数；不传则不使用该引脚；
注意事项：仅 SPI 接口屏幕需要填写；
参数示例：9
config.pin_dc ,
参数含义：屏幕芯片初始化命令序列；
数据类型：table；
取值范围：每行格式为 {命令, 数据1, 数据2, ..., delay = 延时毫秒}，格式说明见 1.2 节；
是否必选：可选传入此参数；
注意事项："custom" 面板按屏幕数据手册的初始化流程填写；内置面板传入此参数会覆盖内置
初始化命令序列；命令序列仅初始化期间使用，初始化完成后自动释放；
参数示例：{{0x11, delay = 120}, {0x29, delay = 20}}
config.custom_cmds ,
}
是否必选：必须传入此参数；
注意事项：table 内可选字段不需要就整个都不填，写下标必须赋值，只写下标会报语法错误；
参数示例：见下方示例代码
返回值
local init_result, err = display.init(panel_name, config)
init_result
含义说明：初始化是否成功；
数据类型：boolean；
取值范围：true表示成功，false表示失败；
注意事项：失败时第二个返回值为错误信息字符串；
返回示例：true
err
含义说明：初始化失败时的错误信息；
数据类型：string；
取值范围："unknown panel or interface"表示面板型号与接口类型组合不支持、
"panel timing setup fail"表示时序参数配置失败、
"custom_cmds setup fail"表示初始化命令序列格式错误、
"init fail"表示底层初始化失败；
是否必选：初始化成功时无此返回值；
返回示例："unknown panel or interface"
示例
-- 示例1：RGB接口"custom"面板初始化
local result, err = display.init("custom", {
interface = "rgb", -- RGB接口
w = 1024, -- 屏幕水平分辨率
h = 600, -- 屏幕竖直分辨率
hbp = 120, -- 水平后廊
hspw = 40, -- 水平同步脉宽
hfp = 150, -- 水平前廊
vbp = 23, -- 垂直后廊
vspw = 10, -- 垂直同步脉宽
vfp = 12, -- 垂直前廊
pclk_hz = 51 * 1000 * 1000, -- 像素时钟51MHz
pin_pwr = 42, -- 供电引脚
pin_rst = 15, -- 复位引脚
})
log.info("display", "init", result, err)
-- 示例2：SPI接口内置型号"st7789"初始化
local result = display.init("st7789", {
interface = "spi", -- SPI接口
w = 240, -- 屏幕水平分辨率
h = 320, -- 屏幕竖直分辨率
pin_dc = 9, -- 数据/命令选择引脚
pin_rst = 15, -- 复位引脚
pin_bl = 42, -- 背光引脚
})
log.info("display", "init", result)
4.2 display.on([id])
功能
打开屏幕显示，拉高供电引脚和背光引脚；display.init() 初始化完成后会自动调用本接口，不需要在初始化后重复调用；
参数
id
参数含义：显示组件 ID；
数据类型：number；
取值范围：0~4，与 display.init() 配置的 config.id 对应；
是否必选：可选传入此参数；不传则操作默认屏幕；
注意事项：单屏场景不需要填写；
参数示例：0
返回值
local on_result = display.on()
on_result
含义说明：操作是否成功；
数据类型：boolean；
取值范围：true表示成功，false表示失败；
注意事项：未初始化就调用返回false；
返回示例：true
示例
-- 打开默认屏幕显示
display.on()
4.3 display.off([id])
功能
关闭屏幕显示，拉低供电引脚和背光引脚；关闭后显示缓冲区内容保留，再次调用 display.on() 恢复显示；
参数
id
参数含义：显示组件 ID；
数据类型：number；
取值范围：0~4，与 display.init() 配置的 config.id 对应；
是否必选：可选传入此参数；不传则操作默认屏幕；
注意事项：单屏场景不需要填写；
参数示例：0
返回值
local off_result = display.off()
off_result
含义说明：操作是否成功；
数据类型：boolean；
取值范围：true表示成功，false表示失败；
注意事项：未初始化就调用返回false；
返回示例：true
示例
-- 关闭默认屏幕显示，适合息屏省电场景
display.off()
4.4 display.sleep([id])
功能
屏幕进入休眠模式，关闭背光并让屏幕芯片进入低功耗状态；休眠不断开电源，功耗高于 display.off()，但唤醒更快；
参数
id
参数含义：显示组件 ID；
数据类型：number；
取值范围：0~4，与 display.init() 配置的 config.id 对应；
是否必选：可选传入此参数；不传则操作默认屏幕；
注意事项：单屏场景不需要填写；
参数示例：0
返回值
local sleep_result = display.sleep()
sleep_result
含义说明：操作是否成功；
数据类型：boolean；
取值范围：true表示成功，false表示失败；
注意事项：未初始化就调用返回false；
返回示例：true
示例
-- 屏幕休眠，适合短时间息屏、之后需要快速恢复显示的场景
display.sleep()
sys.wait(5000) -- 休眠5秒，期间屏幕低功耗显示
display.wakeup() -- 5秒后唤醒屏幕恢复显示
4.5 display.wakeup([id])
功能
从休眠模式唤醒屏幕，恢复屏幕芯片正常工作状态并恢复背光；与 display.sleep() 配对使用；
参数
id
参数含义：显示组件 ID；
数据类型：number；
取值范围：0~4，与 display.init() 配置的 config.id 对应；
是否必选：可选传入此参数；不传则操作默认屏幕；
注意事项：单屏场景不需要填写；
参数示例：0
返回值
local wakeup_result = display.wakeup()
wakeup_result
含义说明：操作是否成功；
数据类型：boolean；
取值范围：true表示成功，false表示失败；
注意事项：未初始化就调用返回false；
返回示例：true
示例
-- 从休眠状态唤醒屏幕
display.wakeup()
4.6 display.flush([id])
功能
将显示缓冲区的内容刷新到屏幕；
注意事项
1、RGB 接口屏幕的帧缓冲由显示控制器持续扫描输出，display.fill()、display.fillCircle() 绘制的内容直接可见，不需要调用本接口；
2、SPI 等接口的屏幕，每次修改显示缓冲区后必须调用本接口才能显示到屏幕；
参数
id
参数含义：显示组件 ID；
数据类型：number；
取值范围：0~4，与 display.init() 配置的 config.id 对应；
是否必选：可选传入此参数；不传则操作默认屏幕；
注意事项：单屏场景不需要填写；
参数示例：0
返回值
local flush_result = display.flush()
flush_result
含义说明：刷新操作是否成功；
数据类型：boolean；
取值范围：true表示成功，false表示失败；
注意事项：未初始化就调用返回false；
返回示例：true
示例
-- 在SPI接口屏幕上绘制红色矩形并刷新到屏幕
display.fill(20, 20, 300, 200, 0xF800) -- 绘制红色矩形到显示缓冲区
display.flush() -- 刷新显示缓冲区内容到屏幕
4.7 display.fill([id], x1, y1, x2, y2, color)
功能
将 color 颜色填充到一个以左上角为（x1,y1）右下角为（x2,y2）的矩形区域，坐标超出屏幕范围会自动裁剪到屏幕内；
参数
id
参数含义：显示组件 ID；
数据类型：number；
取值范围：0~4，与 display.init() 配置的 config.id 对应；
是否必选：可选传入此参数；不传则操作默认屏幕；
注意事项：单屏场景不需要填写；
参数示例：0
x1
参数含义：起始X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：矩形区域的左上角X坐标；
参数示例：20
y1
参数含义：起始Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：矩形区域的左上角Y坐标；
参数示例：30
x2
参数含义：结束X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：矩形区域的右下角X坐标；
参数示例：220
y2
参数含义：结束Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：矩形区域的右下角Y坐标；
参数示例：230
color
参数含义：填充颜色值；
数据类型：number；
取值范围：16位RGB565颜色值 0x0000-0xFFFF，常用颜色：0xFFFF白色、0x0000黑色、
0xF800红色、0x07E0绿色、0x001F蓝色、0xFFE0黄色、0x07FF青色、0xF81F洋红色；
其他颜色按 RGB565 转换逻辑从24位RGB888转换，可参考 lcd 核心库文档 1.1 节；
是否必选：必须传入此参数；
注意事项：颜色值与初始化配置的像素格式对应，16位像素格式填 RGB565 颜色值；
参数示例：0xF800
返回值
local fill_result = display.fill(x1, y1, x2, y2, color)
fill_result
含义说明：填充操作是否成功；
数据类型：boolean；
取值范围：true表示成功，false表示失败；
注意事项：坐标全部超出屏幕范围时返回false；填充内容写入显示缓冲区，SPI接口屏幕
需要再调用display.flush()才能显示到屏幕；
返回示例：true
示例
-- 填充以(20,20)为左上角、(300,200)为右下角的红色矩形
display.fill(20, 20, 300, 200, 0xF800)
-- 填充整个屏幕的白色背景
local width, height = display.getSize()
display.fill(0, 0, width - 1, height - 1, 0xFFFF)
4.8 display.fillCircle([id], cx, cy, r, color)
功能
以（cx,cy）为圆心、r 为半径填充一个 color 颜色的实心圆；
参数
id
参数含义：显示组件 ID；
数据类型：number；
取值范围：0~4，与 display.init() 配置的 config.id 对应；
是否必选：可选传入此参数；不传则操作默认屏幕；
注意事项：单屏场景不需要填写；
参数示例：0
cx
参数含义：圆心X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：120
cy
参数含义：圆心Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：160
r
参数含义：圆半径；
数据类型：number；
取值范围：大于等于0的整数；
是否必选：必须传入此参数；
注意事项：圆超出屏幕范围的部分自动裁剪；
参数示例：50
color
参数含义：填充颜色值；
数据类型：number；
取值范围：16位RGB565颜色值 0x0000-0xFFFF；
是否必选：必须传入此参数；
注意事项：颜色值与初始化配置的像素格式对应；
参数示例：0x07E0
返回值
local circle_result = display.fillCircle(cx, cy, r, color)
circle_result
含义说明：填充操作是否成功；
数据类型：boolean；
取值范围：true表示成功，false表示失败；
注意事项：填充内容写入显示缓冲区，SPI接口屏幕需要再调用display.flush()才能显示到屏幕；
返回示例：true
示例
-- 以(120,160)为圆心填充半径50的绿色实心圆
display.fillCircle(120, 160, 50, 0x07E0)
4.9 display.sendSeq([id], cmd_table)
功能
向屏幕芯片发送一条命令序列，用于屏幕调试或修改屏幕芯片寄存器配置；
参数
id
参数含义：显示组件 ID；
数据类型：number；
取值范围：0~4，与 display.init() 配置的 config.id 对应；
是否必选：可选传入此参数；不传则操作默认屏幕；
注意事项：单屏场景不需要填写；
参数示例：0
cmd_table
参数含义：命令序列表；
数据类型：table；
取值范围：第一个元素是命令字节，后续元素是该命令携带的数据字节，每个元素为0~255的整数；
例如{0x36, 0x08}表示发送命令0x36，携带1个数据字节0x08；
是否必选：必须传入此参数；
注意事项：发送的命令按屏幕数据手册支持的寄存器命令填写，发送不支持的命令会造成显示异常；
参数示例：{0x36, 0x08}
返回值
local seq_result = display.sendSeq({0x36, 0x08})
seq_result
含义说明：发送是否成功；
数据类型：boolean；
取值范围：true表示成功，false表示失败；
注意事项：空表或未初始化时返回false；
返回示例：true
示例
-- 发送命令0x36，携带数据0x08，设置屏幕显示扫描方向
display.sendSeq({0x36, 0x08})
4.10 display.setRotation([id], rotation)
功能
设置屏幕显示旋转方向，支持 0°、90°、180°、270° 四个方向，90° 为逆时针旋转 90°；
参数
id
参数含义：显示组件 ID；
数据类型：number；
取值范围：0~4，与 display.init() 配置的 config.id 对应；
是否必选：可选传入此参数；不传则操作默认屏幕；
注意事项：单屏场景不需要填写；
参数示例：0
rotation
参数含义：旋转角度；
数据类型：number；
取值范围：display.ROTATE_0表示0°，适合正常方向显示；
display.ROTATE_90表示逆时针90°，适合横屏显示；
display.ROTATE_180表示180°，适合倒装屏幕；
display.ROTATE_270表示逆时针270°（顺时针90°），适合横屏显示；
是否必选：必须传入此参数；
注意事项：1、旋转90°/270°时display.getSize()返回的宽高互换（如1024×600的屏幕变为600×1024），
display.getPhySize()的返回值不随旋转改变；上层代码按display.getSize()返回的宽高
绘制即可铺满全屏；
参数示例：display.ROTATE_90
返回值
local rotation_result = display.setRotation(rotation)
rotation_result
含义说明：设置是否成功；
数据类型：boolean；
取值范围：true表示成功，false表示失败；
注意事项：未初始化就调用返回false；
返回示例：true
示例
-- 屏幕逆时针旋转90度横屏显示
display.setRotation(display.ROTATE_90)
4.11 display.getSize([id])
功能
获取屏幕显示宽高；
参数
id
参数含义：显示组件 ID；
数据类型：number；
取值范围：0~4，与 display.init() 配置的 config.id 对应；
是否必选：可选传入此参数；不传则获取默认屏幕的尺寸；
注意事项：单屏场景不需要填写；
参数示例：0
返回值
local width, height = display.getSize()
width
含义说明：屏幕宽度；
数据类型：number；
取值范围：正整数；
是否必选：返回值的第一个参数；
注意事项：如果未初始化会返回0；
返回示例：1024
height
含义说明：屏幕高度；
数据类型：number；
取值范围：正整数；
是否必选：返回值的第二个参数；
注意事项：如果未初始化会返回0；
返回示例：600
示例
-- 获取屏幕尺寸并打印
local width, height = display.getSize()
log.info("display", "size", width, height)
4.12 display.getPhySize([id])
功能
获取屏幕物理分辨率，即帧缓冲的原始宽高；与 display.getSize() 的区别：getPhySize 返回帧缓冲的物理宽高，不随旋转改变，getSize 返回显示区域的宽高，旋转 90°/270° 时宽高互换；
参数
id
参数含义：显示组件 ID；
数据类型：number；
取值范围：0~4，与 display.init() 配置的 config.id 对应；
是否必选：可选传入此参数；不传则获取默认屏幕的物理尺寸；
注意事项：单屏场景不需要填写；
参数示例：0
返回值
local phy_width, phy_height = display.getPhySize()
phy_width
含义说明：屏幕物理宽度；
数据类型：number；
取值范围：正整数；
是否必选：返回值的第一个参数；
注意事项：如果未初始化会返回0；
返回示例：1024
phy_height
含义说明：屏幕物理高度；
数据类型：number；
取值范围：正整数；
是否必选：返回值的第二个参数；
注意事项：如果未初始化会返回0；
返回示例：600
示例
-- 获取屏幕物理分辨率并打印
local phy_width, phy_height = display.getPhySize()
log.info("display", "phy size", phy_width, phy_height)
4.13 display.getFbInfo([id])
功能
获取 FrameBuffer 显存信息，适合需要直接读写显存的场景（如配合 DMA 搬运图像数据、与摄像头预览对接）；
参数
id
参数含义：显示组件 ID；
数据类型：number；
取值范围：0~4，与 display.init() 配置的 config.id 对应；
是否必选：可选传入此参数；不传则获取默认屏幕的显存信息；
注意事项：单屏场景不需要填写；
参数示例：0
返回值
local fb_addr, fb_size, fb_count = display.getFbInfo()
fb_addr
含义说明：FrameBuffer 显存地址；
数据类型：userdata；
取值范围：有效的显存地址；
是否必选：返回值的第一个参数；
注意事项：未初始化返回nil；
返回示例：userdata类型地址
fb_size
含义说明：FrameBuffer 显存大小；
数据类型：number；
取值范围：正整数，单位字节；
是否必选：返回值的第二个参数；
注意事项：暂无；
返回示例：1228800
fb_count
含义说明：FrameBuffer 数量；
数据类型：number；
取值范围：1表示单缓冲，2表示双缓冲；
是否必选：返回值的第三个参数；
注意事项：暂无；
返回示例：1
示例
-- 获取显存信息并打印
local fb_addr, fb_size, fb_count = display.getFbInfo()
log.info("display", "fb", fb_addr, fb_size, fb_count)
五、常见问题
5.1 display 核心库和 lcd 核心库怎么选
1、新项目 UI 开发推荐使用 AirUI 核心库，AirUI 基于 display 核心库实现复杂界面渲染；
2、需要直接控制显存、多屏幕管理、自定义面板初始化时使用 display 核心库；
3、简单图形绘制且已经在使用 lcd 核心库的存量项目可继续使用 lcd 核心库；
4、QSPI 接口屏幕只能使用 lcd 核心库，display 核心库暂不支持 QSPI 接口。
5.2 display.init() 初始化失败返回 "unknown panel or interface"
panel_name 和 config.interface 不是支持的组合，解决方法：
1、检查 panel_name 和 config.interface 是否在 1.1 节表格的组合内；
2、SPI 接口屏幕的 IC 未内置时，选用内置 SPI 型号名（如 "st7789"）并传入 custom_cmds 自定义初始化命令序列；
3、"custom" 面板只支持 "rgb"、"dsi"、"lvds" 接口，SPI 接口不支持 "custom" 面板名。
5.3 脚本报错 attempt to call field 'init' (a nil value)
当前固件未集成 display 核心库，请烧录 Air1601/Air1602 的 102 号固件；
5.4 display.getSize() 返回 0, 0
display.init() 初始化成功之前调用 getSize 会返回 0, 0，检查初始化是否成功，初始化完成后再获取屏幕尺寸；
5.5 绘制后屏幕没有显示
1、SPI 接口屏幕修改显示缓冲区后必须调用 display.flush() 才能显示到屏幕；
2、检查 display.init() 是否返回 true，初始化失败显示缓冲区不可用；
3、RGB 接口屏幕画面显示不全或闪屏，检查 pclk_hz 是否按屏幕数据手册填写，像素时钟过低会导致画面显示不全。
六、产品支持说明
1、display 核心库需要固件支持，目前仅 Air1601/Air1602 的 102 号固件支持 display 核心库，其他型号和固件版本暂不支持，使用前请确认烧录的固件版本；
七、更新说明
版本号：202610121127
-
更新时间：2026-10-12
-
更新内容：
- 初版，覆盖 init/on/off/sleep/wakeup/flush/fill/fillCircle/sendSeq/setRotation/getSize/getPhySize/getFbInfo 共 13 个接口和 4 个旋转常量的使用说明