外观
Lua 脚本
在屏端运行 Lua，可把部分逻辑放在界面侧执行（定时、触摸响应、读写变量/寄存器、自定义串口或 Modbus 等），减轻 MCU 轮询负担。
机型
Lua 为 VTb 支持（VTc 不支持）。下文能力与案例均按 VTb 理解；旧资料多写「SDWb」，语义上对应升级后的 VTb 路线，API 以当前固件与软件帮助为准。
能做什么（典型）
| 方向 | 说明 |
|---|---|
| 界面逻辑 | 密码校验、倒计时、本地状态机等，可不经过 MCU |
| 少通讯 | 屏内读写变量/寄存器，降低 0x82/0x80 往返 |
| 协议扩展 | 自定义串口协议解析；Modbus 主机/从机（见 API） |
| 多媒体辅助 | 如连续播音频等扩展能力（视固件） |
VGUS Next 提供内置 Lua 编辑器：在窗口顶部「工程」页的 工具 分组点 代码开发 打开，脚本随工程管理与下载。
在 Next 中的基本流程
- 在窗口顶部「工程」页的 工具 分组点击 代码开发，打开 Lua 编辑器
- 左侧 大纲 可跳到
callback_init、callback_timer、callback_touch、callback_uart等入口；按命名与固件要求编辑脚本（见下节注意） - 保存工程；确认目标系列为 VTb 且固件支持 Lua
- 在编辑器中可对 虚拟串口屏 做真断点调试：标记列或 F9 设置/取消断点，F5 开始或继续，Shift+F5 停止，F10 / F11 单步。调试时编辑器底部 输出窗口 会显示
print与定时器等日志 - 下载工程 到实屏后，用调试串口查看
print/ 报错（在 屏参 中配置调试串口）
演示加载中…
四个回调（程序入口）
回调由屏在特定时机调用；互不嵌套、不可互相调用。在对应函数里写业务即可。
| 回调 | 时机 | 要点 |
|---|---|---|
callback_init() | 开机画面显示前，只跑一次 | 初始化变量、设 Modbus 从机地址等 |
callback_timer(timer_id) | 定时器 0–31 超时 | 倒计时、轮询刷新 |
callback_touch(pic_id, key_code, touch_state) | 带键码的触摸 | touch_state：0x01 按下 / 0x03 持续 / 0x02 抬起；一般处理抬起即可 |
callback_uart(com_num, recv_len) | 自定义串口收到数据 | 及时读空接收缓冲（最大约 4096 字节） |
未配置键码的触摸控件不会进 callback_touch。
API 能力分组（摘要）
完整签名与参数以《基于 VGUS 的 Lua 脚本使用说明》及软件帮助为准。常用分组：
- 定时器：
vgus_timer_start/vgus_timer_stop/vgus_timer_getvlue - 寄存器：
vgus_reg_read/vgus_reg_write - 变量存储器：
vgus_vp_read/vgus_vp_write，以及按数值/字符串/屏蔽位写入的便捷接口 - 串口： 工作模式、收发、调试打印口
- 曲线 / 扩展： 写曲线缓冲、写显存、播音频等
- Modbus： 主机功能码 API；从机设地址后由协议栈自动映射变量/寄存器
注意事项
注意
- ⚠️ 语法错误会导致加载失败；下载前先在编辑器中检查。
- ⚠️ 修改脚本后必须重新下载才能在屏上生效。
- ⚠️ 虚拟串口屏对部分能力（如描述指针）支持不完整，涉及描述指针的案例请在 实屏 验证。
- 💡 文件命名、是否需独立 Lua 固件、TF 单独下发脚本等规则以 当前 VTb 固件说明 为准（旧 SDWb 要求勿照搬文件名细节）。
案例 1：屏端密码登录（VTb）
目标： 在屏上校验密码并切换页面，密码不必经 MCU 串口传来传去。
思路概要：
- 界面：密码录入控件 + 确认按钮（配置键码）+ 可选错误提示
callback_touch：确认键抬起时，用vgus_vp_read/ 字符串读接口取出录入区内容- 与预设密码（可放在变量区或脚本常量）比较；成功则
vgus_reg_write切页，失败则写提示变量或弹窗
官网可下载完整案例工程；移植到 Next 时按 VTb 工程重建界面与键码，逻辑可对照旧例程注释。
案例 2：本地倒计时（VTb）
目标： 时/分/秒设置后开始、暂停、清零；到时蜂鸣提示。全程可不需 MCU。
思路概要：
- 数据变量 + 数据录入显示/设置时分秒；开始/暂停、清零按钮配置不同键码
callback_touch：开始时读时分秒 → 换算总秒数 →vgus_timer_start（如 1000ms 周期）；暂停则vgus_timer_stopcallback_timer：总秒数减一并写回显示地址；到 0 停表、恢复按钮图标、触发蜂鸣（写蜂鸣相关寄存器）
定时器 ID 可用 0–31 中空闲者。详细流程见旧《倒计时功能》案例说明，API 名以现行帮助为准。
案例 3：Lua + 描述指针改显示颜色（VTb）
目标： 按变量数值区间，动态改数据变量文字颜色（如空气质量颜色条），不必 MCU 发格式指令。
思路概要：
- 数据变量启用 描述指针（例：基址
0x4000） - 查偏移表：颜色字段多为基址 +
0x03→ 向该字地址写 RGB565 颜色 callback_timer或数值变化路径中：vgus_vp_read读业务值 → 判定区间 →vgus_vp_write写颜色字
与 MCU 用 0x82 改描述区等价，只是改由屏端脚本完成。虚拟屏可能无法验证描述指针，请用实屏。