Tangara's firmware includes extensive support for the Lua programming language. Lua is a small but very expressive scripting language, and is very easy to learn. If this is your first time encountering Lua, then the online version of Programming in Lua is an excellent read.
All of Tangara's UI is written in Lua, using bindings to the LVGL graphics library, as well as a small two-way data binding framework implemented in the C++ firmware.
Developing in Lua
Tangara's default Lua UI is located in the
lua/ subdirectory of the ESP32 firmware repository. This directory is assembled into an SPIFFS filesystem image, and then flashed onto your device as a part of a standard
If your editor supports LSP, then you may want to consider installing an configuring lua-language-server for completions, formatting, and diagnostics. A configuration file,
.luarc.json, is already provided in the root of the ESP32 repository. This file configures the language server to use the stub modules in
luals-stubs/ to generate completions for modules that are provided by the C++ firmware.
You can find complete reference documentation for the Lua bindings provided by Tangara here.
This reference documentation is created with LDoc, using the stub modules in
ldoc-stubs/. (Unfortunately, lua-language-server and LDoc use different annotations styles that are mutually incompatible, so we are not able to use the same set of stubs for both tools.)
When using the USB serial console on your device, you can access a basic Lua REPL environment for interactive testing. You can access this environment by entering
lua into the console.
At time of writing, the REPL environment is somewhat limited, as it is missing a number of bindings that are available to the Lua scripts responsible for the UI.
The REPL is built using lua-term and lua-repl, which are flashed to the 'repl' partition on your device as a part of a standard build (although you will not usually ever need to modify this partition).