Skip to content

mirkosertic/Megahub / .claude/skills/lua-integration

lua-integration

Verified

Lua scripting context for the Megahub project. Use when working on Lua script execution, Lua bindings, libluahub, Lua error handling, Lua threads, or the Blockly-to-Lua code generation pipeline.

FileKindSize
SKILL.mdskill md2.9 KB
---
name: lua-integration
description: Lua scripting context for the Megahub project. Use when working on Lua script execution, Lua bindings, libluahub, Lua error handling, Lua threads, or the Blockly-to-Lua code generation pipeline.
---

# Lua Integration — Megahub ESP32

## Overview

- **Lua 5.4** embedded interpreter
- All custom Lua bindings: `lib/megahub/src/libluahub.cpp`
- Lua state created in `lib/megahub/src/megahub.cpp` → `newLuaState()`
- Scripts stored on LittleFS/SD, loaded on demand
- Execution triggered via BLE command (app request type 6 = execute-lua)

---

## Execution Flow

```
BLE request (type 6, Lua code payload)
  → megahub.cpp: executeLUACode()
      → newLuaState()       (~20ms, opens standard libs + registers custom bindings)
      → lua_pcall()         (executes the script)
      → cleanup Lua state
```

From real device logs: execution of a motor control script completes in ~62ms.

---

## Lua Bindings (`libluahub.cpp`)

Key functions available in Lua scripts:

| Lua function | Purpose |
|-------------|---------|
| `hub.init(fn)` | Register initialization block (runs first) |
| `hub.startthread(name, fn, stackSize)` | Start a FreeRTOS task running a Lua coroutine |

**Threads**: `hub.startthread()` creates a FreeRTOS task. Stack size is specified in bytes (e.g., 4096). The thread runs as a Lua coroutine and should yield periodically.

---

## Critical Rules

- **Always** wrap Lua execution in `lua_pcall()` — never use `lua_call()` in production code
- **Always** install an error handler before pcall to get useful error messages
- **Never** let Lua errors propagate unhandled — they will crash the firmware
- **Lua threads via `hub.startthread()`** consume both FreeRTOS stack and Lua VM heap
- The Lua VM runs in the main heap; large scripts reduce heap available for BLE, LEGO, etc.
- Long-running scripts must yield periodically — a tight Lua loop will starve other tasks

---

## Error Handling Pattern

```cpp
// Safe Lua execution (in megahub.cpp)
lua_State* L = newLuaState();
if (!L) { ERROR("Failed to create Lua state"); return; }

int result = lua_pcall(L, 0, 0, 0);
if (result != LUA_OK) {
    ERROR("Lua error: %s", lua_tostring(L, -1));
    lua_pop(L, 1);
}
// Always close state when done
lua_close(L);
```

---

## Blockly → Lua Pipeline

1. User builds program in Blockly editor (browser)
2. Blockly generates Lua code (custom generators in `frontend/src/components/blockly/`)
3. Lua code sent to firmware via BLE (streaming upload or direct execute)
4. Firmware executes via `executeLUACode()`

The generated Lua code always follows a structure with `hub.init()` and optionally `hub.startthread()` for background monitoring loops.

---

## Memory Impact

From device logs:
- Creating a new Lua state: ~30KB heap consumed (~170KB → ~140KB)
- A script with `hub.startthread("Device monitor", fn, 4096)` adds another ~4KB stack + Lua coroutine overhead
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall