Introduction

Lua was chosen for EdgeTX, because it is a small language designed to be highly extensible by libraries written in C and C++, so it can be integrated into other systems like EdgeTX. It is also relatively efficient, both in terms of memory and CPU usage, and hence well suited for the radios.

In addition to the provided libraries, Lua has a very elegant mechanism for loading new Lua code modules during run-time. A lot of the elegance comes from the way that the loading mechanism meshes with another concept supported by Lua: first class functions with closures.

First Class Functions

Computer science pioneer Christopher Strachey introduced the concept of functions as first-class objects in his paper Fundamental Concepts in Programming Languages from 1967. What it means is that functions can be treated as other variables: as arguments passed in function calls, as results returned from function calls, and a function identifier can be re-assigned to another chunk of function code, just like a variable ca be assigned to a new value.

In Lua, a function declaration is really "syntactic sugar" for assigning a variable to the chunk of code that is called when the function is invoked, i.e.

local function f(x) return x + 1 end

is the same as

local f = function(x) return x + 1 end

You can even add functions to Lua tables, i.e.

t = { f = f }

will add the above function to the table t, as a field that is also called f. Does that look familiar to the return statement required at the end of a Lua script?

Yes indeed, because a script is really an anonymous function that returns a list of functions to the system. The function declarations assign variables to chunks of function code, these variables are added to the list returned at the end of the script, and the system then calls the functions periodically to run the script. So the script itself is run one time initially, and subsequently the functions returned by the last statement are called periodically.

Closures

Another important concept that goes with first-class functions, is closures. This is the environment of the function with the variable names that the function can see. Please consider the following function counter that returns another function:

local function counter(start, step)
  local x = start

  return function()
    local y = x
    x = x + step
    return y
  end
end

The function is returned directly without being assigned to a variable name. The closure of the function returned is the body of the function counter, containing both the arguments start and step, and the local variable x. So if c1 = counter(1, 1) then c1() will return 1, 2, 3, ... when called repeatedly, and if c2 = counter(2, 3) then c2() will return 2, 5, 8, ...

Likewise, the local variables that you declare outside the functions of your script can be used by all of the functions in your script, and they persist between function calls, but they are not visible to other scripts.

The widget scripts are a little trickier, as you can register multiple instances of the same widget script, and all of these instances run within the same Lua closure. Therefore, local variables declared outside any functions in a widget script are shared among all of the instances of that script. But each call to the create(...) function returns a new widget list to the system. And since this list is unique to each instance, you can add private instance variables to it.

Functions with Variable Number of Arguments

Please consider this function:

local function match(x, ...)
  for i, y in ipairs({...}) do
    if x == y then
      return true
    end
  end
  return false
end

It takes an argument x and a vararg list ... A vararg list is just like a list of arguments separated by commas, and you can call the function with any number of arguments greater than 1. Inside the function, you can also treat ... like a comma separated list of variables, e.g. in the above function, ... is converted to a table by {...} just like you could construct a table by e.g. {a, b, c}. The table is iterated with the ipairs function to look for an element matching the first argument x. So e.g. the following statement

if event == EVT_VIRTUAL_ENTER or event == EVT_VIRTUAL_EXIT then

can be replaced by

if match(event, EVT_VIRTUAL_ENTER, EVT_VIRTUAL_EXIT) then

You can also use ... directly as a comma separated list of values, e.g. local a, b, c = ... will assign the three variables to the three first arguments following x, or nil if none are given.

LUA Version

EdgeTX 2.10 uses LUA interpreter and compiler version 5.2 For detailed reference read Lua 5.2 Reference Manual

Included standard libraries

Standard LUA library has been simplified and only a subset of functions and their functionality is available.

Available functions:

• io.open()

• io.close()

• io.read()

• io.write()

• io.seek()

Examples

Read the whole file

Append data to file

Purpose

Function scripts are invoked via EdgeTX 'Lua Script' of Special Functions configuration page.

Typical uses of Function scripts are:

• specialized handling in response to switch position changes

• customized announcements

Execution & Lifetime

Function script is loded when model is selected. Script executes until

• it misbehaves (e.g. run-time error or low memory)

• One-time Script is running. When One-time script finishes execution, Wigdet Script resumes execution.

File Location

Function scripts are located on the SD card in the folder /SCRIPTS/FUNCTIONS/

Interface

Every Function script must include a return statement at the end, defining its interface to EdgeTX.

This statement returns a table with the following fields:

Parameters none

Return values none

Parameters none

Return Values none

Parameters none

Return Values none\

Example

local function my_init()
  -- Called once when the script is loaded
end

local function my_run()
  -- Called periodically while the Special Function switch is on
end

local function my_background()
  -- Called periodically while the Special Function switch is off
end

return { run = my_run, background = my_background, init = my_init }

Purpose

Mixes Scripts take one or more values as inputs, do some processing in Lua code, and output one or more values. Each model can have several Mixes Scripts associated with it, and these scripts are run periodically. They behave similarly to standard EdgeTX mixers, but at the same time they provide a much more flexible and powerful tool.

Typical use cases:

• replacement for complex mixes that are not critical to model function

• complex processing of inputs and reaction to their current state and/or their history

• filtering of telemetry values

Execution & Lifetime

Mixes script is loded when model is selected. Script executes until

• it misbehaves (e.g. run-time error or low memory)

• One-time Script is running. When One-time script finishes execution, Wigdet Script resumes execution.

File Location

Mixes scripts are located on SD card in folder /SCRIPTS/MIXES/

Interface

Every Mixes Script must include a return statement at the end, defining its interface to EdgeTX. This statement returns a table with the following fields:

This function is called periodicaly when script is running. Parameters Variables matching those used in input table Return values Variables matching those used in output table\

This function is called once when Mixes Script is loaded and executed for the first time

Parameters none Return values none\

The input table defines what values are available as input(s) to custom scripts.

There are two forms of input table entries

SOURCE

{ "<name>", SOURCE }

SOURCE inputs provide the current value of a selected OpenTX variable. The source must be selected by the user when the script is configured. Source can be any value that EdgeTX knows about (inputs, channels, telemetry values, switches, custom functions etc.). Note: the typical input range is -1024 thru +1024. Simply divide the input value by 10.24 to convert to a percentage from -100% to +100%.

VALUE

{ "<name>", VALUE, <min>, <max>, <default> }

VALUE inputs provide a constant value that is set by the user when the script is configured.

• name - maximum length of 8 characters

• min - minimum value of -128

• max - maximum value of 127

• default - must be within the valid range specified

• Maximum of 6 inputs per script

The output table defines only name(s), as the actual values are returned by the script's run function.

{ "<name1>", "<name2>" }

Examples

Example of <decribe what it does>.

local my_input =
  {
    { "Strength", SOURCE},           -- user selects source (typically slider or knob)
    { "Interval", VALUE, 0, 100, 0 } -- interval value, default = 0.
  }

local my_output = { "Val1", "Val2" }

local function my_init()
  -- Called once when the script is loaded
end

local function my_run(Strength, Interval) -- Must match input table
  local v1, v2
  -- Called periodically
  return v1, v2                        -- Must match output table
end

return { input = my_input, output = my_output, run = my_run, init = my_init }

Example where Lua mix script is used to drive ailerons in some clever way, but control falls back to the standard aileron mix if script is killed. Second mixer line replaces the first one when the script is alive:

CH1  [I4]Ail Weight(+100%)
  := LUA4b Weight(+100%)

Purpose

Widget scripts are avaiable on radios equiped with color LCD. They are designed to run constantly in the background performinfg various task. Widget scripts are mostly used to extend EdgeTX functionality via Widgets that are places by user on Main Views. They are equivalent of Telemetry Scripts on radios equiped with B&W LCD.

Most of the time, widget scripts show some info in a Widget's zone in one of the user defined Main Views. They cannot receive direct input from the user via key events with exeption of being displayed in so called Full Screen mode. Full screen mode can be entered by selecting the widget, pressing ENTER and selecting Full screen from the widget's contextual menu, or by double tapping the widget on radios with a touch screen. Full screen mode can be exited by long pressing the EXIT (RTN) button, or by calling the Lua function lcd.exitFullScreen().

Each model can have up to nine Main Views, with up to 8 widgets per screen, depending on their size and layout. Each instance of a widget has his own options table.

Execution & Lifetime

All widget scripts on the SD card are loaded into memory when the model is selected, even widgets that are not used. This has the side effect that any global functions defined in a widget script will always be available to other widget scripts. It also means that any Widget Script placed in proper location on the SD card will consume part of the radio's memory - even if it is not being used.

Script executes until:

• it misbehaves (e.g. too long runtime, run-time error, or low memory)

• One-Time script is running. When One-time script finishes execution, Wigdet Script resumes execution.

File Location

Widget scripts are located on the SD card, each one in their specific folder: /WIDGETS/<folder name>/

Widget script name is constant and has to be named main.lua

Interface

Every Widget Script must include a return statement at the end, defining its interface to EdgeTX. This statement returns a table with the following fields:

Parameters

Return values

Parameters

Return values none

Parameters

Return values none

Parameters

Return values none

Examples

local name = "WidgetName"

-- Create a table with default options
-- Options can be changed by the user from the Widget Settings menu
-- Notice that each line is a table inside { }
local options = {
  { "Source", SOURCE, 1 },
  -- BOOL is actually not a boolean, but toggles between 0 and 1
  { "Boolean", BOOL, 1 },
  { "Value", VALUE, 1, 0, 10},
  { "Color", COLOR, ORANGE },
  { "Text", STRING, "Max8chrs" }
}

local function create(zone, options)
  -- Runs one time when the widget instance is registered
  -- Store zone and options in the widget table for later use
  local widget = {
    zone = zone,
    options = options
  }
  -- Add local variables to the widget table,
  -- unless you want to share with other instances!
  widget.someVariable = 3
  -- Return widget table to EdgeTX
  return widget
end

local function update(widget, options)
  -- Runs if options are changed from the Widget Settings menu
  widget.options = options
end

local function background(widget)
  -- Runs periodically only when widget instance is not visible
end

local function refresh(widget, event, touchState)
  -- Runs periodically only when widget instance is visible
  -- If full screen, then event is 0 or event value, otherwise nil
end

return {
  name = name,
  options = options,
  create = create,
  update = update,
  refresh = refresh,
  background = background
}

Purpose

One-time scripts are used mainly to perform tasks that are not connected with flying. In example ELRS configuration LUA script. They do their task and are then terminated (by user or function) and unloaded.

Execution & Lifetime

Script is executed when user selects "Execute" on a script file from SD card browser screen, or opens a Lua Tool, or creates a new model with a Wizard script.

The script executes until:

• it returns value different from 0 (except returning string that contains new script name to be executed)

• is forcefully closed by user by long press of EXIT key

• is forcefully closed by system if it misbehaves (e.g. run-time error or low

  memory)

File Location

One-Time Scripts can be placed anywhere on SD card, however, the folder /SCRIPTS/ is recommended.

Interface

Every script must include a return statement at the end, defining its interface to EdgeTX. This statement returns a table with the following fields:

Parameters

Return values

Parameters none

Return Values none

Examples

Simplest one-time LUA script

One-Time LUA script with initialization and exit feature if user short press and release EXIT (RTN) key

Radios with B&W LCD screen

Radios with Grayscale LCD screen

Radios with COLOR LCD screen

Technical Data

LUA data

Inputs overview

EdgeTX internal Source List contains every source available on particular radio model.

Source List groups

Source List ID

Particular Source List ID is a integer number from 1 to whatever last source entry is used by EdgeTX developers during firmware implementation. Different Radios have different number of physical inputs that affects this list. Therefore for the same source type (ie LS04 - Logical switch number 4) sourceListID can have different value on particular radio model

Source List Name

Purpose

Although they are named "Telemetry scripts" in fact they can be used to perform constant task while running in background. Telemetry scripts are mostly used for building customized screens that are avalilable to user directly from main screen using key shortcut. Each model can have up to three active scripts as configured on the model's Telemetry configuration page. The same script can be assigned to multiple models.

Execution & Lifetime

Telemetry script is loaded and executed when model is selected. Script executes until:

• it misbehaves (e.g. run-time error or low memory)

• is running. When One-time script finishes execution, Wigdet Script resumes execution.

File Location

Telemetry scripts are located on the SD card in the folder /SCRIPTS/TELEMETRY/.

Interface

Every Telemetry script must include a return statement at the end, defining its interface to EdgeTX. This statement returns a table with the following fields:

Parameters

Return values none

Parameters none

Return Values none

Parameters none

Return Values none

Examples