Lua Scripting

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 idf.py flash.

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.

API Reference

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.)

Interactive REPL

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).