Loading...
Loading...
Loading...
Loading...
This section introduces the types of Lua scripts supported by EdgeTX and how they may be used.
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
WARNING - Do not use Lua Custom scripts for controlling any aspect of your model that could cause a crash if the script stops executing!
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!
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
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...)
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)
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:
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).
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
The input table defines what values are available as input(s) to custom scripts. There are two forms of input table entries.
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 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)
The output table defines only name(s), as the actual values are returned by the script's run function.
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.
This section provides more specifics on the EdgeTX Lua implementation. Here you will find syntax rules for interface tables and functions.
This section includes Acknowledgments and Getting Started.
TODO: Need to determine status of wizard in 2.2
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.
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)
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).
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
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
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)
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).
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)
WARNING - Running a One-Time script will suspend execution of all other currently loaded Lua scripts (Custom, Telemetry, and Functions)
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.
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)
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.
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
A non-zero return value from run
will halt the script.
EdgeTX Companion 2.6 is available for download here (pick the version for your operating system from Assets heading at the bottom of the page - filename will have cpn
as part of the name).
If you intend to use mixer scripts, when updating the firmware on your transmitter you need to make sure the lua
option is checked in the settings for your radio profile (Main menu -> Settings ->Settings...) as shown below. This is not required if you only intend to run telemetry, one-time and function scripts, support for those is included by default.
Also note that the SD Structure path should contain a valid path to a copy of your transmitter's SD card contents, although that's not specific to Lua.
The EdgeTX team has no intention of making a profit from their work. EdgeTX is free and open source and will remain free and open source. But EdgeTX is more expensive to maintain than most open source projects. The reason is that there is a never ending flood of hardware to integrate and maintain code for. Hardware that costs.
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.
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 ).
Widgets are located on the SD card, each in their specific folder /WIDGETS/<name>/main.lua (<name> must be in 8 characters or less).
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
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 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
The event
parameter indicates which transmitter key has been pressed (see ).
The event
parameter indicates which transmitter key has been pressed (see ).
When the widget is in full screen mode, then event
is either 0, a , or a .
If event
is a , then touchState
is a table. Otherwise, it is nil
.