ezOS

Introduction

ezOS provides a comprehensive Lua API for building applications on the T-Deck Plus hardware. This reference documents all available functions, organized by module.

Memory Model

• Lua allocations use PSRAM — The Lua VM allocates all memory from the 8MB PSRAM, not the limited 320KB internal SRAM
• Strings are immutable — Each string operation creates a new string; avoid concatenation in loops
• Tables use memory — Empty tables take ~40 bytes; consider reusing tables in performance-critical code
• Garbage collection — Runs automatically, but you can trigger it with ez.system.gc()

Coroutines and Yielding

Many ezOS APIs are designed for coroutine-based async programming:

local function load_async()
    local data = load_module("/scripts/heavy_module.lua")  -- Yields while loading
    process(data)
end
spawn(load_async)

Functions that yield are noted in their documentation. Don't call yielding functions outside of a coroutine context.

Error Handling

Most functions return nil on error rather than throwing. Check return values:

local file = ez.storage.read_file("/path")
if not file then
    print("Failed to read file")
    return
end

Color Format

Display functions use RGB565 format (16-bit color). Use ez.display.rgb(r, g, b) to convert from 8-bit RGB, or use predefined colors from ez.display.colors:

local red = ez.display.colors.RED
local custom = ez.display.rgb(128, 64, 255)

Coordinate Systems

• Pixel coordinates start at (0, 0) in the top-left corner
• Character cells are used by text-mode functions like draw_box()
• Display size: 320×240 pixels, typically 40×15 character cells with medium font

Best Practices

1. Prefer local variables — Globals are slower and use more memory
2. Reuse tables — Clear and reuse instead of creating new ones
3. Batch drawing — Draw everything, then call flush() once per frame
4. Unload unused modules — Use unload_module() to free memory
5. Check memory — Use ez.system.get_lua_memory() to monitor usage