About the Lua interpreter
Section titled “About the Lua interpreter”ESP3D-X embeds a Lua 5.4 scripting engine that can execute Lua scripts directly on the device. Scripts run asynchronously in a dedicated task and can communicate with the connected machine (FluidNC, grblHAL, …) through the ESP3D-X message bus.
Lua is a lightweight, high-level, multi-paradigm programming language designed for embedded use. Please refer to Lua for more information about the language itself.
In addition to the standard Lua libraries, ESP3D-X exposes a few additional functions and constants that let a script interact with the machine and the board’s GPIO.
ESP3D-X functions
Section titled “ESP3D-X functions”| Name | Description |
|---|---|
print(…) | Send text to the machine output. Do not forget to add \n at the end of a command line. |
available() | Return the number of incoming messages waiting to be read. |
readData() | Read the next incoming message (returns a string, or nil if none). |
delay(ms) | Wait for a number of milliseconds (checks pause/stop while waiting). |
yield() | Yield execution to let the system run. |
millis() | Return the number of milliseconds since the board started. |
pinMode(pin, mode) | Configure the mode of a GPIO pin. |
digitalWrite(pin, value) | Set the level of a GPIO pin. |
digitalRead(pin) | Read the level of a GPIO pin. |
Constants
Section titled “Constants”| Constant | Value |
|---|---|
HIGH | 1 |
LOW | 0 |
INPUT | floating input |
OUTPUT | output |
INPUT_PULLUP | input with pull-up |
INPUT_PULLDOWN | input with pull-down |
Standard Lua libraries
Section titled “Standard Lua libraries”The following standard Lua libraries are available to scripts:
base, table, string, math, utf8.
Running scripts
Section titled “Running scripts”Scripts are executed from the filesystem using ESP3D commands:
| Command | Description |
|---|---|
[ESP300]<path> | Execute the script located at <path> (e.g. [ESP300]/fs/script.lua). |
[ESP301] | Query the interpreter status (idle / running / paused / error). |
[ESP301]action=PAUSE | Pause the running script at the next checkpoint. |
[ESP301]action=RESUME | Resume a paused script. |
[ESP301]action=ABORT | Stop the running script immediately. |
[ESP420] | System status — shows lua: idle or lua: running (<path>). |
Autostart
Section titled “Autostart”A script can be launched automatically at startup. This is defined at build time in customizations/lua/customizations.h:
#define ESP3D_LUA_AUTOSTART_SCRIPT "/fs/init.lua"The autostart script runs asynchronously and does not block the boot sequence.
Limitations
Section titled “Limitations”| Constraint | Value |
|---|---|
| Concurrent scripts | 1 (a new run is rejected while one is active) |
| Maximum script file size | 2048 bytes |
| Maximum incoming message size | 128 bytes (longer messages are truncated) |
analogWrite | not implemented (LEDC conflict with buzzer) |
analogRead | not implemented |