evan
75b3a2c490
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.
19 lines
1.5 KiB
Markdown
19 lines
1.5 KiB
Markdown
# ESP32 Lua API Guidelines
|
|
|
|
This is a clean contract for repositories under the same owner's control. Choose the best shared
|
|
API without preserving old names, signatures, or behavior; consumers migrate to the contract.
|
|
|
|
Every firmware implements all declarations under `lua/api/core/`. Optional hardware contracts
|
|
live under `lua/api/features/`, as one file or one directory per feature; `sys.hasFeature(name)`
|
|
guarantees the complete matching contract. Every namespace belongs to exactly one feature or to
|
|
core, so a feature is a provider pointer rather than a claim to validate: a panel is the `screen`
|
|
feature (`screen` and `tree`, including the saved rotation and theme), registered only when the
|
|
firmware supplies a `GuiProvider`, and calibration is `touch.setCalibration()`.
|
|
Lua-language sources stay under `lua/`; C/C++ and the vendored interpreter stay under `native/`.
|
|
Apps are fully trusted; keep permissions and sandboxing out of scope.
|
|
Firmware commits dirty display content and owns panel refresh policy. Binding annotations under
|
|
`native/src/bindings/` generate matching `lua/api/` files; regenerate instead of editing files
|
|
marked generated. Each `@lua-module`/`@lua-augment` directive sits immediately above the
|
|
`luaL_Reg` table it describes, which is how one source declares several namespaces. This repository owns portable `lua/lib/` modules; shared UI owns theme application and persistence. Use `ble` for BLE/GATT
|
|
and reserve `bt` for a future Classic Bluetooth contract.
|