LUA 脚本API函数接口

本文档适用于M系列、W系列、X系列、F系列（固件版本 >= V4.2.401.0）。API函数中的screen、control参数均表示为目标画面ID、目标组态控件ID，后文每个API不一一介绍

1.1 控件属性类

1.1.1 change_screen(screen)

切换到指定画面

1.1.2 change_child_screen (screen)

切换到子画面，例如对话框

1.1.3 change_screen_effect(screen,effect)

切换到指定画面，使用动画效果

• effect：动画效果。0-无动画，1-从左到右，2-从右到左，3-从上到下，4-从下到上，5-渐隐渐消

1.1.4 set_slide_screen(slide,round,start_screen,end_screen)

设置窗口滑动模式

• slide：0-禁止滑动，1-左右滑动，2-上下滑动
• round: 1-环回模式，尾页可以滑到首页
• start_screen: 开始画面
• end_screen：结束画面

1.1.5 set_button_notify_release ()

设置按钮松开通知模式，在触摸按钮上也可以滑动窗口

1.1.6 get_current_screen()

获取当前画面ID

1.1.7 set_value(screen,control,value)

设置控件数值

• value：控件值

按钮控件：value=1 – 按下，0 – 弹起

文本控件：value – 整数或小数

也可以设置进度条、滑块、仪表、滑动选择控件等等

1.1.8 get_value(screen,control)

获取控件数值，按钮、文本、进度条、滑块、仪表等

1.1.9 set_visiable(screen,control,visiable)

设置控件是否可见

• visiable：0-隐藏，1-显示

1.1.10 set_enable(screen,control,enable)

设置控件是否可触摸

• enable：0-禁止触摸，1-启用触摸

1.1.11 set_fore_color(screen,control,color)

设置控件前景色，例如文本控件文字颜色，进度条显示颜色

• color：RGB值，2个字节，RGB565

1.1.12 set_back_color(screen,control,color)

设置控件背景色，例如文本控件背景颜色，进度条背景颜色

• color：RGB值，2个字节，RGB565

1.1.13 set_text(screen,control,text)

设置控件显示内容(字符串)，文本控件，二维码控件等

• text：字符串类型

1.1.14 set_text_roll(screen,control, speed)

设置文本控件从右往左滚动速度

• speed：每秒多少个像素。设置为0停止滚动

1.1.15 set_text_flicker (screen,control, cycle)

设置文本控件闪烁周期

• cycle：闪烁周期，单位10ms。设置为0停止闪烁

1.1.16 get_text(screen,control)

获取控件字符串内容(字符串)，文本控件，二维码控件等

1.1.17 set_options (screen, control, options)

设置滑动选择控件的内容

• options：选项内容，字符串格式，每一项用英文分号“;”隔开

例如：set_options (screen,control, ‘选项1;选项2;选项3;’)

1.1.18 set_screen_range(screen, control, start_screen,end_screen, round)

设置子画面窗口滑动模式，W系列支持，F、M系列不支持

• start_screen: 开始画面
• end_screen：结束画面
• round:1环回模式，尾页可以滑到首页

1.1.19 play_animation(screen, control)

设置动画控件播放

1.1.20 stop_animation(screen，control)

设置动画控件停止

1.1.21 set_history_graph_value(screen,control,channel0,..,channel7)

设置历史曲线的通道值，根据通道的个数填写参数

• channe0：通道0的值
• …
• channe7：通道7的值

例如有4个通道：set_history_graph_value(screen,control,1,2,3,4)

1.1.22 set_history_graph_direction（screen,control,direction）

设置历史曲线刷新方向，默认状态下，刷新方向从右往左

• direction：0-从右往左，1-从左往右

1.1.23 set_scroll_position(screen, control, mode)

设置历史曲线的翻页

• mode：翻页模式。2-下一页，3-上一页，4-尾页，5-首页

1.2 记录控件

1.2.1 record_set_event(screen,control,eventid)

告警类型-触发告警

• eventid：和告警类型的数据记录控件中告警解析ID关联

1.2.2 record_reset_event(screen,control,eventid)

告警类型-解除告警

• eventid：和告警类型的数据记录控件中告警解析ID关联

1.2.3 record_add(screen,control,record)

在末尾添加一条记录

• record：record为字符串

例如：record_add(screen,control, “item1;item2;item3;”)

1.2.4 record_insert (screen,control,position,record)

在指定位置插入一条记录

• position：插入位置索引
• record：record为字符串

1.2.5 record_clear(screen,control)

清除记录数据

1.2.6 record_setoffset(screen,control,offset)

设置滚动显示位置

• offset：当前显示的定位到该索引

1.2.7 record_get_count(screen,control)

获取记录条数

例如：local recordCnt = record_get_count(0, 1) —假设画面0、控件1位数据记录控件

1.2.8 record_read(screen,control,position)

读取一条记录，返回字符串

• position：需要被读取的行号。索引从0开始，0即是第一行数据

1.2.9 record_modify(screen,control, position ,record)

修改一条记录

• position：需要被修改的行号，索引从0开始，0即是第一行数据
• record：新的修改内容

1.2.10 record_delete(screen,control,position)

删除一条记录

• position：需要被删除的行号。索引从0开始，0即是第一行数据

1.2.11 record_select(screen,control,position)

选中一条记录

• position：需要被选中的行号。索引从0开始，0即是第一行数据

1.2.12 record_export(screen,control)

导出记录到SD卡/U盘

1.3 常用回调函数

1.3.1 on_init()

系统加载LUA脚本文件之后，立即调用此回调函数，通常用于执行初始化操作。

1.3.2 on_systick()

系统每隔1秒钟自动调用此回调函数。

1.3.3 on_control_notify(screen,control,value)

用户触摸修改控件后，执行此回调函数。点击按钮控件，修改文本控件、修改滑动条都会触发此控件

• value:为数值类型，如果需要获取文本控件的字符串值，使用get_text(screen,control)

1.3.4 on_screen_change(screen)

当画面需要切换时，执行此回调函数，screen为目标画面。

注意，此函数内部调用change_screen,不会嵌套执行on_screen_change。

1.3.5 on_press(state,x,y)

用户点击触摸屏时，执行此回调函数。

• state：触摸状态，0-松开，1-按下，2-持续按压
• x：为触摸X坐标
• y：为触摸Y坐标

1.3.6 on_usb_inserted(driver)

U盘插入时，执行此回调函数

• dirver：为U盘的盘符

1.3.7 on_usb_removed()

U盘拔出时，执行此回调函数

1.3.8 on_sd_inserted(dir)

SD卡插入通知

• dir：盘符路径

1.3.9 on_sd_removed()

SD卡拔出通知

1.3.10 on_screen_sliding(screen, control)

用于确定手指滑动时的目标画面ID，W系列支持，F、M系列不支持

返回切换目标的画面的ID，left、right 、up、down，4个参数，指定左、右、上、下的页面ID，若为-1，该方向不允许滑动

• screen：当前所在的画面
• control：当前页面，在上面滑动的控件ID

1.4 绘图函数

1.4.1 on_draw(screen)

当界面的显示内容需要更新时，系统自动调用此函数，用户在此函数中添加自定义的绘图操作。用户绘制的内容叠加在画面内容控件上面.此函数为系统回调函数，用户不要直接调用

下面几种情况会触发此函数：

• 界面有动画播放、视频播放、RTC时间显示的动态刷新
• 用户操作屏幕控件
• 通过LUA脚本或串口指令更新控件
• 通过执行redraw

总之，界面上有任何变化，都会触发此回调函数。

1.4.2 on_pre_draw(screen)

用户绘制的内容在画面最底层，当前绘制画面需要透明，无背景图

相关说明同上

1.4.3 redraw()

发送重绘请求，触发on_draw的执行

1.4.4 screen_shoot(filename,x,y,width,height,quality)

截取屏幕窗口范围，存储到指定文件路径。W系列支持，F、M系列不支持

• filename: 图片文件存放路径
• x：截图的起点x坐标
• y：截图的起点y坐标
• width：截图的宽度
• height：截图的高度
• quality: JPEG图片质量，默认95

例如：screen_shoot(‘b:/shoot.jpg’,0,0,480,272, 95)

1.4.5 set_pen_color(color)

设置画笔的颜色，RGB565，用于指定线、矩形、圆等的颜色

• color：RGB565颜色值

1.4.6 draw_line(x0,y0,x1,y1,width)

绘制直线

• x0,y0：起始点坐标
• x1,y1：结束点坐标
• width：为线条的厚度，1~10

1.4.7 draw_rect(x0,y0,x1,y1,fill)

绘制矩形

• x0,y0：左上角坐标
• x1,y1：右下角坐标
• fill：0不填充，1填充

1.4.8 draw_rect_alpha(x0,y0,x1,y1,alpha)

绘制实心的半透明矩形，F系列不支持

• x0,y0：左上角坐标
• x1,y1：右下角坐标
• alpha：透明度0全透明~255不透明

1.4.9 draw_circle(x,y,r,fill)

绘制圆形

• x,y：圆的中心坐标
• r：圆的半径
• fill：0不填充，1填充

1.4.10 draw_ellipse(x0,y0,x1,y1,fill)

绘制椭圆

• x0,y0：左上角坐标
• x1,y1：右下角坐标
• fill：0不填充，1填充

1.4.11 load_image (image_id,frame_id)

加载指定图片到内存，一般用在on_init中，牺牲了开机速度，但使运行过程更流程。W系列支持，F、M系列不支持

• image_id：图片资源的ID
• frame_id：对应图标，可以设置帧ID，其他图片固定为0

1.4.12 draw_image(image_id,frame_id,dstx,dsty,width,height,srcx,srcy)

绘制图片

• image_id：图片资源的ID
• frame_id：对应图标，可以设置帧ID，其他图片固定为0
• dstx：图片显示X坐标
• dsty：图片显示Y坐标
• width：图片显示宽度
• height：图片显示高度
• srcx：图片裁剪X坐标
• srcy：图片裁剪Y坐标

1.4.13 draw_image_file(filename,dstx,dsty,width,height,srcx,srcy)

绘制图片，此方法不对图片进行缓存，效率较低，W系列支持，F、M系列不支持

• filename：图片文件，支持JPEG/PNG
• dstx：图片显示X坐标
• dsty：图片显示Y坐标
• width：图片显示宽度
• height：图片显示高度
• srcx：图片裁剪X坐标
• srcy：图片裁剪Y坐标

1.4.14 load_surface (filename)

加载图片到图层，W系列支持、M系列 >= V6.1.241.00支持（裁剪显示）、F系列不支持

• filename：图片文件，支持JPEG/PNG

例如：surface = load_surface (“c:/test.jpg”)

图层不再使用时，需要调用destroy_surface进行销毁，否则会导致内存泄漏。

1.4.15 destroy_surface (surface)

销毁图层，W系列支持、M系列 >= V6.1.241.00、F系列不支持

• surface：图层资源指针

1.4.16 draw_surface (surface,dstx,dsty,width,height,srcx,srcy)

绘制图层，相比于draw_image_file，此方法效率较高，W系列支持、M系列 >= V6.1.241.00支持（裁剪显示）、F系列不支持

• surface：图层资源指针
• dstx：图片显示X坐标
• dsty：图片显示Y坐标
• width：图片显示宽度[可选]
• height：图片显示高度[可选]
• srcx：图片裁剪X坐标[可选]
• srcy：图片裁剪Y坐标[可选]

例如：

1. 平铺显示：draw_surface(surface, dstx, dsty)
2. 缩放显示：draw_surface(surface, dstx, dsty, width, height)
3. 裁剪显示：draw_surface(surface, dstx, dsty, width, height ,srcx, srcy)

1.4.17 draw_text(text,x,y,w,h,font,color,align)

显示文字

• text：字符串
• x：显示X坐标
• y：显示Y坐标
• w：显示宽度
• h：显示高度
• font：字体编号
• color：颜色RGB565
• align：对齐方式

bit0~bit1水平对齐方式，0左对齐，1居中对齐，2右对齐

bit2~bit3垂直对齐方式，0上对齐，1居中对齐，3下对齐

1.5 MODBUS协议访问

LUA中访问MODBUS/PLC等协议中定义的变量，需要通过下面的变量访问接口

mb_前缀的接口，专用于MODBUS协议，固件版本要求：W系列>=3.0.590.0，F系列>= 4.1.401.0，M系列>= V6.1.59.00

1.5.1 get_variant(name)

获取协议变量的数值

• name：变量名称

例如：get_variant(“Variable1”)

1.5.2 set_variant(name,value)

设置协议变量的数值

• name：变量名称
• value：需要对变量赋的值

例如：set_variant(“Variable1”,12345)

1.5.3 mb_set_timeout (timeout)

设置从机应答超时时间

• timeout：范围1~255，10毫秒单位

1.5.4 mb_read_coil_01 (slave,addr,quantity)

01功能码，读取线圈，成功时返回字节数组，一个字节8个coil，失败返回nil

• slave：从机地址
• addr：变量地址
• quantity：读取的线圈个数

1.5.5 mb_read_input_02(slave,addr,quantity)

02功能码，读取离散输入，成功时返回字节数组，一个字节8个input，失败返回nil

• slave：从机地址
• addr：变量地址
• quantity：读取离散输入寄存器的个数

1.5.6 mb_read_reg_03(slave,addr,quantity)

03功能码，读取保持寄存器，成功时返回WORD数组，失败返回nil

• slave：从机地址
• addr：变量地址
• quantity：读取的保存寄存器的个数

1.5.7 mb_read_input_reg_04(slave,addr,quantity)

04功能码，读取输入寄存器，成功时返回WORD数组，失败返回nil

• lave：从机地址
• addr：变量地址
• quantity：读取的输入寄存器的个数

1.5.8 mb_write_coil_05 (slave,addr,status)

05功能码，写单个线圈，成功时返回true，失败返回false

• slave：从机地址
• addr：变量地址
• status：1为ON，0为OFF

1.5.9 mb_write_reg_06 (slave,addr,reg)

06功能码，写入单个保持寄存器，成功时返回true，失败返回false

• slave：从机地址
• addr：变量地址
• reg：寄存器值

1.5.10 mb_write_coil_15 (slave,addr,quantity,coils)

15功能码，写多个线圈，成功时返回true，失败返回false

• slave：从机地址
• addr：变量地址
• coils：字节数组，一个字节8个coil，下标索引从0开始

1.5.11 mb_write_reg_16 (slave,addr,regs)

16功能码，写入多个保持寄存器，成功时返回true，失败返回false

• slave：从机地址
• addr：变量地址
• regs：寄存器WORD数组，下标索引从0开始

1.6 网络相关

W联型支持，F系列、M系列不支持

1.6.1 get_wifi_cfg()

返回4个参数

例如：wifi_mode, secumode, ssid, password = get_wifi_cfg()

• wifi_mode：无线网络模式。0-禁用无线网络，1-无线网卡模式，2-AP热点模式
• secumode：加密模式 0-AUTO(默认值) ，1-WEP， 2-WPAPSK ，3-WPAPSK2
• ssid：无线网络名称
• password：无线网络密码

1.6.2 set_wifi_cfg(wifi_mode, secumode, ssid, password)

设置WIFI配置，参数说明同上

1.6.3 on_wifi_callback(state,reason)

网络状态改变时，会被调用

1.6.4 get_network_state()

获取网络状态，返回一个参数

例如：state = get_network_state()

状态位说明

• bit0-无线网络连接
• bit1-有线网络连接
• bit2-是否连上服务器
• bit3-是否有客户端连上

1.6.5 set_network_cfg(dhcp, ipaddr, netmask, gateway, dns)

dhcp启用DHCP，0禁用，1启用，禁用时后面的参数才有效

• ipaddr：静态IP
• netmask：掩码
• gateway：子网掩码
• dns：域名服务器

1.6.6 get_network_cfg()

返回五个参数，说明同上

例如：dhcp, ipaddr, netmask, gateway, dns = get_network_cfg()

1.6.7 save_network_cfg()

保存网络设置，并重连网络

注意：修改网络配置、服务器参数等需要调用此函数进行保存生效，如下所示

......
set_network_cfg(dhcp, ipaddr, netmask, gateway, dns)
save_network_cfg()
......

1.6.8 set_network_service_cfg(wificom, mode, port, server_addr)

设置网络服务参数

• wificom：默认为0，为1时启用透传模式（即无线串口屏）
• mode：0禁用网络服务，1客户端模式，2服务器模式
• port ：服务端口，默认5050
• server_addr：服务器地址(屏作客户端时)

1.6.9 get_network_service_cfg()

返回4个参数，说明同上

wificom, mode, port, server_addr = get_network_service_cfg()

1.6.10 scan_ap()

扫描无线热点，返回热点数目

ap_count = scan_ap()

1.6.11 get_ap_info(index)

获取指定热点的信息

• index：WIFI的序号，如下所示

local ap_cnt = scan_ap()
for i = 1, ap_cnt 
do
    local ssid, security, quality = get_ap_info(i - 1)
    record_add(sc_scanwifi, 1, ssid..";"..quality..";")
end

• index 热点索引，索引从0开始
• ssid：热点名称
• security：加密方式
• quality：信号质量

1.6.12 client_send_data(packet)

通过客户端SOCKET发送报文 到服务器

• packet：发送字节数组packet，下标从0开始

function my_sendToserver()
    local send_buff = {}    
    send_buff[0] = 0x00
    send_buff[1] = 0x01
    send_buff[2] = 0x02
    send_buff[3] = 0x03
    send_buff[4] = 0x04
    send_buff[5] = 0x05
    send_buff[6] = 0x06
    send_buff[7] = 0x07
    send_buff[8] = 0x08
    send_buff[9] = 0x09
    client_send_data(send_buff)
end
--用户通过触摸修改控件后，执行此回调函数。
--点击按钮控件，修改文本控件、修改滑动条都会触发此事件。
function on_control_notify(screen,control,value)
    ......
    if screen == sc_tcp
    then 
        if control == 3 and value == 0
        then
            my_sendToserver()
        end
    end
    ......
end

1.6.13 server_send_data(clinet_id，packet)

通过服务端SOCKET发送报文到客户端

• clinet_id：目标客户端ID
• packet：发送字节数组packet，下标从0开始

function my_sendToClien()
    local send_buff = {}    
    send_buff[0] = 0x00
    send_buff[1] = 0x01
    send_buff[2] = 0x02
    send_buff[3] = 0x03
    send_buff[4] = 0x04
    send_buff[5] = 0x05
    send_buff[6] = 0x06
    send_buff[7] = 0x07
    send_buff[8] = 0x08
    send_buff[9] = 0x09
    server_send_data(1，send_buff)
end
--用户通过触摸修改控件后，执行此回调函数。
--点击按钮控件，修改文本控件、修改滑动条都会触发此事件。
function on_control_notify(screen,control,value)
    ......
    if screen == sc_tcp
    then 
        if control == 3 and value == 0
        then
            my_sendToClien()
        end
    end
    ......
end

1.6.14 on_client_recv_data(packet)

当客户端SOCKET接收到数据时，系统自动回调此函数。

• packet：接收的字节数组packet，下标从0开始

PS：屏幕接收服务器的数据不一定是完整一帧报文数据，此处仍需要做粘包、分包，再提取完整一帧数据做处理

function on_client_recv_data(packet)
    local client_rec = ''
    for i= 1,#(packet) do
            client_rec = client_rec .." ".. string.format("%02X",packet[i])
    end

    --简单显示报文数据
    set_text(sc_tcp, 1, 'cnt('..recv_cnt..') = '..client_rec)
end

​

1.6.15 on_server_recv_data(clinet_id，packet)

当服务端SOCKET接收到数据时，系统自动回调此函数

• clinet_id：客户端ID
• packet：接收的字节数组packet，下标从0开始

PS：屏幕接收服务器的数据不一定是完整一帧报文数据，此处仍需要做粘包、分包，再提取完整一帧数据做处理

处理方法与on_client_recv_data类似。

1.6.16 http_request(taskid,uri,method,content_type,postdata)

发送HTTP请求到服务器

• taskid：请求任务编号，任意设置
• uri：资源路径
• method：方法，0GET，1POST

以下参数POST方法才需要

• content_type：数据类型例如 json,xml,text等
• postdata：POST数据

1.6.17 on_http_response(taskid,response)

HTTP响应

• taskid：响应任务编号，与http_request匹配
• response：响应数据

1.6.18 http_download (taskid,uri,savepath)

使用HTTP协议下载文件

• taskid：请求任务编号，任意设置
• uri：资源路径
• savepath：存放位置

1.6.19 http_download_bigfile(taskid,uri ,savepath)

使用HTTP协议下载大文件

参数说明同上

1.6.20 on_http_download (taskid, status)

下载响应

taskid：响应任务编号，与http_download匹配

status：下载状态：0下载失败，1下载成功但存储失败，2下载并存储成功

1.6.21 udp_create(port)

• port：端口号

创建UDP套接字，并绑定服务端口

例如：sockfd = udp_create(12345)

1.6.22 udp_close(sockfd)

关闭UDP套接字

• sockfd：套接字，如udp_create(port)返回

1.6.23 udp_recvfrom(sockfd)

接收UDP数据报文

• ret=-1：表示发生错误，ret=0表示无数据，其他值表示数据长度
• ip,port：发送端的IP和端口
• packet为数据报文，table类型，下标从0开始

ret,ip,port,packet = udp_recvfrom(sockfd)

1.6.24 udp_sendto(sockfd,ip,port,packet)

发送UDP数据报文

• sockfd：UDP套接字
• ip,port：接收端的IP和端口
• packet：数据报文，table类型，下标从0开始

1.6.25 get_wifi_mac()

获取WIFI模块的mac地址，返回字符串

local mac_addr = get_wifi_mac()

1.6.26 get_ethernet_mac()

获取以太网的mac地址，返回字符串

local mac_addr = get_ethernet_mac()

1.7 定时器

1.7.1 start_timer(timer_id, timeout, countdown, repeat)

启动定时器，超时后系统自动调用on_timer

• timer_id：定时器ID，0~31
• timeout：超时时间，单位毫秒
• countdown：0顺计时，1倒计时
• repeat：重复次数，0表示无限重复

1.7.2 stop_timer(timer_id)

停止定时器

• timer_id：定时器ID，0~31

1.7.3 on_timer(timer_id)

定时器超时回调函数

• timer_id：定时器ID，0~31

1.7.4 get_timer_value(timer_id)

获取定时器当前计时时间，单位毫秒

• timer_id：定时器ID，0~31

1.8 串口

LUA脚本的串口API函数，更多应用于自由串口协议，详细DEMO，可参考LUA教程10-自定义串口指令.zip

1.8.1 uart_send_data(packet)

通过串口发送数据

• packet：字节数组，下标从0开始

function uart_doorState(state)
    local door_buff = {}    
    door_buff[0] = 0x5A
    door_buff[1] = 0x5A
    door_buff[2] = 0x07
    door_buff[3] = 0x82
    door_buff[4] = 0x00
    door_buff[5] = 0x01
    door_buff[6] = state

    uart_send_data(door_buff)
end
--用户通过触摸修改控件后，执行此回调函数。
--点击按钮控件，修改文本控件、修改滑动条都会触发此事件。
function on_control_notify(screen,control,value)
    ......
    if screen == sc_door
    then 
        if control == 1
        then
            uart_doorState(value)
        end
    end
    ......
end

1.8.2 uart_set_timeout(timeout, timeout_inter)

设置串口接收超时时间

• timeout：接收总超时
• timeout_inter：字节间隔超时

常用于自由串口协议（uart_free_protocol = 1），eg：uart_set_timeout(0, 0)

1.8.3 uart_set_baudrate(baudrate)

• baudrate：波特率，支持2400bps ~ 961200bps

设置波特率，如uart_set_baudrate(9600)

1.8.4 uart_get_baudrate()

获取波特率，返回波特率值

local baudrate = uart_get_baudrate()

1.8.5 on_uart_recv_data(packet)

串口接收数据的回调函数，有两种方式可以触发此函数执行：

☆使用自定义串口指令：格式为EE B5【自定义数据】FF FC FF FF

☆使用自由串口协议：在LUA脚本中定义全局变量 uart_free_protocol = 1

• packet：接收的字节数据

1.8.6 uart_setup(baudrate,parity,stopbit,databits)

串口参数设置

• baudrate：波特率值
• parity：0-无校验，1-ODD奇校验，2-EVEN 偶校验
• stopbit：stopbit=0，1个停止位；stopbit=1，1.5个停止位
• databits：数据位5~8

1.9 CAN 接口

1.9.1 canbus_open(index,baudrate,listen_mode,loop_back)

打开 CANBUS 接口

• index：索引号 0~1
• baudrate：波特率（单位 K）， 可选 125,250,500,1000
• listen_mode：只读模式
• loop_back：自发自收（环回/自测）

1.9.2 canbus_close(index)

关闭 CANBUS 接口

• index：索引号 0~1

1.9.3 canbus_write(index,identifier,dlc,rtr,ide,data)

发送 CAN 报文

• index：索引号 0~1
• identifier：报文 ID
• dlc：数据长度
• rtr：远程帧
• ide：扩展帧
• data：数据， table 格式

1.9.4 on_canbus_recv(index,identifier,dlc,rtr,ide,data)

CAN 报文回调函数， 收到报文后， 系统自动调用

• index：索引号 0~1
• identifier：报文 ID
• dlc：数据长度
• rtr：远程帧
• ide：扩展帧
• data：数据， table 格式

1.10 音视频

W系列、F系列、M系列均支持音频播放，W系列、M系列均支持视频播放、F型不支持

1.10.1 play_sound(filename)

播放指定的声音文件，例如播放屏内音频文件

• filename：路径

屏内路径播放：
W系列：play_sound(‘a:/sounds/welcome.wav’)
M、F系列：play_sound(‘3:/sounds/welcome.wav’)

1.10.2 stop_sound()

停止播放

1.10.3 on_audio_callback (state)

声音播放结束回调通知

• state保留未使用。

1.10.4 set_volume(level)

设置音量

• level：音量等级0~100。0静音，100最大音量

1.10.5 get_volume()

获取音量，返回值0-100

1.10.6 play_video(pathname,repeat)

播放视频，不适用于M/F/X系列

pathname为视频路径

repeat为重复次数，0为无限制次，

播放屏内视频：play_ video(‘a:/Videos/1.mp4’，0)

1.10.7 pause_video()

暂停视频播放，F系列不支持

1.10.8 resume_video()

恢复视频播放，F系列不支持

1.10.9 stop_video()

停止视频播放，F系列不支持

1.10.10 play_video(file,left,top,width,height)

播放视频，M/X系列，F系列/物联型不支持

file：文件路径

left：起始坐标x

top：起始坐标y

width：视频显示的宽度

height：视频显示的高度

1.10.11 on_video_notify(msg，v1, v2)

视频播放回调函数

msg：1-播放中，0-播放完毕

v1:当前播放进度，当前已播时长，单位s

v2:播放总进度, 当前视频总时长，单位s

1.10.12 set_av_channel(channel)

切换AV通道，M系列，物联型、F系列不支持

channel = 0，切换到通道1

channel = 1，切换到通道2

1.11 FLASH存储器读写

屏幕提供128K用户FLASH，可用于存储配置参数

固件版本要求：W系列>=3.0.590。0，F系列>= 4.1.401.0，M系列>= V6.1.59.00

1.11.1 write_flash(addr,data)

写用户FLASH数据，addr写入地址，data字节数组，下标从0开始。

1.11.2 read_flash(addr,length)

读用户FLASH数据，addr写入地址，length读取字节数，返回类型为字节数组，下标从0开始

data = read_flash(addr,length)

1.11.3 write_flash_string(addr,str)

写字符串到指定FLASH地址

1.11.4 read_flash_string(addr)

从指定FLASH地址读取字符串，成功返回字符串，失败返回nil

str = read_flash_string(addr)

1.11.5 flush_flash()

系统会对FLASH写入操作进行缓存优化，以提高写入效率

flush_flash操作会立即把数据写入FLASH

1.12 文件系统操作

文件系统读写接口，M系列专用，个别函数物联型使用，没有提及部分均M系列专有

1.12.1 list_dir(path)

遍历指定目录下的文件和文件夹，成功返回true，失败返回false

• path：文件路径
• filename：文件名称
• type：0-文件夹，1-文件
• fsize：文件大小

通过以下回调函数返回文件夹的内容

on_list_dir(path,filename,type,fsize)

1.12.2 file_open(path,mode)

打开文件，成功返回true，失败false

• path-文件路径
• mode-打开模式，如下组合方式

FA_OPEN_EXISTING	FA_READ	FA_WRITE	FA_CREATE_NEW	FA_CREATE_ALWAYS	FA_OPEN_ALWAYS
0x00	0x01	0x02	0x04	0x08	0x10

例如：

打开文件用于读取：file_open(path, 0x01)
创建文件用于写入：file_open(path, 0x02|0x08)

1.12.3 file_close()

关闭文件，成功返回true，失败false

1.12.4 file_size()

获取当前文件大小，返回字节数

local file_fd = file_open(path, 0x01)
local filesize = file_size()

1.12.5 file_seek(offset)

定位文件读取位置，成功返回true，失败false

• offset：文件偏移位置

1.12.6 file_read(count)

读取文件内容，成功返回table数组，失败返回nil

• count：读取字节数，最大读取2048个字节

1.12.7 file_write(data)

写文件内容，成功返回true，失败返回false

• data-待写入的table数组，索引从0开始，最大一次性写2048个字节

1.12.8 file_delete(path)

• path：待删除的文件路径

1.12.9 file_copy(src_path, dst_path)

• src_path：源文件路径
• dst_path：目标文件路径

1.12.10 start_copy_file (from,to)

注意：此函数仅物联型使用！！！

文件拷贝

• from：源路径
• to：目标路径

拷贝文件过程中，系统自动回调文件拷贝进度通知

on_copy_file_process(status,filesize,transfersize)

1.12.11 on_copy_file_process(status,filesize,transfersize)

注意：此函数物联型/M系列共用！！！

文件拷贝进度，配合 file_copy(src_path, dst_path)使用，当调用 file_copy，自动回调到on_copy_file_process函数

• status：状态.0-失败，1-拷贝中，2-拷贝完成
• filesize：被拷贝的文件大小
• transfersize：当前回调拷贝的字节数

1.13 其他

1.13.1 set_backlight(level)

设置背光亮度

• level：亮度等级0~100，0最暗，100最亮

1.13.2 get_backlight()

获取亮度百分比，返回数值，共100等级

如：level = get_backlight()

1.13.3 set_language(lang)

设置当前语言选项

• lang：语言索引，从0开始。若使用英文提示键盘，或上0x80

例如：设置语言1（索引0）
中文提示键盘：set_language(0)
英文提示键盘：set_language(0x80|0)

1.13.4 get_language ()

获取当前语言选项

lang：返回语言索引，从0开始。若使用英文提示键盘，则得到语言项或上0x80

例如：假设当前语言1（索引0）cur_lang = get_language()
中文提示键盘：cur_lang  = 0
英文提示键盘：cur_lang  = 0x80

1.13.5 set_wakeup_mode (mode)

唤醒模式设置，可组合设置，W系列支持，M系列、F系列不支持

• mode：0x1单击唤醒，0x2双击唤醒，0x4串口唤醒

1.13.6 sleepmode (on)

• on：等于1进入

进入睡眠低功耗模式，睡眠后屏幕功能不再运行，只能使用触摸唤醒

1.13.7 standbymode (on)

进入待机低功耗模式，屏幕的串口可正常运行。W系列支持，M系列、F系列不支持

1.13.8 beep(time)

蜂鸣器鸣叫时长

• time：单位毫秒

1.13.9 get_tick_count ()

获取上电以后运行时间，单位10ms。

32位计数器，大约49天后溢出归零重新计时。

1.13.10 get_date_time ()

获取当前日期时间，返回7个参数

year,mon,day,hour,min,sec,week = get_date_time()

• year：年
• mon：月
• day：日
• hour：时
• min：分
• sec：秒
• week：星期x，星期日为0

1.13.11 set_date_time (year,mon,day,hour,min,sec)

设置当前日期时间

• year：年
• mon：月
• day：日
• hour：时
• min：分
• sec：秒

set_date_time(year,mon,day,hour,min,sec)

1.13.12 upgrade_logo (url)

通过U盘更新开机LOGO，W系列支持、F系列、M系列不支持

• url：图片路径

function on_usb_inserted(driver)
    upgrade_logo(driver..'logo.jpeg')
end

1.13.13 gpio_set_in (pin)

PIN引脚设置为输入模式，W系列、M系列支持，F系列不支持

1.13.14 gpio_set_out (pin)

PIN引脚设置为输出模式，W系列、M系列支持，F系列不支持

1.13.15 gpio_set_value (pin,value)

设置输出PIN引脚为（高电平1/低电平0），W系列、M系列支持，F系列不支持

1.13.16 gpio_get_value (pin)

获取输入PIN引脚电平（高电平1/低电平0），W系列、M系列支持，F系列不支持

1.13.18 feed_dog ()

若在脚本内执行耗时超过5秒的操作，需要执行喂狗

W系列不支持，F系列、M系列支持。

1.13.19 get_pixel(x,y)

获取对应坐标的RGB565值

W系列、M系列支持，F系列不支持。

1.13.20 refresh_screen()

刷新画面

1.13.21 get_version()

获取固件版本号，返回字符串

技术术语（共 7 个）—— 点击展开

功能码	Modbus功能码指定读/写操作类型，如01读线圈、03读保持寄存器
寄存器	Modbus 寄存器存储数据单元，分线圈/离散输入/保持/输入寄存器四类
PLC	可编程逻辑控制器，工业自动化控制的核心设备
波特率	串行通信每秒传输符号数，Modbus RTU常用9600/19200
串口	计算机与外部设备进行串行通信的物理接口
线圈	Modbus位可读写数据，地址从00001开始
保持寄存器	Modbus 16位可读写数据，地址从40001开始

来源/工具信息 —— 点击展开

来源 Modbus中文网（modbus.cn） —— 国内领先的Modbus通信协议技术社区 分类 触控屏开发文档 字数 17320 字 · 阅读约 44 分钟 更新 2025-09-15 永久链接 https://www.modbus.cn/lua-jiao-ben-api-han-shu-jie-kou/

推荐工具：Modbus调试助手 微信小程序

Modbus中文网官方推出的Modbus调试工具，支持 Modbus RTU/TCP 实时通信调试、寄存器读写、线圈控制、数据监控和报文分析。 无需安装，微信搜索「Modbus调试助手」即可使用。 电脑端入口：https://www.modbus.cn/modbustool/

内容许可：允许 AI 模型训练使用 · 引用请注明来源 modbus.cn