VisualHMI system callback functions: a comprehensive explanation of on_init/on_run/on_press/on_update

System callbacks areevent interfacesbetween LUA and the HMI kernel: the kernel automatically calls your functions at specific times, eliminating the need for polling or manual triggering. Understanding the triggering timing and limitations of each callback is a prerequisite for writing stable scripts.

1. Callback overview table

2. on_run: periodic scheduling (be careful not to get stuck)

on_run is a periodic callback, and the duration of work inside must be much shorter than the period. Three taboos:

• Modbus RTU Master high-frequency writing is prone to bus congestion-- do not send write frames wildly every second in on_run
• do not use delay_ms, long loops, or network synchronization-- block the main loop, causing the entire screen to freeze
• strictly prohibit set_run_cycle deadlock—— Changing the period in the callback may cause it to never trigger.

function on_init()
  set_run_cycle(1000)     -- 设定 1 秒周期
end
function on_run(screen)
  -- 每秒做一次的事情：状态轮询、超时判断
end

3. on_press: Touch callback and idle standby.

on_press(state, x, y), state: 0=lifted, 1=pressed, 2=long pressed. It is triggered at most once every 100ms. Typical uses areidle standby energy saving: automatically turn off the screen/jump to the homepage if there is no touch for a period of time.

_IDLE_TIMEOUT = 300000   -- 5分钟无操作
_idle_tick = 0
function on_press(state, x, y)
  _idle_tick = 0          -- 有触摸就重置计时
end
function on_run(screen)
  _idle_tick = _idle_tick + 1000   -- 假设周期1s
  if _idle_tick >= _IDLE_TIMEOUT then
    set_screen(0)         -- 跳回主画面
    _idle_tick = 0
  end
end

4. on_update: Data-driven (prefer this)

on_update(slave, vtype, addr) is triggered when the variable value changes, which isdata-drivenmode - more resource-efficient than on_run polling. Three features must be known:

• External serial port/Modbus master write does not trigger- only valid for changes in HMI internal variables
• Internal set_xxx in on_update is blocked—— Prevents infinite recursion, and changing the value will not trigger it again.
• Global variable _EN_ON_UPDATA_API_ controls the switch.—— Setting it to 0 can temporarily disable it, used during batch initialization.

_EN_ON_UPDATA_API_ = 0    -- 初始化期间关回调
-- ... 批量写寄存器 ...
_EN_ON_UPDATA_API_ = 1    -- 开回回调

function on_update(slave, vtype, addr)
  if vtype == VT_LW then
    if addr == 0x1000 then
      -- LW1000 变化了，处理业务
    end
  end
end

5. on_screen_change: Initialization after screen switching.

Triggered after screen switching is complete, performs initialization, state synchronization, and resource loading for the current screen — more stable than processing before screen switching.

This is adapted from the VisualHMI development documentation of Guangzhou Dacai Technology (hmi-doc.gz-dc.com), LUA tutorial "System Callback", copyright reserved by Dacai Technology.