LCD 核心库

作者：江访

一、概述

LCD 驱动模块是一个功能丰富的显示屏控制接口，支持多种接口类型的 LCD 屏幕，包括 SPI、QSPI、RGB 等。该模块提供了显示屏初始化、图形绘制、文本显示、图像处理、屏幕休眠、唤醒等功能。

1.1 RGB565 介绍

1.1.1 颜色分量转 16 位 RGB565 颜色逻辑

人眼大约能区分数百万到上千万种颜色。在计算机程序中，颜色通常用二进制表示。24 位颜色（即 2²⁴，约 1600 万种）足以覆盖人眼可识别的所有颜色范围。这种表示方式占用 3 个字节，分别对应光的三原色：红（R）、绿（G）、蓝（B），每种颜色各占 1 个字节。 在嵌入式场景资源有限，为了节省存储空间或适配硬件限制，需要将 24 位的 RGB888 颜色转换为 16 位的 RGB565 格式。RGB565 中，红色（R）和蓝色（B）各占 5 位，绿色（G）占 6 位。

下面以颜色分量 R:255、G:50、B:88 为例，演示转换过程：

1. 将各颜色分量转为二进制，并提取高位部分：
2. R: 11111111 → 取高 5 位 → 11111
3. G: 00110010 → 取高 6 位 → 001100
4. B: 01011000 → 取高 5 位 → 01011
5. 将提取的位按 RGB565 格式组合：
6. 排列顺序为：R（5 位） + G（6 位） + B（5 位）
7. 组合结果为：11111 001100 01011
8. 将组合后的二进制转换为十六进制：
9. 1111100110001011 → 对应十六进制值为 0xF98B

1.1.2 RGB565 常用颜色，可以在调用 LCD 库接口时直接使用

除以下颜色，其他更丰富的颜色可以使用 windows 画图软件的取色器进行提取或者从配色网站获取，然后按转换逻辑进行转换。

WHITE       = 0xFFFF,  -- 白色，颜色分量 R = 248-255, G = 252-255, B = 248-255
BLACK       = 0x0000,  -- 黑色，颜色分量 R = 0, G = 0, B = 0
RED         = 0xF800,  -- 红色，颜色分量 R = 248-255, G = 0, B = 0
GREEN       = 0x07E0,  -- 绿色，颜色分量 R = 0, G = 252-255, B = 0
BLUE        = 0x001F,  -- 蓝色，颜色分量 R = 0, G = 0, B = 248-255
YELLOW      = 0xFFE0,  -- 黄色，颜色分量 R = 248-255, G = 252-255, B = 0
CYAN        = 0x07FF,  -- 青色，颜色分量 R = 0, G = 252-255, B = 248-255
MAGENTA     = 0xF81F,  -- 洋红色，颜色分量 R = 248-255, G = 0, B = 248-255
GRAY        = 0x8410,  -- 灰色，颜色分量 R = 128-135, G = 128-131, B = 128-135
LIGHTGRAY   = 0xC618,  -- 浅灰色，颜色分量 R = 192-199, G = 192-195, B = 192-199
DARKGRAY    = 0x4208,  -- 深灰色，颜色分量 R = 64-71, G = 64-67, B = 64-71
ORANGE      = 0xFC00,  -- 橙色，颜色分量 R = 248-255, G = 128-131, B = 0
PINK        = 0xFE19,  -- 粉色，颜色分量 R = 248-255, G = 192-195, B = 200-207
BROWN       = 0x8200,  -- 棕色，颜色分量 R = 128-135, G = 64-67, B = 0
PURPLE      = 0x8010,  -- 紫色，颜色分量 R = 128-135, G = 0, B = 128-135
LIME        = 0x07E0,  -- 酸橙色，颜色分量 R = 0, G = 252-255, B = 0
NAVY        = 0x0010,  -- 海军蓝，颜色分量 R = 0, G = 0, B = 128-135
TEAL        = 0x0410,  -- 蓝绿色，颜色分量 R = 0, G = 128-131, B = 128-135
MAROON      = 0x8000,  -- 栗色，颜色分量 R = 128-135, G = 0, B = 0
OLIVE       = 0x8400,  -- 橄榄色，颜色分量 R = 128-135, G = 128-131, B = 0
SILVER      = 0xC618,  -- 银色，颜色分量 R = 192-199, G = 192-195, B = 192-199
GOLD        = 0xFEA0,  -- 金色，颜色分量 R = 248-255, G = 215-218, B = 0

1.1.3 使用 RGB565 颜色接口注意事项

1. LCD核心库中很多接口都使用到RGB565颜色，以下这些接口可以直接填入16位RGB565颜色值（0x0000-0xFFFF）进行显示。
2. 当以下接口使用lcd.rgb565(r, g, b, swap) 和lcd.rgb565(rgb888, swap)接口转换后的颜色值进行显示时，swap参数需要填false，否则会出现显示反色的情况。

   lcd.clear(color)                        -- 按设置的颜色或背景色清屏；
   lcd.fill(x1, y1, x2, y2,color)          -- 填充矩形区域；
   lcd.drawPoint(x,y,color)                -- 画一个可设置颜色的点；
   lcd.drawLine(x1,y1,x2,y2,color)         -- 在两点之间画一条线；
   lcd.drawRectangle(x1,y1,x2,y2,color)    -- 从绘制一个矩形框；
   lcd.drawCircle(x,y,r,color)             -- 绘制一个圆圈；
   lcd.drawStr(x,y,str,fg_color)           -- 显示字符串；
   lcd.setColor(back,fore)                 -- 设置LCD显示的前景色和背景色；
   

3. 当使用lcd.draw(x1, y1, x2, y2,buff)接口将buff缓冲区内容进行显示时，若zbuff.create()接口创建的纯色buff缓冲区使用的是lcd.rgb565(r, g, b, swap) 和lcd.rgb565(rgb888, swap)转换后的颜色，此时swap参数需要填true，否则会出现反色。使用时可以查看第四节 函数详解中4.9 lcd.draw(x1, y1, x2, y2,buff)的示例。

1.2 LCD 核心库初始化的内置型号和 custom 型号的差异

1.2.1 内置型号

在函数详解部分，LCD 初始化函数 lcd.init() 的第一个参数 driver_ic 支持以下具体型号：

"st7796"、"st7789"、"st7735"、"st7735v"、"st7735s" "gc9a01"、"gc9106l"、"gc9306x"、"ili9486" 这些是核心库已预适配的显示驱动芯片型号。对于内置型号，库底层已完成各芯片在 LuatOS 系统上正常显示所需的参数配置。使用时，仅需指定对应型号、连接的硬件端口、屏幕方向及分辨率即可完成初始化，后续显示操作将自动按照初始化参数执行。

1.2.2 "custom"型号

"custom"表示当前核心库内置未适配的显示芯片型号。由于显示芯片品牌和型号众多，无法全部内置，因此 LCD 核心库提供了自定义初始化功能。 用户需根据具体显示芯片的数据手册，自行配置初始化参数。在 lcd.init() 的第二个参数 param 中，支持传入以下配置表（table）：

参数表说明

参数名	含义	数据类型	是否必选	说明与示例
pin_pwr	LCD背光引脚GPIO编号	number	可选	示例：7
port	LCD硬件驱动端口类型	number/string	必选	可选值：lcd.HWID_0（专用LCD SPI）、lcd.RGB（RGB端口）、0/1/2（标准SPI端口ID）、lcd.QSPI_MODE（QSPI端口）、"device"（SPI设备对象）
pin_dc	数据/命令选择引脚GPIO编号	number	条件必选	使用标准SPI或"device"时必须设置
pin_rst	复位引脚GPIO编号	number	可选	示例：10
direction	屏幕方向	number	可选	默认lcd.direction_0，可选0/90/180/270度
w	水平分辨率	number	必选	示例：240
h	垂直分辨率	number	必选	示例：320
xoffset	X偏移量	number	可选	默认0
yoffset	Y偏移量	number	可选	默认0
sleepcmd	睡眠命令	number	可选	默认0x10
wakecmd	唤醒命令	number	可选	默认0x11
direction0~direction270	各方向命令	number	可选	对应0x00、0x60、0xC0、0xA0等
interface_mode	接口软件驱动类型	string	可选	用于QSPI模式细分
bus_speed	QSPI/RGB总线速率(Hz)	number	可选	上限80MHz，示例：70000000
hbp/hspw/hfpvbp/vspw/vfp/vs	时序校准参数	number	可选	主要用于非内置型号调试
flush_rate	刷新率(0.1Hz)	number	可选	示例：600
rb_swap	交换x/y方向	boolean	可选	默认false
initcmd	自定义初始化命令表	table	可选	用于"custom"型号初始化流程

1.3 LCD 英文字体和中文字体如何使用

1.3.1 坐标说明

未设置 x,y 坐标翻转的正常情况下，默认以点（0,0）位置为左上角，水平方向为 x 坐标，竖直方向为 y 坐标；

lcd.drawStr(x,y,str,fg_color)接口显示内容以设置的坐标为左下角，其余是以设置的坐标为左上角。

1.3.2 字体说明

使用字体常量中的字体需要先使用 lcd.setFont(font, indentation)进行设置；

使用 gtfont 字体需要外置 gtfont 芯片并完成初始化后才能使用，且不需要使用 lcd.setFont(font, indentation)进行设置，可直接使用；

目前 Air780EPM 未内置中文字体和 lcd.font_open_iconic_weather_6x_t 天气图标字体；

1.4 LCD 核心库都支持哪些图形操作

1.4.1 注意事项

使用 buff = lcd.image2raw(file)接口解码 jpg/jpeg 格式图片时，图片像素高度或宽度必须是 16 的倍数，否则可能出现显示异常。

1.4.2 LCD库基本图形效果

图形效果	点		lcd.drawPoint(x,y,color)
	线		lcd.drawLine(x1,y1,x2,y2,color)
	空心圆		lcd.drawCircle(x,y,r,color)
	矩形框		lcd.drawRectangle(x1,y1,x2,y2,color)
	实心矩形		lcd.fill(x1, y1, x2, y2,color)
	显示图片		lcd.showImage(x, y, file) 或者 buff = lcd.image2raw(file) lcd.draw(x1, y1, x2, y2, buff)
	二维码		lcd.drawQrcode(x, y, str, size)

二、核心示例

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

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

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

2.1 核心代码

-- 主循环
local function ui_main()

lcd.init(
    "st7796",
    {
        port = lcd.HWID_0,
        pin_pwr = 7,
        pin_rst = 19,
        direction = 0,
        w = 320,
        h = 480,
        xoffset = 0,
        yoffset = 0
    }
)

while true do

    -- 设置颜色，白底黑字，背景色:白色(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天气字体
    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()
    sys.wait(5000)
    end
end

sys.taskInit(ui_main)

2.2 效果演示

2.3 代码说明

1：通过 lcd.showImage(0, 0, "/luadb/logo.jpg") 显示合宙logo标志图片。
2：由 lcd.drawCircle(120, 40, 40, 0x001F) 绘制的蓝色圆形轮廓。
3：通过 lcd.drawPoint(120, 40, 0x001F) 绘制的蓝色点，位于圆形中心。
4：由 lcd.drawLine(170, 40, 280, 40, 0x001F) 绘制的蓝色水平直线。
5：通过 lcd.drawRectangle(170, 50, 280, 80, 0x001F) 绘制的蓝色矩形框。
6：由多个 lcd.drawXbm 函数绘制的“上”“海”“合”“宙”四个汉字的位图组合而成。
7：使用 lcd.font_open_iconic_weather_6x_t 字体，lcd.drawStr(1, 155, "A")，显示多云图标。
8：使用 lcd.font_open_iconic_weather_6x_t 字体，lcd.drawStr(60, 155, "B")，显示月亮图标。
9：使用 lcd.font_open_iconic_weather_6x_t 字体，lcd.drawStr(120, 155, "C")，显示雨云图标。
10：使用 lcd.font_open_iconic_weather_6x_t 字体，lcd.drawStr(180, 155, "D")，显示星星图标。
11：使用 lcd.font_open_iconic_weather_6x_t 字体， lcd.drawStr(240, 155, "E")，显示太阳图标。 
12：使用 lcd.setFont(lcd.font_opposansm12) 字体，搭配 lcd.drawStr 函数，以该字体显示“hello hezhou”。
13：使用 lcd.setFont(lcd.font_opposansm16) 字体，搭配 lcd.drawStr 函数，以该字体显示“hello hezhou”。
14：使用 lcd.setFont(lcd.font_opposansm18) 字体，搭配 lcd.drawStr 函数，以该字体显示“hello hezhou”。
15：使用 lcd.setFont(lcd.font_opposansm20) 字体，搭配 lcd.drawStr 函数，以该字体显示“hello hezhou”。
16：使用 lcd.setFont(lcd.font_opposansm22) 字体，搭配 lcd.drawStr 函数，以该字体显示“hello hezhou”。
17：使用 lcd.setFont(lcd.font_opposansm24) 字体，搭配 lcd.drawStr 函数，以该字体显示“hello hezhou”。
18：使用 lcd.setFont(lcd.font_opposansm32) 字体，搭配 lcd.drawStr 函数，以该字体显示“hello hezhou”。
19：使用lcd.font_opposansm12_chinese字体，由 lcd.drawStr(160, 168, "扫码进入Air8000资料站",0x0000) 显示。
20：通过 lcd.drawQrcode(200, 170, "https://docs.openluat.com/air8000/", 100) 绘制，内容为指定URL的二维码。
21：由 lcd.fill(10, 380, 150, 460, 0xF800) 绘制红色区域背景。
22：由 lcd.fill(170, 380, 310, 460, 0x07E0) 绘制绿色区域背景。
23：由 lcd.drawStr(70, 420, "重拍", 0xFFFF) 绘制红色区域上的“重拍”文字。
24：由 lcd.drawStr(230, 420, "返回", 0xFFFF) 绘制绿色区域上的“返回”文字。

三、常量详解

核心库常量，顾名思义是由合宙 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用，包含以下常量；

常量类型	常量	类型	解释	在哪使用
字体常量	lcd.font_unifont_t_symbols	font	符号字体，字体纤细，大小12号，等宽，包含：英文，数字，英文符号	1、设置接下来使用的字体，如12号中文字体lcd.setFont(lcd.font_opposansm12_chinese)2、使设置颜色：默认上一次设置：lcd.setColor(0xFFFF, 0x0000)，白底黑字3、使用：lcd.drawStr(70, 420, "重拍", 0xFFFF)--不带颜色参数按设置颜色显示，带颜色按颜色参数显示
	lcd.font_open_iconic_weather_6x_t	font	天气字体，天气图标，尺寸48*48，“A”-“E”
	lcd.font_opposansm12	font	12号字体，包含：英文，数字，英文符号
	lcd.font_opposansm16	font	16号字体，包含：英文，数字，英文符号
	lcd.font_opposansm18	font	18号字体，包含：英文，数字，英文符号
	lcd.font_opposansm20	font	20号字体，包含：英文，数字，英文符号
	lcd.font_opposansm22	font	22号字体，包含：英文，数字，英文符号
	lcd.font_opposansm24	font	24号字体，包含：英文，数字，英文符号
	lcd.font_opposansm32	font	32号字体，包含：英文，数字，英文符号，注意：没有26-30字体
	lcd.font_opposansm12_chinese	font	12号中文字体，使用前先设置字体，lcd.setFont(lcd.font_opposansm12_chinese)
	lcd.font_opposansm14_chinese	font	14号中文字体，12号以上中文字体目前未默认内置，使用前可以查询型号对应固件功能支持说明
	lcd.font_opposansm16_chinese	font	16号中文字体，12号以上中文字体目前未默认内置，使用前可以查询型号对应固件功能支持说明
	lcd.font_opposansm18_chinese	font	18号中文字体，12号以上中文字体目前未默认内置，使用前可以查询型号对应固件功能支持说明
	lcd.font_opposansm20_chinese	font	20号中文字体，12号以上中文字体目前未默认内置，使用前可以查询型号对应固件功能支持说明
	lcd.font_opposansm22_chinese	font	22号中文字体，12号以上中文字体目前未默认内置，使用前可以查询型号对应固件功能支持说明
	lcd.font_opposansm24_chinese	font	24号中文字体，12号以上中文字体目前未默认内置，使用前可以查询型号对应固件功能支持说明
	lcd.font_opposansm32_chinese	font	32号中文字体，12号以上中文字体目前未默认内置，使用前可以查询型号对应固件功能支持说明
初始化命令常量	lcd.direction_0	int	0°方向常量，direction = 0和direction = lcd.direction_0相等	lcd.init()初始化屏幕，第二个参数table内使用
	lcd.direction_90	int	90°方向常量，direction = 1和direction = lcd.direction_90相等
	lcd.direction_180	int	180°方向常量，direction = 2和direction = lcd.direction_180相等
	lcd.direction_270	int	270°方向常量，direction = 3和direction = lcd.direction_270相等
	lcd.HWID_0	硬件lcd驱动id0	LCD专用接口，Air780EPM/EHM/EHV/EGH/Air8000系列支持，可查看引脚复用表
	lcd.RGB	硬件RGB	Air6101/8101支持
	lcd.QSPI_MODE	QSPI接口	Air8000系列，Air780EHM/EGH/EHV支持
使用设置常量	lcd.ACC_HW_JPEG	硬件加速	硬件加速功能，JPG/JPEG格式图片硬解码，Air8000系列，Air780EHM/EGH/EHV支持	lcd.init()初始化屏幕后使用
	lcd.ACC_HW_ALL	硬件加速	全部硬件加速功能，目前仅JPG/JPEG格式图片硬解码功能

四、函数详解

4.1 lcd.init(driver_ic, param, spi_dev, init_in_service)

功能

lcd 显示屏初始化：

参数

driver_ic

参数含义：lcd显示IC类型；
数据类型：string；
取值范围：
目前LCD类型支持："st7796"、"st7789"、"st7735"、"st7735v"、"st7735s"、"gc9a01"、
                "gc9106l"、"gc9306x"、"ili9486"、"custom"（自定义型号）；
                1、内置型号LCD库底层已经将显示IC参数适配好，只需要传入型号，长宽、方向
                   等基本信息即可完成初始化，确保正确显示，后续会扩展更多支持的型号；
                2、当driver_ic = "custom"时
                    1）param中的参数，需要根据显示芯片手册要求填写更多参数；
                    2）屏幕调试命令可以选择放在param参数中的initcmd{}内执行，
                       也可以单独使用lcd.cmd执行，多个命令用zbuff传入，具体可看lcd.cmd接口说明；
                    3）执行完lcd.init()后，还需要使用lcd.user_done()来表示自定义初始化完成；
是否必选：必须传入此参数；
注意事项：根据实际使用的LCD屏幕驱动IC填写对应的参数；
参数示例："st7789"

param

参数含义：LCD屏幕初始化配置参数表；
数据类型：table；
取值范围：table中包含多个配置字段，各字段说明如下：
注意事项：table内可选参数如果不需要就整个都不需要填，如果有下标就必须赋值，只写下标例如param ={pin_pwr = ，pin_rst = }会报语法错误，正确的形式是param ={pin_pwr =1 ，pin_rst = 2}

{ 
    参数含义：LCD背光引脚GPIO端口号，设置可通过该引脚控制屏幕背光；
    数据类型：number；
    取值范围：有效的GPIO端口号；
    是否必选：可选传入此参数；如果没有传入，根据自己的硬件设计需要自行控制背光；
    注意事项：暂无；
    参数示例：7
    pin_pwr = ,

    参数含义：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.HWID_0
    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需要赋值；
    参数示例：31
    pin_dc = ,


    参数含义：LCD复位引脚GPIO号；
    数据类型：number；
    取值范围：有效的GPIO端口号；
    是否必选：可选传入此参数；
    注意事项：1、当参数port = lcd.RGB时，pin_rst参数保持为空；
             2、当参数port = 其他类型时，pin_rst参数根据实际情况填写；
    参数示例：10
    pin_rst = ,

    参数含义：LCD屏幕方向；
    数据类型：number；
    取值范围：lcd.direction_0表示显示方向为0°；
             lcd.direction_90表示显示方向为90°；
             lcd.direction_180表示显示方向为180°；
             lcd.direction_270表示显示方向为270°；
    是否必选：可选传入此参数；不传入此参数，默认是0度方向；
    注意事项：设置屏幕的显示方向；
    参数示例：lcd.direction_0
    direction = ,

    参数含义：LCD水平分辨率；
    数据类型：number；
    取值范围：正整数；
    是否必选：必须传入此参数；
    注意事项：设置屏幕的宽度像素值；
    参数示例：240
    w = ,

    参数含义：LCD竖直分辨率；
    数据类型：number；
    取值范围：正整数；
    是否必选：必须传入此参数；
    注意事项：设置屏幕的高度像素值；
    参数示例：320
    h = ,

    参数含义：X偏移；
    数据类型：number；
    取值范围：整数；
    是否必选：可选传入此参数，省略此参数则偏移量默认为0；
    注意事项：不同屏幕IC和不同屏幕方向会有差异；
    参数示例：0
    xoffset = ,

    参数含义：Y偏移；
    数据类型：number；
    取值范围：整数；
    是否必选：可选传入此参数，省略此参数则偏移量默认为0；
    注意事项：不同屏幕IC和不同屏幕方向会有差异；
    参数示例：0
    yoffset = ,

    参数含义：睡眠命令；
    数据类型：number；
    取值范围：十六进制命令值；
    是否必选：可选传入此参数，默认0x10；
    注意事项：使用lcd.sleep()时发送配置的命令；
    参数示例：0x10
    sleepcmd = ,

    参数含义：唤醒命令；
    数据类型：number；
    取值范围：十六进制命令值；
    是否必选：可选传入此参数，默认0x11；
    注意事项：使用lcd.wakeup()时发送配置的命令；
    参数示例：0x11
    wakecmd = ,

    参数含义：0°方向的命令；
    数据类型：number；
    取值范围：十六进制命令值；
    是否必选：可选传入此参数，省略此参数时默认为0x00；
    注意事项：不同屏幕IC会有差异；
    参数示例：0x00
    direction0 = ,

    参数含义：90°方向的命令；
    数据类型：number；
    取值范围：十六进制命令值；
    是否必选：可选传入此参数，省略此参数时默认为0x60；
    注意事项：不同屏幕IC会有差异；
    参数示例：0x01
    direction90 = ,

    参数含义：180°方向的命令；
    数据类型：number；
    取值范围：十六进制命令值；
    是否必选：可选传入此参数，省略此参数时默认为0xC0；
    注意事项：不同屏幕IC会有差异；
    参数示例：0x02
    direction180 = ,

    参数含义：270°方向的命令；
    数据类型：number；
    取值范围：十六进制命令值；
    是否必选：可选传入此参数，省略此参数时默认为0xA0；
    注意事项：不同屏幕IC会有差异；
    参数示例：0x03
    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参数保持为空；
    参数示例：lcd.QSPI_MODE
    interface_mode = ,

    参数含义：QSPI/RGB总线速率，单位为Hz；
    数据类型：number；
    取值范围：正整数；
    是否必选：可选传入此参数；
    注意事项：目前LCD核心库设置速率上限是80MHz，目前LCD库支持的型号
             显示IC型号:jd9261t, QSPI接口，bus_speed = 70000000
             显示IC型号:co5300,  QSPI接口，bus_speed = 60000000
             显示IC型号:st7265,  RGB接口， bus_speed = 30000000             
             其他QSPI/RGB接口显示IC，根据芯片手册要求填此参数
    参数示例：

    bus_speed = ,

    参数含义：水平后廊，用于生成水平扫描时序，控制有效数据传输前的延迟周期；
    数据类型：number；
    取值范围：正整数；
    是否必选：可选传入此参数；
    注意事项：此参数为校准调试参数，lcd.init()中driver_ic支持的型号不需要填写，
             其他非driver_ic支持的型号，如果出现不显示或显示不正确的情况，
             首先优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；
    参数示例：10
    hbp = ,

    参数含义：水平同步脉冲宽度，初始化时参与水平同步信号的时序计算，决定水平同步脉冲的持续周期；
    数据类型：number；
    取值范围：正整数；
    是否必选：可选传入此参数，无默认值；
    注意事项：此参数为校准调试参数，lcd.init()中driver_ic支持的型号不需要填写，
             其他非driver_ic支持的型号，如果出现不显示或显示不正确的情况，
             首先优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；
    参数示例：5
    hspw = ,

    参数含义：水平前廊，用于水平扫描时序配置，控制有效数据传输后的延迟周期；
    数据类型：number；
    取值范围：正整数；
    是否必选：可选传入此参数，无默认值；
    注意事项：此参数为校准调试参数，lcd.init()中driver_ic支持的型号不需要填写，
             其他非driver_ic支持的型号，如果出现不显示或显示不正确的情况，
             首先优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；
    参数示例：10
    hfp = ,

    参数含义：垂直后廊，在垂直扫描时序配置中生效，控制帧数据传输前的垂直延迟周期；
    数据类型：number；
    取值范围：正整数；
    是否必选：可选传入此参数，无默认值；
    注意事项：此参数为校准调试参数，lcd.init()中driver_ic支持的型号不需要填写，
             其他非driver_ic支持的型号，如果出现不显示或显示不正确的情况，
             首先优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；
    参数示例：10
    vbp = ,

    参数含义：垂直同步脉冲宽度，初始化时参与垂直同步信号的时序计算，决定垂直同步脉冲的持续周期；
    数据类型：number；
    取值范围：正整数；
    是否必选：可选传入此参数，无默认值；
    注意事项：此参数为校准调试参数，lcd.init()中driver_ic支持的型号不需要填写，
             其他非driver_ic支持的型号，如果出现不显示或显示不正确的情况，
             首先优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；
    参数示例：5
    vspw = ,

    参数含义：垂直前廊，用于垂直扫描时序配置，控制帧数据传输后的垂直延迟周期；
    数据类型：number；
    取值范围：正整数；
    是否必选：可选传入此参数，无默认值；
    注意事项：此参数为校准调试参数，lcd.init()中driver_ic支持的型号不需要填写，
             其他非driver_ic支持的型号，如果出现不显示或显示不正确的情况，
             首先优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；
    参数示例：10
    vfp = ,

    参数含义：垂直同步，用于控制垂直同步信号的使能或参数，具体作用依赖屏幕驱动 IC 的时序要求；
    数据类型：number；
    取值范围：正整数；
    是否必选：可选传入此参数，无默认值；
    注意事项：此参数为校准调试参数，lcd.init()中driver_ic支持的型号不需要填写，
             其他非driver_ic支持的型号，如果出现不显示或显示不正确的情况，
             首先优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；
    参数示例：1
    vs = ,


    参数含义：刷新率，用于控制屏幕扫描时的帧刷新频率，驱动会根据该值调整数据传输的周期；
    数据类型：number；
    取值范围：正整数，单位0.1Hz；
    是否必选：可选传入此参数，无默认值；
    注意事项：屏幕选型时建议询问厂家对应的型号是否带RAM，若不带则根据芯片手册建议进行设置；
    参数示例：600
    flush_rate = ,

    参数含义：调换x方向（默认为水平方向）和y方向判定（默认为竖直方向）；
    数据类型：boolean；
    取值范围：true或false；
    是否必选：可选传入此参数，不填则默认值为false，一般不需要使用；
    注意事项：false（默认）：x 为水平方向，y 为竖直方向；
             true：交换 x 和 y 的方向判定，适用于特殊屏幕布局需求
    参数示例：false
    rb_swap = ，

    参数含义：自定义屏幕初始化命令表，在lcd.init()内部执行初始化后，
             会自动调用lcd.cmd按顺序执行initcmd表内的命令；
    数据类型：table；
    取值范围：包含初始化命令序列的table；
    是否必选：可选传入此参数；
    注意事项：用于自定义屏幕初始化流程，driver_ic为"custom"时才使用，命令格式如下；
             1、0x01xxxx: 表示延时，xxxx为延时ms时间
             2、0x02xxxx: 表示命令，xxxx为命令码
             3、0x03xxxx: 表示参数，xxxx为参数值
    参数示例：{0x0200FE, 0x030000},等价于执行lcd.cmd(0xfe, 0x00)
    initcmd = ,
}

spi_dev

参数含义：SPI设备对象；
数据类型：userdata；
取值范围：SPI设备对象；
是否必选：可选传入此参数；
注意事项：当param.port = "device"时有效，当port ≠ "device"时可省略该参数或者填nil；
参数示例：spi.deviceSetup(0, 1)返回的设备对象；

init_in_service

参数含义：是否允许在后台初始化LCD，速度比不使用后台初始化稍快。            
 数据类型：boolean；
 取值范围：true或false或nil；
 是否必选：可选传入此参数，默认值为false；
 注意事项：目前仅Air8000主控soc系列、Air780EHM/EGH/EHV等主控soc支持该功能，
          支持的型号推荐使用，不支持的型号省略此参数；
 参数示例：nil

返回值

local lcdinit_result = lcd.init(driver_ic, param, spi_dev, init_in_service)

lcdinit_result

参数含义：初始化是否成功；
 数据类型：boolean；
 取值范围：true：初始化成功，false：初始化失败
 注意事项：虽然这个函数返回了true，不代表一定会显示，只代表底层执行完了初始化

示例 1 driver_ic = "st7796"，初始化

-- 使用LCD专用接口初始化示例，目前Air780EHM/EHV/EGH/Air8000等支持lcd专用接口的型号支持

-- 按配置执行lcd初始化
local lcdinit_result = lcd.init(
    "st7796",
    {
        port = lcd.HWID_0,
        pin_pwr = 7,
        pin_rst = 19,
        direction = lcd.direction_0,
        w = 320,
        h = 480,
        xoffset = 0,
        yoffset = 0
    }
)

-- 打印lcd初始化执行结果
log.info("lcdinit_result",lcdinit_result）

示例 2 param.port = "device" ,spi_dev =spi 对象的方式初始化

-- 初始化spi0的st7735s 注意:lcd初始化之前需要先初始化spi接口
spi_lcd = spi.deviceSetup(0,20,0,0,8,2000000,spi.MSB,1,1)

-- 按配置执行lcd初始化
local lcdinit_result = lcd.init(
        "st7735s",
        {
            port = "device",
            pin_pwr = 7,
            pin_rst = 19,
            direction = lcd.direction_90,
            w = 160,
            h = 80,
            xoffset = 1,
            yoffset = 26
        },
        spi_lcd
    )

-- 打印lcd初始化执行结果
log.info("lcdinit_result",lcdinit_result）

示例 3：rgb 屏幕初始化

-- rgb屏幕初始化
-- 按配置执行lcd初始化
local lcdinit_result = lcd.init("h050iwv",{port = lcd.RGB, w = 800,h = 480})

-- 打印lcd初始化执行结果
log.info("lcdinit_result",lcdinit_result）

示例 4：co5300 QSPI 接口使用 custom 方式进行初始化，芯片配置命令使用 lcd.cmd 的方式

-- 1. 初始化参数定义：存储LCD核心配置信息
local lcd_param = {
    port = lcd.HWID_0,      -- LCD专用接口
    pin_rst = 36,           -- LCD复位引脚
    direction = lcd.direction_0,     -- 屏幕显示方向：0=默认方向
    w = 480,                -- 屏幕宽度
    h = 480,                -- 屏幕高度
    xoffset = 0,            -- X轴偏移：0=显示起始点从屏幕左边缘开始
    yoffset = 0,            -- Y轴偏移：0=显示起始点从屏幕上边缘开始
    sleepcmd = 0x10,        -- 睡眠模式命令
    wakecmd = 0x11,         -- 唤醒命令
    interface_mode = lcd.QSPI_MODE, -- 接口模式：选择QSPI
    bus_speed = 60000000,  -- QSPI总线速率：60MHz
    rb_swap = true          -- 数据字节交换使能：适配硬件数据传输顺序，避免颜色错位
}

-- 2. QSPI接口模式配置：定义QSPI数据传输规则
-- 第1个参数0x02：标准SPI写指令，用于向芯片写命令/参数
-- 第2个参数0x32：4线像素写入24时钟地址，长地址模式
-- 第3个参数0x12：4线像素写入6时钟地址，短地址模式
-- 作用：告诉CO5300“后续用QSPI 4线模式传输数据，支持长/短地址两种像素写入方式”
-- 相当于给芯片“定规矩”——后续数据怎么传、地址用多少时钟，避免传错
lcd.qspi(0x02, 0x32, 0x12)

-- 3. LCD硬件初始化与复位：让芯片进入初始状态
-- 调用LCD驱动初始化函数，加载上面定义的lcd_param配置（接口、分辨率等）
local lcdinit_result = lcd.init("custom", lcd_param)  

-- 4. co5300命令页切换：选择要使用的命令集
-- 命令码0xFE：命令页切换命令
-- 参数0x00：切换到“命令页0
-- 作用：CO5300有多个命令页（如基础命令页、Gamma命令页），这里选默认页，后续才能用基础命令（如0x3A像素格式）
-- 相当于打开“命令手册的基础章节”，后续操作都在这个章节里找命令
lcd.cmd(0xfe, 0x00)

-- 5. 设置SPI模式：配置SPI接口细节
-- 命令码0xC4：设置SPI模式命令
-- 参数0x80：具体配置（bit7=1，通常表示“启用SPI写RAM功能”，手册7.5.57节参数说明）
-- 作用：开启SPI接口向显示内存（RAM）写数据的功能，后续才能传图像数据到屏幕
-- 相当于给SPI接口“开权限”——允许往屏幕的“显存”里写数据
lcd.cmd(0xc4, 0x80)

-- 6. 设置接口像素格式：定义颜色数据的格式
-- 命令码0x3A：接口像素格式命令
-- 参数0x55：配置为“RGB565格式”（16位/像素，R=5位、G=6位、B=5位，手册7.5.32节参数表）
-- 作用：告诉芯片“后续传的颜色数据是RGB565格式”，避免芯片解析错误（比如传RGB565却按RGB888解析，颜色会乱）
-- 相当于约定“颜色数据的编码规则”——比如“每16位代表一个像素，前5位是红、中间6位是绿、后5位是蓝”
lcd.cmd(0x3a, 0x55)

-- 7. 开启撕裂效应：避免画面闪烁
-- 命令码0x35：撕裂效应开启命令
-- 参数0x00：模式1（仅输出V-sync和V-Blanking信号，手册5.3.1节）
-- 作用：TE引脚会输出同步信号，MCU可根据这个信号判断“什么时候写显存不会导致画面撕裂”（比如避开屏幕刷新时写数据）
-- 相当于给MCU发“通知”——“现在可以写数据，不会让画面闪”
lcd.cmd(0x35, 0x00)

-- 8. 写显示控制：配置显示器基础控制参数
-- 命令码0x53：写CTRL显示命令
-- 参数0x20：具体控制配置（bit5=1，通常表示“启用亮度控制”或“默认显示控制模式”，手册7.5.40节参数说明）
-- 作用：配置显示器的核心控制逻辑，比如亮度调节使能、显示驱动时序等
-- 相当于设置屏幕的“基础工作规则”，比如是否允许调亮度、驱动屏幕的时序参数
lcd.cmd(0x53, 0x20)

-- 9. 设置显示亮度：调节屏幕正常亮度
-- 命令码0x51：写显示亮度命令
-- 参数0x7a：亮度值（0x00=最暗，0xFF=最亮，0x7A=122/255≈48%亮度，适合日常使用）
-- 作用：设置OLED屏幕的正常显示亮度，避免过亮耗电或过暗看不清
-- 相当于调节屏幕的“背光亮度”，这里设为中等亮度
lcd.cmd(0x51, 0x7a)

-- 10. 设置高亮度模式（HBM）亮度：应对强光场景
-- 命令码0x63：写HBM显示亮度命令
-- 参数0xaa：高亮度模式下的亮度值（0xAA=170/255≈67%亮度，比正常模式亮，适合户外强光场景）
-- 作用：配置“高亮度模式”的亮度（HBM模式需单独开启，这里先设亮度值）
-- 相当于设置屏幕的“强光模式亮度”，后续开启HBM时就用这个亮度
lcd.cmd(0x63, 0xaa)

-- 11. 设置内存数据访问控制：定义屏幕显示方向
-- 命令码0x36：内存数据访问控制命令
-- 参数0x00：默认方向配置（MY=0、MX=0、RGB=0，即“行从上到下、列从左到右、RGB颜色顺序”，手册7.5.29节参数表）
-- 作用：控制显存数据的扫描方向，比如是否旋转、镜像，这里设为默认方向，避免画面颠倒
-- 相当于设置屏幕的“显示方向”——比如“数据从左上角开始显示，不旋转”
lcd.cmd(0x36, 0x00)

-- 13. 退出睡眠模式：唤醒屏幕
-- 作用：芯片上电后默认在睡眠模式（低功耗，不显示），发送此命令唤醒芯片，开启内部振荡器、Gamma电路等
-- 注意：必须唤醒后，后续“开启显示”命令才有效
-- 相当于按屏幕的“电源键”，从休眠中唤醒，准备显示
lcd.cmd(0x11)  -- 唤醒显示芯片

-- 14. 开启显示：完成初始化，屏幕开始显示
-- 作用：最后一步，开启显示驱动电路，将显存中的数据输出到屏幕（之前都是配置，这步才真正“亮屏”）
-- 注意：必须在“退出睡眠模式”后发送，否则无效
-- 相当于按屏幕的“显示开关”，之前的配置都做好了，这步让屏幕亮起来
lcd.cmd(0x29)  -- 命令码0x29：显示开启命令

-- 15. 打印lcd初始化执行结果
log.info("lcdinit_result",lcdinit_result）

-- 16. 公用显示设置：初始化显示缓存与刷新
lcd.setupBuff(nil, false)  -- 设置帧缓冲区，使用vm内存
lcd.autoFlush(false)       -- 禁止自动刷新
lcd.user_done()            -- 通知驱动“用户初始化完成”，后续可正常调用显示接口
lcd.clear()                -- 清除屏幕缓存数据
lcd.flush()                -- 手动刷新缓存数据到屏幕

示例 5：co5300 QSPI 接口使用 custom 方式进行初始化，芯片配置命令使用 initcmd 的方式

-- 1. 初始化参数定义：存储LCD核心配置信息
local lcd_param = {
    port = lcd.HWID_0,      -- QSPI硬件接口，使用专用LCD接口
    pin_rst = 36,           -- LCD复位引脚  
    direction = lcd.direction_0,     -- 屏幕显示方向：0=默认方向
    w = 480,                -- 屏幕宽度
    h = 480,               -- 屏幕高度
    xoffset = 0,            -- X轴偏移
    yoffset = 0,            -- Y轴偏移
    sleepcmd = 0x10,        -- 睡眠模式命令
    wakecmd = 0x11,         -- 唤醒命令
    interface_mode = lcd.QSPI_MODE, -- 接口模式：选择QSPI
    bus_speed = 60000000,  -- QSPI总线速率：60MHz
    rb_swap = true,          -- 数据字节交换使能：适配硬件数据传输顺序，避免颜色错位
    initcmd  =
            {
                -- 命令格式说明：
                -- 0x01xxxx: 延时，xxxx为延时ms时间
                -- 0x02xxxx: 命令，xxxx为命令码
                -- 0x03xxxx: 数据，xxxx为参数值
                0x0200FE, 0x030000,    -- lcd.cmd(0xfe, 0x00)
                0x0200C4, 0x030080,    -- lcd.cmd(0xc4, 0x80)  
                0x02003A, 0x030055,    -- lcd.cmd(0x3a, 0x55)
                0x020035, 0x030000,    -- lcd.cmd(0x35, 0x00)
                0x020053, 0x030020,    -- lcd.cmd(0x53, 0x20)
                0x020051, 0x03007A,    -- lcd.cmd(0x51, 0x7a)
                0x020063, 0x0300AA,    -- lcd.cmd(0x63, 0xaa)
                0x020036, 0x030000,    -- lcd.cmd(0x36, 0x00)
                0x000011,              -- lcd.cmd(0x11)等于lcd.wakeup()
                0x000029               -- lcd.cmd(0x29)
            }
}


-- 2. QSPI接口模式配置：定义QSPI数据传输规则
lcd.qspi(0x02, 0x32, 0x12)

-- 3.按配置执行lcd初始化
local lcdinit_result = lcd.init("custom", lcd_param)  -- 调用LCD驱动初始化函数，加载上面定义的lcd_param配置（接口、分辨率等）

-- 打印lcd初始化执行结果
log.info("lcdinit_result",lcdinit_result）

lcd.setupBuff(nil, false)  -- 设置帧缓冲区，使用vm内存
lcd.autoFlush(false)       -- 禁止自动刷新
lcd.user_done()            -- 通知驱动“用户初始化完成”，后续可正常调用显示接口
lcd.clear()                -- 清除屏幕缓存数据
lcd.flush()                -- 手动刷新缓存数据到屏幕

示例 6：st7796s 使用 custom 的形式进行自定义初始化，芯片配置命令使用 initcmd 的方式

-- st7796s使用custom的形式进行自定义初始化

-- SPI设备初始化配置
spi.setup(
    lcd.HWID_0,  -- LCD端口号：使用LCD专用接口
    nil,         -- CS片选脚：设为nil表示1个接口接一个屏幕不需要片选
    0,           -- CPHA=0：时钟相位，数据在时钟的第一个边沿采样
    0,           -- CPOL=0：时钟极性，空闲时时钟为低电平
    8,           -- 8位数据宽度：每个SPI传输包含8个比特
    20000000,    -- 20MHz波特率：SPI通信速度，20MHz是常用速度
    spi.MSB,     -- 高位先传：数据传输顺序，Most Significant Bit first
    1,           -- 主机模式：设备作为SPI主机
    1            -- 全双工模式：同时发送和接收数据
)

-- 初始化参数配置
local lcd_param = {
    -- 必须参数
    port = lcd.HWID_0,           -- 使用硬件LCD专用接口
    w = 320,                     -- 水平分辨率
    h = 480,                     -- 垂直分辨率

    -- 引脚配置
    pin_pwr = 25,                -- 背光控制引脚：GPIO25控制屏幕背光
    pin_rst = 36,                -- 复位引脚：GPIO36用于硬件复位屏幕

    -- 显示方向
    direction = lcd.direction_0, -- 显示方向0°：正常方向显示

    -- 方向命令配置
    direction0 = 0x00,           -- 0°方向：
    direction90 = 0x60,          -- 90°方向：
    direction180 = 0xC0,         -- 180°方向：
    direction270 = 0xA0,         -- 270°方向：

    -- 偏移量
    xoffset = 0,                 -- X偏移：显示区域在X方向的偏移像素
    yoffset = 0,                 -- Y偏移：显示区域在Y方向的偏移像素

    -- 睡眠/唤醒命令
    sleepcmd = 0x10,             -- 睡眠命令：SLPIN命令，进入睡眠模式
    wakecmd = 0x11,              -- 唤醒命令：SLPOUT命令，退出睡眠模式

    -- 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个参数点，校正暗部色彩曲线
    }
}

-- 按配置执行lcd初始化
local lcdinit_result = lcd.init("custom", lcd_param)
lcd.user_done()        -- 通知驱动“用户初始化完成”，后续可正常调用显示接口

-- 打印lcd初始化执行结果
log.info("lcdinit_result",lcdinit_result）

-- 清除初始化屏幕残留
lcd.clear()

示例 7：st7796s 使用 custom 的形式进行自定义初始化，芯片配置命令使用 lcd.cmd 的方式

-- SPI设备初始化配置
spi.setup(
    lcd.HWID_0,  -- LCD端口号：使用LCD专用接口
    nil,         -- CS片选脚：设为nil表示1个接口接一个屏幕不需要片选
    0,           -- CPHA=0：时钟相位，数据在时钟的第一个边沿采样
    0,           -- CPOL=0：时钟极性，空闲时时钟为低电平
    8,           -- 8位数据宽度：每个SPI传输包含8个比特
    20000000,    -- 20MHz波特率：SPI通信速度，20MHz是常用速度
    spi.MSB,     -- 高位先传：数据传输顺序，Most Significant Bit first
    1,           -- 主机模式：设备作为SPI主机
    1            -- 全双工模式：同时发送和接收数据
)

-- 初始化参数配置
local lcd_param = {
    -- 必须参数
    port = lcd.HWID_0,           -- 使用硬件LCD接口0，与spi.deviceSetup一致
    w = 320,                     -- 水平分辨率：ST7796S标准分辨率为320像素
    h = 480,                     -- 垂直分辨率：ST7796S标准分辨率为480像素

    -- 引脚配置
    pin_pwr = 25,                -- 背光控制引脚：GPIO25控制屏幕背光
    pin_rst = 36,                -- 复位引脚：GPIO36用于硬件复位屏幕

    -- 显示方向
    direction = lcd.direction_0, -- 显示方向0°：正常方向显示

    -- 偏移量
    xoffset = 0,                 -- X偏移：显示区域在X方向的偏移像素
    yoffset = 0,                 -- Y偏移：显示区域在Y方向的偏移像素

    -- 睡眠/唤醒命令
    sleepcmd = 0x10,             -- 睡眠命令：SLPIN命令，进入睡眠模式
    wakecmd = 0x11,              -- 唤醒命令：SLPOUT命令，退出睡眠模式

    -- 接口模式
    interface_mode = lcd.WIRE_4_BIT_8_INTERFACE_I,  -- 4线SPI 8bit模式I
}

-- 按配置执行lcd初始化
local lcdinit_result = lcd.init("custom", lcd_param)

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

-- 创建一个100字节的zbuff空间，空间不支持扩容，提前设置好大小
local buff1 = zbuff.create(100)

-- 2. 帧率控制2 - 空闲模式
-- 设置空闲模式下的帧率参数
-- buff1内容: 0x0C, 0x0C, 0x00, 0x33, 0x33
buff1:write(0x0C, 0x0C, 0x00, 0x33, 0x33)
lcd.cmd(0xB2, buff1, 5)

-- 3. 门控制
-- 设置门控参数，控制扫描行数
-- 设置VCOM电压值，影响对比度
lcd.cmd(0xB7, 0x35)

-- 4. VCOM设置
lcd.cmd(0xBB, 0x32)

-- 5. 电源控制3
-- 设置电源控制参数3
lcd.cmd(0xC2, 0x01)

-- 6. 电源控制4
-- 设置VCOMH电压
lcd.cmd(0xC3, 0x15)

-- 7. 电源控制5
-- 设置VCOML电压
lcd.cmd(0xC4, 0x20)

-- 8. VCOM偏移控制
-- 设置VCOM偏移量
lcd.cmd(0xC6, 0x0F)

-- 9. 电源控制1
-- 设置主要的电源控制参数
-- buff1内容: 0xA4, 0xA1
buff1:write(0xA4, 0xA1)
lcd.cmd(0xD0, buff1, 2)

 -- 10. 正伽马校正
 -- 15个参数点，校正亮部色彩曲线
-- buff1内容: 0xD0, 0x08, 0x0E, 0x09, 0x09, 0x05, 0x31, 0x33, 0x48, 0x17, 0x14, 0x15, 0x31, 0x34
buff1:write(0xD0, 0x08, 0x0E, 0x09, 0x09, 0x05, 0x31, 0x33, 0x48, 0x17, 0x14, 0x15, 0x31, 0x34)
lcd.cmd(0xE0, buff1, 14)

-- 11. 负伽马校正
-- 15个参数点，校正暗部色彩曲线
-- buff1内容: 0xD0, 0x08, 0x0E, 0x09, 0x09, 0x15, 0x31, 0x33, 0x48, 0x17, 0x14, 0x15, 0x31, 0x34
buff1:write(0xD0, 0x08, 0x0E, 0x09, 0x09, 0x15, 0x31, 0x33, 0x48, 0x17, 0x14, 0x15, 0x31, 0x34)
lcd.cmd(0xE1, buff1, 14)

-- 执行自定义初始化
lcd.user_done()

-- 打印lcd初始化执行结果
log.info("lcdinit_result",lcdinit_result）

-- 清除初始化屏幕残留
lcd.clear()

---

4.2 lcd.cmd(cmd, param, param_len)

功能

发送 LCD 命令

说明

本接口参数 cmd 为具体命令，本接口参数 param 为命令携带的参数，例如：需要设置偏移量，cmd 是设置偏移的命令，param 为具体偏移量参数。

参数

cmd

参数含义：LCD命令值；
数据类型：number；
取值范围：有效的LCD命令值；
是否必选：必须传入此参数；
注意事项：根据LCD驱动IC的命令集选择对应的命令；
参数示例：0x21

param

参数含义：命令参数；
数据类型：number或zbuff或nil；
取值范围：命令参数数组；
是否必选：可选传入此参数；
注意事项：某些命令需要附带参数；
参数示例：-- 休眠唤醒
        lcd.cmd(0x11)
        -- 执行0x3A命令，将0x05参数配置进去
        lcd.cmd(0x3A, 0x05)
        -- 执行0xB2命令，将多个参数通过zbuff的方式传入
        -- 创建一个100字节的zbuff空间，空间不支持扩容，提前设置好大小
        local buff1 = zbuff.create(100)
        -- buff1内容: 0x0C, 0x0C, 0x00, 0x33, 0x33
        buff1:write(0x0C, 0x0C, 0x00, 0x33, 0x33)
        -- 执行0xB2命令，将buff1中的参数配置进去
        lcd.cmd(0xB2, buff1, 5)

param_len

参数含义：参数长度；
数据类型：number；
取值范围：正整数；
是否必选：可选传入此参数；
注意事项：当传入param参数为zbuff数据类型时，需要指定参数长度；
参数示例：2

返回值

无

示例

-- 休眠唤醒
lcd.cmd(0x11)

-- 执行0x3A命令，将0x05参数配置进去
lcd.cmd(0x3A, 0x05)

-- 执行0xB2命令，将多个参数通过zbuff的方式配置
-- 创建一个100字节的zbuff空间，空间不支持扩容，提前设置好大小
local buff1 = zbuff.create(100)
-- buff1内容: 0x0C, 0x0C, 0x00, 0x33, 0x33
buff1:write(0x0C, 0x0C, 0x00, 0x33, 0x33)
-- 执行0xB2命令，将buff1中的参数配置进去
lcd.cmd(0xB2, buff1, 5)

---

4.3 lcd.setupBuff(nil, onheap)

功能

该函数用于设置显示屏的显示缓冲区。缓冲区将按照屏幕初始化尺寸（宽度 × 高度）及 RGB565 色彩格式分配内存，每个像素占用 2 字节，其中红色（R）占 5 位、绿色（G）占 6 位、蓝色（B）占 5 位。

注意事项

启用缓冲区后，缓冲区会占用固定的内存空间（大小为：屏幕宽度 × 屏幕高度 × 2 字节），所有绘图操作结果所生成的数据将首先写入缓冲区，在执行刷新指令时，系统会一次性将缓冲区中的数据快速传输至屏幕。

若不设置缓冲区，模块需要一边处理图像数据一边等待数据发送，每次只要产生显示数据都需要寻找端口然后发送，相对于设置缓冲区实现同样的操作运行效率更低。

参数

nil

参数含义：配置指针；
数据类型：nil；
取值范围：该参数暂时没用，只能填nil；
是否必选：是；
注意事项：只能填nil；
参数示例：nil

onheap

参数含义：内存分配位置标志；
数据类型：boolean；
取值范围：true表示使用heap内存，false表示使用vm内存；
是否必选：可选传入此参数，默认使用vm内存；
注意事项：rtos.meminfo("sys") 查询的是heap内存,rtos.meminfo()查询的是vm内存,
         系统运行后可以根据剩余内存空间大小选择使用哪种内存；
参数示例：false

返回值

local setupBuff_result = lcd.setupBuff(nil, onheap)

setupBuff_result

参数含义：缓冲区设置是否成功；
数据类型：boolean；
取值范围：true表示成功，false表示失败；
注意事项：缓冲区设置失败可能是内存不足导致；
返回示例：true

示例

-- 初始化lcd的buff缓冲区
lcd.setupBuff(nil, false)  -- 设置帧缓冲区，使用vm内存
lcd.autoFlush(false)       -- 禁止自动刷新
lcd.clear()                -- 清除屏幕缓存数据
lcd.flush()                -- 手动刷新缓存数据到屏幕

---

4.4 lcd.autoFlush(enable)

功能

设置自动刷新功能，自动检测需配合 lcd.setupBuff 使用。

注意事项

自动刷新逻辑是 setupBuff 内有数据变化就会刷新数据到屏幕，如果没有设置屏幕缓存区，自动刷新就没有效果。

参数

enable

参数含义：是否启用自动刷新；
数据类型：boolean；
取值范围：true表示启用自动刷新，false表示禁用自动刷新；
是否必选：必须传入此参数；
注意事项：默认为true，禁用自动刷新后需要使用lcd.flush()手动刷新；
参数示例：false

返回值

无

示例

设置缓冲区，手动刷新缓冲区数据到屏幕

-- 设置缓冲区并禁用自动更新
lcd.setupBuff(nil, false)   -- 设置帧缓冲区，使用vm内存
lcd.autoFlush(false)        -- 关闭自动刷新

-- 禁止自动更新后，使用lcd.flush()主动刷新数据到屏幕
lcd.flush()                -- 图像一次性刷新到屏幕

设置缓冲区，自动刷新缓冲区数据到屏幕

-- 设置缓冲区并用自动更新
lcd.setupBuff(nil, false)  -- 设置帧缓冲区，使用vm内存
lcd.autoFlush(true)       -- 打开自动刷新,图像显示一个刷新一个

---

4.5 lcd.clear(color)

功能

按设置的颜色或背景色清屏；

参数

color

参数含义：清屏颜色；
数据类型：number；
取值范围：RGB565颜色值；
是否必选：可选传入此参数；
注意事项：如果不传入颜色参数，使用lcd.setColor的背景色清屏；
参数示例：0x0000
        -- 颜色转换说明
        假设我们需要填充一个以颜色分量为R:255,G:50,B:88的24位颜色
        先将24位颜色的颜色分量按RGB顺序转换为二进制，然后按R高5位，G高6位，B高5位提取
            R:11111111 --→ 按高位提取5位颜色分量， --→ R:11111
            G:00110010 --→ 按高位提取6位颜色分量， --→ G:001100
            B:01011000 --→ 按高位提取5位颜色分量， --→ B:01011
        将提取的数据按R占高5位，G占中6位，B占低5位组合，
        换算为16进制，得到了16位RGB565颜色值为0xF98B
            11111 001100 01011 --→ 0xF98B

        -- RGB565常用颜色
        WHITE       = 0xFFFF,  -- 白色，颜色分量 R = 248-255, G = 252-255, B = 248-255
        BLACK       = 0x0000,  -- 黑色，颜色分量 R = 0, G = 0, B = 0
        RED         = 0xF800,  -- 红色，颜色分量 R = 248-255, G = 0, B = 0
        GREEN       = 0x07E0,  -- 绿色，颜色分量 R = 0, G = 252-255, B = 0
        BLUE        = 0x001F,  -- 蓝色，颜色分量 R = 0, G = 0, B = 248-255
        YELLOW      = 0xFFE0,  -- 黄色，颜色分量 R = 248-255, G = 252-255, B = 0
        CYAN        = 0x07FF,  -- 青色，颜色分量 R = 0, G = 252-255, B = 248-255
        MAGENTA     = 0xF81F,  -- 洋红色，颜色分量 R = 248-255, G = 0, B = 248-255
        GRAY        = 0x8410,  -- 灰色，颜色分量 R = 128-135, G = 128-131, B = 128-135
        LIGHTGRAY   = 0xC618,  -- 浅灰色，颜色分量 R = 192-199, G = 192-195, B = 192-199
        DARKGRAY    = 0x4208,  -- 深灰色，颜色分量 R = 64-71, G = 64-67, B = 64-71
        ORANGE      = 0xFC00,  -- 橙色，颜色分量 R = 248-255, G = 128-131, B = 0
        PINK        = 0xFE19,  -- 粉色，颜色分量 R = 248-255, G = 192-195, B = 200-207
        BROWN       = 0x8200,  -- 棕色，颜色分量 R = 128-135, G = 64-67, B = 0
        PURPLE      = 0x8010,  -- 紫色，颜色分量 R = 128-135, G = 0, B = 128-135
        LIME        = 0x07E0,  -- 酸橙色，颜色分量 R = 0, G = 252-255, B = 0
        NAVY        = 0x0010,  -- 海军蓝，颜色分量 R = 0, G = 0, B = 128-135
        TEAL        = 0x0410,  -- 蓝绿色，颜色分量 R = 0, G = 128-131, B = 128-135
        MAROON      = 0x8000,  -- 栗色，颜色分量 R = 128-135, G = 0, B = 0
        OLIVE       = 0x8400,  -- 橄榄色，颜色分量 R = 128-135, G = 128-131, B = 0
        SILVER      = 0xC618,  -- 银色，颜色分量 R = 192-199, G = 192-195, B = 192-199
        GOLD        = 0xFEA0,  -- 金色，颜色分量 R = 248-255, G = 215-218, B = 0

返回值

无

示例

_-- LCD清屏_
lcd.clear(0x0000)

---

4.6 lcd.setColor(back,fore)

功能

LCD 颜色设置函数，用于设置 LCD 显示的前景色和背景色； 注意事项

若没有使用该接口，默认前景色为黑色，背景色为白色；

参数

back

参数含义：背景颜色值；不设置默认使用白色背景色和黑色前景色；
数据类型：number；
取值范围：RGB565格式的颜色值（0x0000-0xFFFF）；
是否必选：必须传入此参数；
注意事项：设置显示内容的背景颜色；
参数示例：0x0000（黑色）

fore

参数含义：前景颜色值；
数据类型：number；
取值范围：RGB565格式的颜色值（0x0000-0xFFFF）；
是否必选：必须传入此参数；
注意事项：设置显示内容的前景（文字、图形）颜色；
参数示例：0xFFFF（白色）
        -- 颜色转换说明
        假设我们需要填充一个以颜色分量为R:255,G:50,B:88的24位颜色
        先将24位颜色的颜色分量按RGB顺序转换为二进制，然后按R高5位，G高6位，B高5位提取
            R:11111111 --→ 按高位提取5位颜色分量， --→ R:11111
            G:00110010 --→ 按高位提取6位颜色分量， --→ G:001100
            B:01011000 --→ 按高位提取5位颜色分量， --→ B:01011
        将提取的数据按R占高5位，G占中6位，B占低5位组合，
        换算为16进制，得到了16位RGB565颜色值为0xF98B
            11111 001100 01011 --→ 0xF98B

        -- RGB565常用颜色
        WHITE       = 0xFFFF,  -- 白色，颜色分量 R = 248-255, G = 252-255, B = 248-255
        BLACK       = 0x0000,  -- 黑色，颜色分量 R = 0, G = 0, B = 0
        RED         = 0xF800,  -- 红色，颜色分量 R = 248-255, G = 0, B = 0
        GREEN       = 0x07E0,  -- 绿色，颜色分量 R = 0, G = 252-255, B = 0
        BLUE        = 0x001F,  -- 蓝色，颜色分量 R = 0, G = 0, B = 248-255
        YELLOW      = 0xFFE0,  -- 黄色，颜色分量 R = 248-255, G = 252-255, B = 0
        CYAN        = 0x07FF,  -- 青色，颜色分量 R = 0, G = 252-255, B = 248-255
        MAGENTA     = 0xF81F,  -- 洋红色，颜色分量 R = 248-255, G = 0, B = 248-255
        GRAY        = 0x8410,  -- 灰色，颜色分量 R = 128-135, G = 128-131, B = 128-135
        LIGHTGRAY   = 0xC618,  -- 浅灰色，颜色分量 R = 192-199, G = 192-195, B = 192-199
        DARKGRAY    = 0x4208,  -- 深灰色，颜色分量 R = 64-71, G = 64-67, B = 64-71
        ORANGE      = 0xFC00,  -- 橙色，颜色分量 R = 248-255, G = 128-131, B = 0
        PINK        = 0xFE19,  -- 粉色，颜色分量 R = 248-255, G = 192-195, B = 200-207
        BROWN       = 0x8200,  -- 棕色，颜色分量 R = 128-135, G = 64-67, B = 0
        PURPLE      = 0x8010,  -- 紫色，颜色分量 R = 128-135, G = 0, B = 128-135
        LIME        = 0x07E0,  -- 酸橙色，颜色分量 R = 0, G = 252-255, B = 0
        NAVY        = 0x0010,  -- 海军蓝，颜色分量 R = 0, G = 0, B = 128-135
        TEAL        = 0x0410,  -- 蓝绿色，颜色分量 R = 0, G = 128-131, B = 128-135
        MAROON      = 0x8000,  -- 栗色，颜色分量 R = 128-135, G = 0, B = 0
        OLIVE       = 0x8400,  -- 橄榄色，颜色分量 R = 128-135, G = 128-131, B = 0
        SILVER      = 0xC618,  -- 银色，颜色分量 R = 192-199, G = 192-195, B = 192-199
        GOLD        = 0xFEA0,  -- 金色，颜色分量 R = 248-255, G = 215-218, B = 0

返回值

无

示例

-- lcd颜色设置
lcd.setColor(0xFFFF, 0x0000)  -- 白底黑字，后续文字、位图会按此设置显示

-- 颜色转换说明
假设我们需要填充一个以颜色分量R:255,G:50,B:88的24位颜色
先将24位颜色的颜色分量按RGB顺序转换为二进制
    R:11111111 --→ 按高位提取颜色分量，R提取5位:11111
    G:00110010 --→ 按高位提取颜色分量，G提取6位:001100
    B:01011000 --→ 按高位提取颜色分量，B提取6位:01011
然后按R占高5为，G占中6位，B占低5为组合为16位的RGB565颜色，得到了所需填入的16位RGB565颜色值为0xF98B
    11111 001100 01011 --→ 0xF98B

---

4.7 lcd.flush()

功能

主动刷新数据到界面

注意事项

1、设置了缓冲区，启用了自动刷新，再执行此接口相当于再手动刷新一次，没有实际效果还会消耗系统运行资源；

2、设置了缓冲区，禁用了自动刷新，此时需要调用此接口手动刷新数据到界面；

3、未设置缓冲区，不管有没有启用自动刷新，只能使用此接口手动刷新数据到界面；

参数

无

返回值

local flush_result = lcd.flush()

flush_result

参数含义：刷新操作是否成功；
数据类型：boolean；
取值范围：true表示成功，false或nil表示失败；
注意事项：需要先调用lcd.setupBuff设置缓冲区，并调用lcd.autoFlush(false)禁用自动刷新；
返回示例：true

示例

-- 初始化lcd的buff缓冲区
lcd.setupBuff(nil, false)  -- 设置帧缓冲区，使用vm内存
lcd.autoFlush(false)       -- 禁止自动刷新
lcd.clear()                -- 清除屏幕缓存数据
lcd.flush()                -- 手动刷新缓存数据到屏幕

---

4.8 lcd.fill(x1, y1, x2, y2,color)

功能

将 color 颜色填充到一个以左上角为（x1,y1）右下角为（x2y2)的矩形区域；

参数

x1

参数含义：起始X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：矩形区域的左上角X坐标；
参数示例：20

y1

参数含义：起始Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：矩形区域的左上角Y坐标；
参数示例：30

x2

参数含义：结束X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：矩形区域的右下角X坐标；
参数示例：220

y2

参数含义：结束Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：矩形区域的右下角Y坐标；
参数示例：30

color

参数含义：填充颜色；
数据类型：number；
取值范围：RGB565颜色值；
是否必选：必须传入此参数；
注意事项：使用RGB565格式的颜色值；
参数示例：0x001F，        
        -- 颜色转换说明
        假设我们需要填充一个以颜色分量为R:255,G:50,B:88的24位颜色
        先将24位颜色的颜色分量按RGB顺序转换为二进制，然后按R高5位，G高6位，B高5位提取
            R:11111111 --→ 按高位提取5位颜色分量， --→ R:11111
            G:00110010 --→ 按高位提取6位颜色分量， --→ G:001100
            B:01011000 --→ 按高位提取5位颜色分量， --→ B:01011
        将提取的数据按R占高5位，G占中6位，B占低5位组合，
        换算为16进制，得到了16位RGB565颜色值为0xF98B
            11111 001100 01011 --→ 0xF98B

        -- RGB565常用颜色
        WHITE       = 0xFFFF,  -- 白色，颜色分量 R = 248-255, G = 252-255, B = 248-255
        BLACK       = 0x0000,  -- 黑色，颜色分量 R = 0, G = 0, B = 0
        RED         = 0xF800,  -- 红色，颜色分量 R = 248-255, G = 0, B = 0
        GREEN       = 0x07E0,  -- 绿色，颜色分量 R = 0, G = 252-255, B = 0
        BLUE        = 0x001F,  -- 蓝色，颜色分量 R = 0, G = 0, B = 248-255
        YELLOW      = 0xFFE0,  -- 黄色，颜色分量 R = 248-255, G = 252-255, B = 0
        CYAN        = 0x07FF,  -- 青色，颜色分量 R = 0, G = 252-255, B = 248-255
        MAGENTA     = 0xF81F,  -- 洋红色，颜色分量 R = 248-255, G = 0, B = 248-255
        GRAY        = 0x8410,  -- 灰色，颜色分量 R = 128-135, G = 128-131, B = 128-135
        LIGHTGRAY   = 0xC618,  -- 浅灰色，颜色分量 R = 192-199, G = 192-195, B = 192-199
        DARKGRAY    = 0x4208,  -- 深灰色，颜色分量 R = 64-71, G = 64-67, B = 64-71
        ORANGE      = 0xFC00,  -- 橙色，颜色分量 R = 248-255, G = 128-131, B = 0
        PINK        = 0xFE19,  -- 粉色，颜色分量 R = 248-255, G = 192-195, B = 200-207
        BROWN       = 0x8200,  -- 棕色，颜色分量 R = 128-135, G = 64-67, B = 0
        PURPLE      = 0x8010,  -- 紫色，颜色分量 R = 128-135, G = 0, B = 128-135
        LIME        = 0x07E0,  -- 酸橙色，颜色分量 R = 0, G = 252-255, B = 0
        NAVY        = 0x0010,  -- 海军蓝，颜色分量 R = 0, G = 0, B = 128-135
        TEAL        = 0x0410,  -- 蓝绿色，颜色分量 R = 0, G = 128-131, B = 128-135
        MAROON      = 0x8000,  -- 栗色，颜色分量 R = 128-135, G = 0, B = 0
        OLIVE       = 0x8400,  -- 橄榄色，颜色分量 R = 128-135, G = 128-131, B = 0
        SILVER      = 0xC618,  -- 银色，颜色分量 R = 192-199, G = 192-195, B = 192-199
        GOLD        = 0xFEA0,  -- 金色，颜色分量 R = 248-255, G = 215-218, B = 0

返回值

无

示例

-- 使用黑色填充左上角为（20，30）右下角为（220, 30）的矩形区域；
lcd.fill(20,30,220,30,0x0000)

-- 使用红充左上角为（20，30）右下角为（220, 30）的矩形区域;
lcd.fill(20,30,220,30,0xF800)

---

4.9 lcd.draw(x1, y1, x2, y2,buff)

功能

将 buff 缓冲区内容以（x1,y1）为左上角，按实际 buff 大小进行填充；

注意事项：

参数

x1

参数含义：起始X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：矩形区域的左上角X坐标；
参数示例：20

y1

参数含义：起始Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：矩形区域的左上角Y坐标；
参数示例：30

x2

参数含义：结束X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：可选传入此参数，填入nil时，x2坐标默认是x1加上buff内颜色宽度或图片的宽度；
注意事项：矩形区域的右下角X坐标；
参数示例：nil

y2

参数含义：结束Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数，填入nil时，y2坐标默认是y1加上buff内颜色高度或图片的高度；
注意事项：矩形区域的右下角Y坐标；
参数示例：nil

buff

参数含义：缓冲区内容；
数据类型：userdata（zbuff对象）；
取值范围：有效的zbuff缓冲区；
是否必选：必须传入此参数；
注意事项：需要使用zbuff.create创建的缓冲区；
参数示例：zbuff.create({100,100,16},0x001F)

返回值

无

示例

-- RGB565 16位颜色填充，显示填入颜色
local red1 = 0xF800   -- 红色
local buff1 = zbuff.create({100,100,16},red1)  --创建一个大小100*100，16位颜色，颜色0xF800的buff   
lcd.draw(20,30,nil,nil,buff1)     -- 将buff内容左上角显示在（20，30）坐标处

-- 使用RGB565 颜色填充并显示方式二
local red2 = lcd.rgb565(0xFF, 0x00, 0x00, true)  --红色
local buff2 = zbuff.create({100,100,16},red2)
lcd.draw(20,140,nil,nil,buff2)

-- 使用RGB565 颜色填充并显示方式三
local red3 = lcd.rgb565(0xFF0000, true)  -- 红色
local buff3 = zbuff.create({100,100,16},red3)
lcd.draw(20,30,nil,nil,buff3)

-- 使用jpg图片硬解码填充，可以提前将图片存入zbuff,调用时渲染速度会更快，但会占用图片高*宽*2大小的内存
-- 当前只支持jpg、jpeg格式；Air8000系列和Air780EHM/EGH/EHV支持
-- 硬解码图片尺寸必须是16的倍数
local lcd_zbuff = lcd.image2raw("/luadb/logo.jpg")
lcd.draw(10, 10, nil, nil, lcd_zbuff )

---

4.10 lcd.drawPoint(x,y,color)

功能

画一个可设置颜色的点；

参数

x

参数含义：点的X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：点的水平位置；
参数示例：20

y

参数含义：点的Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：点的垂直位置；
参数示例：30

color

参数含义：点的颜色；
数据类型：number；
取值范围：RGB565颜色值；
是否必选：可选参数；
注意事项：绘画颜色默认前景色，使用RGB565格式的颜色值；
参数示例：0x001F
        -- 颜色转换说明
        假设我们需要填充一个以颜色分量为R:255,G:50,B:88的24位颜色
        先将24位颜色的颜色分量按RGB顺序转换为二进制，然后按R高5位，G高6位，B高5位提取
            R:11111111 --→ 按高位提取5位颜色分量， --→ R:11111
            G:00110010 --→ 按高位提取6位颜色分量， --→ G:001100
            B:01011000 --→ 按高位提取5位颜色分量， --→ B:01011
        将提取的数据按R占高5位，G占中6位，B占低5位组合，
        换算为16进制，得到了16位RGB565颜色值为0xF98B
            11111 001100 01011 --→ 0xF98B

        -- RGB565常用颜色
        WHITE       = 0xFFFF,  -- 白色，颜色分量 R = 248-255, G = 252-255, B = 248-255
        BLACK       = 0x0000,  -- 黑色，颜色分量 R = 0, G = 0, B = 0
        RED         = 0xF800,  -- 红色，颜色分量 R = 248-255, G = 0, B = 0
        GREEN       = 0x07E0,  -- 绿色，颜色分量 R = 0, G = 252-255, B = 0
        BLUE        = 0x001F,  -- 蓝色，颜色分量 R = 0, G = 0, B = 248-255
        YELLOW      = 0xFFE0,  -- 黄色，颜色分量 R = 248-255, G = 252-255, B = 0
        CYAN        = 0x07FF,  -- 青色，颜色分量 R = 0, G = 252-255, B = 248-255
        MAGENTA     = 0xF81F,  -- 洋红色，颜色分量 R = 248-255, G = 0, B = 248-255
        GRAY        = 0x8410,  -- 灰色，颜色分量 R = 128-135, G = 128-131, B = 128-135
        LIGHTGRAY   = 0xC618,  -- 浅灰色，颜色分量 R = 192-199, G = 192-195, B = 192-199
        DARKGRAY    = 0x4208,  -- 深灰色，颜色分量 R = 64-71, G = 64-67, B = 64-71
        ORANGE      = 0xFC00,  -- 橙色，颜色分量 R = 248-255, G = 128-131, B = 0
        PINK        = 0xFE19,  -- 粉色，颜色分量 R = 248-255, G = 192-195, B = 200-207
        BROWN       = 0x8200,  -- 棕色，颜色分量 R = 128-135, G = 64-67, B = 0
        PURPLE      = 0x8010,  -- 紫色，颜色分量 R = 128-135, G = 0, B = 128-135
        LIME        = 0x07E0,  -- 酸橙色，颜色分量 R = 0, G = 252-255, B = 0
        NAVY        = 0x0010,  -- 海军蓝，颜色分量 R = 0, G = 0, B = 128-135
        TEAL        = 0x0410,  -- 蓝绿色，颜色分量 R = 0, G = 128-131, B = 128-135
        MAROON      = 0x8000,  -- 栗色，颜色分量 R = 128-135, G = 0, B = 0
        OLIVE       = 0x8400,  -- 橄榄色，颜色分量 R = 128-135, G = 128-131, B = 0
        SILVER      = 0xC618,  -- 银色，颜色分量 R = 192-199, G = 192-195, B = 192-199
        GOLD        = 0xFEA0,  -- 金色，颜色分量 R = 248-255, G = 215-218, B = 0

返回值

无

示例

-- 在（20,30）位置，画一个颜色为0x001F的点
lcd.drawPoint(20,30,0x001F)

---

4.11 lcd.drawLine(x1,y1,x2,y2,color)

功能

在两点之间画一条线，支持斜线；

参数

x1

参数含义：起点X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：线条起点的水平位置；
参数示例：20

y1

参数含义：起点Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：线条起点的垂直位置；
参数示例：30

x2

参数含义：终点X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：线条终点的水平位置；
参数示例：220

y2

参数含义：终点Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：线条终点的垂直位置；
参数示例：30

color

参数含义：线条颜色；
数据类型：number；
取值范围：RGB565颜色值；
是否必选：可选参数；
注意事项：绘画颜色默认前景色，使用RGB565格式的颜色值；
参数示例：0x001F
        -- 颜色转换说明
        假设我们需要填充一个以颜色分量为R:255,G:50,B:88的24位颜色
        先将24位颜色的颜色分量按RGB顺序转换为二进制，然后按R高5位，G高6位，B高5位提取
            R:11111111 --→ 按高位提取5位颜色分量， --→ R:11111
            G:00110010 --→ 按高位提取6位颜色分量， --→ G:001100
            B:01011000 --→ 按高位提取5位颜色分量， --→ B:01011
        将提取的数据按R占高5位，G占中6位，B占低5位组合，
        换算为16进制，得到了16位RGB565颜色值为0xF98B
            11111 001100 01011 --→ 0xF98B

        -- RGB565常用颜色
        WHITE       = 0xFFFF,  -- 白色，颜色分量 R = 248-255, G = 252-255, B = 248-255
        BLACK       = 0x0000,  -- 黑色，颜色分量 R = 0, G = 0, B = 0
        RED         = 0xF800,  -- 红色，颜色分量 R = 248-255, G = 0, B = 0
        GREEN       = 0x07E0,  -- 绿色，颜色分量 R = 0, G = 252-255, B = 0
        BLUE        = 0x001F,  -- 蓝色，颜色分量 R = 0, G = 0, B = 248-255
        YELLOW      = 0xFFE0,  -- 黄色，颜色分量 R = 248-255, G = 252-255, B = 0
        CYAN        = 0x07FF,  -- 青色，颜色分量 R = 0, G = 252-255, B = 248-255
        MAGENTA     = 0xF81F,  -- 洋红色，颜色分量 R = 248-255, G = 0, B = 248-255
        GRAY        = 0x8410,  -- 灰色，颜色分量 R = 128-135, G = 128-131, B = 128-135
        LIGHTGRAY   = 0xC618,  -- 浅灰色，颜色分量 R = 192-199, G = 192-195, B = 192-199
        DARKGRAY    = 0x4208,  -- 深灰色，颜色分量 R = 64-71, G = 64-67, B = 64-71
        ORANGE      = 0xFC00,  -- 橙色，颜色分量 R = 248-255, G = 128-131, B = 0
        PINK        = 0xFE19,  -- 粉色，颜色分量 R = 248-255, G = 192-195, B = 200-207
        BROWN       = 0x8200,  -- 棕色，颜色分量 R = 128-135, G = 64-67, B = 0
        PURPLE      = 0x8010,  -- 紫色，颜色分量 R = 128-135, G = 0, B = 128-135
        LIME        = 0x07E0,  -- 酸橙色，颜色分量 R = 0, G = 252-255, B = 0
        NAVY        = 0x0010,  -- 海军蓝，颜色分量 R = 0, G = 0, B = 128-135
        TEAL        = 0x0410,  -- 蓝绿色，颜色分量 R = 0, G = 128-131, B = 128-135
        MAROON      = 0x8000,  -- 栗色，颜色分量 R = 128-135, G = 0, B = 0
        OLIVE       = 0x8400,  -- 橄榄色，颜色分量 R = 128-135, G = 128-131, B = 0
        SILVER      = 0xC618,  -- 银色，颜色分量 R = 192-199, G = 192-195, B = 192-199
        GOLD        = 0xFEA0,  -- 金色，颜色分量 R = 248-255, G = 215-218, B = 0

返回值

无

示例

-- 画一条点（20,30）至点（220,50）,颜色为0xF98B的斜线
lcd.drawLine(20,30,220,50,0xF98B)

---

4.12 lcd.drawRectangle(x1,y1,x2,y2,color)

功能

从绘制一个左上角坐标为（x1,y1），右下角坐标为（x2,y2)，颜色为 color 参数的矩形框；

参数

x1

参数含义：矩形左上角X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：矩形左上角的水平位置；
参数示例：20

y1

参数含义：矩形左上角Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：矩形左上角的垂直位置；
参数示例：40

x2

参数含义：矩形右下角X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：矩形右下角的水平位置；
参数示例：220

y2

参数含义：矩形右下角Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：矩形右下角的垂直位置；
参数示例：80

color

参数含义：矩形边框颜色；
数据类型：number；
取值范围：RGB565颜色值；
是否必选：可选参数；
注意事项：绘画颜色默认前景色，使用RGB565格式的颜色值；
参数示例：0xF98B
        -- 颜色转换说明
        假设我们需要填充一个以颜色分量为R:255,G:50,B:88的24位颜色
        先将24位颜色的颜色分量按RGB顺序转换为二进制，然后按R高5位，G高6位，B高5位提取
            R:11111111 --→ 按高位提取5位颜色分量， --→ R:11111
            G:00110010 --→ 按高位提取6位颜色分量， --→ G:001100
            B:01011000 --→ 按高位提取5位颜色分量， --→ B:01011
        将提取的数据按R占高5位，G占中6位，B占低5位组合，
        换算为16进制，得到了16位RGB565颜色值为0xF98B
            11111 001100 01011 --→ 0xF98B

        -- RGB565常用颜色
        WHITE       = 0xFFFF,  -- 白色，颜色分量 R = 248-255, G = 252-255, B = 248-255
        BLACK       = 0x0000,  -- 黑色，颜色分量 R = 0, G = 0, B = 0
        RED         = 0xF800,  -- 红色，颜色分量 R = 248-255, G = 0, B = 0
        GREEN       = 0x07E0,  -- 绿色，颜色分量 R = 0, G = 252-255, B = 0
        BLUE        = 0x001F,  -- 蓝色，颜色分量 R = 0, G = 0, B = 248-255
        YELLOW      = 0xFFE0,  -- 黄色，颜色分量 R = 248-255, G = 252-255, B = 0
        CYAN        = 0x07FF,  -- 青色，颜色分量 R = 0, G = 252-255, B = 248-255
        MAGENTA     = 0xF81F,  -- 洋红色，颜色分量 R = 248-255, G = 0, B = 248-255
        GRAY        = 0x8410,  -- 灰色，颜色分量 R = 128-135, G = 128-131, B = 128-135
        LIGHTGRAY   = 0xC618,  -- 浅灰色，颜色分量 R = 192-199, G = 192-195, B = 192-199
        DARKGRAY    = 0x4208,  -- 深灰色，颜色分量 R = 64-71, G = 64-67, B = 64-71
        ORANGE      = 0xFC00,  -- 橙色，颜色分量 R = 248-255, G = 128-131, B = 0
        PINK        = 0xFE19,  -- 粉色，颜色分量 R = 248-255, G = 192-195, B = 200-207
        BROWN       = 0x8200,  -- 棕色，颜色分量 R = 128-135, G = 64-67, B = 0
        PURPLE      = 0x8010,  -- 紫色，颜色分量 R = 128-135, G = 0, B = 128-135
        LIME        = 0x07E0,  -- 酸橙色，颜色分量 R = 0, G = 252-255, B = 0
        NAVY        = 0x0010,  -- 海军蓝，颜色分量 R = 0, G = 0, B = 128-135
        TEAL        = 0x0410,  -- 蓝绿色，颜色分量 R = 0, G = 128-131, B = 128-135
        MAROON      = 0x8000,  -- 栗色，颜色分量 R = 128-135, G = 0, B = 0
        OLIVE       = 0x8400,  -- 橄榄色，颜色分量 R = 128-135, G = 128-131, B = 0
        SILVER      = 0xC618,  -- 银色，颜色分量 R = 192-199, G = 192-195, B = 192-199
        GOLD        = 0xFEA0,  -- 金色，颜色分量 R = 248-255, G = 215-218, B = 0

返回值

无

示例

-- 从绘制一个左上角坐标为（20,40），右下角坐标为（220,80)，颜色为0x001F参数的矩形框；
lcd.drawRectangle(20,40,220,80,0x001F)

---

4.13 lcd.drawCircle(x,y,r,color)

功能

以坐标（x,y)位置为圆心，绘制一个半径为 r 值，颜色为 color 参数的圆圈；

参数

x

参数含义：圆心X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：圆心的水平位置；
参数示例：120

y

参数含义：圆心Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：圆心的垂直位置；
参数示例：120

r

参数含义：圆的半径；
数据类型：number；
取值范围：正整数；
是否必选：必须传入此参数；
注意事项：圆的半径大小；
参数示例：20

color

参数含义：圆的颜色；
数据类型：number；
取值范围：RGB565颜色值；
是否必选：可选参数；
注意事项：绘画颜色默认前景色，使用RGB565格式的颜色值；
参数示例：0xF98B
        -- 颜色转换说明
        假设我们需要填充一个以颜色分量为R:255,G:50,B:88的24位颜色
        先将24位颜色的颜色分量按RGB顺序转换为二进制，然后按R高5位，G高6位，B高5位提取
            R:11111111 --→ 按高位提取5位颜色分量， --→ R:11111
            G:00110010 --→ 按高位提取6位颜色分量， --→ G:001100
            B:01011000 --→ 按高位提取5位颜色分量， --→ B:01011
        将提取的数据按R占高5位，G占中6位，B占低5位组合，
        换算为16进制，得到了16位RGB565颜色值为0xF98B
            11111 001100 01011 --→ 0xF98B

        -- RGB565常用颜色
        WHITE       = 0xFFFF,  -- 白色，颜色分量 R = 248-255, G = 252-255, B = 248-255
        BLACK       = 0x0000,  -- 黑色，颜色分量 R = 0, G = 0, B = 0
        RED         = 0xF800,  -- 红色，颜色分量 R = 248-255, G = 0, B = 0
        GREEN       = 0x07E0,  -- 绿色，颜色分量 R = 0, G = 252-255, B = 0
        BLUE        = 0x001F,  -- 蓝色，颜色分量 R = 0, G = 0, B = 248-255
        YELLOW      = 0xFFE0,  -- 黄色，颜色分量 R = 248-255, G = 252-255, B = 0
        CYAN        = 0x07FF,  -- 青色，颜色分量 R = 0, G = 252-255, B = 248-255
        MAGENTA     = 0xF81F,  -- 洋红色，颜色分量 R = 248-255, G = 0, B = 248-255
        GRAY        = 0x8410,  -- 灰色，颜色分量 R = 128-135, G = 128-131, B = 128-135
        LIGHTGRAY   = 0xC618,  -- 浅灰色，颜色分量 R = 192-199, G = 192-195, B = 192-199
        DARKGRAY    = 0x4208,  -- 深灰色，颜色分量 R = 64-71, G = 64-67, B = 64-71
        ORANGE      = 0xFC00,  -- 橙色，颜色分量 R = 248-255, G = 128-131, B = 0
        PINK        = 0xFE19,  -- 粉色，颜色分量 R = 248-255, G = 192-195, B = 200-207
        BROWN       = 0x8200,  -- 棕色，颜色分量 R = 128-135, G = 64-67, B = 0
        PURPLE      = 0x8010,  -- 紫色，颜色分量 R = 128-135, G = 0, B = 128-135
        LIME        = 0x07E0,  -- 酸橙色，颜色分量 R = 0, G = 252-255, B = 0
        NAVY        = 0x0010,  -- 海军蓝，颜色分量 R = 0, G = 0, B = 128-135
        TEAL        = 0x0410,  -- 蓝绿色，颜色分量 R = 0, G = 128-131, B = 128-135
        MAROON      = 0x8000,  -- 栗色，颜色分量 R = 128-135, G = 0, B = 0
        OLIVE       = 0x8400,  -- 橄榄色，颜色分量 R = 128-135, G = 128-131, B = 0
        SILVER      = 0xC618,  -- 银色，颜色分量 R = 192-199, G = 192-195, B = 192-199
        GOLD        = 0xFEA0,  -- 金色，颜色分量 R = 248-255, G = 215-218, B = 0

返回值

无

示例

-- 以坐标（120,120)位置为圆心，绘制一个半径为20值，颜色为0x001F的圆圈；
lcd.drawCircle(120,120,20,0x001F)

---

4.14 lcd.drawQrcode(x, y, str, size)

功能

以参数（x,y）坐标为左上角，绘制一个内容为参数 str，边长像素为传入参数 size 的正方形二维码；

参数

x

参数含义：二维码左上角X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：二维码显示的起始水平位置；
参数示例：0

y

参数含义：二维码左上角Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：二维码显示的起始垂直位置；
参数示例：0

str

参数含义：二维码内容字符串；
数据类型：string；
取值范围：有效的字符串内容；
是否必选：必须传入此参数；
注意事项：需要编码为二维码的字符串；
参数示例："https://docs.openluat.com/"

size

参数含义：二维码尺寸，显示大小为正方形,尺寸 = size*size；
数据类型：number；
取值范围：正整数，size建议填大于21的参数；
是否必选：必须传入此参数；
注意事项：二维码等级1级-40级，每级尺寸按（8+4*二维码等级+9)计算，
         1级尺寸21，2级尺寸25，3级尺寸29……40级尺寸177，假如设置尺寸为24，
         24大于1级尺寸小于2级尺寸，那么会显示一个21*21像素的二维码,外面3个像素的白框。         
参数示例：21

返回值

无

示例

-- 以坐标（0，0）为左上角，显示内容为"https://docs.openluat.com/"，尺寸为177*177大小的二维码
lcd.drawQrcode(0, 0, "https://docs.openluat.com/", 177)

---

4.15 lcd.drawXbm(x, y, w, h, data)

功能

绘制 XBM 格式位图；

注意事项

XBM 是位图格式，每个像素使用 RGB565 颜色值来表示；

参数

x

参数含义：位图起始X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：位图显示的起始水平位置；
参数示例：0

y

参数含义：位图起始Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：位图显示的起始垂直位置；
参数示例：0

w

参数含义：位图宽度；
数据类型：number；
取值范围：正整数；
是否必选：必须传入此参数；
注意事项：位图的像素宽度；
参数示例：16

h

参数含义：位图高度；
数据类型：number；
取值范围：正整数；
是否必选：必须传入此参数；
注意事项：位图的像素高度；
参数示例：16

data

参数含义：位图数据，每一个字节代表一个像素；
数据类型：string；
取值范围：有效的位图数据字符串；
是否必选：必须传入此参数；
注意事项：需要使用特定格式的位图数据，取模可以使用PCtoLCD2002软件，方式：阴码 逐行 逆向生成数据；
参数示例：string.char(0x80,0x00,0x80,0x00,0x40,0x01,0x20,0x02,0x10,0x04,0x48,0x08,0x84,0x10,0x83,0x60,
                    0x00,0x00,0xF8,0x0F,0x00,0x08,0x00,0x04,0x00,0x04,0x00,0x02,0x00,0x01,0x80,0x00)

返回值

无

示例

-- 取模使用PCtoLCD2002软件即可，方式：阴码 逐行 逆向
-- 在位置(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))

---

4.16 lcd.showImage(x, y, file)

功能

显示图片，当前只支持 jpg、jpeg 格式；

参数

x

参数含义：图片左上角显示位置X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：图片显示的起始水平位置；
参数示例：0

y

参数含义：图片左上角显示位置Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：图片显示的起始垂直位置；
参数示例：0

file

参数含义：图片文件路径；
数据类型：string；
取值范围：有效的文件路径；
是否必选：必须传入此参数；
注意事项：支持jpg、jpeg格式图片；
参数示例："/luadb/logo.jpg"

返回值

无

示例

lcd.showImage(0,0,"/luadb/logo.jpg")

---

4.17 lcd.image2raw(file)

功能

解码图片，当前只支持 jpg、jpeg 格式；

参数

file

参数含义：图片文件路径；
数据类型：string；
取值范围：有效的文件路径；
是否必选：必须传入此参数；
注意事项：支持jpg、jpeg格式图片，图片宽和高必须是16的倍数；
参数示例："/luadb/logo.jpg"

返回值

local lcd_zbuff = lcd.image2raw(file)

lcd_zbuff

zbuff
参数含义：解码后的图像缓冲区；
数据类型：userdata；
取值范围：有效的zbuff对象；
是否必选：必选，否则创建就没有意义；
注意事项：可以使用lcd.draw函数显示此缓冲区；
返回示例：zbuff对象

示例

-- 使用jpg图片硬解码创建zbuff
lcd_zbuff = lcd.image2raw("/luadb/logo.jpg")

-- 以点(0, 0)为左上角显示zbuff内容
lcd.draw(0, 0, nil, nil, lcd_zbuff)

---

4.18 lcd.setFont(font)

功能

设置接下来使用的字体

参数

font

参数含义：字体对象；
数据类型：userdata；
取值范围：有效的字体对象；
是否必选：必须传入此参数；
注意事项：所使用字体需要是字体常量列表内的；
参数示例：lcd.font_opposansm12

返回值

无

示例

-- 设置为字体,对之后的drawStr有效,调用lcd.drawStr前一定要先设置
-- 若提示 "only font pointer is allow" , 则代表当前固件不含对应字体
-- lcd库的默认字体均以 lcd.font_ 开头
lcd.setFont(lcd.font_opposansm12)
lcd.drawStr(40,10,"drawStr")
lcd.setFont(lcd.font_opposansm12_chinese) -- 具体取值可参考api文档的常量
lcd.drawStr(40,40,"drawStr测试")

---

4.19 lcd.drawStr(x,y,str,fg_color)

功能

显示字符串；

参数

x

参数含义：字符串左下角显示X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：字符串左下角会显示在设置坐标处；
参数示例：40

y

参数含义：字符串左下角显示Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：字符串左下角会显示在设置坐标处；
参数示例：10

str

参数含义：要显示的字符串；
数据类型：string；
取值范围：UTF-8格式字符串；
是否必选：必须传入此参数；
注意事项：支持中英文混合显示；
参数示例："drawStr测试"

fg_color

参数含义：前景颜色；
数据类型：number；
取值范围：RGB565颜色值；
是否必选：可选传入此参数；
注意事项：如不填写则使用之前设置的颜色，绘制只会绘制字体部分，背景需要自己清除
参数示例：0xF98B
        -- 颜色转换说明
        假设我们需要填充一个以颜色分量为R:255,G:50,B:88的24位颜色
        先将24位颜色的颜色分量按RGB顺序转换为二进制，然后按R高5位，G高6位，B高5位提取
            R:11111111 --→ 按高位提取5位颜色分量， --→ R:11111
            G:00110010 --→ 按高位提取6位颜色分量， --→ G:001100
            B:01011000 --→ 按高位提取5位颜色分量， --→ B:01011
        将提取的数据按R占高5位，G占中6位，B占低5位组合，
        换算为16进制，得到了16位RGB565颜色值为0xF98B
            11111 001100 01011 --→ 0xF98B

        -- RGB565常用颜色
        WHITE       = 0xFFFF,  -- 白色，颜色分量 R = 248-255, G = 252-255, B = 248-255
        BLACK       = 0x0000,  -- 黑色，颜色分量 R = 0, G = 0, B = 0
        RED         = 0xF800,  -- 红色，颜色分量 R = 248-255, G = 0, B = 0
        GREEN       = 0x07E0,  -- 绿色，颜色分量 R = 0, G = 252-255, B = 0
        BLUE        = 0x001F,  -- 蓝色，颜色分量 R = 0, G = 0, B = 248-255
        YELLOW      = 0xFFE0,  -- 黄色，颜色分量 R = 248-255, G = 252-255, B = 0
        CYAN        = 0x07FF,  -- 青色，颜色分量 R = 0, G = 252-255, B = 248-255
        MAGENTA     = 0xF81F,  -- 洋红色，颜色分量 R = 248-255, G = 0, B = 248-255
        GRAY        = 0x8410,  -- 灰色，颜色分量 R = 128-135, G = 128-131, B = 128-135
        LIGHTGRAY   = 0xC618,  -- 浅灰色，颜色分量 R = 192-199, G = 192-195, B = 192-199
        DARKGRAY    = 0x4208,  -- 深灰色，颜色分量 R = 64-71, G = 64-67, B = 64-71
        ORANGE      = 0xFC00,  -- 橙色，颜色分量 R = 248-255, G = 128-131, B = 0
        PINK        = 0xFE19,  -- 粉色，颜色分量 R = 248-255, G = 192-195, B = 200-207
        BROWN       = 0x8200,  -- 棕色，颜色分量 R = 128-135, G = 64-67, B = 0
        PURPLE      = 0x8010,  -- 紫色，颜色分量 R = 128-135, G = 0, B = 128-135
        LIME        = 0x07E0,  -- 酸橙色，颜色分量 R = 0, G = 252-255, B = 0
        NAVY        = 0x0010,  -- 海军蓝，颜色分量 R = 0, G = 0, B = 128-135
        TEAL        = 0x0410,  -- 蓝绿色，颜色分量 R = 0, G = 128-131, B = 128-135
        MAROON      = 0x8000,  -- 栗色，颜色分量 R = 128-135, G = 0, B = 0
        OLIVE       = 0x8400,  -- 橄榄色，颜色分量 R = 128-135, G = 128-131, B = 0
        SILVER      = 0xC618,  -- 银色，颜色分量 R = 192-199, G = 192-195, B = 192-199
        GOLD        = 0xFEA0,  -- 金色，颜色分量 R = 248-255, G = 215-218, B = 0

返回值

无

示例

-- 显示之前先设置为12号英文字体,对之后的drawStr有效
lcd.setFont(lcd.font_opposansm12)
-- 显示字符串
lcd.drawStr(40,10,"drawStr")

-- 显示之前先设置为12号中文字体,对之后的drawStr有效
lcd.setFont(lcd.font_opposansm12_chinese)
-- 显示字符串，并加上颜色
lcd.drawStr(40,40,"drawStr测试",0x1234)

---

4.20 lcd.drawGtfontUtf8Gray(str,size,gray,x,y)

功能

使用 gtfont 灰度显示 UTF8 字符串，字体边缘平滑，颜色比 lcd.drawGtfontUtf8(str,size,x,y)略浅；

注意事项

需要外置 gtfont 字体芯片并进行初始化后才能使用，不需要使用 u8g2.SetFont(font, indentation)进行设置；

参数

str

参数含义：UTF8编码的字符串；
数据类型：string；
取值范围：有效的UTF8字符串；
是否必选：必须传入此参数；
注意事项：直接使用UTF8编码，无需转换；
参数示例："你好合宙"

size

参数含义：字体大小；
数据类型：number；
取值范围：支持16-192号大小字体；
是否必选：必须传入此参数；
注意事项：字体像素大小；
参数示例：32

gray

参数含义：灰度级别；
数据类型：number；
取值范围：0/1/2/4：灰度[1阶/2阶/4阶]；
是否必选：必须传入此参数；
注意事项：灰度值越大颜色越深；
参数示例：4

x

参数含义：显示起始X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：文字左上角显示的起始水平位置；
参数示例：0

y

参数含义：显示起始Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：文字左上角显示的起始垂直位置；
参数示例：40

返回值

无

示例

lcd.drawGtfontUtf8Gray("你好合宙",32,4,0,40)

---

4.21 lcd.drawGtfontUtf8(str,size,x,y)

功能

使用 gtfont 显示 UTF8 字符串，字体边缘有锯齿，颜色比 lcd.drawGtfontUtf8Gray(str,size,gray,x,y)稍深；

注意事项

需要外置 gtfont 字体芯片并进行初始化后才能使用，不需要使用 u8g2.SetFont(font, indentation)进行设置；

参数

str

参数含义：UTF8编码的字符串；
数据类型：string；
取值范围：有效的UTF8字符串；
是否必选：必须传入此参数；
注意事项：直接使用UTF8编码，无需转换；
参数示例："你好合宙"

size

参数含义：字体大小；
数据类型：number；
取值范围：支持16-192号大小字体；
是否必选：必须传入此参数；
注意事项：字体像素大小；
参数示例：32

x

参数含义：显示起始X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：文字左上角显示的起始水平位置；
参数示例：0

y

参数含义：显示起始Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：文字左上角显示的起始垂直位置；
参数示例：0

返回值

无

示例

lcd.drawGtfontUtf8("你好合宙",32,0,0)

---

4.22 lcd.drawGtfontGb2312Gray(str,size,gray,x,y)

功能

使用 gtfont 显示 gb2312 编码格式字符串，支持灰度显示；

注意事项

需要外置 gtfont 字体芯片并进行初始化后才能使用，不需要使用 u8g2.SetFont(font, indentation)进行设置；

参数

str

参数含义：GB2312编码的字符串；
数据类型：string；
取值范围：GB2312编码的字符串；
是否必选：必须传入此参数；
注意事项：需要使用GB2312编码，其他编码需要转换；
参数示例：utf8ToGb2312("你好合宙")

size

参数含义：字体大小；
数据类型：number；
取值范围：支持16-192号大小字体；
是否必选：必须传入此参数；
注意事项：字体像素大小；
参数示例：32

gray

参数含义：灰度级别；
数据类型：number；
取值范围：0/1/2/4：灰度[1阶/2阶/4阶]；
是否必选：必须传入此参数；
注意事项：灰度值越大颜色越深；
参数示例：4

x

参数含义：显示起始X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：文字左上角显示的起始水平位置；
参数示例：0

y

参数含义：显示起始Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：文字左上角显示的起始垂直位置；
参数示例：40

返回值

无

示例

-- 注意, gtfont是额外的字体芯片硬件, 需要外挂在SPI总线才能调用本函数的
function utf8ToGb2312(utf8s)
    local cd = iconv.open("ucs2", "utf8")
    local ucs2s = cd:iconv(utf8s)
    cd = iconv.open("gb2312", "ucs2")
    return cd:iconv(ucs2s)
end

lcd.drawGtfontGb2312Gray(utf8ToGb2312("你好合宙"),32,4,0,40)

---

4.23 lcd.drawGtfontGb2312(str,size,x,y)

功能

使用 gtfont 显示 gb2312 编码格式字符串，

注意事项

需要外置 gtfont 字体芯片并进行初始化后才能使用，不需要使用 u8g2.SetFont(font, indentation)进行设置；

参数

str

参数含义：GB2312编码的字符串；
数据类型：string；
取值范围：GB2312编码的字符串；
是否必选：必须传入此参数；
注意事项：需要使用GB2312编码，其他编码需要进行格式转换；
参数示例：utf8ToGb2312("你好合宙")

size

参数含义：字体大小；
数据类型：number；
取值范围：支持16-192号大小字体；
是否必选：必须传入此参数；
注意事项：字体像素大小；
参数示例：32

x

参数含义：显示起始X坐标；
数据类型：number；
取值范围：屏幕范围内的X坐标值；
是否必选：必须传入此参数；
注意事项：文字左上角显示的起始水平位置；
参数示例：0

y

参数含义：显示起始Y坐标；
数据类型：number；
取值范围：屏幕范围内的Y坐标值；
是否必选：必须传入此参数；
注意事项：文字左上角显示的起始垂直位置；
参数示例：0

返回值

无

示例

-- 注意, gtfont是额外的字体芯片硬件, 需要外挂在SPI总线才能调用本函数的

function utf8ToGb2312(utf8s)
    local cd = iconv.open("ucs2", "utf8")
    local ucs2s = cd:iconv(utf8s)
    cd = iconv.open("gb2312", "ucs2")
    return cd:iconv(ucs2s)
end

lcd.drawGtfontGb2312(utf8ToGb2312("你好合宙"),32,0,0)

---

4.24 lcd.getSize()

功能

获取屏幕尺寸，返回初始化时传入的尺寸；

参数

无

返回值

local width, height = lcd.getSize()

参数含义：屏幕宽度；
数据类型：number；
取值范围：正整数；
是否必选：返回值的第一个参数；
注意事项：如果未初始化会返回0；
返回示例：240
width

参数含义：屏幕高度；
数据类型：number；
取值范围：正整数；
是否必选：返回值的第二个参数；
注意事项：如果未初始化会返回0；
返回示例：320
height

示例

local width, height = lcd.getSize()
log.info("lcd", "size", width, height)

---

4.25 lcd.reset_pin(level)

功能

控制 LCD 复位引脚的电平状态，用于手动控制 LCD 硬复位；2025/9/5 启用

参数

level

参数含义：复位引脚的电平状态；
数据类型：number；
取值范围：1表示高电平，0表示低电平；
是否必选：必须传入此参数；
注意事项：通过控制复位引脚的电平可以实现LCD的硬件复位；
参数示例：1

返回值

无

示例

-- LCD复位引脚高电平
lcd.reset_pin(1)

-- LCD复位引脚低电平（复位）
lcd.reset_pin(0)

-- 延时后恢复高电平
sys.wait(100)
lcd.reset_pin(1)

---

4.26 lcd.on()

功能

拉高背光引脚，开启 LCD 显示屏背光，如果执行 lcd.init 屏幕初始化时，参数 port ≠ lcd.RGB,那么执行此命令还会向显示芯片发送一条 0x29 命令；

参数

无

返回值

无

示例

-- 开启lcd显示屏背光
lcd.on()

---

4.27 lcd.off()

功能

拉低背光引脚，关闭 LCD 显示屏背光，如果执行 lcd.init 屏幕初始化时，参数 port ≠ lcd.RGB,那么执行此命令还会向显示芯片发送一条 0x28 命令；

参数

无

返回值

无

示例

-- 关闭lcd显示屏背光
lcd.off()

---

4.28 lcd.sleep()

功能

使 LCD 睡眠；

1、lcd.init 初始化时配置了休眠指令，使用该接口会发送配置的休眠指令给显示芯片；如果 lcd.init 初始化时没有配置休眠指令，则发送默认指令 0x11 给显示芯片；

2、如果 lcd.init 初始化时正确设置了背光引脚 GPIO 号，使用该接口会在发送休眠指令后，会拉低初始化设置的背光 GPIO 引脚电平，如果没有配置，则不会执行拉低背光引脚 GPIO 操作。

参数

无

返回值

无

示例

-- lcd睡眠
lcd.sleep()

---

4.29 lcd.wakeup()

功能

使 LCD 唤醒；

1、lcd.init 初始化时配置了休眠指令，使用该接口会发送配置的唤醒指令给显示芯片；如果 lcd.init 初始化时没有配置唤醒指令，则发送默认指令 0x10 给显示芯片；

2、如果 lcd.init 初始化时正确设置了背光引脚 GPIO 号，使用该接口会在发送唤醒指令后，会拉高初始化设置的背光 GPIO 引脚电平，如果没有配置，则不会执行拉高背光引脚 GPIO 操作。

参数

无

返回值

无

示例

-- lcd唤醒
lcd.wakeup()

---

4.30 lcd.invon()

功能

LCD 颜色反显打开，

显示颜色反显：黑色变白色，白色变黑色，红色变青色、绿色变品红色、蓝色变黄色；

参数

无

返回值

无

示例

-- lcd反显
lcd.invon()

---

4.31 lcd.invoff()

功能

LCD 颜色反显关闭；

参数

无

返回值

无

示例

-- lcd反显关闭
lcd.invoff()

---

4.32 lcd.rgb565(r, g, b, swap)

功能

RGB565 颜色生成函数，按 R、G、B 颜色分量转换为用于显示的 16 位 RGB565 格式颜色值；

参数

r

参数含义：红色分量值；
数据类型：number；
取值范围：取值范围为
         16进制0x00-0xFF；
         10进制0-255；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：0xF0或240

g

参数含义：绿色分量值；
数据类型：number；
取值范围：取值范围为
         16进制0x00-0xFF；
         10进制0-255；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：0x9C或者156

b

参数含义：蓝色分量值；
数据类型：number；
取值范围：取值范围为
         16进制0x00-0xFF；
         10进制0-255；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：0x2D或者45

swap

参数含义：是否翻转字节顺序；
数据类型：boolean；
取值范围：true表示翻转字节顺序，false表示不翻转；
是否必选：可选传入此参数，默认值为true；
注意事项：默认翻转，LuatOS中LCD画图和显示字体对RGB565颜色处理时会自动翻转颜色，         
         所以，以下这些接口使用lcd.rgb565(r, g, b, swap)生成的颜色，swap填false；
             lcd.clear(color)                        -- 按设置的颜色或背景色清屏；
             lcd.fill(x1, y1, x2, y2,color)          -- 填充矩形区域；
             lcd.drawPoint(x,y,color)                -- 画一个可设置颜色的点；
             lcd.drawLine(x1,y1,x2,y2,color)         -- 在两点之间画一条线；
             lcd.drawRectangle(x1,y1,x2,y2,color)    -- 从绘制一个矩形框；
             lcd.drawCircle(x,y,r,color)             -- 绘制一个圆圈；
             lcd.drawStr(x,y,str,fg_color)           -- 显示字符串；
             lcd.setColor(back,fore)                 -- 设置LCD显示的前景色和背景色；

         以下接口使用lcd.rgb565(r, g, b, swap)生成的颜色，swap填true；
             lcd.draw(x1, y1, x2, y2,buff)           -- 不进行转换显示buff缓冲区内容；

参数示例：true             
          -- 颜色转换说明
        假设我们需要填充一个以颜色分量为R:255,G:50,B:88的24位颜色
        先将24位颜色的颜色分量按RGB顺序转换为二进制，然后按R高5位，G高6位，B高5位提取
            R:11111111 --→ 按高位提取5位颜色分量， --→ R:11111
            G:00110010 --→ 按高位提取6位颜色分量， --→ G:001100
            B:01011000 --→ 按高位提取5位颜色分量， --→ B:01011

            11111 001100 01011 --→ 0xF98B      
        -- swap填false转换过程
        swap填false,先将提取的数据按R占高5位，G占中6位，B占低5位组合，
        换算为16进制，得到了填入的16位RGB565颜色值为0xF98B
            11111 001100 01011 --→ 0xF98B

        -- swap填true转换过程    
        swap填true,先将提取的数据按R占高5位，G占中6位，B占低5位组合，
            11111 001100 01011 整理格式为 11111001 10001011 
        再将所得到的值，高8位和低8位交互位置，换算为16进制，得到16位RGB565颜色值为0x8BF9，
            11111001 10001011 --→ 10001011 11111001 --→ 0x8BF9

返回值

local rgb565color= lcd.rgb565(r, g, b, swap)

rgb565color

参数含义：生成的RGB565格式颜色值；
数据类型：number；
取值范围：16位颜色值（0x0000-0xFFFF）；
注意事项：RGB565格式使用5位红色、6位绿色、5位蓝色；
返回示例：0xF800（红色）

示例

-- 1. 三参数形式, 红/绿/蓝, 各8bit
local red = lcd.rgb565(0xFF, 0x00, 0x00)
local green = lcd.rgb565(0x00, 0xFF, 0x00)
local blue = lcd.rgb565(0x00, 0x00, 0xFF)

-- 2. 四参数形式, 红/绿/蓝, 各8bit, 增加swap的设置
local red = lcd.rgb565(0xFF, 0x00, 0x00, true)
local green = lcd.rgb565(0x00, 0xFF, 0x00, true)
local blue = lcd.rgb565(0x00, 0x00, 0xFF, true)

4.33 lcd.rgb565(rgb888, swap)

功能

RGB565 位颜色生成函数，用于生成 LCD 显示使用的 16 位 RGB565 格式颜色值；

参数

rgb888

参数含义：24位RGB颜色值；
数据类型：number；
取值范围：取值范围为24位RGB颜色值（0x000000-0xFFFFFF）；
是否必选：必须传入此参数；
注意事项：为24位RGB值；
参数示例：0xFF0000

swap

参数含义：是否翻转字节顺序；
数据类型：boolean；
取值范围：true表示翻转字节顺序，false表示不翻转；
是否必选：可选传入此参数，默认值为true；
注意事项：默认翻转，LuatOS中LCD画图和显示字体对RGB565颜色处理时会自动翻转颜色，         
         所以，以下这些接口使用lcd.rgb565(r, g, b, swap)生成的颜色，swap填false；
             lcd.clear(color)                        -- 按设置的颜色或背景色清屏；
             lcd.fill(x1, y1, x2, y2,color)          -- 填充矩形区域；
             lcd.drawPoint(x,y,color)                -- 画一个可设置颜色的点；
             lcd.drawLine(x1,y1,x2,y2,color)         -- 在两点之间画一条线；
             lcd.drawRectangle(x1,y1,x2,y2,color)    -- 从绘制一个矩形框；
             lcd.drawCircle(x,y,r,color)             -- 绘制一个圆圈；
             lcd.drawStr(x,y,str,fg_color)           -- 显示字符串；
             lcd.setColor(back,fore)                 -- 设置LCD显示的前景色和背景色；

         以下接口使用lcd.rgb565(r, g, b, swap)生成的颜色，swap填true；
             lcd.draw(x1, y1, x2, y2,buff)           -- 不进行转换显示buff缓冲区内容；
参数示例：true
        -- 颜色转换说明
        假设我们需要将0xABCDEF的24位RGB888颜色转换为LCD库使用的16位RGB565颜色，
        先将24位颜色转换为二进制
            10101011 11001101 11101111

        -- swap填false转换过程                   
        将1-5位、9-14位，17-21位提取出来，重新组合，得到0xA7D
            10101 110011 11101 --→  0xA7D

        -- swap填true转换过程  
        将1-5位、9-14位，17-21位提取出来，重新组合，得到0xA7D
            10101 110011 11101 --→  0xA7D
        再将所得到的值，高8位和低8位交互位置，得到16位RGB565颜色值为0x7DAE，
            10101 110011 11101 --→ 01111101 10101110 --→ 0x7DAE

返回值

local rgb565color= lcd.rgb565(rgb888, swap)

rgb565color

参数含义：生成的RGB565格式颜色值；
数据类型：number；
取值范围：16位颜色值（0x0000-0xFFFF）；
注意事项：RGB565格式使用5位红色、6位绿色、5位蓝色；
返回示例：0xF800（红色）

示例

-- 1. 单参数形式, 24bit RGB值, swap = true, 推荐
local red =   lcd.rgb565(0xFF0000)
local green = lcd.rgb565(0x00FF00)
local blue =  lcd.rgb565(0x0000FF)

-- 2. 两参数形式, 24bit RGB值, 增加swap的设置
local red =   lcd.rgb565(0xFF0000, true)
local green = lcd.rgb565(0x00FF00, true)
local blue =  lcd.rgb565(0x0000FF, true)

---

4.34 lcd.qspi(1_wire_command, 1_wire_command_4_wire_data, 4_wire_command_4_wire_data, vsync_reg, hsync_cmd, hsync_reg)

功能

硬件 LCD QSPI 接口配置函数，用于配置 QSPI 接口的 LCD 屏幕驱动参数，需要在 lcd.init 前调用，定义 QSPI 数据传输规则，所有 QSPI 接口屏幕都能使用；

参数

1_wire_command

参数含义：LCD命令模式下的QSPI指令；
数据类型：number；
取值范围：显示芯片有效的QSPI指令值；
是否必选：必须传入此参数；
注意事项：配置命令模式下的通信参数；
参数示例：0x02

1_wire_command_4_wire_data

参数含义：LCD数据模式下，1线地址，4线数据的QSPI指令；
数据类型：number；
取值范围：显示芯片有效的QSPI指令值；
是否必选：必须传入此参数；
注意事项：配置数据模式下的通信参数；
参数示例：0x32

4_wire_command_4_wire_data

参数含义：LCD数据模式下，4线地址，4线数据的QSPI指令；
数据类型：number或nil；
取值范围：显示芯片有效的QSPI指令值；
是否必选：可选传入此参数；
注意事项：可以留空，如果存在，发送数据时优先使用这个模式；
参数示例：0x12

vsync_reg

参数含义：帧同步时的地址值；
数据类型：number或nil；
取值范围：有效的寄存器地址值；
是否必选：可选传入此参数；
注意事项：只有无RAM的屏幕需要，如果能用0x2C发送数据则不需要这个参数；
参数示例：0xDE

hsync_cmd

参数含义：行同步时的指令；
数据类型：number或nil；
取值范围：有效的指令值；
是否必选：可选传入此参数；
注意事项：一般情况和命令模式下的指令一致，只有无RAM的屏幕需要，如果能用0x2C发送数据则不需要这个参数；
参数示例：0x60

hsync_reg

参数含义：行同步时的地址值；
数据类型：number或nil；
取值范围：有效的寄存器地址值；
是否必选：可选传入此参数；
注意事项：只有无RAM的屏幕需要，如果能用0x2C发送数据则不需要这个参数；
参数示例：0xDE

返回值

无

示例

-- sh8601z驱动ic所需的qspi配置
lcd.qspi(0x02, 0x32, 0x12)
-- jd9261t驱动ic所需的qspi配置
lcd.qspi(0xde, 0xde, nil, 0x61, 0xde, 0x60)
-- CO5300驱动ic所需的qspi配置
lcd.qspi(0x02, 0x32, 0x12)

---

4.35 lcd.user_done()

功能

标记用户自定义 LCD 初始化完成，使后续显示操作生效。

注意事项

当使用 lcd.init 初始化 LCD 且指定 driver_ic = "custom"时，在完成自定义初始化命令序列后，必须调用本 API 来标记初始化过程已完成，否则 LCD 无法正常显示。

参数

无

返回值

无

示例

-- 1. 初始化参数定义：存储LCD核心配置信息
local lcd_param = {
    port = lcd.HWID_0,      -- QSPI硬件接口ID，选择第0路硬件QSPI控制器
    pin_rst = 36,           -- LCD复位引脚
    direction = lcd.direction_0,      -- 屏幕显示方向：默认0度方向
    w = 480,                -- 屏幕宽度
    h = 480,                -- 屏幕高度
    xoffset = 0,            -- X轴偏移：0=显示起始点从屏幕左边缘开始
    yoffset = 0,            -- Y轴偏移：0=显示起始点从屏幕上边缘开始
    sleepcmd = 0x10,        -- 睡眠模式命令
    wakecmd = 0x11,         -- 唤醒命令
    interface_mode = lcd.QSPI_MODE, -- 接口模式：选择QSPI
    bus_speed = 60000000,  -- QSPI总线速率：60MHz
    rb_swap = true          -- 数据字节交换使能：适配硬件数据传输顺序，避免颜色错位
}

-- 3. QSPI接口模式配置：定义QSPI数据传输规则
-- 第1个参数0x02：标准SPI写指令，用于向芯片写命令/参数
-- 第2个参数0x32：4线像素写入24时钟地址，长地址模式
-- 第3个参数0x12：4线像素写入6时钟地址，短地址模式
-- 作用：告诉CO5300“后续用QSPI 4线模式传输数据，支持长/短地址两种像素写入方式”
-- 相当于给芯片“定规矩”——后续数据怎么传、地址用多少时钟，避免传错
lcd.qspi(0x02, 0x32, 0x12)


-- 4. LCD硬件初始化与复位：让芯片进入初始状态
-- 调用LCD驱动初始化函数，加载上面定义的lcd_param配置（接口、分辨率等）
lcd.init("user", lcd_param)  

-- 5. co5300命令页切换：选择要使用的命令集
-- 命令码0xFE：命令页切换命令
-- 参数0x00：切换到“命令页0
-- 作用：CO5300有多个命令页（如基础命令页、Gamma命令页），这里选默认页，后续才能用基础命令（如0x3A像素格式）
-- 相当于打开“命令手册的基础章节”，后续操作都在这个章节里找命令
lcd.cmd(0xfe, 0x00)

-- 6. 设置SPI模式：配置SPI接口细节
-- 命令码0xC4：设置SPI模式命令
-- 参数0x80：具体配置（bit7=1，通常表示“启用SPI写RAM功能”，手册7.5.57节参数说明）
-- 作用：开启SPI接口向显示内存（RAM）写数据的功能，后续才能传图像数据到屏幕
-- 相当于给SPI接口“开权限”——允许往屏幕的“显存”里写数据
lcd.cmd(0xc4, 0x80)

-- 7. 设置接口像素格式：定义颜色数据的格式
-- 命令码0x3A：接口像素格式命令
-- 参数0x55：配置为“RGB565格式”（16位/像素，R=5位、G=6位、B=5位，手册7.5.32节参数表）
-- 作用：告诉芯片“后续传的颜色数据是RGB565格式”，避免芯片解析错误（比如传RGB565却按RGB888解析，颜色会乱）
-- 相当于约定“颜色数据的编码规则”——比如“每16位代表一个像素，前5位是红、中间6位是绿、后5位是蓝”
lcd.cmd(0x3a, 0x55)

-- 8. 开启撕裂效应：避免画面闪烁
-- 命令码0x35：撕裂效应开启命令
-- 参数0x00：模式1（仅输出V-sync和V-Blanking信号，手册5.3.1节）
-- 作用：TE引脚会输出同步信号，MCU可根据这个信号判断“什么时候写显存不会导致画面撕裂”（比如避开屏幕刷新时写数据）
-- 相当于给MCU发“通知”——“现在可以写数据，不会让画面闪”
lcd.cmd(0x35, 0x00)

-- 9. 写显示控制：配置显示器基础控制参数
-- 命令码0x53：写CTRL显示命令
-- 参数0x20：具体控制配置（bit5=1，通常表示“启用亮度控制”或“默认显示控制模式”，手册7.5.40节参数说明）
-- 作用：配置显示器的核心控制逻辑，比如亮度调节使能、显示驱动时序等
-- 相当于设置屏幕的“基础工作规则”，比如是否允许调亮度、驱动屏幕的时序参数
lcd.cmd(0x53, 0x20)

-- 10. 设置显示亮度：调节屏幕正常亮度
-- 命令码0x51：写显示亮度命令
-- 参数0x7a：亮度值（0x00=最暗，0xFF=最亮，0x7A=122/255≈48%亮度，适合日常使用）
-- 作用：设置OLED屏幕的正常显示亮度，避免过亮耗电或过暗看不清
-- 相当于调节屏幕的“背光亮度”，这里设为中等亮度
lcd.cmd(0x51, 0x7a)

-- 11. 设置高亮度模式（HBM）亮度：应对强光场景
-- 命令码0x63：写HBM显示亮度命令
-- 参数0xaa：高亮度模式下的亮度值（0xAA=170/255≈67%亮度，比正常模式亮，适合户外强光场景）
-- 作用：配置“高亮度模式”的亮度（HBM模式需单独开启，这里先设亮度值）
-- 相当于设置屏幕的“强光模式亮度”，后续开启HBM时就用这个亮度
lcd.cmd(0x63, 0xaa)

-- 12. 设置内存数据访问控制：定义屏幕显示方向
-- 命令码0x36：内存数据访问控制命令
-- 参数0x00：默认方向配置（MY=0、MX=0、RGB=0，即“行从上到下、列从左到右、RGB颜色顺序”，手册7.5.29节参数表）
-- 作用：控制显存数据的扫描方向，比如是否旋转、镜像，这里设为默认方向，避免画面颠倒
-- 相当于设置屏幕的“显示方向”——比如“数据从左上角开始显示，不旋转”
lcd.cmd(0x36, 0x00)

-- 13. 退出睡眠模式：唤醒屏幕
-- 作用：芯片上电后默认在睡眠模式（低功耗，不显示），发送此命令唤醒芯片，开启内部振荡器、Gamma电路等
-- 注意：必须唤醒后，后续“开启显示”命令才有效
-- 相当于按屏幕的“电源键”，从休眠中唤醒，准备显示
lcd.cmd(0x11)  -- 唤醒显示芯片

-- 14. 开启显示：完成初始化，屏幕开始显示
-- 作用：最后一步，开启显示驱动电路，将显存中的数据输出到屏幕（之前都是配置，这步才真正“亮屏”）
-- 注意：必须在“退出睡眠模式”后发送，否则无效
-- 相当于按屏幕的“显示开关”，之前的配置都做好了，这步让屏幕亮起来
lcd.cmd(0x29)  -- 命令码0x29：显示开启命令

-- 15. 公用显示设置：初始化显示缓存与刷新
lcd.setupBuff(nil, false)  -- 设置帧缓冲区，使用vm内存
lcd.autoFlush(false)       -- 禁止自动刷新
lcd.user_done()            -- 通知驱动“用户初始化完成”，后续可正常调用显示接口
lcd.clear()                -- 清除屏幕缓存数据
lcd.flush()                -- 手动刷新缓存数据到屏幕

---

4.36 lcd.setAcchw(type,enable)

功能

LCD 初始化完成后，默认开启所有支持的硬件加速功能（目前仅支持 JPEG 图像硬解码）。

注意事项

对于 Air780EHM/EGH/EHV/Air8000 系列, 默认开启 JPG 硬件解码, JPG 图片的长宽都需要是 16 的倍数, 否则会出现画面拉伸的现象

参数

type

参数含义：硬件加速类型；
数据类型：number；
取值范围：lcd.ACC_HW_JPEG、lcd.ACC_HW_ALL等加速类型常量，目前仅支持JPE/JPEG硬解码；
是否必选：必须传入此参数；
注意事项：目前硬件加速仅支持 JPEG 图像解码；
参数示例：lcd.ACC_HW_JPEG

enable

参数含义：开启或关闭标志；
数据类型：boolean；
取值范围：true/false；
是否必选：可选传入此参数；
注意事项：true表示开启，false表示关闭，默认关闭；
参数示例：false

返回值

无

示例

lcd.setAcchw(lcd.ACC_HW_JPEG,false) -- 关闭硬件加速的jpeg解码功能
lcd.setAcchw(lcd.ACC_HW_ALL,false) -- 关闭所有硬件加速

4.37 lcd.reset_pin(level)

功能

控制 lcd reset pin 拉高或者拉低,2025/9/5 启用

参数

level

参数含义：reset脚电平；
数据类型：number；
取值范围：1或0；
是否必选：必须传入此参数；
注意事项：1高电平，0低电平；
参数示例：1

返回值

无

示例

--  拉高lcd reset脚电平
lcd.reset_pin(1)

五、产品支持说明

1. LCD 需要硬件支持, 请确认你的设备有 lcd 屏幕接口，可以查看选型手册对应型号及固件是否支持 LCD 功能或 LCD 库
2. 支持 SPI QSPI RGB 等多种接口的 lcd 屏幕, 取决于具体的硬件
3. 对于 Air780EHM/EGH/EHV/Air8000 系列, 默认开启 JPG 硬件解码, JPG 图片的长宽都需要是 16 的倍数, 否则会出现画面拉伸的现象
4. 大部分 API 都只能在 lcd.init()成功后使用

六 附录：自定义字体文件制作和使用方法

1. 显示效果

1. 下载字体制作工具；

2. 准备好.ttf 和.otf 格式的字体；

3. 打开 u8g2_font_tool.exe，点击选择字体；

4.1 字体和软件需要放到非中文目录下；

4.2 一定要能显示完整的字体名才能进行转换；

4.3 字体命名长度不能超过 23 个字符，比如：我命名为“dinglie_16_chinese.bin”；

1. 连同生成的.bin 文件同代码一起烧录到模组内；

1. 按以下接口进行调用；

   -- 设置烧录到系统文件中的字体文件为接下来使用的字体
   lcd.setFontFile("/luadb/dinglie_16_chinese.bin")
   
   --设置前景色和背景色
   lcd.setColor(0xFFFF, 0xA2D5)
   
   -- 使用 lcd.drawStr 接口显示文字
   lcd.drawStr(310,100,"你好 LuatOS")