WARNING - Do not use Lua Custom scripts for controlling any aspect of your model that could cause a crash if the script stops executing!

Overview

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

Please note: the firmware must be compiled with the option LUA_MIXER=Y for Custom scripts to be available.

Please note: the scripts should be as short as possible, to avoid delays. It is also important to keep in mind that other loaded Telemetry and Function scripts can add to the response time, or worse: hang the system!

Typical uses

• 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

Limitations

• cannot update LCD screen or perform user input.

• should not exceed allowed run-time/ number of instructions.

• custom scripts are run with less priority than built-in mixes. Their execution period is around 30ms and is not guaranteed!

• can be disabled/killed anytime due to logic errors in script, not enough free memory, etc...)

Lifetime

• Custom scripts are loaded from SD card when model is selected

• init __function is called first

• run function is called periodically (about 30 times per second)

• the script is killed (stopped and disabled) if it misbehaves (e.g. run-time error or low memory)

• all Custom scripts are stopped while a One-Time script is running (see Lua One-time scripts)

Disabled script

If the script output is used as a mixer source , and the script is killed for whatever reason, then the whole mixer line is disabled ! This can be used for example to provide a fallback in case Lua Custom script is killed.

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

File Location

Place them on SD card in folder /SCRIPTS/MIXES/. File name length (without extension) must be 6 characters or less (this limit was 8 characters in OpenTX 2.1).

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:

• input table (optional)

• output table (optional)

• init function (optional)

• run function

Example

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

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

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

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

return { input=input, output=output, run=run, init=init }

Input table

The input table defines what values are available as input(s) to custom scripts. There are two forms of input table entries.

{ "<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%.

{ "<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 (was 8 in 2.1)

Output table

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

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

Note: the above names are only visible as source values on the radio screen when the script is running. If the model is edited in Companion, then the values show as LUA1a and LUA1b etc.

TODO: Need to determine status of wizard in 2.2

Overview

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

Typical uses of Function scripts are:

• specialized handling in response to switch position changes

• customized announcements

Please be aware that:

• all function scripts are stopped if a One-Time Lua script is running

• Function scripts DO NOT HAVE ACCESS TO LCD DISPLAY

Lifetime

• init function is called once when the model is selected

• depending on the switch associated with the Special Function, either the run function (switch = on) or the background function (switch = off) is called periodically

• the script is stopped and disabled if it misbehaves (e.g. run-time error or low memory)

File Location

Scripts are located on the SD card in the folder /SCRIPTS/FUNCTIONS/<name>.lua. File name length (without extension) must be 6 characters or less (this limit was 8 characters in OpenTX 2.1).

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:

• init function (optional)

• run function

• background function (optional)

Example

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

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

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

return { run=run, background=background, init=init }

Overview

Telemetry scripts are used for building customized screens. 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.

Please note: Telemetry scripts are only available on radios with telemetry screens, such as e.g. FrSky Taranis models (including Xlite), Radiomaster TX12 and and Jumper T12.

Lifetime

• Telemetry scripts are loaded when the model is selected.

• init function is called one time when the script is loaded

• background function is periodically; both when the telemetry screen is visible and when it is not.

• run function is called periodically only when the telemetry screen is visible

• script is stopped and disabled if it misbehaves (e.g. run-time error or low memory)

• all telemetry scripts are stopped if a one-time script is running (see One-time scripts)

File Location

Scripts are located on the SD card in the folder /SCRIPTS/TELEMETRY/<name>.lua. File name length (without extension) must be 6 characters or less (this limit was 8 characters in OpenTX 2.1).

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:

• init function (optional)

• background function (optional)

• run function

Example

local function init()
  -- init is called once when model is loaded
end

local function background()
  -- background is called periodically
end

local function run(event)
  -- run is called periodically only when screen is visible
end

return { run = run, background = background, init = init }

Notes:

• The event parameter indicates which transmitter key has been pressed (see Key Events).

WARNING - Running a One-Time script will suspend execution of all other currently loaded Lua scripts (Custom, Telemetry, and Functions)

Overview

One-Time scripts start when called upon by a specific radio function or when the user selects them from a contextual menu. They do their task and are then terminated and unloaded. Please note that all persistent scripts are halted during the execution of One-Time scripts. They are automatically restarted once the One-Time script is finished. This is done to provide enough system resources to execute the one time script.

Lifetime

Script is executed when user selects Execute on a script file from SD card browser screen.

Script executes until:

• it returns value different from 0

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

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

  memory)

File Location

Place them anywhere on SD card, the folder /SCRIPTS/ is recommended. The only exception is official model wizard script, that should be put into /SCRIPTS/WIZARD/ folder that way it will start automatically when new model is created.

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:

• init function (optional)

• run function

Example

local function init()
  -- init is called once when model is loaded
end

local function run(event)
  -- run is called periodically only when screen is visible
  -- A non-zero return value will halt the script
  return x
end

return { run=run, init=init }

Notes:

• The event parameter indicates which transmitter key has been pressed (see Key Events).

• A non-zero return value from run will halt the script.

Overview

Most of the time, widget scripts show some info in a zone either in the top bar or in one of the user defined main views, and they cannot receive direct input from the user via key events like e.g. Telemetry scripts.

But widgets on the main views can also be shown in full screen mode, where they take over the entire screen area. And here they receive user input via key events, and for radios with touch screen, also touch events. Full screen mode can be entered by selecting the widget, pressing ENTER and selecting Full screen on the widget menu, or by double tapping the widget on radios with a touch screen. Full screen mode can be exited by long pressing the RETURN button, or by calling the Lua function lcd.exitFullScreen().

Each model can have up to five 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.

Please note: Widget scripts are only available on radios with color screens, e.g. FrSky Horus models, Radiomaster TX16 and Jumper T16.

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 script on the SD card will consume part of the radio's memory - even if it is not being used. Therefore, it is important to either keep widget scripts small, or to use Lua's loadScript() function to load code dynamically.

They can be added to the top bar or a main view through the telemetry setup menu. When a widget has been added to a screen, then the widget functions are called as follows:

• create is called once when the widget instance is registered (started).

• update is called when widget settings are changed by the user.

• background is called periodically when the widget instance is not visible. Note: this is different from the way that telemetry scripts are handled.

• refresh is called periodically when the widget instance is visible. Note: if you want background to run when the widget is visible, then call it from refresh.

• A widget script is stopped and disabled if it misbehaves (e.g. too long runtime, run-time error, or low memory)

• All widgets are stopped while a One-Time script is running (see One-Time scripts).

File Location

Widgets are located on the SD card, each in their specific folder /WIDGETS/<name>/main.lua (<name> must be in 8 characters or less).

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:

• name string

• options table

• create function

• update function

• background function (optional)

• refresh function

Example

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
}

Notes

• The name must be max. 10 characters long.

• options is passed to create and then stored in Lua. Changing it has no effect on EdgeTX.

• If options is changed by the user in the Widget Settings menu, then update will be called with a new options table, unaffected by any changes made by Lua code to the old options table.

• Maximum five options are allowed, with names of max. 10 characters, and no spaces.

• If local variables are declared outside functions in the widget script, then they are shared between all instances of the widget.

• Therefore, local variables that are private for each instance should be added to the widget table in the create function before returning the widget table to EdgeTX.

• When the widget is in full screen mode, then event is either 0, a key event value, or a touch event value.

• If event is a touch event value, then touchState is a table. Otherwise, it is nil.

• When the widget is not in full screen mode, then both event and touchState are nil.

• The size of the widget's screen area is as follows:

  • Full screen mode: LCD_W by LCD_H

  • Not full screen mode: zone.w by zone.h