VisualHMI - Lua 脚本API函数接口

概述

在 VisualHMI 平台（基于 Lua 5.3） 的嵌入式环境中，并非完整支持 Lua 5.3 的所有库函数。平台对 Lua 标准库进行了裁剪，以适配资源受限的 MCU 环境，并集成了大量HMI 专用 API。

适用范围：VisualHMI - HMI&M系列&Dx系列

例程下载链接：ViusalHMI - Lua脚本.pdf

以下是 VisualHMI 中 Lua 脚本实际可用的核心库函数分类说明

✅ 一、基本语言特性（完全支持）

这些是 Lua 语言核心，通常全部可用：

• 控制结构：if/then/else, while, for, repeat/until

• 函数定义：function ... end

• 表（Table）基础操作

t = {a=1, b=2}
t[1] = "hello"
#t      -- 获取长度（仅对数组部分有效）

• 算术/逻辑/关系运算符：+ - * / % ^, and or not, == ~= < > <= >=、<< >>、&
• 字符串：".."

✅ 二、部分支持的标准库

1. string 库（常用函数支持）

❌ 不支持：string.gmatch, string.rep（长重复可能溢出）

2. table 库（基础操作支持）

❌ 不支持：table.unpack

3. math 库（有限支持）

❌ 不支持：math.log, math.exp（除非明确需要）

❌ 三、通常被禁用的标准库

📌 四、总结开发原则

记住：VisualHMI 的 Lua 是 “Lua 语法 + 平台 API” 的混合体，不是通用 Lua 环境。聚焦于平台提供的专用接口，才能高效、稳定地完成 HMI 逻辑开发。

💡 五、自动生成Lua

VisualHMI平台提供大量专用API接口，配合工程可以完成大部分的内部逻辑处理， MCU可以只参与数据传输部分，不参与逻辑处理。点击菜单工程栏→脚本编程, 默认在工程目录下生成main.lua，且自动定义变量的数据类型，假设工程当前Modbus协议，如下所示：

ENCRYPT_=0    --LUA脚本加密

--数据类型定义
VT_LW = 1    --变量地址
VT_RW = 2    --FLASH存储
VT_0x = 10   --线圈
VT_1x = 11   --输入点
VT_3x = 12   --输入寄存器
VT_4x = 13   --保持寄存器


function on_init()
end

function on_run(screen)
end

function on_update(slave,vtype,addr)
end

function on_draw(screen_id,control_id)
end

定义的数据类型：VT_0x线圈、VT_1x离散输入、VT_3x输入寄存器，VT_4x保持寄存器。在读(get_uint16/get_int16...)、写(set_uint16/set_int16)、on_update中vtype的变量类型，对应定义的变量，如下所示：

--数据类型定义
VT_LW = 1    --变量地址
VT_RW = 2    --FLASH存储
VT_0x = 10   --线圈
VT_1x = 11   --输入点
VT_3x = 12   --输入寄存器
VT_4x = 13   --保持寄存器


function on_init()
    set_bit(VT_0x,0x0000,1) --modbus 协议，设置线圈0x0000地址的值为1
    local val = get_bit(VT_1x,0x0000) --modbus 协议，获取离散输入0x0000地址的值
    set_uint16(VT_4x,0x1000, 1) --modbus 协议，设置保持寄存器0x1000地址的值为1
    local val = get_uint16(VT_3x,0x1000) --modbus 协议，获取输入寄存器0x1000的值
end

function on_update(slave,vtype,addr)
    if slave == 0
    then
        if vtype == VT_4x
        then
            .....
        end
    end
end

1.常用回调函数

1.1.on_init()

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

ENCRYPT_=0    --LUA脚本加密

--数据类型定义
VT_LW = 1    --变量地址
VT_RW = 2    --FLASH存储
VT_0x = 10   --线圈
VT_1x = 11   --输入点
VT_3x = 12   --输入寄存器
VT_4x = 13   --保持寄存器

function on_init()
    dofile('test.lua')--分多文件编辑,加载其他lua文件
    set_uint16(VT_4x, 0x0000, 1)--初始化寄存
end

1.2.on_run(screen)

周期性回调函数，on_run(screen) 是 HMI 系统提供的核心周期性任务调度入口，由系统在每个主循环周期自动调用，用于执行需要定期更新的逻辑，如实时数据显示、状态轮询、后台监控等

❗ 问题：

• 🔴 如HMI作为Modbus RTU Master 时，在on_run高频写入从机设备寄存器，造成通信负载过高，可能引发总线堵塞、设备响应延迟
• 🔴 不可在 on_run 中使用 delay_ms()、长循环、网络同步请求等
• 🔴 严禁在 on_run 内部调用 set_run_cycle()（可能导致调度器死锁）

💡 示例： 即在on_ru设置从机寄存器，需要条件触发式写入，如下所示：

function on_run(screen)
    local start   = get_uint16(VT_4x, 0x1000)  -- 启动标志
    local target  = get_uint16(VT_4x, 0x1001)  -- 目标值
    local current = get_uint16(VT_4x, 0x1002)  -- 当前值

    -- 仅当设备已启动且目标 ≠ 当前值时才操作
    if start == 1 and target ～= current then
        set_uint16(VT_4x, 0x1002, target)
        -- 可选：加一次写入保护，避免重复写
    end
end

1.3.on_update(slave, vtype, addr)

HMI 系统提供的变量变更事件回调函数，当用户操作或脚本逻辑修改了受监控的寄存器/变量值时，系统自动触发该回调。该机制实现了 “数据驱动” 的编程模型：无需轮询，仅在数据变化时响应，极大提升系统效率与实时性。

• slave：站号索引，0开始
• vtype：变量类型，生成main.lua，自动定义变量的数据类型
• addr：变量地址

✅ 会触发 on_update 的场景

❌ 不会触发 on_update 的场景

💡 示例

如下所示，以Modbus 协议为例，当其他回调函数设置寄存器，均不想触发on_update回调，可以定义全局变量如下处理：

ENCRYPT_=0    --LUA脚本加密

EN_ON_UPDATE_API_CB = 1 --全局变量，其他回调函数设置寄存器时，为1执行，为0直接退出

--数据类型定义
VT_LW = 1    --变量地址
VT_RW = 2    --FLASH存储
VT_0x = 10   --线圈
VT_1x = 11   --输入点
VT_3x = 12   --输入寄存器
VT_4x = 13   --保持寄存器

function on_init()
    EN_ON_UPDATE_API_CB = 0

    --user code
    set_uint16(VT_LW, 0x1000，0x55AA)

    EN_ON_UPDATE_API_CB = 1
end

function on_run(screen)
    EN_ON_UPDATE_API_CB = 0
    --user code
    EN_ON_UPDATE_API_CB = 1
end

function on_update(slave, vtype, addr)
    if EN_ON_UPDATE_API_CB == 0
    then
        return
    end

    if slave == 0
    then
        if vtype == VT_4x --保持寄存器
        then
            if addr == 0x1000
            then
                local val = get_uint16(VT_4x, addr)   
                if val == 1
                then
                    set_uint16(VT_4x, 0x0001, val) 
                end
            end
        elseif vtype == VT_0x --线圈
        then
            if addr == 0x0000
            then
                local val = get_uint16(VT_0x, addr)
                if val == 1
                then
                    set_uint16(VT_0x, 0x0001, val) 
                end
            end
        end
    end

    if vtype == VT_LW --内部寄存器
    then
        if addr == 0x1000
        then
            local val = get_uint16(VT_LW, addr)
            if 0x55AA == val
            then
                 set_uint16(VT_4x, 0x0000, val)  
            end
        end
    end
end

function on_draw(screen_id,control_id)
    EN_ON_UPDATE_API_CB = 0

    --user code

    EN_ON_UPDATE_API_CB = 1
end

function on_screen_change(screen)
    EN_ON_UPDATE_API_CB = 0

    --user code
    if screen == 1
    then
        set_bit(VT_0x, 0x0000, 1)
    end

    EN_ON_UPDATE_API_CB = 1
end

1.4.on_screen_change(screen)

画面切换事件回调函数，在每次画面切换完成之后由系统自动调用。该函数用于执行与画面切换相关的初始化、状态同步、资源加载或业务逻辑处理。

1.5.on_press(state, x, y)

系统提供的全局触摸事件回调函数，用于捕获用户在屏幕上的原始触摸操作。该函数由系统在检测到触摸状态变化时自动调用，每 100 毫秒最多触发一次

💡 注意：此函数提供的是底层坐标事件，不依赖于具体控件，即使点击空白区域也会触发。

1.6.on_usb_inserted(driver)

系统提供的U盘插入回调函数，当用户将 U 盘（或 USB 存储设备）成功插入 HMI 设备的 USB 接口，并被系统识别后，系统自动调用此函数。建议用全局变量来记录盘符

💡 示例

g_usb_disk = ''
function on_usb_inserted(driver)
    g_usb_disk= drive..'/'
end

-- 具体文件路径，如U盘目录下的1.txt
>g_usb_disk..'1.txt'

--访问具体文件，建议先判断盘符g_usb_disk是否合法
if g_usb_disk ~= ''
then 
    --usercode 
end

1.7.on_usb_removed()

系统提供的U盘拔出事件回调函数，当用户移除 U 盘后，系统检测到设备断开时自动调用此函数。

💡 示例

function on_usb_removed()
    g_usb_disk= ''
end

1.8.on_sd_inserted(dir)

系统提供的SD卡插入回调函数，当用户将 SD卡成功插入 HMI 设备的SD卡接口，并被系统识别后，系统自动调用此函数。建议用全局变量来记录盘符

💡 示例

g_sd_disk = ''
function on_sd_inserted(dir)
    g_sd_disk= dir..'/'
end

-- 具体文件路径，如SD目录下的1.txt
>g_sd_disk..'1.txt'

--访问具体文件，建议先判断盘符g_sd_disk是否合法
if g_sd_disk ~= ''
then 
    --usercode 
end

1.9.on_sd_removed()

系统提供的SD拔出事件回调函数，当用户移除 SD后，系统检测到设备断开时自动调用此函数

💡 示例

function on_sd_removed()
    g_sd_disk= ''
end

1.10.on_parse_timestamp(screen,control,timestamp)

系统提供的时间显示格式化回调函数，专用于告警记录、数据记录、操作记录表格等内置时间字段的自定义格式。

📊 参数说明

仅在满足以下条件时才会被系统调用：

🔑 control 必须 ≠ 0，控件类型：告警显示、数据记录、操作记录

即：只有所属的控件ID具有有效 ID（非 0） 时，系统才会触发此回调。

💡 示例

function on_parse_timestamp(screen,control,timestamp)
    local year,mon,day,hour,min,sec = make_datetime(timestamp)
    local new_timestamp = ''
    if screen == 0 and control == 1
    then
        return (string.format('%04d-%02d-%02d %02d:%02d:%02d',  year,mon,day,hour,min,sec))
    elseif  screen == 2 and control == 1
    then
        return (string.format('%04d-%02d-%02d %02d:%02d:%02d',  year,mon,day,hour,min,sec))
    end
end

2.读写寄存器函数

2.1.set_notify(enable)

set_notify(enable) 是 HMI 系统提供的全局串口发送通知开关函数，用于临时启用或禁用变量变更时的自动通信行为。

• 当 set_notify(0) 时：后续通过 set_xxx() 修改变量不会触发协议栈向从机（如主板、PLC）发送串口指令
• 当 set_notify(1) 时：恢复默认行为，变量修改会自动通过串口/总线下发

📊 参数说明

💡 示例

--如DCBUS协议下，设置0x1000地址，不通过串口下发给主板：
set_notify(0) -- 禁止通知
set_uint16(VT_LW, 0x1000, 1)--设置参数
set_notify(1)-- 启用通知

2.2.select_slave(slave_id)

HMI 在多从机通信模式（如 Modbus RTU等总线协议）下，通过select_slave，临时指定从站索引，使得后续的 get_xxx() / set_xxx() 操作时，访问指定从机寄存器。

✅ 核心作用：切换指定从站，访问对应从站寄存器。

📊 参数说明

💡 映射关系由 HMI 工程配置决定：

• slave_id = 0 → 站号 = 10
• slave_id = 1 → 站号 = 33

💡 示例

如Modbus RTU协议中，总线有2个从机，第一个从机站号10，第2个从机站号为33，可封装如下函数：

-- 全局：从机在线状态掩码地址（由HMI系统定义）
local SLAVE_ONLINE_MASK_ADDR = 0x01A3

-- 安全读取保持寄存器
function mb_read_holding(slave_index, reg_addr)
    -- 检查从机是否在线（bitN = 1 表示在线）
    local online_mask = get_uint16(VT_LW, SLAVE_ONLINE_MASK_ADDR)
    if (online_mask >> slave_index) & 1 == 0 then
        return nil, "offline"  -- 返回错误状态
    end

    select_slave(slave_index)
    return get_uint16(VT_4x, reg_addr), "ok"
end

-- 安全写入保持寄存器
function mb_write_holding(slave_index, reg_addr, value)
    local online_mask = get_uint16(VT_LW, SLAVE_ONLINE_MASK_ADDR)
    if (online_mask >> slave_index) & 1 == 0 then
        return false
    end

    feed_dog()  -- 防止看门狗复位（长操作时必要）
    select_slave(slave_index)
    set_uint16(VT_4x, reg_addr, value)
    return true
end

-- 读取从机0（站号10）的0x1000寄存器
local val, status = mb_read_holding(0, 0x1000)
if status == "ok" then
    print("Value:", val)
else
    print("From slave offline")
end

-- 写入从机1（站号33）的0x2000寄存器
mb_write_holding(1, 0x2000, 12345)

2.3.set_endian(en)

变量字节序（大小端）设置函数。set_endian(en) 是 HMI 系统在主从机通信模式（如 Modbus、FX3U 等）下提供的全局字节序控制函数，用于指定多字节数据（如 uint16、uint32、float）在通过串口/总线与从机交换时的字节排列顺序。

📊 参数说明

该设置直接影响 set_xxx() 和 get_xxx() 函数在读写寄存器时的底层字节打包/解析方式。

✅ 仅在通信协议涉及多字节数据传输时生效，对纯内部变量（如 VT_LW）通常无影响。

2.4.set_bit(vtype, addr, value， count)

多位寄存器批量写入函数，set_bit(vtype, addr, value, count) 是 HMI 系统提供的批量位寄存器写入函数，用于一次性设置连续多个位寄存器（bit）或单个位寄存器（bit）的状态，适用于 Modbus RTU的线圈（Coils）、FX3U 的 X/Y/S/M 等位寄存器。

📊 参数说明

📡 通信触发机制（关键行为）

调用 set_bit() 并不总是立即发送串口报文。其通信行为受以下两个条件共同约束：

✅ 条件 1 :HMI 处于主机模式（Master Mode）

• 仅当 HMI 配置为 Modbus 主站 、DCBUS或XGUS，如配置为Modbus RTU Master, 才会主动发送串口报文；
• 若为从机模式Slave，此API仅更新本地镜像，不会发送任何报文。

✅ 条件 2：串口通知未被禁止set_notify

• 系统提供 set_notify(enable) 接口用于临时抑制通信输出
• 仅当通知使能（set_notify(1) 或默认状态）时，此API才会主动发送串口报文；
• 若通知被禁用（set_notify(0)），函数仅更新本地缓存

1. 示例：批量下发， Modbus

-- 构建16位控制字（仅低13位有效）
local coils = 0
coils = coils | (get_uint16(VT_LW, g_addr['急停关机']) << 0)   -- bit0: 急停
coils = coils | (get_uint16(VT_LW, g_addr['枪锁']) << 2)       -- bit2: 电子锁
coils = coils | ((get_uint16(VT_RW, g_flash['波特率选择']) > 0 and 1 or 0) << 12) -- bit12: 波特率标志

-- 批量写入13位到线圈区 0x00B6
select_slave(target_slave)
set_bit(VT_0x, 0x00B6, coils, 13)  -- 一次通信完成13个开关控制

2. 示例：单个下发， Fx3U

set_bit(VT_M, 100, 1)

2.5.get_bit (vtype, addr)

位寄存器读取函数。get_bit(vtype, addr) 是 HMI 系统提供的位读取函数，用于读取单个位地址的状态（布尔量：0 或 1）。该函用于读取 Modbus 线圈/输入。

📊 参数说明

🔑 get_bit(vtype, addr) 是从 HMI 的本地缓存（内存镜像）中读取数据，而非实时向 PLC/设备发起串口请求。

🔴 工作机制：

1. HMI 后台任务 按照工程中配置的轮询周期，ModbusRTU为例，自动从 PLC 读取 VT_0、VT_1x 等通信变量；
2. 读取到的数据被缓存在 HMI 内存中，形成“寄存器镜像”；
3. 脚本调用 get_bit(VT_1x, 0x1000) 时，直接返回本地缓存值，不产生新的串口帧；
4. 因此，脚本层的 get_xxx() 是零通信开销的。

✅ 优势：避免脚本逻辑导致通信风暴，保证系统实时性与稳定性

🔁 数据同步机制 -- 主机模式，以Modbus RTU为例

✅ 工程配置

• 在 HMI 工程中，当用户为画面控件、告警条件或资料采样项绑定了通信变量（如 VT_0x:100）时，系统会自动生成后台轮询任务；
• 后续调用 get_bit(VT_0x，100) 即可获得最新值；

📌 示例： 若画面中有一个位状态指示灯绑定到 VT_0x:100，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

✅ 脚本主动触发的按需读取（start_read）

• 当脚本逻辑需要访问未被工程引用的变量时，可调用 start_read(vtype, addr, count) 显式请求数据同步；
• 调用后，HMI 通信任务会将指定地址范围的数据从设备读入本地缓存；
• 后续调用 get_bit() 即可获得最新值；

📌 示例： start_read(VT_0x, 100, 1)，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

💡 示例

local state = get_bit(VT_0x, 0x0000) --获取线圈0x0000地址的状态

2.6.set_uint16(vtype, addr, value)

16位无符号整型寄存器写入函数，set_uint16(vtype, addr, value) 是 HMI 系统提供的16 位无符号整数写入函数，用于向指定地址写入一个 0～65535 范围的数值。

📊 参数说明

✅ 核心用途：实现对 Modbus 保持寄存器、FX3U D 寄存器、HMI 内部变量等 16 位数据区的写入。

📡 通信触发机制（关键行为）

调用 set_uint16() 并不总是立即发送串口报文。其通信行为受以下两个条件共同约束：

✅ 条件 1 HMI 处于主机模式（Master Mode）

• 仅当 HMI 配置为 Modbus 主站 、DCBUS或XGUS，如配置为Modbus RTU Master, 才会主动发送串口报文；
• 若为从机模式Slave，此API仅更新本地镜像，不会发送任何报文。

✅ 条件 2：串口通知未被禁止set_notify

• 系统提供 set_notify(enable) 接口用于临时抑制通信输出
• 仅当通知使能（set_notify(1) 或默认状态）时，此API才会主动发送串口报文；
• 若通知被禁用（set_notify(0)），函数仅更新本地缓存

💡 示例

set_uint16(VT_LW, 0x1000, 12345) --设置屏幕内部寄存器0x1000地址为12345

2.7.get_uint16(vtype, addr)

16位无符号整型寄存器读取函数，get_uint16(vtype, addr)是 HMI 系统提供的16 位无符号整数读取函数，用于向指定地址获取一个 0～65535 范围的数值。

📊 参数说明

🔑 get_uint16(vtype, addr) 是从 HMI 的本地缓存（内存镜像）中读取数据，而非实时向 PLC/设备发起串口请求。

🔴 工作机制：

1. HMI 后台任务 按照工程中配置的轮询周期，自动从 PLC 读取 VT_3x、VT_4x 等通信变量；
2. 读取到的数据被缓存在 HMI 内存中，形成“寄存器镜像”；
3. 脚本调用 get_uint16(VT_3x, 0x1000) 时，直接返回本地缓存值，不产生新的串口帧；
4. 因此，脚本层的 get_xxx() 是零通信开销的。

✅ 优势：避免脚本逻辑导致通信风暴，保证系统实时性与稳定性

🔁 数据同步机制 -- 主机模式，以Modbus RTU为例

✅ 工程配置

• 在 HMI 工程中，当用户为画面控件、告警条件或资料采样项绑定了通信变量（如Modbus RTU Master:VT_4x:100）时，系统会自动生成后台轮询任务；
• 后续调用 get_uint16(VT_4x，100)` 即可获得最新值；

📌 示例： 若画面中有一个数值控件绑定到 VT_0x:100，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

✅ 脚本主动触发的按需读取（start_read）

• 当脚本逻辑需要访问未被工程引用的变量时，可调用 start_read(vtype, addr, count) 显式请求数据同步；
• 调用后，HMI 通信任务会将指定地址范围的数据从设备读入本地缓存；
• 后续调用 get_uint16(VT_4x，100) 即可获得最新值；

📌 示例： start_read(VT_4x, 100, 1)，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

💡 示例

local val = get_uint16 (VT_LW, 0x1000) --获取屏幕内部寄存器0x1000地址的

2.8.set_int16(vtype, addr, value)

16位有符号整型寄存器写入函数，set_int16(vtype, addr, value) 是 HMI 系统提供的16 位有符号整数写入函数，用于向指定地址写入一个-32768 ～ +32767 范围的整数值

📊 参数说明

✅ 核心用途：实现对支持有符号数的 Modbus 寄存器、PLC 数据区或 HMI 内部变量的带符号整型写入

📡 通信触发机制（关键行为）

调用 set_int16() 并不总是立即发送串口报文。其通信行为受以下两个条件共同约束：

✅ 条件 1 HMI 处于主机模式（Master Mode）

• 仅当 HMI 配置为 Modbus 主站 、DCBUS或XGUS，如配置为Modbus RTU Master, 才会主动发送串口报文；
• 若为从机模式Slave，此API仅更新本地镜像，不会发送任何报文。

✅ 条件 2：串口通知未被禁止set_notify

• 系统提供 set_notify(enable) 接口用于临时抑制通信输出
• 仅当通知使能（set_notify(1) 或默认状态）时，此API才会主动发送串口报文；
• 若通知被禁用（set_notify(0)），函数仅更新本地缓存

💡 示例

set_int16(VT_LW, 0x1000, 12345) --设置屏幕内部寄存器0x1000地址为-12345

2.9.get_int16(vtype, addr)

16位有符号整型寄存器读取函数，get_int16(vtype, addr)是 HMI 系统提供的16 位有符号整数读取函数，用于从指定地址获取一个 -32768 ～ +32767 范围的数值。

📊 参数说明

🔑 get_int16(vtype, addr) 是从 HMI 的本地缓存（内存镜像）中读取数据，而非实时向 PLC/设备发起串口请求。

🔴 工作机制：

1. HMI 后台任务 按照工程中配置的轮询周期，自动从 PLC 读取 VT_3x、VT_4x 等通信变量；
2. 读取到的数据被缓存在 HMI 内存中，形成“寄存器镜像”；
3. 脚本调用 get_int16(VT_3x, 0x1000) 时，直接返回本地缓存值，不产生新的串口帧；
4. 因此，脚本层的 get_xxx() 是零通信开销的。

✅ 优势：避免脚本逻辑导致通信风暴，保证系统实时性与稳定

🔁 数据同步机制 -- 主机模式，以Modbus RTU为例

✅ 工程配置

• 在 HMI 工程中，当用户为画面控件、告警条件或资料采样项绑定了通信变量（如Modbus RTU Master:VT_4x:100）时，系统会自动生成后台轮询任务；
• 后续调用 get_int16(VT_4x，100)` 即可获得最新值；

📌 示例： 若画面中有一个数值控件绑定到 VT_4x:100，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

✅脚本主动触发的按需读取（start_read）

• 当脚本逻辑需要访问未被工程引用的变量时，可调用 start_read(vtype, addr, count) 显式请求数据同步；
• 调用后，HMI 通信任务会将指定地址范围的数据从设备读入本地缓存；
• 后续调用 get_int16(VT_4x，100) 即可获得最新值；

📌 示例： start_read(VT_4x, 100, 1)，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

💡 示例

local val = get_int16 (VT_LW, 0x1000)--获取屏幕内部寄存器0x1000地址的值

2.10.set_uint32(vtype, addr, value)

32位无符号整型寄存器写入函数，set_uint32(vtype, addr, value) 是 HMI 系统提供的32 位无符号整数写入函数，用于向指定地址写入一个 0 ～ 4,294,967,295 范围内的整数值。

📊 参数说明

✅ 核心用途：实现对 Modbus 保持寄存器、FX3U D 寄存器等区域的32 位无符号整型数据写入。

📡 通信触发机制（关键行为）

调用 set_uint32() 并不总是立即发送串口报文。其通信行为受以下两个条件共同约束：

✅ 条件 1 HMI 处于主机模式（Master Mode）

• 仅当 HMI 配置为 Modbus 主站 、DCBUS或XGUS，如配置为Modbus RTU Master, 才会主动发送串口报文；
• 若为从机模式Slave，此API仅更新本地镜像，不会发送任何报文。

✅ 条件 2：串口通知未被禁止set_notify

• 系统提供 set_notify(enable) 接口用于临时抑制通信输出
• 仅当通知使能（set_notify(1) 或默认状态）时，此API才会主动发送串口报文；
• 若通知被禁用（set_notify(0)），函数仅更新本地缓存

💡 示例

set_uint32(VT_LW, 0x1000, 123456) --设置屏幕内部寄存器0x1000地址为123456

2.11.get_uint32(vtype, addr)

32位无符号整型寄存器读取函数，get_uint32(vtype, addr)是HMI 系统提供的32 位无符号整数读取函数，用于从指定地址读取一个 0 ～ 4,294,967,295 范围的整数值

📊 参数说明

🔑 get_uint32() 仅从 HMI 内存缓存中读取数据，不会向 PLC/设备发送任何串口指令。

🔴 工作机制：

1. HMI 后台任务 按照工程中配置的轮询周期，自动从 PLC 读取 VT_3x、VT_4x 等通信变量；
2. 读取到的数据被缓存在 HMI 内存中，形成“寄存器镜像”；
3. 脚本调用 get_uint32(VT_3x, 0x1000) 时，直接返回本地缓存值，不产生新的串口帧；
4. 因此，脚本层的 get_xxx() 是零通信开销的。

✅ 优势：避免脚本逻辑导致通信风暴，保证系统实时性与稳定性

🔁 数据同步机制 -- 主机模式，以Modbus RTU为例

✅ 工程配置

• 在 HMI 工程中，当用户为画面控件、告警条件或资料采样项绑定了通信变量（如Modbus RTU Master:VT_4x:100）时，系统会自动生成后台轮询任务；
• 后续调用 get_uint32(VT_4x，100)` 即可获得最新值；

📌 示例： 若画面中有一个数值控件绑定到 VT_4x:100，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

✅ 脚本主动触发的按需读取（start_read）

• 当脚本逻辑需要访问未被工程引用的变量时，可调用 start_read(vtype, addr, count) 显式请求数据同步；
• 调用后，HMI 通信任务会将指定地址范围的数据从设备读入本地缓存；
• 后续调用 get_uint32(VT_4x，100) 即可获得最新值；

📌 示例： start_read(VT_4x, 100, 2)，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

💡 示例

local val = get_uint32 (VT_LW, 0x1000)--获取屏幕内部寄存器0x1000地址的值

2.12.set_int32(vtype, addr, value)

32位有符号整型寄存器写入函数，set_int32(vtype, addr, value) 是 HMI 系统提供的32 位有符号整数写入函数，用于向指定地址的双字地址写入一个 -2,147,483,648 ～ +2,147,483,647 范围内的整数值。

📊 参数说明

✅ 核心用途：实现对 Modbus 保持寄存器、FX3U D 寄存器等区域的32 位有符号整型数据写入。

📡 通信触发机制（关键行为）

调用 set_int32() 并不总是立即发送串口报文。其通信行为受以下两个条件共同约束：

✅ 条件 1 HMI 处于主机模式（Master Mode）

• 仅当 HMI 配置为 Modbus 主站 、DCBUS或XGUS，如配置为Modbus RTU Master, 才会主动发送串口报文；
• 若为从机模式Slave，此API仅更新本地镜像，不会发送任何报文。

✅ 条件 2：串口通知未被禁止set_notify

• 系统提供 set_notify(enable) 接口用于临时抑制通信输出
• 仅当通知使能（set_notify(1) 或默认状态）时，此API才会主动发送串口报文；
• 若通知被禁用（set_notify(0)），函数仅更新本地缓存

💡 示例

set_int32(VT_LW, 0x1000, -123456) --设置屏幕内部寄存器0x1000地址为-123456

2.13.get_int32(vtype, addr)

32位有符号整型寄存器读取函数，get_int32(vtype, addr)是HMI 系统提供的32 位有符号整数读取函数，用于从指定地址读取一个 -2,147,483,648 ～ +2,147,483,647 范围内的整数值

📊 参数说明

🔑 get_int32() 仅从 HMI 内存缓存中读取数据，不会向 PLC/设备发送任何串口指令。

🔴 工作机制：

1. HMI 后台任务 按照工程中配置的轮询周期，自动从 PLC 读取 VT_3x、VT_4x 等通信变量；
2. 读取到的数据被缓存在 HMI 内存中，形成“寄存器镜像”；
3. 脚本调用 get_int32(VT_3x, 0x1000) 时，直接返回本地缓存值，不产生新的串口帧；
4. 因此，脚本层的 get_xxx() 是零通信开销的。

✅ 优势：避免脚本逻辑导致通信风暴，保证系统实时性与稳定性

🔁 数据同步机制 -- 主机模式，以Modbus RTU为例

✅ 工程配置

• 在 HMI 工程中，当用户为画面控件、告警条件或资料采样项绑定了通信变量（如Modbus RTU Master:VT_4x:100）时，系统会自动生成后台轮询任务；
• 后续调用 get_
• int32(VT_4x，100)` 即可获得最新值；

📌 示例： 若画面中有一个数值控件绑定到 VT_4x:100，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

✅ 脚本主动触发的按需读取（start_read）

• 当脚本逻辑需要访问未被工程引用的变量时，可调用 start_read(vtype, addr, count) 显式请求数据同步；
• 调用后，HMI 通信任务会将指定地址范围的数据从设备读入本地缓存；
• 后续调用 get_int32(VT_4x，100) 即可获得最新值；

📌 示例： start_read(VT_4x, 100, 2)，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

💡 示例

local val = get_int32 (VT_LW, 0x1000)--获取屏幕内部寄存器0x1000地址的值

2.14.set_uint64(vtype, addr, value)

64位无符号整型寄存器写入函数，set_uint64(vtype, addr, value) 是 HMI 系统提供的64 位无符号整数写入函数，用于地址写入一个 0 ～ 2⁶⁴−1 范围内的整数值。

📊 参数说明

✅ 核心用途：实现对支持 64 位数据的设备或 HMI 内部变量的超大无符号整型写入。

📡 通信触发机制（关键行为）

调用 set_uint64() 并不总是立即发送串口报文。其通信行为受以下两个条件共同约束：

✅ 条件 1 HMI 处于主机模式（Master Mode）

• 仅当 HMI 配置为 Modbus 主站 、DCBUS或XGUS，如配置为Modbus RTU Master, 才会主动发送串口报文；
• 若为从机模式Slave，此API仅更新本地镜像，不会发送任何报文。

✅ 条件 2：串口通知未被禁止set_notify

• 系统提供 set_notify(enable) 接口用于临时抑制通信输出
• 仅当通知使能（set_notify(1) 或默认状态）时，此API才会主动发送串口报文；
• 若通知被禁用（set_notify(0)），函数仅更新本地缓存

💡 示例

set_uint64(VT_LW, 0x1000, 1234567890) --设置屏幕内部寄存器0x1000地址为1234567890

2.15.get_uint64 (vtype, addr)

64位有符号整型寄存器读取函数，get_uint64(vtype, addr)是HMI 系统提供的64 位有符号整数读取函数，用于从指定地址读取一个0 ～ 2⁶⁴−1 范围内的整数值。

📊 参数说明

🔑 get_uint64() 仅从 HMI 内存缓存中读取数据，不会向 PLC/设备发送任何串口指令。

🔴 工作机制：

1. HMI 后台任务 按照工程中配置的轮询周期，自动从 PLC 读取 VT_3x、VT_4x 等通信变量；
2. 读取到的数据被缓存在 HMI 内存中，形成“寄存器镜像”；
3. 脚本调用 get_uint64(VT_3x, 0x1000) 时，直接返回本地缓存值，不产生新的串口帧；
4. 因此，脚本层的 get_xxx() 是零通信开销的。

✅ 优势：避免脚本逻辑导致通信风暴，保证系统实时性与稳定性

🔁 数据同步机制 -- 主机模式，以Modbus RTU为例

✅ 工程配置

• 在 HMI 工程中，当用户为画面控件、告警条件或资料采样项绑定了通信变量（如Modbus RTU Master:VT_4x:100）时，系统会自动生成后台轮询任务；
• 后续调用 get_uint64(VT_4x，100)` 即可获得最新值；

📌 示例： 若画面中有一个数值控件绑定到 VT_4x:100，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

✅ 脚本主动触发的按需读取（start_read）

• 当脚本逻辑需要访问未被工程引用的变量时，可调用 start_read(vtype, addr, count) 显式请求数据同步；
• 调用后，HMI 通信任务会将指定地址范围的数据从设备读入本地缓存；
• 后续调用 get_uint64(VT_4x，100) 即可获得最新值；

📌 示例： start_read(VT_4x, 100, 4)，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

💡 示例

local val = get_uint64 (VT_LW, 0x1000)--获取屏幕内部寄存器0x1000地址的值

2.16.set_int64(vtype, addr, value)

64位有符号整型寄存器写入函数，set_int64(vtype, addr, value) 是 HMI 系统提供的64 位有符号整数写入函数，用于地址写入一个 -2⁶³ ～ 2⁶³−1范围的整数值。

📊 参数说明

✅ 核心用途：实现对支持 64 位数据的设备或 HMI 内部变量的超大无符号整型写入。

📡 通信触发机制（关键行为）

调用 set_int64() 并不总是立即发送串口报文。其通信行为受以下两个条件共同约束：

✅ 条件 1 HMI 处于主机模式（Master Mode）

• 仅当 HMI 配置为 Modbus 主站 、DCBUS或XGUS，如配置为Modbus RTU Master, 才会主动发送串口报文；
• 若为从机模式Slave，此API仅更新本地镜像，不会发送任何报文。

✅ 条件 2：串口通知未被禁止set_notify

• 系统提供 set_notify(enable) 接口用于临时抑制通信输出
• 仅当通知使能（set_notify(1) 或默认状态）时，此API才会主动发送串口报文；
• 若通知被禁用（set_notify(0)），函数仅更新本地缓存

💡 示例

set_int64(VT_LW, 0x1000, -1234567890) --设置屏幕内部寄存器0x1000地址为-1234567890

2.17.get_int64 (vtype, addr)

64位有符号整型寄存器读取函数，get_int64(vtype, addr)是HMI 系统提供的64 位有符号整数读取函数，用于从指定地址读取一个 -2⁶³ ～ 2⁶³−1 范围内的整数值。

📊 参数说明

🔑 get_int64() 仅从 HMI 内存缓存中读取数据，不会向 PLC/设备发送任何串口指令。

🔴 工作机制：

1. HMI 后台任务 按照工程中配置的轮询周期，自动从 PLC 读取 VT_3x、VT_4x 等通信变量；
2. 读取到的数据被缓存在 HMI 内存中，形成“寄存器镜像”；
3. 脚本调用 get_int64(VT_3x, 0x1000) 时，直接返回本地缓存值，不产生新的串口帧；
4. 因此，脚本层的 get_xxx() 是零通信开销的。

✅ 优势：避免脚本逻辑导致通信风暴，保证系统实时性与稳定性

🔁 数据同步机制 -- 主机模式，以Modbus RTU为例

✅ 工程配置

• 在 HMI 工程中，当用户为画面控件、告警条件或资料采样项绑定了通信变量（如Modbus RTU Master:VT_4x:100）时，系统会自动生成后台轮询任务；
• 后续调用 get_int64(VT_4x，100)` 即可获得最新值；

📌 示例： 若画面中有一个数值控件绑定到 VT_4x:100，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

✅ 脚本主动触发的按需读取（start_read）

• 当脚本逻辑需要访问未被工程引用的变量时，可调用 start_read(vtype, addr, count) 显式请求数据同步；
• 调用后，HMI 通信任务会将指定地址范围的数据从设备读入本地缓存；
• 后续调用 get_int64(VT_4x，100) 即可获得最新值；

📌 示例： start_read(VT_4x, 100, 4)，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

💡 示例

local val = get_int64 (VT_LW, 0x1000)--获取屏幕内部寄存器0x1000地址的值

2.18.set_float(vtype, addr, value)

单精度浮点数寄存器写入函数，set_float(vtype, addr, value) 是 HMI 系统提供的单精度浮点数（IEEE 754 32 位）写入函数，用于向指定地址写入实数值。

📊 参数说明

✅ 核心用途：实现对 Modbus 保持寄存器、PLC 数据区或 HMI 内部变量的浮点型参数设置与指令下发。

📡 通信触发机制（关键行为）

调用 set_float() 并不总是立即发送串口报文。其通信行为受以下两个条件共同约束：

✅ 条件 1 HMI 处于主机模式（Master Mode）

• 仅当 HMI 配置为 Modbus 主站 、DCBUS或XGUS，如配置为Modbus RTU Master, 才会主动发送串口报文；
• 若为从机模式Slave，此API仅更新本地镜像，不会发送任何报文。

✅ 条件 2：串口通知未被禁止set_notify

• 系统提供 set_notify(enable) 接口用于临时抑制通信输出
• 仅当通知使能（set_notify(1) 或默认状态）时，此API才会主动发送串口报文；
• 若通知被禁用（set_notify(0)），函数仅更新本地缓存

💡 示例

set_float(VT_LW, 0x1000，1.234)--设置屏幕内部寄存器0x1000地址为1.234

2.19.get_float (vtype, addr)

单精度浮点数寄存器读取函数，get_float(vtype, addr) 是 HMI 系统提供的单精度浮点数（IEEE 754 32 位）读取函数，用于从指定地址读取一个带小数的实数值。

📊 参数说明

🔑 get_float 仅从 HMI 内存缓存中读取数据，不会向 PLC/设备发送任何串口指令。

🔴 工作机制：

1. HMI 后台任务 按照工程中配置的轮询周期，自动从 PLC 读取 VT_3x、VT_4x 等通信变量；
2. 读取到的数据被缓存在 HMI 内存中，形成“寄存器镜像”；
3. 脚本调用 get_float(VT_3x, 0x1000) 时，直接返回本地缓存值，不产生新的串口帧；
4. 因此，脚本层的 get_xxx() 是零通信开销的。

✅ 优势：避免脚本逻辑导致通信风暴，保证系统实时性与稳定

🔁 数据同步机制 -- 主机模式，以Modbus RTU为例

✅ 工程配置

• 在 HMI 工程中，当用户为画面控件、告警条件或资料采样项绑定了通信变量（如Modbus RTU Master:VT_4x:100）时，系统会自动生成后台轮询任务；
• 后续调用 get_float(VT_4x，100)` 即可获得最新值；

📌 示例： 若画面中有一个数值控件绑定到 VT_4x:100，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

✅ 脚本主动触发的按需读取（start_read）

• 当脚本逻辑需要访问未被工程引用的变量时，可调用 start_read(vtype, addr, count) 显式请求数据同步；
• 调用后，HMI 通信任务会将指定地址范围的数据从设备读入本地缓存；
• 后续调用 get_float(VT_4x，100) 即可获得最新值；

📌 示例： start_read(VT_4x, 100, 4)，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

💡 示例

local val = get_float(VT_LW, 0x1000)--获取屏幕内部寄存器0x1000地址的值

2.20.set_double(vtype, addr, value)

双精度浮点数寄存器写入函数，set_double(vtype, addr, value) 是 HMI 系统提供的双精度浮点数（IEEE 754 64 位）写入函数，用于向指定地址写入一个高精度实数值。

📊 参数说明

✅ 核心用途：实现对 Modbus 保持寄存器、PLC 数据区或 HMI 内部变量的双精度型参数设置与指令下发。

📡 通信触发机制（关键行为）

调用 set_double() 并不总是立即发送串口报文。其通信行为受以下两个条件共同约束：

✅ 条件 1 HMI 处于主机模式（Master Mode）

• 仅当 HMI 配置为 Modbus 主站 、DCBUS或XGUS，如配置为Modbus RTU Master, 才会主动发送串口报文；
• 若为从机模式Slave，此API仅更新本地镜像，不会发送任何报文。

✅ 条件 2：串口通知未被禁止set_notify

• 系统提供 set_notify(enable) 接口用于临时抑制通信输出
• 仅当通知使能（set_notify(1) 或默认状态）时，此API才会主动发送串口报文；
• 若通知被禁用（set_notify(0)），函数仅更新本地缓存

💡 示例

set_double(VT_LW, 0x1000,1.23456789)--设置屏幕内部寄存器0x1000地址为1.23456789

2.21.get_double (vtype, addr)

双精度浮点数寄存器读取函数，get_double(vtype, addr) 是 HMI 系统提供的双精度浮点数（IEEE 754 64 位）读取函数，用于从指定地址读取一个高精度实数值。

📊 参数说明

🔑 get_double 仅从 HMI 内存缓存中读取数据，不会向 PLC/设备发送任何串口指令。

🔴 工作机制：

1. HMI 后台任务 按照工程中配置的轮询周期，自动从 PLC 读取 VT_3x、VT_4x 等通信变量；
2. 读取到的数据被缓存在 HMI 内存中，形成“寄存器镜像”；
3. 脚本调用 get_double (VT_3x, 0x1000) 时，直接返回本地缓存值，不产生新的串口帧；
4. 因此，脚本层的 get_xxx() 是零通信开销的。

✅ 优势：避免脚本逻辑导致通信风暴，保证系统实时性与稳定性

🔁 数据同步机制 -- 主机模式，以Modbus RTU为例

✅ 工程配置

• 在 HMI 工程中，当用户为画面控件、告警条件或资料采样项绑定了通信变量（如Modbus RTU Master:VT_4x:100）时，系统会自动生成后台轮询任务；
• 后续调用 get_double(VT_4x，100)` 即可获得最新值；

📌 示例： 若画面中有一个数值控件绑定到 VT_4x:100，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

✅ 脚本主动触发的按需读取（start_read）

• 当脚本逻辑需要访问未被工程引用的变量时，可调用 start_read(vtype, addr, count) 显式请求数据同步；
• 调用后，HMI 通信任务会将指定地址范围的数据从设备读入本地缓存；
• 后续调用 get_double(VT_4x，100) 即可获得最新值；

📌 示例： start_read(VT_4x, 100, 8)，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

💡 示例

local val = get_double(VT_LW, 0x1000)--获取屏幕内部寄存器0x1000地址的值

2.22.set_string(vtype, addr, strings)

字符串寄存器写入函数，set_string(vtype, addr, str) 是 HMI 系统提供的字符串写入函数，用于向指定地址序列写入一个'UTF-8' 或'GBK' 编码的字符串。

📊 参数说明

✅ 核心用途：实现对 HMI 内部变量或支持字符串的设备寄存器的文本数据写入。

📡 通信触发机制（关键行为）

调用 set_string() 并不总是立即发送串口报文。其通信行为受以下两个条件共同约束：

✅ 条件 1 HMI 处于主机模式（Master Mode）

• 仅当 HMI 配置为 Modbus 主站 、DCBUS或XGUS，如配置为Modbus RTU Master, 才会主动发送串口报文；
• 若为从机模式Slave，此API仅更新本地镜像，不会发送任何报文。

✅ 条件 2：串口通知未被禁止set_notify

• 系统提供 set_notify(enable) 接口用于临时抑制通信输出
• 仅当通知使能（set_notify(1) 或默认状态）时，此API才会主动发送串口报文；
• 若通知被禁用（set_notify(0)），函数仅更新本地缓存

💡 示例

set_string(VT_LW, 0x1000，'Hello VisualHMI)--设置屏幕内部寄存器0x1000地址为Hello VisualHMI

2.23.get_string(vtype, addr，len)

字符串变量读取函数，get_string(vtype, addr, len) 是 HMI 系统提供的字符串读取函数，用于从指定存储区的地址中读取一段以空字符 \0 结尾的文本数据

📊 参数说明

🔑 get_string 仅从 HMI 内存缓存中读取数据，不会向 PLC/设备发送任何串口指令。

🔴 工作机制：

1. HMI 后台任务 按照工程中配置的轮询周期，自动从 PLC 读取 VT_3x、VT_4x 等通信变量；
2. 读取到的数据被缓存在 HMI 内存中，形成“寄存器镜像”；
3. 脚本调用 get_string(VT_3x, 0x1000) 时，直接返回本地缓存值，不产生新的串口帧；
4. 因此，脚本层的 get_xxx() 是零通信开销的。

✅ 优势：避免脚本逻辑导致通信风暴，保证系统实时性与稳定性

🔁 数据同步机制 -- 主机模式，以Modbus RTU为例

✅ 工程配置

• 在 HMI 工程中，当用户为画面控件、告警条件或资料采样项绑定了通信变量（如Modbus RTU Master:VT_4x:100）时，系统会自动生成后台轮询任务；
• 后续调用 get_string(VT_4x，100)` 即可获得最新值；

📌 示例： 若画面中有一个文本控件绑定到 VT_4x:100，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

✅ 脚本主动触发的按需读取（start_read）

• 当脚本逻辑需要访问未被工程引用的变量时，可调用 start_read(vtype, addr, count) 显式请求数据同步；
• 调用后，HMI 通信任务会将指定地址范围的数据从设备读入本地缓存；
• 后续调用 get_string(VT_4x，100) 即可获得最新值；

📌 示例： start_read(VT_4x, 100, 128)，则 HMI 会自动将地址 100 加入轮询列表，并周期性更新其缓存值。

💡 示例

local string = get_string (VT_LW, 0x1000)--获取屏幕内部寄存器0x1000地址的值

2.24.set_uint16_ex(vtype, addr, value1,value2, …, value120)

批量无符号16位寄存器写入函数,set_uint16_ex(vtype, addr, value1, value2, ..., valueN) 是 HMI 系统提供的批量 16 位无符号整数写入函数，用于一次性向连续多个寄存器（最多 120 个）。

📊 参数说明

✅ 核心用途：高效批量设置设备参数。

📡 通信触发机制（关键行为）

调用 set_uint16_ex() 并不总是立即发送串口报文。其通信行为受以下两个条件共同约束：

✅ 条件 1 HMI 处于主机模式（Master Mode）

• 仅当 HMI 配置为 Modbus 主站 、DCBUS或XGUS，如配置为Modbus RTU Master, 才会主动发送串口报文；
• 若为从机模式Slave，此API仅更新本地镜像，不会发送任何报文。

✅ 条件 2：串口通知未被禁止set_notify

• 系统提供 set_notify(enable) 接口用于临时抑制通信输出
• 仅当通知使能（set_notify(1) 或默认状态）时，此API才会主动发送串口报文；
• 若通知被禁用（set_notify(0)），函数仅更新本地缓存

💡 示例

local r_addr = 0x6060
set_uint16_ex(vtype, r_addr,
        1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,
        21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,
        41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,
        61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,
        81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,  101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120)

2.25.set_array(vtype, addr, buff)

批量寄存器写入函数,set_array(vtype, addr, buff) 是 HMI 系统提供的高效批量寄存器写入函数，用于将一个 16 位字（word）数组一次性写入指定起始地址的连续寄存器区域。

与 set_uint16_ex 不同，set_array 接收一个 Lua 表（table）作为缓冲区，而非可变参数列表，更适合程序化生成和动态数据处理。

📊 参数说明

✅ 核心用途：高效写入结构化数据块、通信协议帧、设备配置数组、HMI 内部状态缓存等。

📡 通信触发机制（关键行为）

调用 set_array() 并不总是立即发送串口报文。其通信行为受以下两个条件共同约束：

✅ 条件 1 HMI 处于主机模式（Master Mode）

• 仅当 HMI 配置为 Modbus 主站 、DCBUS或XGUS，如配置为Modbus RTU Master, 才会主动发送串口报文；
• 若为从机模式Slave，此API仅更新本地镜像，不会发送任何报文。

✅ 条件 2：串口通知未被禁止set_notify

• 系统提供 set_notify(enable) 接口用于临时抑制通信输出
• 仅当通知使能（set_notify(1) 或默认状态）时，此API才会主动发送串口报文；
• 若通知被禁用（set_notify(0)），函数仅更新本地缓存

💡 示例

local buff = {}
local r_addr = 0x6060
local index = 120
local data  = 0
for i = 1, 120
do
    buff[i] = i
end
set_array(vtype, r_addr, buff)

2.26.start_read(index,vtype, addr,quantity，cycle，clcye_run，mode)

主机模式下周期性自动读取寄存器的通信控制函数，start_read 是 HMI 在 主机模式（如 Modbus Master、FX3U 主站）下的后台自动轮询机制，用于周期性向从机设备发起读取请求。

📊 参数说明

⚠️ 注意：

• 该函数无返回值；
• 实际数据需通过 get_uint16、get_float 等函数从本地缓存读取；
• 仅在主机模式下有效（如 Modbus RTU/FX3U）。

💡 示例

以Modbus RTU Master模式为例

2.26.1自动后台轮询

• 调用 start_read 后，HMI 系统将该读取任务加入通信调度队列；
• 每个通信周期，系统自动发送 Modbus 请求；
• 返回数据自动写入 HMI 内存镜像区；
• 脚本通过 get_xx(VT_4x, addr) 直接读缓存，无通信延迟。

2.26.2.cycle 与 cycle_run 的调度逻辑

HMI 将通信周期划分为多个“子周期”，用于区分高/低频任务：

🔄 调度时序示例：

1周期 #0 (0ms)   → 读 0x1000（高频）
2周期 #1 (50ms)  → 读 0x1000
3周期 #2 (100ms) → 读 0x1000 + 读 0x2000（低频任务触发）
4周期 #3 (150ms) → 读 0x1000
5周期 #4 (200ms) → 读 0x1000
6周期 #5 (250ms) → 读 0x1000 + 读 0x2000
7...

💡 设计目的：

• 高频变量（如速度、温度）→ cycle=0（每周期读）
• 低频变量（如累计量、状态字）→ cycle=5, cycle_run=4（每 5 周期读一次）→ 降低总线负载，提升系统实时性

2.27.stop_read(index)

停止后台周期性读取任务，stop_read(index) 是 HMI 系统在主机模式（如 Modbus Master、FX3U 主站）下提供的通信任务管理函数，用于停止由 start_read 启动的后台周期性读取任务。调用后，HMI 将立即从通信调度队列中移除该任务，不再向从机设备发送对应的读取指令，但本地缓存中的数据保持不变（保留最后一次成功读取的值）。

📊 参数说明

✅ 核心用途：动态控制通信负载、释放无效轮询、实现按需读取策略。

2.28.stop_all_read()

停止所有脚本启动的后台读取任务，stop_all_read() 是 HMI 系统在主机模式（如 Modbus RTU/TCP Master、FX3U 主站等）下提供的全局通信任务停止函数，用于一次性停止所有由 start_read 启动的后台周期性读取任务

✅ 核心用途：

• 快速释放所有脚本注册的通信资源；
• 适用于系统复位、模式切换、紧急停机等场景；
• 避免逐个调用 stop_read(index) 的繁琐操作。

2.29.set_auto_read(en)

控制“画面绑定变量”自动读取的全局开关，set_auto_read(en) 是 HMI 系统在主机模式（如 Modbus Master、FX3U 主站）下提供的全局通信策略控制函数，用于启用或禁用画面控件所绑定寄存器的自动轮询机制。

📊 参数说明

✅ 核心用途：

• 精细控制通信行为，将“画面自动读取”与“脚本主动读取”解耦；
• 在高性能或低带宽场景下，完全由脚本通过 start_read 接管数据更新；
• 避免系统自动生成冗余或冲突的读取指令。

2.30.create_resp_que()

建响应队列以支持单次读取模式，create_resp_que() 是 HMI 系统在主机模式（如 Modbus Master、FX3U 主站）下提供的通信响应管理函数，用于创建一个临时响应队列，使得后续调用 start_read(..., mode=1) 能够实现仅发送一次读取指令（而非周期性轮询）

核心用途：

• 实现按需单次读取（如设备信息查询、参数加载、诊断请求）；
• 避免为一次性操作启动长期后台任务；
• 与 on_cmd_resp() 配合，可检测是否收到从机响应。

💡 示例

ENCRYPT_=0    --LUA脚本加密

--数据类型定义
VT_LW = 1    --变量地址
VT_RW = 2    --FLASH存储
VT_0x = 10   --线圈
VT_1x = 11   --输入点
VT_3x = 12   --输入寄存器
VT_4x = 13   --保持寄存器

function on_init()
    set_auto_read(0) --脚本控制读
    create_resp_que() --创建队列,可以只读1次存器指令
    start_read(1, VT_4x, 0xA009, 30, 0, 0, 1) --只发一次读A009 ~ A01D 范围的数据
end

2.31.on_cmd_resp(slave,vtype,addr,count,ret,wr)

主机模式通信指令回调函数，on_cmd_resp 是 HMI 系统在主机模式（如 Modbus Master、FX3U 主站）下提供的通信结果异步回调函数，用于捕获每一次读/写指令的执行结果。该函数在 HMI 收到从机响应或发生通信超时后自动触发，是实现通信状态监控、错误处理、流程控制的核心机制。

📊 参数说明

✅ 核心用途：

• 判断单次读写是否成功；
• 实现请求-响应式业务逻辑（如参数下发确认）；
• 配合 create_resp_que() 构建可靠的按需通信流程。

💡 示例

ENCRYPT_=0    --LUA脚本加密

--数据类型定义
VT_LW = 1    --变量地址
VT_RW = 2    --FLASH存储
VT_0x = 10   --线圈
VT_1x = 11   --输入点
VT_3x = 12   --输入寄存器
VT_4x = 13   --保持寄存器

function on_init()
    set_auto_read(0) --脚本控制读
    create_resp_que() --创建队列,可以只读1次存器指令
    start_read(1, VT_4x, 0xA009, 30, 0, 0, 1) --只发一次读A009 ~ A01D 范围的数据
end

function on_cmd_resp(slave,vtype,addr,count,ret,wr)
    print('on_cmd_resp(vtype = '..vtype..', addr = '..(string.format('%04X', addr))..', count = '..count..', ret = '..ret..', wr ='..wr..')')
end

> 通讯成功 ： on_cmd_resp(vtype = 13, addr = A009, count = 30, ret = 0, wr = 0)
>

2.32.set_slave_site(idx, slave_id)

动态修改 从机站号，set_slave_site(idx, slave_id) 是 HMI 系统在主机模式（如 Modbus RTU/TCP Master、FX3U 主站）下提供的从机设备地址动态配置函数，用于在运行时修改已配置从机的站号（Slave ID）。

✅ 核心用途：

• 适应现场设备站号可变的灵活组网需求。

📊 参数说明

3.绘图函数

3.1.on_draw(screen,control)

on_draw 是 HMI 系统提供的控件级自绘回调接口，用于在指定画面的特定控件区域上执行用户自定义的图形绘制。开发者可on_draw函数里调用各类 draw_xxx 图形 API，实现图片、文字、图形(点、线、几何图形)的绘制

📊 参数说明

⚠️ 注意：

1. 该函数为系统回调函数，用户不得直接调用；
2. 所有 draw_xxx 图形绘制指令（如 draw_line、draw_surface 等）必须在此函数内调用才能生效；
3. 控件ID ≠ 0 ，否则自绘功能无效。

3.1.1.触发条件 on_draw

• 界面包含动画、视频、RTC 时间等动态元素刷新；

• 用户触摸或操作屏幕控件；

• 脚本通过 set_xxx更新控件属性；

• 串口/LUA 指令修改寄存器，从而修改控件状态；

• 主动调用 redraw()

3.1.2. 多图层绘制机制

核心原理

HMI 系统采用控件 Z 轴顺序（即界面编辑器中的控件叠放顺序）作为天然的图层管理机制。on_draw(screen_id, control_id) 回调函数在每个可重绘控件独立触发，开发者可通过判断 control_id，将不同的图形内容绘制到对应控件图层（控件叠放上下关系），从而实现逻辑上的“分层叠加”。

✅ 关键设计：控件在界面中的上下排列顺序直接决定了最终视觉的图层叠加顺序。

典型图层结构示例

假设界面从底到顶包含以下元素（Z 轴顺序由低到高）：

📌 注意：

• 蓝色矩形（ID=10）在编辑器中位于黄色矩形（ID=11）下方，因此视觉上被后者部分覆盖；
• 两个矩形均启用自绘功能（ID ≠ 0），系统将在各自区域触发 on_draw。

当系统刷新界面时：

1. 遍历所有需重绘的控件（按 Z 轴从底到顶）；
2. 对每个支持自绘的控件，调用一次 on_draw(screen_id, control_id)；
3. 开发者通过 control_id判断当前绘制目标：
   • 若 control_id == 10 → 在蓝色矩形区域内绘制“水果图片”；
   • 若 control_id == 11 → 在黄色矩形区域内绘制“小岛图片”；
4. 最终合成效果： 原本画面（底） ← 蓝色背景 + 水果（中） ← 黄色背景 + 小岛（顶）

function on_draw(screen_id, control_id)
    if screen_id == 0 and control_id == 1
    then
        draw_surface(surface[1], 293, 88, 222, 353, 0, 0)  --裁剪显示

    elseif screen_id == 0 and control_id == 2
    then
        draw_surface(surface[2], 314, 158, 180, 250, 0, 0) --裁剪显示
    end
end

3.2.redraw()

全局界面重绘触发函数,redraw() 是 HMI 系统提供的全局重绘请求接口，用于主动触发当前画面所有支持自绘的控件执行 on_draw 回调函数，强制刷新界面显示内容。

3.3.set_pen_color(color)

设置绘图画笔颜色，set_pen_color(color) 是 HMI 系统提供的设置画笔颜色函数，用于设置后续所有绘图操作的前景色（画笔颜色），适用于线条、矩形边框、圆形轮廓、文本描边等非填充型或边框型图形的颜色。

📊 参数说明

RGB565 编码示例：

3.4.draw_line(x0,y0,x1,y1,width)

直线绘制函数，draw_line 是 HMI 绘制一条指定起点、终点及线宽的直线段。该线段颜色依赖当前画笔颜（由 set_pen_color 设定）

📊 参数说明

💡 示例

draw_type = 0

mode = {  --绘制类型表
    line = 1,
}

function on_update(slave,vtype,addr)

    if addr == 0x1000
    then
        draw_type = get_uint16(VT_LW, addr) --获取字设置按钮键值
        redraw()--绘图
     end
end

function on_draw(screen_id,control_id)

   local switch = {
        [mode.line] = function(control)
            if screen_id == 0 and control == 1
            then
                --设置画笔黄色划线
                set_pen_color(0xFFE0)
                draw_line(225, 253, 405, 253)

                --设置画笔红色，划线
                set_pen_color(0xF800)
                draw_line(508, 128, 508, 378, 5) 
            end
        end,
    end

    if switch[draw_type]
    then
        switch[draw_type](control)
    end 
end

3.5.draw_rect(x0,y0,x1,y1,fill)

矩形绘制函数，draw_rect 函数是HMI（人机交互界面）开发中常用的绘图接口之一，通过定义左上角和右下角的坐标以及是否填充该矩形，在指定位置绘制一个矩形。

📊 参数说明

💡 示例

draw_type = 0

mode = {  --绘制类型表
    rect = 2,
}

function on_update(slave,vtype,addr)

    if addr == 0x1000
    then
        draw_type = get_uint16(VT_LW, addr)--获取字设置按钮键值
        redraw()--绘图
     end
end

function on_draw(screen_id,control_id)

   local switch = {
        [mode.rect] = function(control)
            if screen_id == 0 and control == 1
            then
                --绘制矩形
                draw_rect(225, 128, (225+180), (128+250), 0)
                draw_rect(418, 163, (418+180), (128+180), 1) 
            end
        end,
    end

    if switch[draw_type]
    then
        switch[draw_type](control)
    end
end

3.6.draw_rect_alpha(x0,y0,x1,y1,alpha)

半透明实心矩形绘制函数，draw_rect_alpha 是 HMI 图形系统提供的半透矩形填充绘图接口，用于指定位内绘制一个带有指定透明度的实心矩形。该函数常用于实现遮罩层

📊 参数说明

💡 示例

draw_type = 0

mode = {  --绘制类型表
    rect_alpha = 3,
}

function on_update(slave,vtype,addr)

    if addr == 0x1000
    then
        draw_type = get_uint16(VT_LW, addr)--获取字设置按钮键值
        redraw()--绘图
     end
end

function on_draw(screen_id,control_id)

   local switch = {
        [mode.rect_alpha] = function(control)
            if screen_id == 0 and control == 1
            then
                --绘制半透矩形
                draw_rect_alpha(225, 128, (225+180), (128+250), 30)
                draw_rect_alpha(418, 163, (418+180), (128+180), 60)
            end
        end,
    end

    if switch[draw_type]
    then
        switch[draw_type](control)
    end 
end

3.7.draw_circle(x,y,r,fill)

圆形绘制函数，draw_circle 是用于绘制圆形的函数。此函数可以基于提供的中心坐标 (x, y)、半径 r 以及填充标志 fill 来绘制一个指定大小和样式的圆形。根据 fill 参数的不同，该函数可以绘制出轮廓圆（非填充）或实心圆（填充）

📊 参数说明

💡 示例

draw_type = 0

mode = {  --绘制类型表
    circle = 4,
}

function on_update(slave,vtype,addr)

    if addr == 0x1000
    then
        draw_type = get_uint16(VT_LW, addr)--获取字设置按钮键值
        redraw()--绘图
     end
end

function on_draw(screen_id,control_id)

   local switch = {
        [mode.circle] = function(control)
            if screen_id == 0 and control == 1
            then
                --绘制圆形
                draw_circle(300, 253, 100, 0)
                draw_circle(450, 253, 150, 1)
            end
        end,
    end

    if switch[draw_type]
    then
        switch[draw_type](control)
    end 
end

3.8.draw_ellipse(x0,y0,x1,y1,fill)

椭圆绘制函数，draw_ellipse 是 HMI 图形系统提供椭圆绘图接口，用于绘制一个内切于指定矩形区域的椭圆。通过控制填充模式与边框表现，可灵活实现从实心椭圆到带厚度轮廓的空心椭圆

📊 参数说明

💡 示例

draw_type = 0

mode = {  --绘制类型表
    ellipse = 5,
}

function on_update(slave,vtype,addr)

    if addr == 0x1000
    then
        draw_type = get_uint16(VT_LW, addr)--获取字设置按钮键值
        redraw()--绘图
     end
end

function on_draw(screen_id,control_id)

   local switch = {
        [mode.ellipse] = function(control)
            if screen_id == 0 and control == 1
            then
                --绘制椭圆
                draw_circle(300, 253, 100, 0)
                draw_circle(450, 253, 150, 1)
            end
        end,
    end

    if switch[draw_type]
    then
        switch[draw_type](control)
    end 
end

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

图片绘制函数，draw_image 是 HMI系统提供绘制图片资源的接口。此函数允许开发者通过指定图片资源ID、显示位置与大小，以及可选的裁剪区域来灵活地控制图像显示。

📊 参数说明

[!note|tip:如何确定image_id] 1.在工程目录下的../build/文件夹，打开image.xml文件，image id = "xx"表示第一个参数

💡 示例

draw_type = 0

mode = {  --绘制类型表
    imageId = 6,
}

function on_update(slave,vtype,addr)

    if addr == 0x1000
    then
        draw_type = get_uint16(VT_LW, addr)--获取字设置按钮键值
        redraw()--绘图
     end
end

function on_draw(screen_id,control_id)

   local switch = {
        [mode.imageId] = function(control)
            if screen_id == 0 and control == 1
            then
                --绘制图片
                draw_image(1, 0, 225, 128, (225+180), (128+250), 0, 0)
                draw_image(2, 0, 418, 163, (418+180), (128+180), 0, 0)
            end
        end,
    end

    if switch[draw_type]
    then
        switch[draw_type](control)
    end 
end

3.10.draw_text(text,x,y,w,h,font_id,size,color,align,charcode)

文本绘制函数，draw_text 是 HMI 图形系统提供的文字绘制接口，用于在指定区域内绘制字符串。支持自定义字体、字号、颜色、对齐方式及字符编码。

📊 参数说明

💡 示例

draw_type = 0

mode = {  --绘制类型表
    text          = 7,
}

function on_update(slave,vtype,addr)

    if addr == 0x1000
    then
        draw_type = get_uint16(VT_LW, addr)--获取字设置按钮键值
        redraw()--绘图
     end
end

function on_draw(screen_id,control_id)

   local switch = {
        [mode.text] = function(control)
            if screen_id == 0 and control == 1
            then
                --绘制文字
                draw_text('Hello HMI&Lua\nCopyright? gz-dc.com ', 195, 96, 408 ,318, 0, 32, 0xF800, 5, 1) 
            end
        end,
    end

    if switch[draw_type]
    then
        switch[draw_type](control)
    end 
end

3.11.load_surface (filename)

图像加载函数,load_surface 用于从指定路径加载 JPEG 或 PNG 格式的图片文件(外部图形,非工程打包的image.bin里的图片资源)，并将其作为句柄（surface）返回。surface后续绘图操作中被引用。

📊 参数说明

⚠️ 关键注意事项

• 路径准确性：确保提供的 filename 路径准确无误，指向有效的 JPEG 或 PNG 文件。
• 内存占用：大尺寸图像或大量图像的同时加载会占用较多内存，应注意资源管理。
• 透明度处理：对于带有透明度信息的 PNG 图像，占用内存比较大

💡 示例

if surface > 0
then
    destroy_surface(surface)
end
surface = load_surface('3:/test.jpg')

3.12.destroy_surface (surface)

图层资源销毁函数，destroy_surface(surface) 用于释放“由 load_surface ”申请的图形资源。调用后，该图层指针失效，不可再用于任何绘图操作

📊 参数说明

✅ 核心用途：

• 防止内存泄漏，尤其在动态加载/卸载图片的场景中；
• 释放 GPU 或帧缓冲区中缓存的图像数据；
• 管理有限的嵌入式系统图形资源。

💡 示例

destroy_surface(surface)

3.13.destroy_all_surface()

批量销毁所有图层资源函数,destroy_all_surface() 是 HMI 图形系统提供的全局图层资源清理接口，用于一次性释放当前脚本上下文中所有已加载的图层（surface）所占用的内存资源。调用后，所有通过 load_surface创建的图层句柄均失效

✅ 核心用途：

• 快速回收全部图像资源，避免逐个管理；
• 简化资源管理逻辑，防止因遗漏导致的内存泄漏。

3.14.draw_surface (surface,dstx,dsty,width,height,srcx,srcy)

draw_surface是绘制由load_surface 申请的图片资源 的接口，将已加载的图层资源（如 JPEG/PNG 图片）绘制到指定位置。支持区域裁剪与尺寸缩放。该函数必须在 on_draw 回调中调用才能生效。

📊 参数说明

💡 示例

draw_type = 0
surface = 0
mode = {  --绘制类型表
    surface_path3 = 8,
}

function on_update(slave,vtype,addr)

    if addr == 0x1000
    then
        if surface > 0
        then
            destroy_surface(surface)
        end
        surface = load_surface('3:/test.jpg')
        --surface = load_surface('1:/test.jpg') --SD卡图片
        --surface = load_surface('2:/test.jpg') --U盘图片
        redraw()--绘图
     end
end

function on_draw(screen_id,control_id)

   local switch = {
        [mode.surface_path3] = function(control)
            if screen_id == 0 and control == 1
            then
                --绘制图片
                draw_surface(surface, 175, 60, 222, 353, 0, 0)
            end
        end,
    end

    if switch[draw_type]
    then
        switch[draw_type](control)
    end 
end

3.15.get_surface_size (surface)

获取图层尺寸函数，get_surface_size(surface) 是 HMI 图形系统提供的图层属性查询接口，用于获取已加载图层（surface）的原始像素尺寸。该函数返回图像的宽度和高度

📊 参数说明

💡 示例

local cur_w,cur_h = get_surface_size (surface)

3.16.clear_image_buffer()

清除内部图片资源缓存函数，clear_image_buffer() 是 HMI 系统提供的全局图像缓存管理接口，用于强制释放图形的图片数据，以降低内存占用

3.17.screen_shoot(filepath)

屏幕截图函数，screen_shoot(filepath) 是 HMI 系统提供的屏幕内容捕获接口，用于将当前显示画面（或指定区域）保存为图像文件（ JPEG 格式）

📊 参数说明

4.数据记录

4.1.record_get_count(sn)

获取资料采样记录总条数函数，record_get_count(sn) 是 HMI 系统提供的数据记录查询接口，用于获取指定资料采样通道（索引为 sn）中已存储的历史记录总条数

📊 参数说明

💡 示例

local cnt = record_get_count(idx)

4.2.record_modify_data(sn, index, data)

修改资料记录内容函数，record_modify_data(sn, index, data) 是 HMI 系统提供的数据记录修改接口，用于修改指定资料采样通道中某一条历史记录的数据内容

📊 参数说明

⚠️ 重要限制：若该资料采样已启用块地址存储模式，数据不可篡改性。

💡 示例1

1. 假设修改第0个资料采样，为uint16，共100个数据，则修改第0行记录为1~100实例如下：

for i = 1, 100
do
    dataTb[i] = i
end
record_modify_data(0, 0, data)

💡 示例2

1. 假设修改第0个资料采样，为uint32，共100个数据，则修改第0行记录为1~100实例如下：

for i = 1, 200
do
    if i % 2 == 0
    then
        dataTb[i] = i
    else
        dataTb[i] = 0
    end
end
record_modify_data(0, 0, data)

uint32共100个参数，共占200个字，所有，data的大小为200。依次类推，64位寄存器为400

4.3.record_write_data(sn, data)

添加资料记录函数，record_write_data(sn, data) 是 HMI 系统提供的数据记录写入接口，用于向指定资料采样通道追加一条新的记录。

📊 参数说明

💡 示例1

1. 假设第0个资料采样，为uint16，共100个数据，添加一条记录，则添加内容为1~100实例如下：

for i = 1, 100
do
    dataTb[i] = i
end
record_write_data(0, data)

💡 示例2

1. 假设第0个资料采样，为uint32，共100个数据，添加一条记录，则添加内容为1~100实例如下：

for i = 1, 200
do
    if i % 2 == 0
    then
        dataTb[i] = i
    else
        dataTb[i] = 0
    end
end
record_write_data(0, data)

4.4.record_read_data(sn, index)

读取资料记录内容函数，record_read_data(sn, index) 是 HMI 系统提供的历史数据查询接口，用于从指定资料采样通道中读取某一条记录的原始数据及其时间戳。

📊 参数说明

返回值

💡 示例1

1. 假设第0个资料采样，为uint16，共100个数据，读取第0个资料采样，第0条数据

local data,timestamp =  record_read_data(0, 0) 
print（'size'..(#data))

>size = 100

💡 示例2

1. 假设第0个资料采样，为uint32，共100个数据，读取第0个资料采样，第0条数据

local data,timestamp =  record_read_data(0, 0) 
print（'size'..(#data))

>size = 200

4.5.record_modify_string(sn, index, strings)

修改字符串类型资料记录函数，record_modify_string(sn, index, strings) 是 HMI 系统为字符串型资料记录通道提供的专用接口，用于修改指定记录行中的内容。每一列数据以分号 ;分隔的字符串形式传入

📊 参数说明

⚠️ 重要限制：若该资料采样已启用块地址存储模式，数据不可篡改性。

💡 示例

--修改第0笔资料，第1行数据的数据为‘item1;item2;item3;item4;item5;’
record_modify_string(0, 0,‘item1;item2;item3;item4;item5;’)

4.6.record_read_string(sn, index)

读取字符串类型资料记录函数，record_read_string(sn, index) 是 HMI 系统为字符串型资料记录通道提供的专用查询接口，用于读取指定记录行的内容及其时间戳。返回的数据以分号 ; 分隔的字符串

📊 参数说明

返回值

💡 示例

假设第0个资料采，为string，读取第0个资料采样，第0条数据

local strings, timestamp = record_read_string(0, 0)
print(‘strings = ’..strings)

> strings = item1;item2;item3;item4;item5;

4.7.record_write_string(sn, strings)

添加字符串类型资料记录函数,record_write_string(sn, strings) 是 HMI 系统为字符串型资料记录通道提供的专用写入接口，用于向指定通道追加一条新的文本记录。数据以分号 ; 分隔的字符串形式传入。

📊 参数说明

💡 示例

假设第0个资料采，为string，添加一条记录“item1;item2;item3;item4;item5;”

--第0笔资料，添加一条记录‘item1;item2;item3;item4;item5;’
 record_write_string( 0,‘item1;item2;item3;item4;item5;’)

4.8.record_clear(sn)

清除资料记录函数，record_clear(sn) 是 HMI 系统提供的资料记录重置接口，用于清空指定通道（sn）中的所有历史记录数据。

📊 参数说明

4.9.on_parse_record(sn,export,datatb)

资料采样记录解析回调函数，on_parse_record(sn, export, datatb) 是 HMI 系统提供的资料记录自定义解析回调接口，属于定制功能。当系统需要显示某条资料采样记录时，会自动调用此函数，允许开发者将原始 word 数组（datatb）转换为自定义显示格式

📊 参数说明

适用于超长(很多列)、每列数据格式不一样的应用，搭配on_get_record_channel(index,channel)使用

4.10.on_get_record_channel(index,channel)

表格单元格数据格式化解析回调函数，on_get_record_channel是 HMI 系统为资料采样表格控件提供的单元格级自定义格式化回调接口（定制功能）。当表格控件需要渲染当前视口（可见区域）内某一单元格时，系统会调用此函数，允许开发者将原始记录中的某字段（word 数据）转换为带单位、小数位数等

📊 参数说明

适用于超长(很多列)、每列数据格式不一样的应用，搭配on_parse_record(index,export,datatb)使用

💡 应用场景 ：on_parse_record + on_get_record_channel

在列头柜智能监控系统中，需要记录144路支路×4参数=576个动态监测点（电压Int16/1位小数、电流Uint16/2位小数、功率Uint32/3位小数、电能Uint32/2位小数），形成工业现场典型的超宽数据矩阵。VisualHMI 通过动态列按需解析的架构，在资源受限的嵌入式HMI上实现毫秒级响应、零卡顿滚动的工业级数据可视化体验。

资料采样配置：

数据记录表格配置：

双回调协同机制：数据流与计算流的精密解耦

📦 数据注入层（on_parse_record）

在Lua脚本on_parse_record回调中，datatb大小为864字

• 若HMI当前没有导出记录export = 0，则赋值给全局变量g_switch_datatb = datatb，return nil

  • g_switch_datatb[1..864] （支路1: [1]=电压, [2]=电流, [3-4]=功率, [5-6]=电能 → 支路144: [859..864]）

• 若HMI当前需要导出记录export = 1，该回调函数会触发N次（当前记录N条记录）。每次回调，拼接144个支路参数形成一条记录，并返回return record_msg

function on_parse_record(index,export,datatb)

    local record_msg = ''

    if index == 0
    then
        if export == 0 --非导出
        then
             g_switch_datatb = datatb
             return nil

        else --导出,拼接每行数据导出

            for i = 1, #datatb,  6
            do
                local u = datatb[i] --INT16
                u = ((u  &  0x8000) == 0x8000) and ((0xFFFF - u - 1)*(-1)) or u

                local a = datatb[i + 1] --UINT16
                local p = ((datatb[i + 2] << 16) | datatb[i + 3]) & 0xFFFFFFFF --UINT32
                local e = ((datatb[i + 4] << 16) | datatb[i + 5]) & 0xFFFFFFFF --UINT32

                u = string.format('%0.1f', (u /   10))..';'
                a = string.format('%0.2f', (a /  100))..';'
                p = string.format('%0.3f', (p / 1000))..';'
                e = string.format('%0.2f', (e /  100))..';'
                record_msg = record_msg..u..a..p..e

           end
        end
    end

    return record_msg
end

单元格解析层（on_get_record_channel）

解析当前视口（可见区域）内的单元格数据格式，并返回。假设：显示第10～20行中的第4～8列动态列时，系统自动忽略不可见列，精准调用55次，函数依据channel参数计算，如下所示： 1️⃣ 数学映射定位 → 根据channel计算支路参数在g_switch_datatb中的偏移

local byPass = (channel // 4) --1~144
local idx = (channel) % 4 --第几个参数/第几列

2️⃣ 格式化数据 → 执行符号处理/高低字拼接/缩放系数转换

if idx == 0 --电压 INT16
then
    val = g_switch_datatb[(byPass)*6 + 1]
    val = ((val  &  0x8000) == 0x8000) and ((0xFFFF - val - 1)*(-1)) or val
    val = string.format('%0.1f', (val /   10))

elseif idx == 1 --电流 UINT16
then
    val = g_switch_datatb[(byPass)*6 + 2]
    val = string.format('%0.2f', (val /  100)

elseif idx == 2 --功率 UINT32
then
    val = ((g_switch_datatb[(byPass)*6 + 3] << 16) | g_switch_datatb[(byPass)*6 + 4]) & 0xFFFFFFFF
    val = string.format('%0.3f', (val / 1000))

elseif idx == 3 --电能 UINT32
then
    val = ((g_switch_datatb[(byPass)*6 + 5] << 16) | g_switch_datatb[(byPass)*6 + 6]) & 0xFFFFFFFF --UINT32
    val = string.format('%0.2f', (val /  100))

end

处理解析当前视口（可见区域）内的单元格数据格式完整代码如下所示：

--表格每通道回调
--index：资料采集索引
--channel:通道,显示当前第几通道
function on_get_record_channel(index,channel) --当下发滚动条拖动时候，channel实时变化

    if index == 0
    then

        local val = 0
        local byPass = (channel // 4) --1~144
        local idx = (channel) % 4 --第几个参数

        if idx == 0 --电压 INT16
        then
            val = g_switch_datatb[(byPass)*6 + 1]
            val = ((val  &  0x8000) == 0x8000) and ((0xFFFF - val - 1)*(-1)) or val
            val = string.format('%0.1f', (val /   10))

        elseif idx == 1 --电流 UINT16
        then
            val = g_switch_datatb[(byPass)*6 + 2]
            val = string.format('%0.2f', (val /  100)

        elseif idx == 2 --功率 UINT32
        then
            val = ((g_switch_datatb[(byPass)*6 + 3] << 16) | g_switch_datatb[(byPass)*6 + 4]) & 0xFFFFFFFF
            val = string.format('%0.3f', (val / 1000))

        elseif idx == 3 --电能 UINT32
        then
            val = ((g_switch_datatb[(byPass)*6 + 5] << 16) | g_switch_datatb[(byPass)*6 + 6]) & 0xFFFFFFFF --UINT32
            val = string.format('%0.2f', (val /  100))

        end

        return val
    end

end

5.告警

在 HMI 系统中，常规告警需求应优先使用内置的“告警设置”进行配置（图形化、可靠、支持历史记录与确认机制）。本文所述的脚本告警 API 仅适用于特殊场景：当告警条目数量庞大、内容高度结构化、触发条件具有逻辑规律时，通过脚本动态生成和管理告警可显著提升开发效率与系统灵活性。

5.1.warning_set_mode(en)

告警触发模式控制函数，warning_set_mode(en) 是 HMI 脚本告警系统的全局使能开关，用于启用后，需要 warning_set 函数的告警触发。

📊 参数说明

💡 示例

ENCRYPT_=0    --LUA脚本加密

--数据类型定义
VT_LW = 1    --变量地址
VT_RW = 2    --FLASH存储

function on_init()
    warning_set_mode(1) --LUA解析告警
end

5.2.warning_set(warning_id,value,count)

批量告警状态设置函数，warning_set() 是 HMI 脚本告警系统的核心操作接口，用于按位批量触发或清除连续的告警条目。该函数将 value 视为一个位掩码（bitmap），其低 count 位分别对应从 warning_id 开始的 count 个告警的状态（1=触发，0=清除）。

🔑 前提条件：必须先调用 warning_set_mode(1) 启用脚本告警模式，否则本函数无效。

📊 参数说明

💡 示例

--读取寄存器值
local err_val = get_uint16(VT_V, 0x1D00)

--将寄存器值的每一个位，对应到告警0~15范围
warning_set(0, err_val , 16)

5.3.on_parse_warning(id, text, screen_id, control_id, p0, p1, p2, p3)

告警内容动态解析回调函数,on_parse_warning 是 HMI 系统提供的告警文本自定义生成接口，开发者根据告警 ID、画面信息，生成自定义的告警描述字符串。

📊 参数说明

返回值

💡 示例

_warningTb = {
--1~96
    '翅片1温度探头故障',
    '翅片2温度探头故障',
    '翅片3温度探头故障',
    '翅片4温度探头故障',
    '回气1温度探头故障',
    '回气2温度探头故障',
    '回气3温度探头故障',
    '回气4温度探头故障',
    '排气1温度探头故障',
    '排气2温度探头故障',
    '排气3温度探头故障',
    '排气4温度探头故障',
    '蒸发1温度探头故障',
    '蒸发2温度探头故障',
    '蒸发3温度探头故障',
    '蒸发4温度探头故障',

    '冷凝1温度探头故障',
    '冷凝2温度探头故障',
    '冷凝3温度探头故障',
    '冷凝4温度探头故障',
    '房内温度探头故障',
    ...
    ...
    ...
    '室内翅片1探头故障',
    '室内翅片2探头故障',
    '室内翅片3探头故障',
    '室内翅片4探头故障',
}

function on_parse_warning(id, text, screen_id, control_id, p0, p1, p2, p3)

--设备1:id0~id95
--...
--...
--...
--设备8:id673~id768

    local slaveId = (id // 96) + 1   --第几个告警
    local msgId = id % 96            --告警类型ID
    local curWarnMsg = ''            --告警描述

    msgId = (msgId == 0) and 1 or (msgId + 1)
    curWarnMsg = math.ceil(slaveId)..'device : '.._warningTb[msgId]

    return curWarnMsg
end

5.4.on_get_warning_param(warning_id)

告警参数动态回调函数,on_get_warning_param(warning_id) 是 HMI 系统提供的告警参数设置接口，当工程告警设置中为启用“告警参数”功能后，系统在显示告警详情时自动调用此函数，通过告警ID，根据具体业务逻辑，返回该告警的参数，支持返回最多 4 个数值/状态参数（data0～data3）；实现个性化、可读性强的告警提示

📊 参数说明

📊 返回值说明

💡 示例1：Lua处理

-- 假设 warning_id = 0 表示温度告警
function on_get_warning_param(warning_id)
    if warning_id == ALARM_TEMP_OVER then
        local current_temp = get_uint16(VT_LW, ADDR_TEMP_SENSOR)
        local threshold = get_uint16(VT_LW,ADDR_TEMP_THRESHOLD)/10
        return current_temp, threshold  -- data0=current, data1=threshold
    end
    -- 其他告警...
end
function on_parse_warning(id, text,  screen_id, control_id, p0, p1, p2, p3)


    if id == ALARM_TEMP_OVER and p0 ~= nil p1 ~= nil then
    then
        return "温度超限：当前温度"..p0.."°C > 额定温度26°C，湿度超限: 当前"..p1.."°C > 80.0°C"
    end

end
-- 告警内容举例: "温度超限：当前温度32°C > 额定温度26°C，湿度超限: 当前85.3°C > 80.0°C"

💡 示例2：告警设置

5.5.on_filter_warning(warning_id)[定制]

告警分类显示过滤回调函数，on_filter_warning(warning_id) 是 HMI 系统提供的告警控制接口，属于定制功能。当一条告警被触发时，系统调用此函数，允许开发者根据 warning_id ,当前的画面ID，返回0 or 1（表示允许显示）。

📊 参数说明

💡 示例

function on_filter_warning(warning_id)

    print('on filter warning('..warning_id..')')
    local ret = 0
    local cur_page = get_screen()
    if warning_id < 100 and cur_page == 0
    then
        ret = 1
    end

    if warning_id > 100 and cur_page == 2
    then
        ret = 1
    end
    return ret
end

5.6.on_select_warning(screen_id,control_id,warning_id,starttime,stoptime,warning_text)[定制]

告警选中事件回调函数（定制功能）,on_select_warning 是 HMI 系统提供的告警交互响应接口，属于定制固件专属功能。当用户在告警列表控件中点击或选中某条告警记录时，系统自动调用此函数，向脚本传递该告警的完整上下文信息，用于触发深度诊断、详细信息等

⚠️ 重要限制：

• 仅在启用定制固件的设备上可用；
• 若工程中为该告警启用了“告警参数”功能，此回调不会被触发（二者互斥）。

📊 参数说明

6.定时器

6.1.start_timer(timer_id, timeout, countdown, repeat)

启动脚本定时器函数,start_timer 是 HMI 系统提供软件定时器。当定时器超时后，系统将自动调用全局回调函数 on_timer(timer_id)，从而实现周期性任务、延时操作、状态轮询等逻辑。

⚠️ 注意：此定时器为应用层软件定时器，精度受系统负载影响，不适用于硬实时控制。

📊 参数说明

6.2.stop_timer(timer_id)

停止脚本定时器函数，stop_timer(timer_id) 是 HMI 系统提供的定时器管理接口，用于立即停止指定 ID 的软件定时器，防止其继续触发 on_timer 回调。

📊 参数说明

6.3.on_timer(timer_id)

定时器超时回调函数，on_timer(timer_id) 是 HMI 系统中定时器事件的统一回调入口。当通过 start_timer 启动的任意定时器超时时，系统会自动调用此函数，并传入对应的 timer_id，开发者可据此执行对于逻辑。

📊 参数说明

💡 示例

如初始化开启1s超时，无限循环的定时器，则每秒输出“hello lua”

function on_timer(timer_id)
    if timer_id == 0
    then
        print('hello lua!!!')
    end
end

function on_init()
    start_timer(0, 1000, 0, 0)    
end

>hello lua!!!
>hello lua!!!
>...

6.4.get_timer_value(timer_id)

获取定时器当前计时值函数，get_timer_value(timer_id) 是 HMI 系统提供的定时器状态查询接口，用于实时获取指定软件定时器的当前计时值（单位：毫秒）。该函数支持顺计时和倒计时两种模式下的读取

📊 参数说明

7.串口

7.1.uart_setup(ch,baudrate,databits,stopbit,parity)

通过 uart_setup(ch, baudrate, databits, stopbit, parity) 函数可对指定串口通道进行通信参数初始化。

📊 参数说明

注意事项

• 主串口：主串口（ch = 0）通常仅仅配置串口数据
• 副串口：未调用 uart_setup 的副串口默认处于关闭状态，无法收发数据。

✅ 在 on_init() 中完成所有副串口的初始化，确保系统启动后即可使用。

7.2.on_uart_recv(ch,packet)

串口数据被动接收回调函数。仅在以下条件下触发：

• 主串口（ch = 0）：需在工程配置中将通讯协议设置为 “自定义”，或在 Lua 脚本中调用set_free_protocol(1) 启用自由协议模式；
• 副串口（ch = 1, 2, ...）：需在脚本初始化阶段（如 on_init()）调用 uart_setup() 完成串口参数配置，系统才会将该通道交由用户脚本管理，并触发此回调。

⚠️ 若主串口已被系统内置协议（如 Modbus、XGUS、FX3U等 等）占用，则主串口 on_uart_recv 不会被调用。

📊 参数说明

💡 关键注意事项

• 数据非帧对齐：packet 可能包含不完整帧（分包）、多帧拼接（粘包） 或任意长度的数据片段，用户必须自行实现缓冲与帧解析逻辑。
• 非中断驱动：该回调由底层的系统任务轮询触发，非硬件中断，应避免在回调中执行耗时操作。
• 副串口必须初始化：未调用 uart_setup(ch, ...) 的副串口不会自动启用，也不会触发回调。
• 主串口（ch = 0）：需在工程配置中将通讯协议设置为 “自定义”，或在 Lua 脚本中调用set_free_protocol(1) 启用自由协议模式；

• DCBUS 与 XGUS 协议对串口参数有固定要求：

  • 停止位：固定为 1 位

  • 校验位：固定为无校验（None）

7.3.uart_send(ch,packet)

向指定串口通道发送字节数组

7.4.set_free_protocol(en)

动态切换主串口（通道 0） 的协议模式，用于在系统内置协议与用户自定义协议之间灵活切换。

📊 参数说明

7.5.uart_rxsize(ch)

读取串口接收缓冲区数据字节数函数，uart_rxsize(ch) 是 HMI 系统提供的串口通信状态查询接口，用于实时获取指定串口通道接收缓冲区中待读取的数据字节数。该函数专为主动式串口协议解析（即脚本轮询读取），用来实现自定义协议功能，详细参考VisualHMI - 自定义协议(主动)(点击跳转)

📊 参数说明

7.6.uart_recv(ch, size)

串口主动接收指定字节数函数，uart_recv(ch, size)是 HMI 系统提供的串口数据读取接口，用于从指定串口的接收缓冲区中主动读取指定数量的字节。该函数需配合 uart_rxsize 使用，构成“查询-读取”主动通信模型，适用于自定义协议解。详细参考VisualHMI - 自定义协议(主动)(点击跳转)

📊 参数说明

7.7.uart_rxclear(ch)

清空串口接收缓冲区函数，uart_rxclear(ch) 是 HMI 系统提供的串口接收缓冲区管理接口，用于立即清空指定串口通道（ch）的接收缓冲区中所有未读取的数据。该函数在自定义串口通信协议开发中至关重要，常用于通信初始化、错误恢复、协议同步等场景，避免残留数据干扰后续帧解析。详细参考VisualHMI - 自定义协议(主动)(点击跳转)

📊 参数说明

7.8.calc_crc16(data)

Modbus CRC-16 校验计算函数，calc_crc16(data) 是 HMI 系统内置的标准 Modbus CRC-16（CRC-16-MODBUS）校验算法实现，用于对指定数据块计算 16 位循环冗余校验码。该函数广泛应用于 Modbus RTU协议的帧完整性验证或组帧，确保串口通信中数据的可靠性。

📊 参数说明

8.音视频

8.1.play_sound(filename)

播放音频文件函数，play_sound(filename) 是 HMI 系统提供的音频播放接口，用于在运行时触发指定音频文件的播放。该功能常用于操作反馈、告警提示、语音引导等场景，提升人机交互的直观性与用户体验。

📊 参数说明

--屏内路径播放：
M：play_sound("3:/sound/welcome.wav")

--SD路径播放：
M：play_sound("1:/welcome.wav")

--U盘路径播放：
M：play_sound("2:/welcome.wav")

8.2.stop_sound()

停止音频播放函数，stop_sound() 是 HMI 系统提供的音频控制接口，用于立即终止当前正在播放的音频文件

8.3.pause_sound()

暂停音频播放函数,pause_sound() 是 HMI 系统提供的音频播放控制接口，用于临时暂停当前正在播放的音频（由 play_sound 启动），并在后续通过 resume_sound() 恢复播放。

8.4.resume_sound()

恢复音频播放函数，resume_sound() 是 HMI 系统提供的音频播放控制接口，用于恢复由 pause_sound() 暂停的音频播放，从暂停时的位置继续播放。该函数必须与 pause_sound() 配套使用。

8.5.play_video(file,left,top,width,height)

视频播放函数，play_video 是 HMI 系统提供的嵌入式视频播放接口，用于在指定屏幕区域播放符合硬件解码能力的 MP4 视频。该功能适用于操作引导、产品演示、安全须知播放等场景，通过富媒体提升人机交互体验

📊 参数说明

⚙️ 视频格式

💡示例

--屏内路径播放：
M：play_video("3:/video/welcome.mp4", 0, 0 800, 480)

--SD路径播放：
M：play_video("1:/welcome.mp4", 0, 0 800, 480)

--U盘路径播放：
M：play_video("2:/welcome.mp4", 0, 0 800, 480)

8.6.pause_video()

暂停视频播放函数，pause_video() 是 HMI 系统提供的视频播放控制接口，用于临时暂停当前正在播放的视频（由 play_video 启动），并在后续通过 resume_video() 从暂停位置继续播放。该功能适用于需要用户交互控制、临时中断演示、同步操作步骤等场景

8.7.resume_video()

恢复视频播放函数,resume_video() 是 HMI 系统提供的视频播放控制接口，用于恢复由 pause_video() 暂停的视频播放，从暂停时的精确帧位置继续播放。该函数必须与 pause_video() 配套使用，共同实现视频的“暂停/继续”交互逻辑，适用于操作引导、教学演示、安全确认等需要用户临时中断并恢复的场景

8.8.stop_video()

停止视频播放函数，stop_video() 是 HMI 系统提供的视频播放终止接口，用于立即停止当前正在播放或已暂停的视频，释放相关解码资源，并清除屏幕上的视频画面。

8.9.on_video_notify(msg，v1, v2)

视频播放状态回调函数，on_video_notify(msg, v1, v2) 是 HMI 系统提供的视频播放事件回调接口，用于在视频播放过程中播放状态与进度信息。

📊 参数说明

8.10.av_init(show,channel,left,top,width,height)

AV 输入初始化函数，av_init 是 HMI 系统提供的模拟输入（AV Input）初始化接口，用于配置并显示来自外部摄像头或视频源（如工业相机、后视摄像头、CVBS 信号）的实时视频流。该功能广泛应用于设备监控、视觉引导、安全预览等需要接入外部模拟视频信号的工业场景。

📊 参数说明

8.11.av_get_status()

获取 AV 播放状态函数,av_get_status() 是 HMI 系统提供的AV 输入状态查询接口，用于检测当前 AV 通道是否正在正常接收并显示外部模拟信号。该函数返回一个状态码，明确指示 AV 输入的实时工作状态，适用于摄像头连接检测、信号有效性判断、故障告警等场景。

📊 参数说明

8.12.av_select(ch)

切换 AV 通道函数，av_select(ch) 是 HMI 系统提供的AV 视频输入通道切换接口，用于在多路 AV 输入源之间动态切换（如通道1 ↔ 通道2）。该功能适用于配备双路模拟输入（如双摄像头、前后视系统）的工业或车载 HMI 设备，实现多视角实时监控与切换。

⚠️ 硬件前提：

• HMI 必须支持至少 2 路 AV 输入通道；

📊 参数说明

8.13.av_show(show)

显示/隐藏 AV 播放函数, av_show(show) 是 HMI 系统提供的AV 显示控制接口，用于动态显示或隐藏当前已初始化的 AV 视频画面，而不中断底层视频信号采集。该功能适用于需要临时遮蔽视频、切换界面焦点、节省渲染资源等场景，实现“后台持续预览 + 前台按需显示”的灵活控制。

📊 参数说明

8.14.video_shoot(filepath, width, height)

视频/AV 画面截图函数。video_shoot(filepath, width, height) 是 HMI 系统提供的实时视频画面捕获接口，用于将当前AV 输入或视频播放窗口的内容截取并保存为 BMP 格式图片。

⚠️ 重要限制说明：视频控件截图截图，特定固件支持。AV输入控件，默认支持

📊 参数说明

8.15.set_color_key(Min_Color,Max_Color,Match)

视频图层色键透明控制函数（M 系列专用），set_color_key 是 M 系列 HMI 专用的视频底层渲染控制接口，用于解决视频图层始终置顶导致无法叠加文字/图形的问题。通过配置一个 RGB 颜色范围 + 比较规则，系统会将视频画面中匹配该颜色范围的像素设为透明，从而允许下层控件（如按钮、文本、图形）透过视频显示，实现“视频+UI 叠加”的混合渲染效果。

📊 参数说明

注：set_color_key(Min_Color,Max_Color,Match)，此API接口函数必须要放在on_init()系统初始化函数中使用，默认在初始时配置的属性

9.文件系统操作

9.1.dofile(name)

Lua 脚本模块加载函数，dofile(name) 是 Lua库提供，用于在运行时加载并执行指定的 .lua 文件。该功能支持将大型脚本工程拆分为多个逻辑模块（如 UI 控制、视频管理、通信协议等），提升代码可读性、可维护性与团队协作效率。

function on_init()
    dofile(‘test.lua’)
end

9.2.list_dir(path)

目录遍历函数，list_dir(path) 是 HMI 系统提供的文件系统目录遍历接口，用于异步扫描指定存储设备或路径下的所有文件与子目录。该函数通过回调机制 on_list_dir(path, filename, type, fsize) 逐项返回结果。

📊 参数说明

M系列存储设备标识：

• '1:' → SD 卡
• '2:' → USB 设备（U盘）
• '3:' → HMI 内部 Flash 存储

DH系列存储设备标识：

• '/sdcard → SD 卡
• '/udisk' → USB 设备（U盘）
• '/data' → HMI 内部 Flash 存储

9.3.on_list_dir(path,filename,type,fsize)

目录遍历结果回调函数,on_list_dir(path, filename, type, fsize) 是 HMI 系统在调用 list_dir(path) 后自动触发的异步回调函数，用于逐项返回指定目录下的文件与子目录信息。该函数由系统在扫描过程中每发现一个条目就调用一次

📊 参数说明

💡 示例

function on_list_dir(path, filename, type, fsize)

    local msg = ''
    if type == 0 --文件夹
    then
    else --文件
         msg = path..'/'..file_name --文件路径
    end
end

9.4.file_open(path,mode)

文件打开函数，file_open(path, mode) 是 HMI 系统提供的底层文件操作接口，用于以指定模式打开本地存储设备（SD卡、U盘、内部Flash）中的文件。该函数是后续进行文件读写等操作的前提，返回布尔值指示操作是否成功。

📊 参数说明

💡 示例

--打开文件读（没有文件创建文件）：
file_open(path, 0x00)

--打开文件覆盖写（没有文件创建文件）：
file_open(path, 0x01)

--打开文件末尾写（没有文件创建文件）：
file_open(path, 0x02)

9.5.file_close()

文件关闭函数，file_close() 是 HMI 系统提供的文件句柄释放接口，用于关闭当前已打开的文件，释放系统资源并确保数据完整写入存储设备。该函数是文件操作（file_open → 读写 → file_close）流程中不可或缺的收尾步骤，尤其在写入操作后调用可防止数据丢失或文件损坏。

📊 参数说明

9.6.file_size()

获取当前打开文件大小函数，file_size() 是 HMI 系统提供的文件信息查询接口，用于获取当前已通过 file_open() 打开的文件的总字节长度。该函数返回值为文件的精确字节数（单位：byte）。

📊 参数说明

💡 示例

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

9.7.file_seek(offset)

文件读写位置定位函数，file_seek(offset) 是 HMI 系统提供的文件指针重定位接口，用于将当前已打开文件的读写位置移动到指定字节偏移处。

📊 参数说明

9.8.file_read(count)

文件内容读取函数，file_read(count) 是 HMI 系统提供的文件数据读取接口，用于从当前已打开的文件中读取指定字节数的数据，并以 Lua 表（table）形式返回字节数组。

📊 参数说明

📊 返回值说明

🔴 内存安全警告： HMI 内存通常有限，读取 文件 文件会直接导致系统崩溃！

🔴 重要内存安全规范： 由于 HMI 设备内存资源极为有限（，严禁将多次读取的数据累积存储于全局变量或长生命周期的缓冲区中。典型错误做法包括：首次读取 2KB 数据存入全局 table，后续每次再读取 2KB 并追加至该 table。此类操作会导致内存持续增长，当处理大文件时，极易引发内存溢出，触发系统看门狗复位，造成设备无预警重启。

正确使用原则： 应采用流式处理（streaming）模式——每次调用 file_read(2048) 后，立即对当前数据块进行解析、校验、写入或显示等处理，处理完毕即释放该数据块，不得保留引用。确保任何时刻内存中仅存在一个不超过 2KB 的临时数据缓冲，从而保障系统长期稳定运行。

💡 示例

local tb = file_read(2048)

9.9.file_write(data)

文件写入函数，file_write(data) 是 HMI 系统提供的底层文件写入接口，用于将指定的字节数据写入当前已通过 file_open() 成功打开的文件中。

📊 参数说明

📊 返回值说明

🔴 重要内存安全规范： HMI 设备内存资源极其有限，严禁在写入前将整个大文件内容（如几 MB 的数据）预先生成并存入全局或局部 table 中。典型错误做法包括：先构造一个包含数万字节的完整数据缓冲区，再分多次调用 file_write() 写入。此类操作在数据准备阶段就可能因内存分配过大而触发系统内存溢出，导致设备在实际写入前即发生无预警重启。

🔴 正确使用原则： 应采用流式生成与写入（streaming write）模式——每次仅准备不超过 2048 字节的待写数据块，立即调用 file_write() 写入文件，随后释放该数据块，再生成下一块。确保任意时刻内存中仅存在一个 ≤2KB 的临时写入缓冲，避免累积大尺寸数据结构。

此规范与 file_read() 的流式处理原则一致，是保障 HMI 系统在文件写入操作中稳定运行、防止因内存过载而崩溃的核心开发准则。

💡 示例

local ret = file_write(write_byte_Tb) -- 1 ≤ data 数组大小 ≤ 2048
return ret

9.10.file_delete(path)

文件删除函数，file_delete(path) 是 HMI 系统提供的文件系统管理接口，用于删除指定路径下的文件。操作成功后，文件将从存储设备中永久移除，且不可恢复。

📊 参数说明

💡 示例

file_delete('1:/1.txt')

9.11.file_copy(src_path, dst_path)

文件复制函数，file_copy(src_path, dst_path) 是 HMI 系统提供的文件系统操作接口，用于将指定源路径的文件完整复制到目标路径，系统会自动触发文件拷贝进度回调函数on_copy_file_process(status, filesize, transfersize)

📊 参数说明

💡 示例

file_copy('1:/1.txt', '1:/1_copy.txt') --从SD卡目录下，复制1.txt为1.copy.txt

9.12.on_copy_file_process(status,filesize,transfersize)

文件拷贝进度回调函数，on_copy_file_process(status, filesize, transfersize) 是 HMI 系统在调用 file_copy(src_path, dst_path) 后自动触发的异步进度回调函数，用于实时反馈文件复制的状态与传输进度

📊 参数说明

💡 示例

function on_copy_file_process(status,filesize,transfersize)

    local progress        = 0

    if status == 0 -- 复制失败
    then

    elseif status == 1 --复制中
    then
        local prg = ((transfersize*100) // filesize) --计算百分比进度

    elseif status == 2 -- 复制成功
    then   
    end

    refresh_screen()-- 刷新界面
end

9.13.mkdir(dir)

在 VisualHMI 平台中，mkdir(dir) 是系统提供的同步文件夹创建接口，用于在指定存储设备路径下创建一个新目录（文件夹）

📊 参数说明

💡扩展：删除目录

在嵌HMI 的文件操作系统中，不支持递归删除目录，仅仅支持删除非空目录，必须按照下面流程操作：

📚 流程

⚠️ 关键约束

• file_delete() 仅支持删除空目录： 若目录非空，调用 file_delete() 将静默失败或返回错误（具体行为取决于 HMI 平台实现，但绝不会自动递归删除）。
• 所有删除操作均为物理删除，不可恢复。

💡扩展：重命名目录

HMI 系统（如基于 FAT/FAT32 的 VisualHMI 平台）中，文件系统层不支持对目录项直接重命名操作。因此，实现“目录重命名“”需通过 模拟重命名 的多步流程完成。

由于底层文件系统不支持 rename() 系统调用对目录的直接重命名，必须通过“创建新目录 → 递归迁移内容 → 删除原目录”的三阶段事务性操作来实现逻辑重命名。

📚 流程

10.CAN 接口

10.1.canbus_open(index,baudrate,listen_mode,loop_back)

CAN 总线接口打开函数,canbus_open(index, baudrate, listen_mode, loop_back) 是 HMI 系统提供的CAN 总线初始化接口，用于配置并启用指定的 CAN 控制器。该函数完成波特率设置、工作模式选择及环回测试使能等关键参数配置，是进行后续 CAN 报文收发（如 canbus_send()、on_canbus_rx()）的前提。

📊 参数说明

10.2.canbus_close(index)

CAN 总线接口关闭函数，canbus_close(index) 是 HMI 系统提供的CAN 总线资源释放接口，用于关闭并禁用指定索引的 CAN 控制器，停止其收发功能并释放相关硬件或驱动资源。

📊 参数说明

10.3.canbus_write(index,identifier,dlc,rtr,ide,data)

CAN 报文发送函数，canbus_write(index, identifier, dlc, rtr, ide, data) 是 HMI 系统提供的CAN 总线报文发送接口，用于向指定 CAN 通道发送一帧标准或扩展格式的 CAN 报文。该函数支持数据帧与远程帧，是实现设备控制、状态请求、数据上报等 CAN 通信功能的核心操作。

📊 参数说明

10.4.on_canbus_recv(index,identifier,dlc,rtr,ide,data)

CAN 报文接收回调函数，on_canbus_recv(index, identifier, dlc, rtr, ide, data) 是 HMI 系统在成功接收到有效 CAN 报文后自动触发的异步回调函数。

📊 参数说明

💡 示例

以下是例子为楼宇对讲、电梯联动、智能门禁等应用，实现地面站PLC与楼层HMI分机之间的双向通信控制