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

refactor(api)!: one namespace per feature, screen split out

Browse Source 
Namespaces were shared across features: `settings` was written by core, the
panel and touch, and `input` by touch and buttons. That made "does this
firmware implement the whole feature?" a question no pointer could answer.

Each namespace now belongs to exactly one feature or to core, so a feature is
a provider pointer and the compiler validates completeness:

  gui, node       -> screen, tree, under the screen feature
  settings        -> screen (rotation, theme), sys (timezone),
                     touch (calibration)
  input           -> touch, buttons

Runtime::open() no longer requires a GuiProvider; a firmware without one runs
with no screen/tree globals and reports sys.hasFeature("screen") false.
Rotation is one value again: GuiProvider::setRotation applies and persists, so
an app rotating the panel transiently puts the old value back itself.
This commit is contained in:
Evan Reichard
2026-08-05 10:26:38 -04:00
parent 445a9b2b8f
commit 75b3a2c490
26 changed files with 556 additions and 626 deletions
Download Patch File Download Diff File Expand all files Collapse all files
native/src/bindings/core/settings.cpp
-101
View File
@@ -1,101 +0,0 @@
// @lua-module settings SettingsLib
#include <lua/runtime.h>
extern "C" {
#include "lauxlib.h"
#include "lua.h"
}
namespace esp32lua {
namespace bindings {
namespace {
int pushStatus(lua_State* state, const Status& status) {
if (status.ok) {
lua_pushboolean(state, true);
return 1;
}
lua_pushnil(state);
lua_pushlstring(state, status.error.data(), status.error.size());
return 2;
}
int getRotation(lua_State* state) {
lua_pushinteger(state, Runtime::from(state)->settings().rotation());
return 1;
}
int setRotation(lua_State* state) {
const lua_Integer degrees = luaL_checkinteger(state, 1);
luaL_argcheck(state, degrees >= 0 && degrees <= 270 && degrees % 90 == 0, 1,
"expected 0, 90, 180, or 270");
return pushStatus(state,
Runtime::from(state)->settings().setRotation(degrees));
}
int getTimezone(lua_State* state) {
const std::string timezone = Runtime::from(state)->settings().timezone();
lua_pushlstring(state, timezone.data(), timezone.size());
return 1;
}
int setTimezone(lua_State* state) {
size_t length = 0;
const char* value = luaL_checklstring(state, 1, &length);
return pushStatus(
state, Runtime::from(state)->settings().setTimezone({value, length}));
}
int getTheme(lua_State* state) {
const std::string theme = Runtime::from(state)->settings().theme();
lua_pushlstring(state, theme.data(), theme.size());
return 1;
}
int setTheme(lua_State* state) {
size_t length = 0;
const char* value = luaL_checklstring(state, 1, &length);
return pushStatus(state,
Runtime::from(state)->settings().setTheme({value, length}));
}
const luaL_Reg FUNCTIONS[] = {
// --- Returns the saved rotation in degrees clockwise.
// @return integer
{"getRotation", getRotation},
// --- Applies and persists the screen rotation.
// @param degrees integer 0, 90, 180, or 270 clockwise.
// @return true|nil ok
// @return string|nil error
{"setRotation", setRotation},
// --- Returns the active POSIX timezone rule.
// @return string
{"getTimezone", getTimezone},
// --- Applies and persists a POSIX timezone rule.
// @param timezone string
// @return true|nil ok
// @return string|nil error
{"setTimezone", setTimezone},
// --- Returns the saved palette name. Apps read ui.getTheme() instead; this
// --- is the stored value, which only ui.setTheme() knows how to apply.
// @return string
{"getTheme", getTheme},
// --- Persists a palette name without applying it. Call ui.setTheme(), which
// --- writes through here and then rebuilds the palette and repaints.
// @param theme string
// @return true|nil ok
// @return string|nil error
{"setTheme", setTheme},
{nullptr, nullptr},
};
} // namespace
void registerSettings(lua_State* state) {
luaL_newlib(state, FUNCTIONS);
lua_setglobal(state, "settings");
}
} // namespace bindings
} // namespace esp32lua
native/src/bindings/core/sys.cpp
+17 -1
View File
@@ -1,5 +1,5 @@
// @lua-module sys SysLib
// @lua-preamble ---@alias Feature "touch"|"buttons"
// @lua-preamble ---@alias Feature "screen"|"touch"|"buttons"
#include "../helpers.h"
@@ -66,6 +66,14 @@ int isClockSynced(lua_State* state) {
lua_pushboolean(state, Runtime::from(state)->sys().isClockSynced());
return 1;
}
int getTimezone(lua_State* state) {
pushString(state, Runtime::from(state)->sys().timezone());
return 1;
}
int setTimezone(lua_State* state) {
const std::string timezone = checkString(state, 1);
return pushStatus(state, Runtime::from(state)->sys().setTimezone(timezone));
}
const luaL_Reg FUNCTIONS[] = {
// --- Returns the implemented API contract version.
@@ -116,6 +124,14 @@ const luaL_Reg FUNCTIONS[] = {
// --- Whether network time synchronization has completed.
// @return boolean
{"isClockSynced", isClockSynced},
// --- Returns the active POSIX timezone rule.
// @return string
{"getTimezone", getTimezone},
// --- Applies and persists a POSIX timezone rule.
// @param timezone string
// @return true|nil ok
// @return string|nil error
{"setTimezone", setTimezone},
{nullptr, nullptr},
};
native/src/bindings/features/buttons.cpp
+6 -5
View File
@@ -32,18 +32,18 @@ int wasReleased(lua_State* state) {
return 1;
}
// @lua-augment input InputLib
// @lua-module buttons ButtonsLib
// @lua-preamble ---@alias Button "up"|"down"|"left"|"right"|"confirm"|"back"
// @lua-preamble
// @lua-preamble -- Roles, not physical buttons: a device maps whatever hardware
// it has onto them, and
// @lua-preamble -- up/down/left/right are the directions node.moveFocus already
// @lua-preamble -- up/down/left/right are the directions tree.moveFocus already
// takes.
const luaL_Reg INPUT_FUNCTIONS[] = {
const luaL_Reg FUNCTIONS[] = {
// ---Returns the roles this device reports, so an app can label only the
// actions it has.
// @return Button[]
{"getButtons", getButtons},
{"getAll", getButtons},
// ---Whether any button is held.
// @return boolean
{"isAnyPressed", isAnyPressed},
@@ -65,7 +65,8 @@ const luaL_Reg INPUT_FUNCTIONS[] = {
} // namespace
void registerButtons(lua_State* state) {
augmentGlobal(state, "input", INPUT_FUNCTIONS);
luaL_newlib(state, FUNCTIONS);
lua_setglobal(state, "buttons");
}
} // namespace bindings
native/src/bindings/core/gui.cpp → native/src/bindings/features/screen/screen.cpp
+65 -40
View File
@@ -1,15 +1,17 @@
// @lua-module gui GuiLib
// @lua-preamble ---@alias GuiColor integer
// @lua-preamble ---@alias GuiFont integer
// @lua-preamble ---@alias GuiTextStyle integer
// @lua-const FONT_SMALL GuiFont 0 Small auxiliary text.
// @lua-const FONT_UI GuiFont 0 Normal controls and labels.
// @lua-const FONT_BODY GuiFont 0 Normal reading text.
// @lua-const FONT_LARGE GuiFont 0 Headings and prominent values.
// @lua-const STYLE_NORMAL GuiTextStyle 0
// @lua-const STYLE_BOLD GuiTextStyle 0
// @lua-module screen ScreenLib
// @lua-preamble -- The panel itself; the widget tree it paints is `tree`, and
// @lua-preamble -- sys.hasFeature("screen") covers both.
// @lua-preamble ---@alias ScreenColor integer
// @lua-preamble ---@alias ScreenFont integer
// @lua-preamble ---@alias ScreenTextStyle integer
// @lua-const FONT_SMALL ScreenFont 0 Small auxiliary text.
// @lua-const FONT_UI ScreenFont 0 Normal controls and labels.
// @lua-const FONT_BODY ScreenFont 0 Normal reading text.
// @lua-const FONT_LARGE ScreenFont 0 Headings and prominent values.
// @lua-const STYLE_NORMAL ScreenTextStyle 0
// @lua-const STYLE_BOLD ScreenTextStyle 0
#include "../helpers.h"
#include "../../helpers.h"
namespace esp32lua {
namespace bindings {
@@ -36,8 +38,17 @@ int setRotation(lua_State* state) {
const int32_t degrees = checkInt(state, 1);
luaL_argcheck(state, degrees >= 0 && degrees <= 270 && degrees % 90 == 0, 1,
"expected 0, 90, 180, or 270");
provider(state).setRotation(degrees);
return 0;
return pushStatus(state, provider(state).setRotation(degrees));
}
int getTheme(lua_State* state) {
pushString(state, provider(state).theme());
return 1;
}
int setTheme(lua_State* state) {
const std::string theme = checkString(state, 1);
return pushStatus(state, provider(state).setTheme(theme));
}
int color(lua_State* state) {
@@ -215,62 +226,76 @@ const luaL_Reg FUNCTIONS[] = {
// --- Returns the live frame height.
// @return integer
{"getHeight", getHeight},
// --- Rotates the live frame without changing the saved preference.
// --- Rotates the panel and persists the choice, so there is one rotation
// --- rather than a live one and a saved one to reconcile.
// @param degrees integer 0, 90, 180, or 270 clockwise.
// @return true|nil ok
// @return string|nil error
{"setRotation", setRotation},
// --- Returns the rotation of the live frame.
// @return integer Degrees clockwise for the live frame.
// --- Returns the rotation in degrees clockwise.
// @return integer
{"getRotation", getRotation},
// --- Returns the saved palette name. Apps read ui.getTheme() instead; this
// --- is the stored value, which only ui.setTheme() knows how to apply.
// @return string
{"getTheme", getTheme},
// --- Persists a palette name without applying it. Call ui.setTheme(),
// which
// --- writes through here and then rebuilds the palette and repaints.
// @param theme string
// @return true|nil ok
// @return string|nil error
{"setTheme", setTheme},
// --- Returns an opaque native color. E-ink implementations quantize RGB to
// available grayscale.
// @param r integer 0 through 255.
// @param g integer 0 through 255.
// @param b integer 0 through 255.
// @return GuiColor
// @return ScreenColor
{"color", color},
// --- Clears the frame.
// @param color GuiColor|nil Defaults to white.
// @param color ScreenColor|nil Defaults to white.
{"clear", clear},
// --- Fills a rectangle.
// @param x integer
// @param y integer
// @param w integer
// @param h integer
// @param color GuiColor
// @param color ScreenColor
{"fillRect", fillRect},
// --- Outlines a rectangle.
// @param x integer
// @param y integer
// @param w integer
// @param h integer
// @param color GuiColor
// @param color ScreenColor
{"drawRect", drawRect},
// --- Draws a line.
// @param x1 integer
// @param y1 integer
// @param x2 integer
// @param y2 integer
// @param color GuiColor
// @param color ScreenColor
// @param width integer|nil Defaults to one pixel.
{"drawLine", drawLine},
// --- Draws a single pixel.
// @param x integer
// @param y integer
// @param color GuiColor
// @param color ScreenColor
{"drawPixel", drawPixel},
// --- Outlines a circle.
// @param x integer Center.
// @param y integer Center.
// @param radius integer
// @param color GuiColor
// @param color ScreenColor
// @param width integer|nil Defaults to one pixel.
{"drawCircle", drawCircle},
// --- Fills a circle.
// @param x integer Center.
// @param y integer Center.
// @param radius integer
// @param color GuiColor
// @param background GuiColor|nil Surface behind an anti-aliased edge.
// @param color ScreenColor
// @param background ScreenColor|nil Surface behind an anti-aliased edge.
{"fillCircle", fillCircle},
// ---Draws an anti-aliased rounded fill, optional gradient, and optional
// border in one pass.
@@ -279,16 +304,16 @@ const luaL_Reg FUNCTIONS[] = {
// @param w integer
// @param h integer
// @param radius integer
// @param background GuiColor Surface behind the anti-aliased edge.
// @param top GuiColor|nil Fill, or gradient top; omitted for no fill.
// @param bottom GuiColor|nil Gradient bottom; defaults to top. Panels
// @param background ScreenColor Surface behind the anti-aliased edge.
// @param top ScreenColor|nil Fill, or gradient top; omitted for no fill.
// @param bottom ScreenColor|nil Gradient bottom; defaults to top. Panels
// without a gradient use top.
// @param border GuiColor|nil Omitted for no border.
// @param border ScreenColor|nil Omitted for no border.
{"roundRect", roundRect},
// --- Fills a polygon.
// @param xs integer[]
// @param ys integer[]
// @param color GuiColor
// @param color ScreenColor
{"fillPolygon", fillPolygon},
// --- Draws a bitmap.
// @param path string Absolute BMP path.
@@ -300,31 +325,31 @@ const luaL_Reg FUNCTIONS[] = {
// @return string|nil error
{"drawBmp", drawBmp},
// --- Measures a text run.
// @param font GuiFont Use a named gui.FONT_* role.
// @param font ScreenFont Use a named screen.FONT_* role.
// @param text string
// @param style GuiTextStyle|nil Defaults to gui.STYLE_NORMAL.
// @param style ScreenTextStyle|nil Defaults to screen.STYLE_NORMAL.
// @return integer
{"getTextWidth", getTextWidth},
// --- Returns the line height of a font role.
// @param font GuiFont Use a named gui.FONT_* role.
// @param style GuiTextStyle|nil Defaults to gui.STYLE_NORMAL.
// @param font ScreenFont Use a named screen.FONT_* role.
// @param style ScreenTextStyle|nil Defaults to screen.STYLE_NORMAL.
// @return integer
{"getFontHeight", getFontHeight},
// --- Draws a text run with its top-left corner at x, y.
// @param font GuiFont Use a named gui.FONT_* role.
// @param font ScreenFont Use a named screen.FONT_* role.
// @param x integer Left edge.
// @param y integer Top edge.
// @param text string
// @param color GuiColor|nil Defaults to black.
// @param style GuiTextStyle|nil Defaults to gui.STYLE_NORMAL.
// @param background GuiColor|nil Omitted for transparent text.
// @param color ScreenColor|nil Defaults to black.
// @param style ScreenTextStyle|nil Defaults to screen.STYLE_NORMAL.
// @param background ScreenColor|nil Omitted for transparent text.
{"drawText", drawText},
{nullptr, nullptr},
};
} // namespace
void registerGui(lua_State* state) {
void registerScreen(lua_State* state) {
luaL_newlib(state, FUNCTIONS);
const FontIds fonts = Runtime::from(state)->gui().fonts();
setField(state, "FONT_SMALL", fonts.small);
@@ -333,7 +358,7 @@ void registerGui(lua_State* state) {
setField(state, "FONT_LARGE", fonts.large);
setField(state, "STYLE_NORMAL", fonts.styleNormal);
setField(state, "STYLE_BOLD", fonts.styleBold);
lua_setglobal(state, "gui");
lua_setglobal(state, "screen");
}
} // namespace bindings
native/src/bindings/core/node.cpp → native/src/bindings/features/screen/tree.cpp
+17 -17
View File
@@ -1,4 +1,4 @@
// @lua-module node NodeLib
// @lua-module tree TreeLib
// @lua-preamble ---@alias NodeId integer
// @lua-preamble ---@alias NodeType "box"|"text"|"button"|"custom"
// @lua-preamble ---@alias NodeDirection "up"|"down"|"left"|"right"
@@ -16,27 +16,27 @@
// @lua-preamble ---@field capture? boolean
// @lua-preamble ---@field interactive? boolean
// @lua-preamble ---@field label? string
// @lua-preamble ---@field font? GuiFont
// @lua-preamble ---@field font? ScreenFont
// @lua-preamble
// @lua-preamble ---@class NodeStyle
// @lua-preamble ---@field color? GuiColor
// @lua-preamble ---@field background? GuiColor Background offered to
// @lua-preamble ---@field color? ScreenColor
// @lua-preamble ---@field background? ScreenColor Background offered to
// descendants.
// @lua-preamble ---@field fill? GuiColor Surface painted by a box.
// @lua-preamble ---@field border? GuiColor
// @lua-preamble ---@field face? GuiColor Default button surface.
// @lua-preamble ---@field pressedFace? GuiColor Pressed button surface.
// @lua-preamble ---@field pressedColor? GuiColor Pressed button text.
// @lua-preamble ---@field focusColor? GuiColor Distinct outline for directional
// focus.
// @lua-preamble ---@field fill? ScreenColor Surface painted by a box.
// @lua-preamble ---@field border? ScreenColor
// @lua-preamble ---@field face? ScreenColor Default button surface.
// @lua-preamble ---@field pressedFace? ScreenColor Pressed button surface.
// @lua-preamble ---@field pressedColor? ScreenColor Pressed button text.
// @lua-preamble ---@field focusColor? ScreenColor Distinct outline for
// directional focus.
// @lua-preamble ---@field radius? integer
// @lua-preamble ---@field font? GuiFont
// @lua-preamble ---@field textStyle? GuiTextStyle
// @lua-preamble ---@field font? ScreenFont
// @lua-preamble ---@field textStyle? ScreenTextStyle
#include <cstdlib>
#include "../../node/painter.h"
#include "../helpers.h"
#include "../../../node/painter.h"
#include "../../helpers.h"
namespace esp32lua {
namespace bindings {
@@ -616,9 +616,9 @@ const luaL_Reg FUNCTIONS[] = {
} // namespace
void registerNode(lua_State* state) {
void registerTree(lua_State* state) {
luaL_newlib(state, FUNCTIONS);
lua_setglobal(state, "node");
lua_setglobal(state, "tree");
}
} // namespace bindings
native/src/bindings/features/touch.cpp
+17 -22
View File
@@ -40,8 +40,21 @@ int isTouched(lua_State* state) {
return 1;
}
// @lua-augment settings SettingsLib
const luaL_Reg SETTINGS_FUNCTIONS[] = {
// @lua-module touch TouchLib
const luaL_Reg FUNCTIONS[] = {
// --- Returns the calibrated touch point, or nothing when the panel is not
// touched.
// @return integer|nil x
// @return integer|nil y
{"getPoint", getTouch},
// --- Returns the uncalibrated touch reading, or nothing when the panel is
// not touched.
// @return integer|nil x
// @return integer|nil y
{"getRawPoint", getRawTouch},
// --- Whether the panel is currently touched.
// @return boolean
{"isTouched", isTouched},
// --- Persists the panel's touch calibration.
// @param x0 integer Raw reading at the left edge.
// @param y0 integer Raw reading at the top edge.
@@ -53,29 +66,11 @@ const luaL_Reg SETTINGS_FUNCTIONS[] = {
{nullptr, nullptr},
};
// @lua-augment input InputLib
const luaL_Reg INPUT_FUNCTIONS[] = {
// --- Returns the calibrated touch point, or nothing when the panel is not
// touched.
// @return integer|nil x
// @return integer|nil y
{"getTouch", getTouch},
// --- Returns the uncalibrated touch reading, or nothing when the panel is
// not touched.
// @return integer|nil x
// @return integer|nil y
{"getRawTouch", getRawTouch},
// --- Whether the panel is currently touched.
// @return boolean
{"isTouched", isTouched},
{nullptr, nullptr},
};
} // namespace
void registerTouch(lua_State* state) {
augmentGlobal(state, "settings", SETTINGS_FUNCTIONS);
augmentGlobal(state, "input", INPUT_FUNCTIONS);
luaL_newlib(state, FUNCTIONS);
lua_setglobal(state, "touch");
}
} // namespace bindings
native/src/embedded_modules.cpp
+2 -2
View File
File diff suppressed because one or more lines are too long
native/src/runtime/runtime.cpp
+15 -15
View File
@@ -11,12 +11,11 @@ namespace bindings {
void registerBle(lua_State* state);
void registerButtons(lua_State* state);
void registerFs(lua_State* state);
void registerGui(lua_State* state);
void registerHttp(lua_State* state);
void registerLog(lua_State* state);
void registerNode(lua_State* state);
void registerSettings(lua_State* state);
void registerScreen(lua_State* state);
void registerSys(lua_State* state);
void registerTree(lua_State* state);
void registerTimer(lua_State* state);
void registerTouch(lua_State* state);
void registerWifi(lua_State* state);
@@ -52,9 +51,9 @@ Runtime::~Runtime() { close(); }
bool Runtime::open() {
if (state_)
return true;
if (!providers_.log || !providers_.settings || !providers_.sys ||
!providers_.fs || !providers_.gui || !providers_.http ||
!providers_.timer || !providers_.wifi || !providers_.ble) {
if (!providers_.log || !providers_.sys || !providers_.fs ||
!providers_.http || !providers_.timer || !providers_.wifi ||
!providers_.ble) {
return false;
}
@@ -64,19 +63,20 @@ bool Runtime::open() {
*static_cast<Runtime**>(lua_getextraspace(state_)) = this;
luaL_openlibs(state_);
// Primary Namespaces
bindings::registerBle(state_);
bindings::registerFs(state_);
bindings::registerGui(state_);
bindings::registerHttp(state_);
bindings::registerLog(state_);
bindings::registerNode(state_);
bindings::registerSettings(state_);
bindings::registerSys(state_);
bindings::registerTimer(state_);
bindings::registerWifi(state_);
// Feature namespaces extend the tables the core registrations just created,
// so they always follow them.
// Feature Namespaces
if (providers_.gui) {
bindings::registerScreen(state_);
bindings::registerTree(state_);
}
if (providers_.touch)
bindings::registerTouch(state_);
if (providers_.buttons)
@@ -90,9 +90,7 @@ void Runtime::close() {
cancelAllTimers();
lua_close(state_);
state_ = nullptr;
mainRef_ = 0; // the registry it referenced went with the state
// Node handles mean nothing to the next lua_State, so an app that inherited
// the previous tree would build onto its nodes.
mainRef_ = 0;
tree_.reset();
appPath_.clear();
appTitle_.clear();
@@ -103,7 +101,7 @@ Runtime::Batch::Batch(Runtime& runtime) : runtime_(runtime) {
}
Runtime::Batch::~Batch() {
if (--runtime_.batchDepth_ == 0)
if (--runtime_.batchDepth_ == 0 && runtime_.providers_.gui)
runtime_.providers_.gui->commit();
}
@@ -319,6 +317,8 @@ std::string Runtime::appDataPath() const {
}
bool Runtime::hasFeature(const std::string& feature) const {
if (feature == "screen")
return providers_.gui != nullptr;
if (feature == "touch")
return providers_.touch != nullptr;
if (feature == "buttons")