The latest version of this guide will always be available here. At the top of the left sidebar there is a version option if you are running an older version of EdgeTX or OpenTX and need the docs for that specific version.
This guide covers the development of user-written scripts for R/C transmitters running the EdgeTX 2.4 operating system with Lua support. Readers should be familiar with EdgeTX/OpenTX, the OpenTX Companion, and know how to transfer files the SD card in the transmitter.
Part I of the guide shows how to enable Lua support for Taranis and includes basic examples of each types of script.
Part II is a programming guide that introduces the types of EdgeTX Lua scripts and how to use them.
Part III is the EdgeTX Lua API Reference
Part IV addresses common issues in converting Lua scripts that were originally written for OpenTX 2.0
Part V addresses common issues in converting Lua scripts that were originally written for OpenTX 2.1
Part VI covers advanced topics with examples
Part I - Script Type Overview
This section introduces the types of Lua scripts supported by EdgeTX and how they may be used.
Introduction
This section includes Acknowledgments and Getting Started.
Acknowledgments
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.
Wizard Script
TODO: Need to determine status of wizard in 2.2
Saving Memory
io.read()
io.close()
io.write()
io.open()
Screen Constants
Name
Description
LCD_W
width in pixels
LCD_H
height in pixels
io.seek()
crossfireTelemetryPush()
This functions allows for sending telemetry data toward the TBS Crossfire link.
When called without parameters, it will only return the status of the output buffer without sending anything.
@status current Introduced in 2.2.0, retval nil added in 2.3.4
Parameters
command command
data table of data bytes
Return value
boolean data queued in output buffer or not.
nil incorrect telemetry protocol.
getRtcTime()
Return current RTC system date as unix timstamp (in seconds since 1. Jan 1970)
Please note the RTC timestamp is kept internally as a 32bit integer, which will overflow in 2038.
Parameters
none
Return value
number Number of seconds elapsed since 1. Jan 1970
defaultStick(channel)
Get stick that is assigned to a channel. See Default Channel Order in General Settings.
@status current Introduced in 2.0.0
Parameters
channel (number) channel number (0 means CH1)
Return value
number Stick assigned to this channel (from 0 to 3)
multiBuffer(address[,value])
This function reads/writes the Multi protocol buffer to interact with a protocol².
@status current Introduced in 2.3.2
Parameters
address to read/write in the buffer
@param (optional): value to write in the buffer
Return value
buffer value (number)
bit32.Library
TODO
GREY()
Returns gray value which can be used in LCD functions
@status current Introduced in 2.0.13
Parameters
none
Return value
(number) a value that represents amount of greyness (from 0 to 15)
Notice
Only available on Taranis
string.Library
TODO
serialWrite(str)
@param str (string) String to be written to the serial port.
Writes a string to the serial port. The string is allowed to contain any character, including 0.
@status current Introduced in 2.3.10
Parameters
none
Return value
none
getRAS()
Return the RAS value or nil if no valid hardware found
@status current Introduced in 2.2.0
Parameters
none
Return value
number representing RAS value. Value bellow 0x33 (51 decimal) are all ok, value above 0x33 indicate a hardware antenna issue.
This is just a hardware pass/fail measure and does not represent the quality of the radio link
Notice
RAS was called SWR in the past
playFile(name)
Play a file from the SD card
@status current Introduced in 2.0.0, changed in 2.1.0
Parameters
path (string) full path to wav file (i.e. “/SOUNDS/en/system/tada.wav”)
Introduced in 2.1.0: If you use a relative path, the current language is appended
to the path (example: for English language: /SOUNDS/en is appended)
Return value
none
popupConfirmation(title, message, event)
Raises a pop-up on screen that asks for confirmation
@status current Introduced in 2.2.0, changed from (title, event) to (title, message, event) in 2.3.8
Parameters
title (string) title to display
message (string) text to display
event (number) the event variable that is passed in from the Run function (key pressed)
Return value
"CANCEL" user pushed EXIT key
Notice
Use only from stand-alone and telemetry scripts.
model.deleteInputs()
Delete all Inputs
@status current Introduced in 2.0.0
Parameters
none
Return value
none
chdir(directory)
Change the working directory
@status current Introduced in 2.3.0
Parameters
directory (string) New working directory
Return value
none
Model Functions
Part III - EdgeTX Lua API Reference
This section describes the Lua libraries, functions and constants that are provided by EdgeTX.
General Functions
setSerialBaudrate(baudrate)
Set baudrate for serial port(s) affected to LUA
@status current Introduced in 2.3.12
Parameters
baudrate Desired baudrate
Return value
none
model.deleteMix(channel, line)
Delete mixer line from specified Channel
@status current Introduced in 2.0.0
Parameters
channel (unsigned number) channel number (use 0 for CH1)
line (unsigned number) mix number (use 0 for first line(mix))
Return value
none
model.defaultInputs()
Set all inputs to defaults
@status current Introduced in 2.0.0
Parameters
none
Return value
none
Using Key and Touch Events
io Library
model.getGlobalVariable(index, flight_mode)
Return current global variable value
Example:
-- get GV3 (index = 2) from Flight mode 0 (FM0)
val = model.getGlobalVariable(2, 0)
Parameters
index zero based global variable index, use 0 for GV1, 8 for GV9
flight_mode Flight mode number (0 = FM0, 8 = FM8)
Return value
nil requested global variable does not exist
number current value of global variable
Notice
a simple warning or notice
Included Lua Libraries
Lua Standard Libraries
Included
package
-
coroutine
-
table
-
since OpenTX 2.1.0 (with limitations)
os
getRotEncSpeed()
Return rotary encoder current speed
@status current Introduced in 2.3.10
Parameters
none
Return value
number in list: ROTENC_LOWSPEED, ROTENC_MIDSPEED, ROTENC_HIGHSPEED
Constants
This section describes various constants that are provided for Lua by EdgeTX.
Get RSSI value as well as low and critical RSSI alarm levels (in dB)
@status current Introduced in 2.2.0
Parameters
none
Return value
rssi RSSI value (0 if no link)
alarm_low Configured low RSSI alarm level
alarm_crit
resetGlobalTimer([type])
Resets the radio global timer to 0.
@status current Introduced in 2.2.2, param added in 2.3
Parameters
(optional) : if set to 'all', throttle ,throttle percent and session timers are reset too
Return value
none
playDuration(duration [, hourFormat])
Play a time value (text to speech)
@status current Introduced in 2.1.0
Parameters
duration (number) number of seconds to play. Only integral part is used.
hourFormat (number):
0 or not present play format: minutes and seconds.
!= 0
Return value
none
model.getInfo()
Get current Model information
@status current Introduced in 2.0.6, changed in 2.2.0
Parameters
none
Return value
table model information:
name (string) model name
bitmap
playHaptic(duration, pause [, flags])
Generate haptic feedback
@status current Introduced in 2.2.0
Parameters
duration (number) length of the haptic feedback in milliseconds
pause (number) length of the silence after haptic feedback in milliseconds
flags (number):
0 or not present play with normal priority
PLAY_NOW
Return value
none
One-Time Scripts
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.
Loading Code Modules Dynamically
Lua makes it easy to load and unload code modules on the fly, to save memory or to provide program extensions.
The function will load a script from a the file and return a function that is the body of the script, as described in the previous section. So you could have the following Lua script file saved on the SD card:
You can load and use the above file with the following code:
So here we put together what we learned in the previous section. The body of the script is an anonymous function returned by loadScript and stored in the variable chunk. It returns the function f when it is called. The local variable c in the script is assigned to the first vararg passed to the call. Since a new closure is created every time we call
defaultChannel(stick)
Get channel assigned to stick. See Default Channel Order in General Settings
@status current Introduced in 2.0.0
Parameters
accessTelemetryPush()
This functions allows for sending SPORT / ACCESS telemetry data toward the receiver, and more generally, to anything connected SPORT bus on the receiver or transmitter.
When called without parameters, it will only return the status of the output buffer without sending anything.
@status current Introduced in 2.3
Parameters
getFlightMode(mode)
Return flight mode data.
@status current Introduced in 2.1.7
Parameters
killEvents(key)
Stops key state machine. See for the detailed description.
Note that functions returns the tables starting with index 0 contrary to LUA's usual index starting with 1
@status current Introduced in 2.0.12
Parameters
model.deleteFlightModes()
Clear all flightModes
@status current Introduced in 2.3.10
Parameters
none
serialRead([num])
@param num (optional): maximum number of bytes to read. If non-zero, serialRead will read up to num characters from the buffer. If 0 or left out, serialRead will read up to and including the first newline character or the end of the buffer. Note that the returned string may not end in a newline if this character is not present in the buffer.
Reads characters from the serial port. The string is allowed to contain any character, including 0.
@status current Introduced in 2.3.8
Parameters
getTxGPS()
Return the internal GPS position or nil if no valid hardware found
@status current Introduced in 2.2.2
Parameters
none
sportTelemetryPop()
Pops a received SPORT packet from the queue. Please note that only packets using a data ID within 0x5000 to 0x50FF (frame ID == 0x10), as well as packets with a frame ID equal 0x32 (regardless of the data ID) will be passed to the LUA telemetry receive queue.
@status current Introduced in 2.2.0
Parameters
none
model.getFlightMode(index)
Return input data for given input and line number
@status current Introduced in 2.3.10
Parameters
getDateTime()
Return current system date and time that is kept by the RTC unit
Parameters
none
model.deleteMixes()
Remove all mixers
@status current Introduced in 2.0.0
Parameters
none
popupWarning(title, event)
Raises a pop-up on screen that shows a warning
@status current Introduced in 2.2.0
Parameters
model.resetSensor(sensor)
Reset Telemetry Sensor parameters
@status current Introduced in 2.3.11
Parameters
model.insertInput(input, line, value)
Insert an Input at specified line
@status current Introduced in 2.0.0, curveType/curveValue/carryTrim added in 2.3, inputName added 2.3.10
Parameters
model.resetTimer(timer)
Reset model timer to a startup value
@status current Introduced in TODO
Parameters
Configured critical RSSI alarm level
play format: hours, minutes and seconds.
(string) bitmap name (not present on X7)
play immediately
stick (number) stick number (from 0 to 3)
Return value
number channel assigned to this stick (from 0 to 3)
nil stick not found
module module index (0 = internal, 1 = external)
rxUid receiver index
sensorId physical sensor ID
frameId frame ID
dataId data ID
value value
Return value
boolean data queued in output buffer or not.
mode (number) flight mode number to return (0 - 8). If mode parameter
is not specified (or contains invalid value), then the current flight mode data is returned.
Return value
multiple returns 2 values:
(number) (current) flight mode number (0 - 8)
(string) (current) flight mode name
value (number) number to play. Value is interpreted as integer.
unit (number) unit identifier [Full list]((../appendix/units.html))
attributes (unsigned number) possible values:
0 or not present plays integral part of the number (for a number 123 it plays 123)
PREC1 plays a number with one decimal place (for a number 123 it plays 12.3)
PREC2 plays a number with two decimal places (for a number 123 it plays 1.23)
Return value
none
frequency (number) tone frequency in Hz (from 150 to 15000)
duration (number) length of the tone in milliseconds
pause (number) length of the silence after the tone in milliseconds
flags (number):
0 or not present play with normal priority.
PLAY_BACKGROUND play in background (built in vario function uses this context)
PLAY_NOW play immediately
freqIncr (number) positive number increases the tone pitch (frequency with time), negative number decreases it. The frequency changes every 10 milliseconds, the change is freqIncr * 10Hz. The valid range is from -127 to 127.
Return value
none
Return value
none
none
Return value
str string. Empty if no new characters were available.
Return value
table representing the current radio position
lat (number) internal GPS latitude, positive is North
lon (number) internal GPS longitude, positive is East
'numsat' (number) current number of sats locked in by the GPS sensor
Get percent of already used Lua instructions in current script execution cycle.
@status current Introduced in 2.2.1
Parameters
none
Return value
usage (number) a value from 0 to 100 (percent)
model.insertMix(channel, line, value)
Insert a mixer line into Channel
@status current Introduced in 2.0.0, parameters below multiplex added in 2.0.13
Parameters
channel (unsigned number) channel number (use 0 for CH1)
line (unsigned number) mix number (use 0 for first line(mix))
value (table) see model.getMix() for table format
Return value
none
return 0 on radio without rotary encoder
if set to 'session', radio session timer is reset too
if set to 'ttimer', radio throttle timer is reset too
if set to 'tptimer', radio throttle percent timer is reset too
chunk
,
f1
and
f2
have different closures with different values of
c
.
-- /SCRIPTS/TestScript.lua
local c = ...
local function f(x)
return x + c
end
return f
local chunk = loadScript("/SCRIPTS/TestScript.lua")
local f1 = chunk(1)
local y = f1(5)
-- y = 5 + 1
local f2 = chunk(3)
local z = f2(5)
-- z = 5 + 3
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
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.
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 }
curve (unsigned number) curve number (use 0 for Curve1)
Return value
nil requested curve does not exist
table curve data:
name (string) name
type (number) type
smooth (boolean) smooth
points (number) number of points
y (table) table of Y values:
key is point number (zero based)
value
x (table) only included for custom curve type:
key is point number (zero based)
value
index (unsigned number) flight mode number (use 0 for FM0)
Return value
nil requested input or line does not exist
table input data:
name (string) input line name
switch (number) input switch index
fadeIn (number) fade in value (in 0.1s)
fadeOut (number) fade out value (in 0.1s)
trimsValues (table) table of trim values:
key is trim number (zero based)
value
trimsModes (table) table of trim mode:
key is trim number (zero based)
value
Telemetry Scripts
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.
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
Example
Notes:
The event parameter indicates which transmitter key has been pressed (see ).
Function Scripts
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
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
Example
crossfireTelemetryPop()
Pops a received Crossfire Telemetry packet from the queue.
@status current Introduced in 2.2.0
Parameters
none
Return value
nil queue does not contain any (or enough) bytes to form a whole packet
multiple returns 2 values:
popupInput(title, event, input, min, max)
Raises a pop-up on screen that allows uses input
@status current Introduced in 2.0.0
Parameters
title (string) text to display
event (number) the event variable that is passed in from the Run function (key pressed)
input (number) value that can be adjusted by the +/- keys
min (number) min value that input can reach (by pressing the - key)
max (number) max value that input can reach
Return value
number result of the input adjustment
"OK" user pushed ENT key
"CANCEL"
Notice
Use only from stand-alone and telemetry scripts.
getVersion()
Return OpenTX version
@status current Introduced in 2.0.0, expanded in 2.1.7, radio type strings changed in 2.2.0, os name added in EdgeTX 2.4.0
Example
This example also runs in OpenTX versions where the function returned only one value:
Output of the above script in simulator:
Parameters
none
Return value
string OpenTX version (ie "2.1.5")
multiple values (available since 2.1.7):
setTelemetryValue(id, subID, instance, value [, unit [, precision [, name]]])
@status current Introduced in 2.2.0
Parameters
id Id of the sensor, valid range is from 0 to 0xFFFF
subID subID of the sensor, usually 0, valid range is from 0 to 7
instance instance of the sensor (SensorID), valid range is from 0 to 0xFF
value fed to the sensor
unit unit of the sensor
precision the precision of the sensor
0 or not present no decimal precision.
!= 0
name (string) Name of the sensor if it does not yet exist (4 chars).
not present Name defaults to the Id.
present
Return value
true, if the sensor was just added. In this case the value is ignored (subsequent call will set the value)
Notice
All three parameters id, subID and instance can't be zero at the same time. At least one of them must be different from zero.
getGeneralSettings()
Returns (some of) the general radio settings
@status current Introduced in 2.0.6, imperial added in TODO, language and voice added in 2.2.0, gtimer added in 2.2.2.
Parameters
none
Return value
table with elements:
battWarn (number) radio battery range - warning value
model.getCustomFunction(function)
Get Custom Function parameters
@status current Introduced in 2.0.0, TODO rename function
Parameters
function (unsigned number) custom function number (use 0 for CF1)
Return value
nil requested custom function does not exist
table custom function data:
model.getSensor(sensor)
Get Telemetry Sensor parameters
@status current Introduced in 2.3.0
Parameters
sensor (unsigned number) sensor number (use 0 for sensor 1)
Return value
nil requested sensor does not exist
table with sensor data:
model.getMix(channel, line)
Get configuration for specified Mix
@status current Introduced in 2.0.0, parameters below multiplex added in 2.0.13
Parameters
channel (unsigned number) channel number (use 0 for CH1)
line (unsigned number) mix number (use 0 for first line(mix))
Return value
nil requested channel or line does not exist
table mix data:
model.getLogicalSwitch(switch)
Get Logical Switch parameters
@status current Introduced in 2.0.0
Parameters
switch (unsigned number) logical switch number (use 0 for LS1)
Return value
nil requested logical switch does not exist
table logical switch data:
getFieldInfo(name)
Return detailed information about field (source)
The list of valid sources is available:
model.getInput(input, line)
Return input data for given input and line number
@status current Introduced in 2.0.0, curveType/curveValue/carryTrim added in 2.3, inputName added 2.3.10, flighmode reworked in 2.3.11
Parameters
loadScript(file [, mode], [,env])
Load a Lua script file. This is similar to Lua's own API method, but it uses OpenTx's optional pre-compilation feature to save memory and time during load.
Return values are same as from Lua API loadfile() method: If the script was loaded w/out errors then the loaded script (or "chunk") is returned as a function. Otherwise, returns nil plus the error message.
@status current Introduced in 2.2.0
Example
model.getTimer(timer)
Get model timer parameters
@status current Introduced in 2.0.0, name added in 2.3.6
Parameters
local function run(event)
local ver, radio, maj, minor, rev, osname = getVersion()
print("version: "..ver)
if radio then print ("radio: "..radio) end
if maj then print ("maj: "..maj) end
if minor then print ("minor: "..minor) end
if rev then print ("rev: "..rev) end
if osname then print ("osname: "..osname) end
return 1
end
return { run=run }
is y value
is x value
is trim value
is trim mode
command (number)
packet (table) data bytes
user pushed EXIT key
battMin
(number) radio battery range - minimum value
battMax (number) radio battery range - maximum value
imperial (number) set to a value different from 0 if the radio is set to the
IMPERIAL units
language (string) radio language (used for menus)
voice (string) voice language (used for speech)
gtimer (number) radio global timer in seconds (does not include current session)
switch
(number) switch index
func (number) function index
name (string) Name of track to play (only returned only returned if action is play track, sound or script)
value (number) value (only returned only returned if action is not play track, sound or script)
mode (number) mode (only returned only returned if action is not play track, sound or script)
param (number) parameter (only returned only returned if action is not play track, sound or script)
active (number) 0 = disabled, 1 = enabled
type
(number) 0 = custom, 1 = calculated
name (string) Name
unit (number) See list of units in the appendix of the OpenTX Lua Reference Guide
prec (number) Number of decimals
id (number) Only custom sensors
instance (number) Only custom sensors
formula (number) Only calculated sensors. 0 = Add etc. see list of formula choices in Companion popup
name
(string) mix line name
source (number) source index
weight (number) weight (1024 == 100%) value or GVAR1..9 = 4096..4011, -GVAR1..9 = 4095..4087
offset (number) offset value or GVAR1..9 = 4096..4011, -GVAR1..9 = 4095..4087
the script is stopped and disabled if it misbehaves (e.g. run-time error or low memory)
function (optional)
(string) OpenTX version (ie "2.1.5")
(string) radio type: x12s, x10, x9e, x9d+, x9d or x7.
If running in simulator the "-simu" is added
(number) major version (ie 2 if version 2.1.5)
(number) minor version (ie 1 if version 2.1.5)
(number) revision number (ie 5 if version 2.1.5)
Since EdgeTX 2.4.0, sixth value added
(string) OS name (i.e. EdgeTX or nil if OpenTX)
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 }
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 }
file (string) Full path and file name of script. The file extension is optional and ignored (see mode param to control which extension will be used). However, if an extension is specified, it should be ".lua" (or ".luac"), otherwise it is treated as part of the file name and the .lua/.luac will be appended to that.
mode (string) (optional) Controls whether to force loading the text (.lua) or pre-compiled binary (.luac) version of the script. By default OTx will load the newest version and compile a new binary if necessary (overwriting any existing .luac version of the same script, and stripping some debug info like line numbers). You can use mode to control the loading behavior more specifically. Possible values are:
b only binary.
t only text.
T
env (integer) See documentation for Lua function loadfile().
Return value
function The loaded script, or nil if there was an error (e.g. file not found or syntax error).
string Error message(s), if any. Blank if no error occurred.
Notice
Note that you will get an error if you specify mode as "b" or "t" and that specific version of the file does not exist (eg. no .luac file when "b" is used). Also note that mode is NOT passed on to Lua's loader function, so unlike with loadfile() the actual file content is not checked (as if no mode or "bt" were passed to loadfile()).
On radios with color display, a color may be added to the flags described above.
There are two types of color constants: one that is an index into a table holding a palette of theme colors, and one that is just a color.
Indexed colors
These are the theme colors plus CUSTOM_COLOR, and they can be changed with the function lcd.setColor(color_index, color). Please note: if an indexed color is changed, then it changes everywhere that it is used. For the theme colors, this is not only in other widgets, but everywhere throughout the radio's user interface!
COLOR_THEME_PRIMARY1
COLOR_THEME_PRIMARY2
COLOR_THEME_PRIMARY3
COLOR_THEME_SECONDARY1
COLOR_THEME_SECONDARY2
COLOR_THEME_SECONDARY3
COLOR_THEME_FOCUS
COLOR_THEME_EDIT
COLOR_THEME_ACTIVE
COLOR_THEME_WARNING
COLOR_THEME_DISABLED
CUSTOM_COLOR
Literal colors
These color constants cannot be changed:
BLACK
WHITE
LIGHTWHITE
Deprecated color constants
These should no longer be used, but they are included for backwards compatibility. The old OpenTX API had a large number of indexed theme colors, and these have been mapped to the new theme colors as follows:
ALARM_COLOR -> COLOR_THEME_WARNING
BARGRAPH_BGCOLOR -> COLOR_THEME_SECONDARY3
BARGRAPH1_COLOR -> COLOR_THEME_SECONDARY1
model.getModule(index)
Get RF module parameters
Type values:
0 NONE
1 PPM
2 XJT_PXX1
3 ISRM_PXX2
4 DSM2
5 CROSSFIRE
6 MULTIMODULE
7 R9M_PXX1
8 R9M_PXX2
9 R9M_LITE_PXX1
10 R9M_LITE_PXX2
11 R9M_LITE_PRO_PXX1
12 R9M_LITE_PRO_PXX2
13 SBUS
14 XJT_LITE_PXX2
subType values for XJT_PXX1:
-1 OFF
0 D16
1 D8
@status current Introduced in 2.2.0
Parameters
index (number) module index (0 for internal, 1 for external)
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.
getGlobalTimer()
Returns radio timers
@status current Introduced added in 2.3.0.
Parameters
none
Return value
table with elements:
gtimer (number) radio global timer in seconds
session
Custom (Mixer) Scripts
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.
fun, err = loadScript("/SCRIPTS/FUNCTIONS/print.lua")
if (fun ~= nil) then
fun("Hello from loadScript()")
else
print(err)
end
(default on simulator) prefer text but load binary if that is the only version available.
bt (default on radio) either binary or text, whichever is newer (binary preferred when timestamps are equal).
Add x to avoid automatic compilation of source file to .luac version.
Eg: "tx", "bx", or "btx".
Add c to force compilation of source file to .luac version (even if existing version is newer than source file).
Eg: "tc" or "btc" (forces "t", overrides "x").
Add d to keep extra debug info in the compiled binary.
Eg: "td", "btd", or "tcd" (no effect with just "b" or with "x").
YELLOW
BLUE
DARKBLUE
GREY
DARKGREY
LIGHTGREY
RED
DARKRED
GREEN
DARKGREEN
LIGHTBROWN
DARKBROWN
BRIGHTGREEN
ORANGE
BARGRAPH2_COLOR -> COLOR_THEME_SECONDARY2
CURVE_AXIS_COLOR -> COLOR_THEME_SECONDARY2
CURVE_COLOR -> COLOR_THEME_SECONDARY1
CURVE_CURSOR_COLOR -> COLOR_THEME_WARNING
HEADER_BGCOLOR -> COLOR_THEME_FOCUS
HEADER_COLOR -> COLOR_THEME_SECONDARY1
HEADER_CURRENT_BGCOLOR -> COLOR_THEME_FOCUS
HEADER_ICON_BGCOLOR -> COLOR_THEME_SECONDARY1
LINE_COLOR -> COLOR_THEME_PRIMARY3
MAINVIEW_GRAPHICS_COLOR -> COLOR_THEME_SECONDARY1
MAINVIEW_PANES_COLOR -> COLOR_THEME_PRIMARY2
MENU_TITLE_BGCOLOR -> COLOR_THEME_SECONDARY1
MENU_TITLE_COLOR -> COLOR_THEME_PRIMARY2
MENU_TITLE_DISABLE_COLOR -> COLOR_THEME_PRIMARY3
OVERLAY_COLOR -> COLOR_THEME_PRIMARY1
SCROLLBOX_COLOR -> COLOR_THEME_SECONDARY3
TEXT_BGCOLOR -> COLOR_THEME_SECONDARY3
TEXT_COLOR -> COLOR_THEME_SECONDARY1
TEXT_DISABLE_COLOR -> COLOR_THEME_DISABLED
TEXT_INVERTED_BGCOLOR -> COLOR_THEME_FOCUS
TEXT_INVERTED_COLOR -> COLOR_THEME_PRIMARY2
TITLE_BGCOLOR -> COLOR_THEME_SECONDARY1
TRIM_BGCOLOR -> COLOR_THEME_FOCUS
TRIM_SHADOW_COLOR -> COLOR_THEME_PRIMARY1
WARNING_COLOR -> COLOR_THEME_WARNING
2 LR12
subType
(number) protocol index
modelId (number) receiver number
firstChannel (number) start channel (0 is CH1)
channelsCount (number) number of channels sent to module
Type (number) module type
if the module type is Multi additional information are available
protocol (number) protocol number (Multi only)
subProtocol (number) sub-protocol number (Multi only)
channelsOrder (number) first 4 channels expected order (Multi only)
(number) radio session in seconds
ttimer (number) radio throttle timer in seconds
tptimer (number) radio throttle percent timer in seconds
This functions allows for sending SPORT telemetry data toward the receiver, and more generally, to anything connected SPORT bus on the receiver or transmitter.
When called without parameters, it will only return the status of the output buffer without sending anything.
@status current Introduced in 2.2.0, retval nil added in 2.3.4
Parameters
sensorId physical sensor ID
frameId frame ID
dataId data ID
value value
Return value
boolean data queued in output buffer or not.
nil incorrect telemetry protocol.
getAvailableMemory()
Get available memory remaining in the Heap for Lua.
Parameters
none
Return value
usage (number) a value returned in b
math.Library
TODO
Please note: the firmware must be compiled with the option LUA=YES 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
initfunction 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:
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
Input table
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)
Output table
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.
CH1 [I4]Ail Weight(+100%)
:= LUA4b Weight(+100%)
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 }
{ "<name>", SOURCE }
{ "<name>", VALUE, <min>, <max>, <default> }
{ "<name1>", "<name2>" }
Edit Settings dialog from OpenTX Companion
Lua Basics
Lua is a small but powerful language. This section will explain a few of the most important concepts.
Introduction
Lua was chosen for OpenTX, and hence also 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 F 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:
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 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:
It takes an argument x and a 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.
References
The helpful, both if you want to learn more about Lua, and if you want to search for answers to specific questions.
Widget Scripts
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.
Flags and Pattern Constants
Many of the lcd functions accept parameters named flags and patterns. The names and their meanings are described below.
Flags
model.getMixesCount(channel)
Get the number of Mixer lines that the specified Channel has
@status current Introduced in 2.0.0
Parameters
model.deleteInput(input, line)
Delete line from specified input
@status current Introduced in 2.0.0
Parameters
channel (unsigned number) channel number (use 0 for CH1)
Return value
number number of mixes for requested channel
input (unsigned number) input number (use 0 for Input1)
line (unsigned number) input line (use 0 for first line)
Return value
none
Part II - EdgeTX Lua API Programming Guide
This section provides more specifics on the EdgeTX Lua implementation. Here you will find syntax rules for interface tables and functions.
model.getInputsCount(input)
Return number of lines for given input
@status current Introduced in 2.0.0
Parameters
input (unsigned number) input number (use 0 for Input1)
local function counter(start, step)
local x = start
return function()
local y = x
x = x + step
return y
end
end
local function match(x, ...)
for i, y in ipairs({...}) do
if x == y then
return true
end
end
return false
end
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 isnot 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 ).
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
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 fullscreen mode, then event is either 0, a , or a .
If event is a , then touchState is a table. Otherwise, it is nil.
When the widget is not in fullscreen mode, then both event and touchState are nil.
The size of the widget's screen area is as follows:
Fullscreen mode: LCD_W by LCD_H
Not fullscreen mode: zone.w
Key Event Constants
This page describes the value that is passed to scripts in the event parameter. It is used in Telemetry and One-Time scripts, as well as widget scripts in full screen mode.
The key event mechanism
Each time a key is pressed, held and released a number of events get generated. Here is a typical flow:
when a key is pressed a FIRST event is generated
if the key continues to be pressed, then after a while a LONG event is generated
if the key continues to be pressed, then a REPEAT events are being generated
when the key is released a BREAK event is generated
Couple of examples:
a short press on key would generate: FIRST, BREAK
a longer pres on key would generate: FIRST, LONG, BREAK
This normal key event sequence can be altered with the function. Any time this function is called (after the FIRST event) all further key events for this key will be suppressed until the next key press of this key. Examples:
kill immediately after the key press would generate: FIRST
kill after the long key press would generate: FIRST, LONG
Constants
The event parameter in the and scripts run function actually carries two pieces of information:
key number
type of event
The two fields are combined into one single number. Some of these combinations are defined as constants and are available to Lua scripts:
Radios with rotary encoder (X7 and Horus) have also:
Virtual events
Given the large number of radios supported by OpenTX, and the large difference in keys available on those, a set of VIRTUAL KEYS has been defined and are mapped to best fit available hardware
Touch Event Constants
In addition to the key events described in the previous section, radios with a color touch screen also provide touch events to the widget scripts.
The following touch events are passed in the event argument to the widget script refresh function (when in full screen mode), just like the key events. The following touch events are provided:
Touch Event Name
Description
EVT_TOUCH_FIRST
When the finger touches down on the screen
EVT_TOUCH_TAP
If the finger leaves the screen after a quick tap
In addition to the above touch events a touchState table is passed to refresh with the following addional data fields:
Notes:
touchState is nil if event is not a touch event. This can be used to test if we have a touch event or a key event.
Since Lua evaluates a nil value to false and everything else to true
model.getOutput(index)
Get servo parameters
@status current Introduced in 2.0.0
Parameters
index (unsigned number) output number (use 0 for CH1)
Return value
nil requested output does not exist
table output parameters:
getValue(source)
Returns the value of a source.
The list of fixed sources:
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 },
}
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 fullscreen, then event is 0 or event value, otherwise nil
end
return {
name = name,
options = options,
create = create,
update = update,
refresh = refresh,
background = background
}
name
(string) name
min (number) Minimum % * 10
max (number) Maximum % * 10
offset (number) Subtrim * 10
ppmCenter (number) offset from PPM Center. 0 = 1500
symetrical (number) linear Subtrim 0 = Off, 1 = On
revert (number) irection 0 = ---, 1 = INV
curve
(number) Curve number (0 for Curve1)
or nil if no curve set
:
if touchState then we have a touch event.
x, y are present for all touch events.
startX, startY, slideX, slideY are only present with EVT_TOUCH_SLIDE.
swipeUp / swipeDown / swipeLeft / swipeRightmay be present only withEVT_TOUCH_SLIDE.
EVT_TOUCH_BREAK
If the finger leaves the screen without tap or slide
EVT_TOUCH_SLIDE
Repeats while the finger is sliding on the screen
touchState fields
Description
x, y
Current touch point
startX, startY
Point where slide started
slideX, SlideY
Movement since previous SLIDE event (or start of slide)
swipeUp / swipeDown / swipeLeft / swipeRight
The field is present and equal to true if a swipe event occurred in that direction
In OpenTX 2.1.x the telemetry sources no longer have a predefined name. To get a telemetry value simply use it's sensor name. For example:
Altitude sensor has a name "Alt"
to get the current altitude use the source "Alt"
to get the minimum altitude use the source "Alt-", to get the maximum use "Alt+"
@status current Introduced in 2.0.0, changed in 2.1.0, Cels+ and Cels- added in 2.1.9
Parameters
source can be an identifier (number) (which was obtained by the getFieldInfo())
or a name (string) of the source.
Return value
value current source value (number). Zero is returned for:
non-existing sources
for all telemetry source when the telemetry stream is not received
far all non allowed sensors while FAI MODE is active
table GPS position is returned in a table:
lat (number) latitude, positive is North
lon
table GPS date/time, see getDateTime()
table Cells are returned in a table (except where no cells were detected in which case the returned value is 0):
table has one item for each detected cell:
key (number) cell number (1 to number of cells)
Notice
Getting a value by its numerical identifier is faster then by its name. While Cels sensor returns current values of all cells in a table, a Cels+ or Cels- will return a single value - the maximum or minimum Cels value.
1 - Wrong number of points
2 - Invalid Curve number
3 - Cuve does not fit anymore
4 - point of out of index
5 - x value not monotonically increasing
6 - y value not in range [-100;100]
7 - extra values for y are set
8 - extra values for x are set
