Skip to main content
Version: v2.4.0 (Current)

🌙 Lua Scripting

Lua is the primary engine behind Artok's interactivity. By embedding a lightweight Lua 5.4 VM (Virtual Machine), Artok allows you to write complex UI logic, animations, and hardware communication protocols without needing to recompile your C firmware for every minor change.

⚙️ Why Lua for Embedded?​

While the Core Engine is written in C for speed, Lua provides:

  • Memory Safety: Automatic garbage collection prevents common memory leaks.
  • Rapid Iteration: Update logic on the fly via the Live Simulator.
  • Small Footprint: The VM adds minimal overhead to the MCU (approx. 100-200 KB Flash).
  • Decoupling: Separate your visual UI logic from your critical real-time hardware tasks.

🛠 Scripting Architecture​

Artok uses an Event-Driven model. You don't write a "Main Loop"; instead, you write functions that react to system or user signals.

1. The Global app Object​

Every script has access to the app and system namespaces to control the lifecycle of the interface.

function on_init()
    app:set_screen("dashboard")
    system:set_backlight(80) -- 0-100%
end

2. Widget References​

Widgets are accessed by their ID defined in the Hierarchy Tree.

-- Change a label text based on a button click
function on_btn_click()
    lbl_status:set_text("System Active")
    lbl_status:set_style_text_color(0x00FF00) -- Green
end

🎨 Advanced Logic Examples​

Multi-State Logic​

Handle complex workflows based on sensor data.

function update_temp_display(celsius)
    lbl_temp:set_text(string.format("%.1f °C", celsius))
    
    if celsius > 45.0 then
        img_warning:set_hidden(false)
        bar_heat:set_style_bg_color(0xFF0000) -- Red
    else
        img_warning:set_hidden(true)
        bar_heat:set_style_bg_color(0x222222) -- Dark Grey
    end
end

Custom Animations​

Create bespoke movements not available in the standard AI Interactions.

function pulse_logo()
    local anim = animation:create()
    anim:set_var(img_logo)
    anim:set_values(100, 150) -- Scale from 100% to 150%
    anim:set_time(500)
    anim:set_playback_time(500)
    anim:set_repeat_count(LOOP_INFINITE)
    anim:start()
end

⚡ C and Lua Interop​

Artok makes it easy to pass data between the high-level UI and the low-level C firmware.

DirectionMethodUse Case
C → Luaartok_lua_call("fn_name", value)Sending sensor data to the UI.
Lua → Chardware:pin_write(13, 1)Controlling a GPIO from a UI button.
Sharedsystem:get_variable("v_batt")Reading a shared memory variable.

🚀 Optimization Tips​

  • Localize Variables: Use local my_var = ... inside functions to speed up access and save memory.
  • Avoid while true: Never write blocking loops in Lua; the UI will freeze. Use Timers instead.
  • Garbage Collection: The engine handles this automatically, but for tight memory constraints, you can manually call collectgarbage() after closing large windows.
LUA 5.4 FEATURES

Artok supports modern Lua 5.4 features, including <const> variables and the improved generational garbage collector, perfect for modern MCUs like the ESP32-S3 or STM32H7.

🚀 Next Steps​