Running a Lua VM on a Microcontroller: Lessons, Trade-offs, and Hard Limits
Published at January 1, 2026 · Last Modified at January 24, 2026 · 6 min read · Tags: lua mcu zephyr embedded-systems rtos memory-management gc fragmentation system-architecture
Running a Lua virtual machine on a microcontroller was not an academic exercise, but part of a real system built under strict resource constraints.
This work is part of Alyn — a lightweight embedded project designed to operate on limited MCU-class hardware while still allowing flexibility at the application level.
Alyn was developed as an assistive system for children with special needs, intended to operate reliably in an underwater pool environment, where robustness, determinism, and low power consumption are critical.
The goal was to introduce controlled runtime configurability and behavior scripting without moving the system to Linux, while consciously accepting the trade-offs imposed by flat memory, lack of an MMU, and real-time constraints.
In this article you’ll learn:
- Why running Lua on an MCU is fundamentally different from Linux systems
- How heap fragmentation manifests without an MMU, even with garbage collection
- What Lua’s GC can and cannot guarantee under constrained memory conditions
- Practical lessons learned from integrating Lua with Zephyr in a real system
Zephyr was selected for its small footprint, deterministic execution, and explicit heap management model.
Rather than hiding memory behavior behind complex allocators, Zephyr makes allocation patterns and fragmentation observable — which is essential when evaluating how a Lua VM behaves under true MCU-class constraints.
Lua was not designed to run on a bare-metal or MCU-class system.
It assumes a dynamic heap, a capable allocator, and a forgiving memory model.
And yet — in the right architecture — running a Lua VM on an MCU can be both practical and powerful.
This post summarizes the real challenges, the failures, and the patterns that actually work when integrating Lua into an MCU system running Zephyr RTOS.
In many embedded products, the real problem is not performance — it’s customization.
Typical pain points:
These pressures often push teams from MCU-based systems to Linux — not because they need Linux, but because they need flexibility.
Lua provides:
Porting Lua is easy.
Running it safely over time is not.
The main challenges are:
Lua’s GC:
This alone disqualifies Lua from hard realtime paths.
On an MCU:
Zephyr’s sys_heap:
Over time:
This is not a bug — it is physics.
A key realization:
Lua GC can free objects.
It cannot fix heap topology.
Even with a correct lua_free() implementation:
At that point, the failure is no longer theoretical.
In my case, the system would run correctly for a long time and then suddenly fail on very small allocations.
The following log was captured during such a failure:
LUA OOM: alloc 16 failed
LUA OOM: alloc 32 failed
On Linux:
On MCUs:
This difference alone explains why Lua feels “safe” on Linux and “fragile” on bare metal.
After multiple iterations and failures, only a few patterns proved stable.
The most important rule:
After system init, Lua must not allocate memory.
This means:
Lua becomes a deterministic behavior engine, not a general runtime.
This prevents both leaks and fragmentation.
If a full reset is required:
Partial resets inside Lua do not work.
A critical architectural win:
This enables:
The MCU becomes a deployment target — not the development bottleneck.
Lua should not be used when:
In those cases, a static FSM or DSL is a better choice.
Lua makes sense when:
In these cases:
MCU + RTOS + scripting can outperform Linux in total system cost and complexity.
Running a Lua VM on an MCU is not a hack — but it is also not a default choice.
It requires:
When done correctly, it enables:
Running Lua on an MCU is not about being clever.
It is about choosing flexibility consciously — and paying its cost upfront.
When the limits are understood, Lua can be a powerful tool.
When they are ignored, the system will eventually fail.
Running Lua on MCU platforms without an MMU exposes memory fragmentation issues that are typically hidden on Linux systems.
This post demonstrated how Lua’s garbage collector behaves under constrained memory conditions on Zephyr OS, and why careful allocator design is required for long-running embedded workloads.
The following links provide concrete implementation examples referenced throughout this post.
This Lua script represents a long-running, stateful workload that continuously allocates and updates Lua-side structures.
A custom memory backend that routes Lua allocations (malloc, realloc, free) into Zephyr’s sys_heap, operating on a fixed-size, flat memory region.
The Lua VM was modified to use the custom allocator correctly, following Lua 5.4’s memory management contract.
Lua memory allocator implementation:
memory.c
Lua auxiliary library (lauxlib.c) allocation path, where custom changes were made to adapt Lua for MCU execution on Zephyr OS:lauxlib.c (allocation path)