VisualHMI Lua API 大全：回调/통신/레지스터读写函数速查表

这是 VisualHMI 平台 Lua 스크립트的完整 API 手册：10 个系统回调 + 32 个读写레지스터函数 + 10 个绘图函数，共 52 个인터페이스。写스크립트前先翻这篇，比逐个翻튜토리얼快。平台基于 Lua 5.3。

0. 基础：自动生成的 main.lua

菜单 엔지니어링→스크립트编程 默认生成 main.lua，自动带프로토콜对应的데이터유형定义：

ENCRYPT_ = 0        -- LUA스크립트加密开关
-- 데이터유형定义（随프로토콜变化，以下为 Modbus）
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

FX3U 프로토콜下还会有 VT_M（内部릴레이）、VT_D（D레지스터）等유형。on_update 里的 vtype、get/set 函数第一个매개변수都用这些常量。

1. 常用回调函数（10 个）

2. 读写레지스터函数（32 个）

2.0 先说两个关键机制（所有 set/get 通用）

机制一：get_xxx() 是零통신开销的。get 시리즈전체从 HMI 本地缓存（内存镜像）读，不产生시리얼 포트帧。HMI 后台任务按엔지니어링설정的轮询周期自动从 PLC 读통신변수（如 Modbus 的 VT_3x/VT_4x）并缓存。화면控件绑定了某주소，该주소就自动进轮询列表；스크립트要读没被엔지니어링引用的주소，用 시작_read 显式请求同步。

机制二：set_xxx() 不一定发시리얼 포트帧。只有两个条件同时满足才主动发프레임：①HMI 是主机모드（Modbus Master/DCBUS/XGUS）；②시리얼 포트通知没被 set_notify(0) 禁止。从机모드下 set 只更新本地镜像。

2.1 통신控制

2.2 位操作

2.3 数值读写（16/32/64 位）

所有 get 시리즈读本地缓存；set 시리즈통신触发看「机制二」。

2.4 문자串与批量

3. 绘图函数（10 个）

전체 draw_xxx 必须在 on_draw(screen_id,control_id) 回调里调用才生效，控件 ID 必须 ≠ 0。图层按控件 Z 轴（편집器叠放顺序）管理，靠判断 control_id 分层绘制。主动새로고침调 redraw()。

4. 绘图实例：switch 表驱动

源文所有绘图예제都是一个套路：on_update 读버튼键值 → redraw() → on_draw 里按键值查 switch 表选绘制函数。以画线+画圆为例：

draw_type = 0
mode = { line = 1, rect = 2, rect_alpha = 3, circle = 4, ellipse = 5, imageId = 6, 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.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,
    [mode.circle] = function(control)
      if screen_id == 0 and control == 1 then
        draw_circle(300, 253, 100, 0)  -- 实心圆
        draw_circle(450, 253, 150, 1)  -- 空心圆，线厚1
      end
    end,
  }
  if switch[draw_type] then switch[draw_type](control_id) end
end

整理自 广州大彩科技 VisualHMI 개발문서（hmi-doc.gz-dc.com）LUA 튜토리얼「Lua 스크립트API函数인터페이스」，版权归大彩科技所有。