ESP3D/libraries/EspLuaEngine-1.0.3/API.md

EspLuaEngine for ESP32

📚 API Reference

EspLuaEngine()

Constructor. Initializes a new Lua state and loads standard libraries.

~EspLuaEngine()

Destructor. Closes the Lua state and frees resources.

bool executeScript(const char* script)

Executes a Lua script.

• Parameters:
  • script: A null-terminated string containing the Lua code to execute.
• Returns: true if the script executes successfully, false otherwise.
• Note: This function is non-blocking and supports pause and stop operations.

bool registerFunction(const char* name, lua_CFunction function, void* userData = nullptr)

Registers a C function to be callable from Lua scripts.

• Parameters:
  • name: The name to use for the function in Lua.
  • function: A pointer to the C function to register.
  • userData: Optional user data to be passed to the function.
• Returns: true if the function is successfully registered, false otherwise.

template<typename T> bool registerConstant(const char* name, T value)

Registers a constant value that can be accessed from Lua scripts.

• Parameters:
  • name: The name to use for the constant in Lua.
  • value: The value of the constant. Supported types include lua_Number, const char*, bool, int, and unsigned char.
• Returns: true if the constant is successfully registered, false otherwise.

void resetState()

Resets the Lua state, clearing all registered functions and constants.

void setPauseFunction(PauseFunction func)

Sets a custom function to be called when execution is paused.

• Parameters:
  • func: A function of type std::function<void(EspLuaEngine*)> to be called during pauses.

void pauseExecution()

Pauses the execution of the current script.

void resumeExecution()

Resumes the execution of a paused script.

void stopExecution()

Stops the execution of the current script.

bool isPaused()

Checks if the script execution is currently paused.

• Returns: true if paused, false otherwise.

bool isRunning()

Checks if a script is currently running.

• Returns: true if running, false otherwise.

Status getStatus()

Gets the current status of the EspLuaEngine.

• Returns: An enum of type EspLuaEngine::Status with possible values:
  • Idle: No script is currently running.
  • Running: A script is currently executing.
  • Paused: Script execution is paused.

bool hasError()

Checks if an error occurred during the last script execution.

• Returns: true if an error occurred, false otherwise.

const char* getLastError()

Gets the last error message.

• Returns: A string containing the last error message, or an empty string if no error occurred.

lua_State* getLuaState()

Gets the underlying Lua state.

• Returns: A pointer to the lua_State object.

🔧 Usage Examples

EspLuaEngine lua;

// Register a custom function
lua.registerFunction("myFunction", l_myCustomFunction);

// Register constants
lua.registerConstant("PI", 3.14159);
lua.registerConstant("PROJECT_NAME", "MyESP32Project");
lua.registerConstant("DEBUG_MODE", true);

// Execute a Lua script
if (lua.executeScript(R"(
    print("PI is: " .. PI)
    print("Project: " .. PROJECT_NAME)
    myFunction()
)")) {
    Serial.println("Script executed successfully");
} else {
    Serial.print("Error executing script: ");
    Serial.println(lua.getLastError());
}

// Pause and resume execution
lua.pauseExecution();
// Do something while paused
lua.resumeExecution();

// Check status
if (lua.getStatus() == EspLuaEngine::Status::Running) {
    Serial.println("Script is running");
}

// Stop execution
lua.stopExecution();

// Reset state
lua.resetState();

📝 Notes

• The EspLuaEngine now supports non-blocking script execution with pause and stop capabilities.
• Use setPauseFunction() to define custom behavior during pauses.
• Always check for errors after executing a script using hasError() and getLastError().
• The engine supports multitasking environments, making it suitable for complex ESP32 projects.
• Important note for ESP8266 users: While state monitoring and control are straightforward on ESP32 due to its task management capabilities, implementation on ESP8266 may require additional libraries or the use of an interrupt system. Currently, this functionality is not fully supported on ESP8266 platforms.

🚀 Platform-Specific Considerations

ESP32

On ESP32, the EspLuaEngine takes full advantage of the FreeRTOS task management system, allowing for efficient multitasking and state control without additional setup.

ESP8266

For ESP8266 users:

• The current implementation may not fully support all state monitoring and control features.
• To achieve similar functionality as on ESP32, you might need to:
  1. Implement a custom interrupt-based system for state checks.
  2. Use additional libraries for task management (e.g., TaskScheduler).
  3. Carefully manage your main loop to prevent blocking while allowing for state checks.

Please note that these advanced features on ESP8266 are not officially supported in the current version of EspLuaEngine and may require custom modifications to the library.