evan/esp32-lua-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initial commit

Browse Source
This commit is contained in:
Evan Reichard
2026-08-03 16:09:07 -04:00
commit 95fa512047
109 changed files with 35023 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
native/test/fake_providers.h
+327
View File
@@ -0,0 +1,327 @@
#pragma once
// Host doubles for every provider, deliberately dumb: they record what a binding asked
// for and hand back canned values, so a test asserts the marshalling rather than a device.
#include <map>
#include <string>
#include <vector>
#include <lua/providers.h>
namespace fake {
using namespace esp32lua;
struct Log : LogProvider {
LogLevel level = LogLevel::Debug;
std::string message;
void write(LogLevel nextLevel, const std::string& nextMessage) override {
level = nextLevel;
message = nextMessage;
}
};
struct Settings : SettingsProvider {
int32_t degrees = 0;
std::string tz = "UTC0";
int32_t rotation() const override { return degrees; }
Status setRotation(int32_t value) override {
degrees = value;
return Status::success();
}
std::string timezone() const override { return tz; }
Status setTimezone(const std::string& value) override {
tz = value;
return Status::success();
}
};
struct Sys : SysProvider {
int32_t millis() const override { return 1234; }
MemoryInfo memory() const override {
const MemoryInfo info = {100, 200, 50};
return info;
}
bool isClockSynced() const override { return true; }
};
struct Fs : FsProvider {
std::map<std::string, std::string> files;
std::string written;
// One buffer handed to the runtime, which owns and deletes it.
struct Reader : FileReader {
std::string content;
size_t at = 0;
int32_t read(char* out, int32_t maxBytes) override {
const size_t remaining = content.size() - at;
const size_t count = remaining < static_cast<size_t>(maxBytes) ? remaining : static_cast<size_t>(maxBytes);
content.copy(out, count, at);
at += count;
return static_cast<int32_t>(count);
}
};
FileReader* openRead(const std::string& path) override {
const std::map<std::string, std::string>::const_iterator found = files.find(path);
if (found == files.end()) return nullptr;
Reader* reader = new Reader();
reader->content = found->second;
return reader;
}
bool exists(const std::string& path) const override { return files.count(path) != 0; }
Status fileSize(const std::string& path, int32_t& size) const override {
const std::map<std::string, std::string>::const_iterator found = files.find(path);
if (found == files.end()) return Status::failure("no such file");
size = static_cast<int32_t>(found->second.size());
return Status::success();
}
Status listDirs(const std::string&, std::vector<std::string>& names) const override {
names.push_back("apps");
return Status::success();
}
Status listFiles(const std::string&, std::vector<std::string>& names) const override {
names.push_back("main.lua");
return Status::success();
}
Status mkdir(const std::string&) override { return Status::success(); }
Status readFile(const std::string& path, int32_t maxBytes, std::string& content) const override {
const std::map<std::string, std::string>::const_iterator found = files.find(path);
if (found == files.end()) return Status::failure("no such file");
if (static_cast<int32_t>(found->second.size()) > maxBytes) return Status::failure("too large");
content = found->second;
return Status::success();
}
Status readLineAt(const std::string& path, int32_t offset, int32_t, bool& found, std::string& line,
int32_t& nextOffset) const override {
const std::map<std::string, std::string>::const_iterator file = files.find(path);
if (file == files.end()) return Status::failure("no such file");
if (offset >= static_cast<int32_t>(file->second.size())) {
found = false;
return Status::success();
}
const size_t end = file->second.find('\n', offset);
line = file->second.substr(offset, end == std::string::npos ? std::string::npos : end - offset);
nextOffset = end == std::string::npos ? static_cast<int32_t>(file->second.size()) : static_cast<int32_t>(end + 1);
found = true;
return Status::success();
}
Status remove(const std::string& path) override {
files.erase(path);
return Status::success();
}
Status removeTree(const std::string&) override { return Status::success(); }
Status rename(const std::string&, const std::string&) override { return Status::success(); }
Status writeFile(const std::string& path, const std::string& content) override {
files[path] = content;
written = content;
return Status::success();
}
};
struct Gui : GuiProvider {
std::string trace;
int32_t degrees = 0;
bool fullscreen = false;
bool gradient = false;
FontIds fonts() const override {
const FontIds ids = {1, 2, 3, 4, 0, 1};
return ids;
}
int32_t width() const override { return 320; }
int32_t height() const override { return 240; }
int32_t rotation() const override { return degrees; }
void setRotation(int32_t value) override { degrees = value; }
int32_t color(int32_t r, int32_t g, int32_t b) const override { return (r << 16) | (g << 8) | b; }
void clear(int32_t) override { trace += "clear;"; }
void fillRect(int32_t, int32_t, int32_t, int32_t, int32_t) override { trace += "fillRect;"; }
void drawRect(int32_t, int32_t, int32_t, int32_t, int32_t) override { trace += "drawRect;"; }
void drawLine(int32_t, int32_t, int32_t, int32_t, int32_t, int32_t) override { trace += "drawLine;"; }
void drawPixel(int32_t, int32_t, int32_t) override { trace += "drawPixel;"; }
void drawCircle(int32_t, int32_t, int32_t, int32_t, int32_t) override { trace += "drawCircle;"; }
void fillCircle(int32_t, int32_t, int32_t, int32_t, const int32_t*) override { trace += "fillCircle;"; }
void roundRect(int32_t, int32_t, int32_t, int32_t, int32_t, int32_t, const int32_t* top, const int32_t* bottom,
const int32_t* border) override {
if (top && bottom && *top != *bottom) gradient = true;
trace += "roundRect(";
trace += top ? "fill" : "-";
trace += border ? ",border" : ",-";
trace += ");";
}
void setFullscreen(bool on) override { fullscreen = on; }
// Stands in for an e-ink panel, where a second commit is a second visible refresh.
void commit() override { commits++; }
int commits = 0;
void fillPolygon(const int32_t*, const int32_t*, size_t count, int32_t) override {
trace += "fillPolygon" + std::to_string(count) + ";";
}
Status drawBmp(const std::string&, const int32_t*, const int32_t*, const int32_t*, const int32_t*) override {
trace += "drawBmp;";
return Status::success();
}
int32_t textWidth(int32_t, const std::string& text, int32_t) const override {
return static_cast<int32_t>(text.size()) * 8;
}
int32_t fontHeight(int32_t, int32_t) const override { return 16; }
void drawText(int32_t, int32_t, int32_t, const std::string& text, int32_t, int32_t, const int32_t*) override {
trace += "drawText(" + text + ");";
}
};
struct Http : HttpProvider {
std::string method;
std::string body;
std::vector<HttpHeader> headers;
int32_t limit = 0;
Status request(const std::string& nextMethod, const std::string&, const std::string& nextBody,
const std::vector<HttpHeader>& nextHeaders, int32_t maxBytes, HttpResponse& response) override {
method = nextMethod;
body = nextBody;
headers = nextHeaders;
limit = maxBytes;
response.status = 404;
response.body = "missing";
return Status::success();
}
Status download(const std::string&, const std::string&, const HttpDownload& options, int32_t& bytesWritten) override {
bytesWritten = options.maxBytes;
return Status::success();
}
};
struct Timer : TimerProvider {
std::vector<TimerId> scheduled;
std::vector<TimerId> cancelled;
Status schedule(TimerId id, int32_t, bool) override {
scheduled.push_back(id);
return Status::success();
}
void cancel(TimerId id) override { cancelled.push_back(id); }
};
struct Wifi : WifiProvider {
WifiStatus current;
bool savedReconnect = false;
Wifi() {
current.state = "connected";
current.ssid = "home";
current.ip = "192.168.1.5";
current.rssi = -50;
}
Status scan(std::vector<WifiNetwork>& networks) override {
const WifiNetwork network = {"home", -50, true};
networks.push_back(network);
return Status::success();
}
Status connect(const std::string* ssid, const std::string*) override {
savedReconnect = ssid == nullptr;
return Status::success();
}
WifiStatus status() const override { return current; }
void disconnect() override { current.state = "disconnected"; }
Status forget() override { return Status::success(); }
};
struct Ble : BleProvider {
int32_t duration = 0;
std::string value;
Status init(const std::string*) override { return Status::success(); }
void deinit() override {}
Status scan(int32_t durationMs, std::vector<BleDevice>& devices) override {
duration = durationMs;
const BleDevice device = {"tag", "aa:bb", -60};
devices.push_back(device);
return Status::success();
}
Status connect(const std::string&) override { return Status::success(); }
void disconnect() override {}
bool isConnected() const override { return true; }
Status read(const std::string&, const std::string&, std::string& out) override {
out = std::string("a\0b", 3);
return Status::success();
}
Status write(const std::string&, const std::string&, const std::string& next) override {
value = next;
return Status::success();
}
Status startAdvertising(const std::string*) override { return Status::success(); }
void stopAdvertising() override {}
};
struct Touch : TouchProvider {
bool down = true;
int32_t calibration[4] = {0, 0, 0, 0};
bool touch(int32_t& x, int32_t& y) const override {
x = 10;
y = 20;
return down;
}
bool rawTouch(int32_t& x, int32_t& y) const override {
x = 300;
y = 700;
return down;
}
bool isTouched() const override { return down; }
Status setCalibration(int32_t x0, int32_t y0, int32_t x1, int32_t y1) override {
calibration[0] = x0;
calibration[1] = y0;
calibration[2] = x1;
calibration[3] = y1;
return Status::success();
}
};
struct Buttons : ButtonsProvider {
std::vector<std::string> buttons() const override {
std::vector<std::string> roles;
roles.push_back("left");
roles.push_back("right");
roles.push_back("confirm");
roles.push_back("back");
return roles;
}
bool isAnyPressed() const override { return false; }
bool isPressed(const std::string& button) const override { return button == "confirm"; }
bool wasPressed(const std::string&) const override { return false; }
bool wasReleased(const std::string&) const override { return false; }
};
// Every provider a Runtime needs, so a test names only what it asserts on.
struct Bench {
Log log;
Settings settings;
Sys sys;
Fs fs;
Gui gui;
Http http;
Timer timer;
Wifi wifi;
Ble ble;
Touch touch;
Buttons buttons;
Providers providers() {
Providers providers;
providers.log = &log;
providers.settings = &settings;
providers.sys = &sys;
providers.fs = &fs;
providers.gui = &gui;
providers.http = &http;
providers.timer = &timer;
providers.wifi = &wifi;
providers.ble = &ble;
providers.touch = &touch;
providers.buttons = &buttons;
return providers;
}
};
} // namespace fake
native/test/lua_smoke.c
+16
View File
@@ -0,0 +1,16 @@
#include <assert.h>
#include <string.h>
#include "lauxlib.h"
#include "lua.h"
int main(void) {
assert(strcmp(LUA_RELEASE, "Lua 5.4.8") == 0);
assert(sizeof(lua_Integer) == 4);
assert(sizeof(lua_Number) == 4);
lua_State* state = luaL_newstate();
assert(state);
lua_close(state);
return 0;
}
native/test/runtime_test.cpp
+291
View File
@@ -0,0 +1,291 @@
#include <cassert>
#include <cstdio>
#include <string>
#include <lua/runtime.h>
#include "fake_providers.h"
extern "C" {
#include "lauxlib.h"
#include "lua.h"
}
namespace {
void run(lua_State* state, const char* chunk) {
if (luaL_dostring(state, chunk) != LUA_OK) {
std::fprintf(stderr, "lua error: %s\n", lua_tostring(state, -1));
assert(false);
}
}
void expectError(lua_State* state, const char* chunk) {
assert(luaL_dostring(state, chunk) != LUA_OK);
lua_pop(state, 1);
}
} // namespace
int main() {
fake::Bench bench;
esp32lua::Runtime runtime(bench.providers());
assert(runtime.open());
lua_State* state = runtime.state();
run(state, "log.info('shared runtime')");
assert(bench.log.level == esp32lua::LogLevel::Info);
assert(bench.log.message == "shared runtime");
run(state,
"assert(settings.getRotation() == 0)\n"
"assert(settings.setRotation(90))\n"
"assert(settings.getTimezone() == 'UTC0')\n"
"assert(settings.setTimezone('EST5EDT'))");
assert(bench.settings.degrees == 90);
assert(bench.settings.tz == "EST5EDT");
expectError(state, "settings.setRotation(45)");
run(state,
"assert(sys.getAPIVersion() == 1)\n"
"assert(sys.hasFeature('touch') and sys.hasFeature('buttons'))\n"
"assert(not sys.hasFeature('eink'))\n"
"local free, total, largest = sys.getMemory()\n"
"assert(free == 100 and total == 200 and largest == 50)");
bench.fs.files["/notes.txt"] = "first\nsecond";
run(state,
"assert(fs.MAX_READ_BYTES == 65536)\n"
"assert(fs.exists('/notes.txt') and not fs.exists('/missing'))\n"
"assert(fs.fileSize('/notes.txt') == 12)\n"
"local size, err = fs.fileSize('/missing')\n"
"assert(size == nil and err == 'no such file')\n"
"assert(fs.readFile('/notes.txt', 64) == 'first\\nsecond')\n"
"local line, nextOffset = fs.readLineAt('/notes.txt', 0, 64)\n"
"assert(line == 'first' and nextOffset == 6)\n"
"assert(fs.readLineAt('/notes.txt', 12, 64) == nil)\n"
"assert(fs.listFiles('/')[1] == 'main.lua')\n"
"assert(fs.writeFile('/out.bin', 'a\\0b'))");
assert(bench.fs.written.size() == 3);
expectError(state, "fs.readFile('/notes.txt', 999999)");
run(state,
"assert(gui.getWidth() == 320 and gui.getHeight() == 240)\n"
"assert(gui.FONT_UI == 2 and gui.STYLE_BOLD == 1)\n"
"assert(gui.color(255, 0, 0) == 0xFF0000)\n"
"gui.setRotation(180)\n"
"gui.clear()\n"
"gui.fillPolygon({1, 2, 3}, {4, 5, 6}, 0)\n"
"gui.drawText(gui.FONT_UI, 0, 0, 'hi')");
assert(bench.gui.degrees == 180);
assert(bench.gui.trace == "clear;fillPolygon3;drawText(hi);");
expectError(state, "gui.fillPolygon({1, 2}, {3}, 0)");
expectError(state, "gui.color(300, 0, 0)");
run(state,
"local response = http.get('https://example.test', {maxBytes = 16, headers = {Accept = 'text/plain'}})\n"
"assert(response.status == 404 and response.body == 'missing')\n"
"assert(http.urlencode('a b/c~') == 'a%20b%2Fc~')\n"
"assert(http.download('https://example.test/f', '/f', {maxBytes = 32}) == 32)");
assert(bench.http.method == "GET" && bench.http.limit == 16);
assert(bench.http.headers.size() == 1 && bench.http.headers[0].name == "Accept");
expectError(state, "http.get('https://example.test', {maxBytes = 999999})");
run(state,
"assert(wifi.scan()[1].ssid == 'home')\n"
"assert(wifi.isConnected())\n"
"assert(wifi.getLocalIP() == '192.168.1.5')\n"
"assert(wifi.getStatus().state == 'connected')\n"
"assert(wifi.connect())");
assert(bench.wifi.savedReconnect);
run(state,
"assert(ble.scan()[1].address == 'aa:bb')\n"
"assert(#ble.read('svc', 'chr') == 3)\n"
"assert(ble.write('svc', 'chr', 'x\\0y'))");
assert(bench.ble.duration == 3000);
assert(bench.ble.value.size() == 3);
run(state,
"fired = 0\n"
"once = timer.after(10, function() fired = fired + 1 end)\n"
"repeated = timer.every(5, function() fired = fired + 10 end)");
assert(bench.timer.scheduled.size() == 2);
runtime.callTimer(bench.timer.scheduled[0]);
runtime.callTimer(bench.timer.scheduled[0]); // a one-shot never fires twice
runtime.callTimer(bench.timer.scheduled[1]);
runtime.callTimer(bench.timer.scheduled[1]);
run(state,
"assert(fired == 21)\n"
"assert(timer.cancel(repeated))\n"
"assert(not timer.cancel(repeated))");
assert(bench.timer.cancelled.size() == 1);
expectError(state, "timer.after(0, function() end)");
run(state,
"assert(settings.setCalibration(100, 200, 300, 400))\n"
"local x, y = input.getTouch()\n"
"assert(x == 10 and y == 20)\n"
"assert(input.isTouched())\n"
"assert(input.isPressed('confirm') and not input.isPressed('back'))\n"
"assert(#input.getButtons() == 4 and input.getButtons()[3] == 'confirm')");
assert(bench.touch.calibration[3] == 400);
// Chrome control and gradients are core: an e-ink provider flattens what it cannot show.
run(state,
"gui.setFullscreen(true)\n"
"gui.roundRect(0, 0, 10, 10, 4, 0, 0xFF, 0x00)\n"
"gui.roundRect(0, 0, 10, 10, 4, 0, nil, nil, 0xFF)");
assert(bench.gui.fullscreen && bench.gui.gradient);
assert(bench.gui.trace.find("roundRect(-,border);") != std::string::npos);
bench.gui.trace.clear();
run(state,
"node.reset()\n"
"local root = node.create(nil, {type = 'box', w = 'fill', h = 'fill', pad = 4, gap = 2})\n"
"local label = node.create(root, {type = 'text', label = 'Hello'})\n"
"local button = node.create(root, {type = 'button', h = 40, interactive = true})\n"
"node.setStyle(root, {background = 0xFFFFFF, fill = 0xFFFFFF, color = 0, face = 0xEEEEEE, focusColor = 0xFF0000})\n"
"assert(node.layout(root, 0, 0, 320, 240))\n"
"local x, y, w, h = node.getRect(label)\n"
"assert(x == 4 and y == 4 and w == 312 and h == 16)\n"
"assert(node.getLabel(label) == 'Hello')\n"
"assert(node.hit(root, 10, 40) == button)\n"
"assert(node.hit(root, 10, 200) == nil)\n"
"assert(node.focusFirst(root) == button)\n"
"assert(node.getFocus() == button)\n"
"assert(node.moveFocus(root, 'up') == button)\n"
"node.setPressed(button, true)\n"
"assert(node.isPressed(button))\n"
"assert(node.getCount() == 3 and node.getFootprint() > 0)\n"
"node.draw(root)\n"
"node.dropScratch()");
assert(bench.gui.trace.find("drawText(Hello);") != std::string::npos);
assert(bench.gui.trace.find("roundRect(fill,-);") != std::string::npos);
expectError(state, "node.create(nil, {type = 'nope'})");
run(state,
"node.reset()\n"
"local root = node.create(nil, {type = 'custom', w = 'fill', h = 'fill'})\n"
"painted = 0\n"
"node.setPainter(function(id, x, y, w, h) painted = painted + w end)\n"
"assert(node.layout(root, 0, 0, 320, 240))\n"
"node.draw(root)\n"
"assert(painted == 320)");
// Callbacks: only init failing stops an app, and a release fires the tap alias after the up.
run(state,
"events = {}\n"
"local function note(name) return function(a) events[#events + 1] = name .. ':' .. tostring(a) end end\n"
"function init(arg) events[#events + 1] = 'init:' .. tostring(arg) end\n"
"function draw(delta) events[#events + 1] = 'draw:' .. delta end\n"
"on_touch_down = note('down')\n"
"on_touch_up = note('up')\n"
"on_touch = note('tap')\n"
"on_button_up = note('bup')\n"
"on_button = note('btap')");
bench.gui.commits = 0;
assert(runtime.callInit("book.epub"));
runtime.callDraw(33);
runtime.callTouch(esp32lua::TouchPhase::Down, 5, 6);
runtime.callTouch(esp32lua::TouchPhase::Move, 5, 7); // the app defines no on_touch_move
runtime.callTouch(esp32lua::TouchPhase::Up, 5, 8);
runtime.callButton("confirm", false);
run(state,
"assert(table.concat(events, ' ') == "
"'init:book.epub draw:33 down:5 up:5 tap:5 bup:confirm btap:confirm')");
// One commit per visit to the app, so six calls and not seven: the release and its tap alias
// are one visible change, and the move nobody handled still ends a batch.
assert(bench.gui.commits == 6);
// A timer firing inside draw is still one batch.
run(state,
"function draw() timer.after(1, function() end) end\n"
"nested = timer.after(1, function() draw() end)");
bench.gui.commits = 0;
runtime.callTimer(bench.timer.scheduled.back());
assert(bench.gui.commits == 1);
run(state, "function init() error('boom') end");
assert(!runtime.callInit(""));
assert(bench.log.message.find("init: ") == 0);
run(state, "function draw() error('kaboom') end");
runtime.callDraw(1); // a failed frame logs and the app keeps running
assert(bench.log.message.find("draw: ") == 0);
// A feature callback without its provider is a wiring bug, not a silent no-op.
{
fake::Bench headless;
esp32lua::Providers providers = headless.providers();
providers.touch = nullptr;
esp32lua::Runtime noTouch(providers);
assert(noTouch.open());
noTouch.callTouch(esp32lua::TouchPhase::Down, 1, 1);
assert(headless.log.message == "callTouch without a touch provider");
run(noTouch.state(), "assert(input.getTouch == nil and input.isPressed ~= nil)");
}
// App loading: a fresh state per app, require reaching the app directory and /.lua/lib, and
// navigation applied between batches rather than inside a callback.
{
fake::Bench host;
host.fs.files["/.lua/lib/greet.lua"] = "return {hello = function() return 'hi' end}";
host.fs.files["/.lua/apps/Home/main.lua"] =
"local greet = require('greet')\n"
"function init(arg) started = greet.hello() .. ':' .. tostring(arg) end";
host.fs.files["/.lua/apps/Reader/main.lua"] =
"local page = require('page')\n"
"function init(arg) started = page.name .. ':' .. arg end";
host.fs.files["/.lua/apps/Reader/page.lua"] = "return {name = 'page'}";
host.fs.files["/.lua/apps/Reader/Notes/main.lua"] = "function init() end";
esp32lua::Runtime app(host.providers());
assert(app.startApp("Home"));
assert(app.appId() == "Home" && app.appTitle() == "Home");
assert(app.appDataPath() == "/.lua/data/Home");
run(app.state(), "assert(started == 'hi:')");
// A subapp shares the app ID, so both routes share one data directory.
run(app.state(), "sys.launch('Reader', 'book.epub')");
assert(app.hasPendingNavigation());
run(app.state(), "assert(started == 'hi:')"); // the current app keeps running until applied
assert(app.applyPendingNavigation());
run(app.state(), "assert(started == 'page:book.epub')");
run(app.state(), "sys.launch('Reader/Notes')");
assert(app.applyPendingNavigation());
assert(app.appPath() == "Reader/Notes" && app.appId() == "Reader");
assert(app.appDataPath() == "/.lua/data/Reader");
// Back unwinds history, then lands on the launcher.
run(app.state(), "sys.back()");
assert(app.applyPendingNavigation() && app.appPath() == "Reader");
run(app.state(), "sys.back()");
assert(app.applyPendingNavigation() && app.appPath() == "Home");
run(app.state(), "sys.back()");
assert(app.applyPendingNavigation() && app.appPath() == "Home");
// sys.replace does not grow history, so back from it still reaches the launcher.
run(app.state(), "sys.replace('Reader', 'other.epub')");
assert(app.applyPendingNavigation() && app.appPath() == "Reader");
run(app.state(), "sys.back()");
assert(app.applyPendingNavigation() && app.appPath() == "Home");
// A missing app, a broken app, and a traversal all leave nothing running.
assert(!app.startApp("Absent"));
assert(!app.hasApp() && app.state() == nullptr);
host.fs.files["/.lua/apps/Broken/main.lua"] = "function init() error('nope') end";
assert(!app.startApp("Broken"));
assert(!app.hasApp());
assert(!app.startApp("../secrets"));
assert(host.log.message.find("refusing to start") == 0);
}
// Missing core providers leave no Lua state behind.
esp32lua::Providers incomplete = bench.providers();
incomplete.fs = nullptr;
esp32lua::Runtime rejected(incomplete);
assert(!rejected.open());
assert(rejected.state() == nullptr);
return 0;
}