Luau Bindings — `sys`

The require("sys") script API — system introspection and control: uptime and monotonic time, tasks, memory, direct memory access (sys.mem), the event log, and reset. It consolidates what the ESP32-P4 spread across os (uptime, heap), the FreeRTOS rtos lib (tasks), and the mem lib (peek/poke). Every function is [antos]. Design & native core: antos_sys.

local sys = require("sys")
print(sys.uptime(), "seconds up")

This is where the genuinely-OS facts live that must not be smuggled onto stock os — wall-clock uptime and monotonic time are here so os.clock() keeps its reference CPU-seconds meaning.

Time & uptime

Function	Behaviour
`sys.uptime()`	Seconds since boot (wall clock).
`sys.uptime_ms()`	Milliseconds since boot.
`sys.monotonic()`	Monotonic seconds — never jumps (this is what the P4's `os.clock` wrongly did).
`sys.boot_time()`	The `os.time`-style epoch at boot.

Tasks

Reconceived from the P4 rtos library. Under Linux on the CM these are processes/threads — the FreeRTOS primitives the old lib exposed (queues, semaphores, mutexes, event groups, software timers, tick math) are gone: they were kernel-specific, and Lua code uses coroutines and the OS instead.

Function	Behaviour
`sys.tasks()`	Array of `{ name, id, state, priority, cpu_pct, mem }` (the `ps`/`top` backend).
`sys.task([id])`	Detail for one task (default: caller).
`sys.spawn(script [, args])`	Start a script as a background task → id.
`sys.wait(id [, timeout])`	Wait for a task to finish; returns its result/exit.
`sys.kill(id)`	Terminate a task.
`sys.set_priority(id, pri)`	Adjust a task's scheduling priority.

Memory

Function	Behaviour
`sys.memory()`	Memory by region: `{ region = { total, free, used, min_free } }` (was `os.heap_info`); `min_free` is worst-case headroom since boot.
`sys.gc([opt])`	Lua GC control — passthrough to `collectgarbage`.

`sys.mem.*` — direct memory access `[antos]`

Bounds-checked peek/poke, folded from the P4 mem library — the retro PEEK/POKE, but safe. On the CM this can reach mapped device registers as well as RAM.

Function	Behaviour
`sys.mem.peek8/16/32/64(addr)`	Read an 8/16/32/64-bit value.
`sys.mem.poke8/16/32/64(addr, value)`	Write one.
`sys.mem.read(addr, len)`	Block read → bytes.
`sys.mem.write(addr, data)`	Block write.
`sys.mem.fill(addr, byte, len)`	Fill a region.
`sys.mem.copy(dst, src, len)`	Copy a region.
`sys.mem.range()`	The accessible address range(s).
`sys.mem.check(addr, len)`	Bounds-check without touching memory.

local sys = require("sys")
local w = sys.mem.peek32(0x4000_0000)         -- read a register
sys.mem.poke8(base + 0x10, 0xFF)              -- POKE, bounds-checked

Every access is range-checked against sys.mem.range(); an out-of-range address returns nil, err rather than faulting.

Event log & diagnostics

Function	Behaviour
`sys.log(tag, msg)`	Append to the system event ring buffer (OLED / debug stream / `dmesg`-style views).
`sys.events([n])`	Read the most recent `n` events.

Info & control

Function	Behaviour
`sys.info()`	OS version, model, hostname, image slot (A/B), FireStorm state.
`sys.image()`	Which A/B OS-image slot is live, and the other's state (the `SYS:` target).
`sys.reset([mode])`	Restart — `"warm"` (default) or `"cold"`. Same as `os.reset`.

antos_sys — design & native core · luau_os (why uptime/memory live here) · Firmware (A/B slots, SYS:) · Debug OLED · AntOS Libraries hub

Luau Bindings — sys