串口屏 Lua 脚本 API 速查：回调函数、界面控制与系统接口

发布日期： 2026-11-04

当组态协议和 MODBUS 都覆盖不了需求时——比如对接第三方私有协议、做批量界面联动、或者要做网络应用——就需要 Lua 脚本。恒域威支持 Lua 的串口屏型号内置脚本引擎，本文按功能归类整理常用 API（依据《LUA 脚本 API V1.1》），完整文档见文末下载。

一、事件回调（on_ 系列）：脚本从哪里开始

回调函数	触发时机
on_init	上电初始化，全局入口
on_uart_recv_data	串口收到数据，自由协议解析的主战场
on_control_notify	控件值变化通知（按钮、滑块等）
on_screen_change	画面切换
on_timer / on_systick	定时器 / 系统滴答
on_press / on_draw	触摸按下 / 自定义绘图
on_usb_inserted / on_sd_inserted（含 removed）	U盘 / SD卡插拔
on_wifi_callback / on_http_response / on_http_download	WIFI 与网络应用
on_video_notify / on_audio_callback	视频播放 / 音频事件
on_client_recv_data / on_server_recv_data	网络客户端 / 服务端收数

二、界面读取与控制（get_ / set_ 系列）

读状态：get_value、get_text、get_current_screen、get_date_time、get_version、get_backlight、get_volume、get_language、get_tick_count、get_wifi_mac、get_network_state 等；
控界面：set_text、set_value、set_fore_color、set_back_color、set_enable、set_backlight、set_volume、set_language、set_date_time、set_history_graph_value、set_slide_screen、set_options 等。

配合 send_data 可向串口/网络主动发数据；play_sound、play_video、play_animation 负责多媒体播放。

三、典型用法：自由协议解析

第三方设备常用私有帧格式。在 on_uart_recv_data 回调里按字节解析帧头、指令与数据，再调用 set_value/set_text 把解析结果刷到控件上，即可实现任意协议对接——这是 Lua 方案相对固定协议最大的价值。多任务时序用 on_timer 定时器驱动，避免在主回调里写死循环。

完整文档下载：恒域威开发者资料库（下载中心），含《LUA 脚本 API V1.1》《Lua 脚本语言中文教程》《F 系列 LUA 使用入门》。

配套资料下载

本文 Lua 回调、界面控制与系统接口的完整函数签名，见官方 Lua 脚本文档（已收录下载中心「Lua 脚本」分类）。

前往下载中心获取 Lua 脚本文档 →