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...
Loading...
Go to https://doc.open-tx.org/opentx-2-3-lua-reference-guide/ for the latest published version of this guide.
This guide covers the development of user-written scripts for R/C transmitters running the OpenTX 2.3 operating system with Lua support. Readers should be familiar with 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 OpenTX Lua scripts and how to use them.
Part III is the OpenTX 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
last updated on 2021/01/09 17:57:00 UTC
The OpenTX team has no intention of making a profit from their work. OpenTX is free and open source and will remain free and open source. But OpenTX 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.
Another reason is that OpenTX maintains a build server that serves firmware compiled on demand. This is where OpenTX Companion orders your customized firmware. The server is not for free and the bandwidth is ever increasing with tens of thousands of firmware downloads each month.
The OpenTX team is grateful to those who have donated to the project. You have helped making OpenTX and OpenTX Companion great.
The Github Donor List is updated at each OpenTX release.
If you would like to contribute to OpenTX, donations are welcome and appreciated:
Return detailed information about field (source)
The list of valid sources is available:
OpenTX Version
Radio
2.0
2.1
2.2
2.3
@status current Introduced in 2.0.8, 'unit' field added in 2.2.0
name
(string) name of the field
table
information about requested field, table elements:
id
(number) field identifier
name
(string) field name
desc
(string) field description
'unit' (number) unit identifier Full list
nil
the requested field was not found
,
, ,
, , ,
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.
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).
Telemetry scripts are started when the model is loaded.
script init function is called
script background function is periodically called when custom telemetry screen is not visible. Notice:
In OpenTX 2.0 this function is not called when the custom telemetry screen is visible.
Starting from OpenTX 2.1 this function is always called no matter if the custom screen is visible or not.
script run function is periodically called when custom telemetry screen is visible
script is stopped and disabled if it misbehaves (too long runtime, error in code, low memory)
all telemetry scripts are stopped while one-time script is running (see Lua One-time scripts)
Every script must include a return statement at the end, that defines its interface to the rest of OpenTX code. This statement defines:
script init function (optional)
script background function
script run function
init_func()
function is called once when script is loaded and begins execution.
bg_func()
is called periodically, the screen visibility does not matter.
run_func(event)
function is called periodically when custom telemetry screen is visible. The event
parameter indicates which transmitter button has been pressed (see Key Events). This is the time when the script has full control of the LCD screen and keys and should draw something on the screen.
TODO: Need to determine status of wizard in 2.2
Function scripts are invoked via the 'Lua Script' option of Special Functions configuration page.
specialized handling in response to switch position changes
customized announcements
should not exceed allowed run-time/ number of instructions.
all function scripts are stopped while one-time script is running (see Lua One-time scripts)
Function scripts DO NOT HAVE ACCESS TO LCD DISPLAY
Place them on SD card in folder /SCRIPTS/FUNCTIONS/
script init function is called once when model is loaded
script run function is periodically called as long as switch condition is true
script is stopped and disabled if it misbehaves (too long runtime, error in code, low memory)
Every script must include a return statement at the end, that defines its interface to the rest of OpenTX code. This statement defines:
script init function (optional, see Init Function Syntax)
script run function (see Run Function Syntax)
local variables retain their values for as long as the model is loaded regardless of switch condition value
The script below is an example of customized countdown announcements. Note that the init function determines which version of OpenTX is running and sets the unit parameter for playNumber() accordingly.
This section provides more specifics on the OpenTX Lua implementation. Here you will find syntax rules for interface tables and functions.
Get servo parameters
@status current Introduced in 2.0.0
index
(unsigned number) output number (use 0 for CH1)
nil
requested output does not exist
table
output parameters:
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
Get Telemetry Sensor parameters
@status current Introduced in 2.3.0
sensor
(unsigned number) sensor number (use 0 for sensor 1)
nil
requested sensor does not exist
table
with sensor data:
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
Widgets are small scripts that show some info in a 'zone' in one of the model specific user defined (telemetry) screens. You can define those screens within the telemetry menu on the HORUS.
Each model can have up to five custom screens, with up to 8 widgets per screen, depending on their size and layout. Each instance of a widget has his own custom settings.
Widgets are located on the SD card, each in their specific folder /WIDGETS/<name>/main.lua (name must be in 8 characters or less).
Widgets need to be registered through the telemetry setup menu.
widget create function is called
widget update function is called upon registration and at change of settings in the telemetry setup menu.
widget background function is periodically called when custom telemetry screen is not visible. Notice:
This is different from the way telemetry scripts are handled
widget refresh function is periodically called when custom telemetry screen is visible
widget is stopped and disabled if it misbehaves (too long runtime, error in code, low memory)
all widgets are stopped while one-time script is running (see Lua One-time scripts)
Once registered, widgets are started when the model is loaded.
Every widget must include a return statement at the end, that defines its interface to the rest of OpenTX code. This statement defines:
widget name (name must be a string of 10 characters or less)
widget options array (maximum five options are allowed, 10 character names max, no spaces!)
widget create function
widget update function
script background function
script refresh function
options are only passed through to OpenTX to be used on widget creation. Don't change them during operation, this has no effect.
create() function is called once when widget is loaded and begins execution.
update() function is called once when widget is loaded and begins execution.
background() is called periodically when custom telemetry screen containing widget is not visible.
refresh() function is called periodically when custom telemetry screen containing wodget is visible.
in the example given, you can see that no global variables or functions are needed to operate the widget.
variables that are used throughout the widget, can best be declared inside the create function as local variables
those local variablkes can then be passed through to the other functions as an element of the widget array that is returned
If defined, init function is called right after the script is loaded from SD card and begins execution. Init is called only once before the run function is called for the first time.
Input Parameters:
none
Return values:
none
Outputs are only used in mix scripts. The output table defines only name(s), the actual values are determined by the script's run function.
Example:
Output name is limited to four characters.
A maximum of 6 outputs are supported
Number Format Outputs are 16 bit signed integers when they leave Lua script and are then divided by 10.24 to produce output value in percent:
Script Return Value
Mix Value in OpenTX
0
0%
996
97.2%
1024
100%
-1024
-100%
TODO: describe how theme scripts work on Horus type transmitters.
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.
Running a One-Time script will suspend execution of all other currently loaded Lua scripts (Mix, Telemetry, and Functions)
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.
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 (too long runtime, error in code, low
memory)
The run function is the function that is periodically called for the lifetime of script execution. Syntax of the run function is different between mix scripts and telemetry scripts.
Input parameters:
zero or more input values, their names are arbitrary, their meaning and order is defined by the input table. (see Input Table Syntax)
Return values:
none - if output table is empty (i.e. script has no output)
values
or -
comma separated list of output values, their order and meaning is defined by the output table. (see Output Table Syntax)
Input parameters:
The key-event parameter indicates which transmitter button has been pressed (see Key Events)
Return values:
A non-zero return value will halt the script
This section introduces the types of Lua scripts supported by OpenTX and how they may be used.
This section includes Acknowledgments and Getting Started.
Lua Standard Libraries
Included
package
-
coroutine
-
table
-
since OpenTX 2.1.0 (with limitations)
os
-
string
since OpenTX 2.1.7
bit32
since OpenTX 2.1.0
math
since OpenTX 2.0.0
debug
-
This section describes the Lua libraries, functions and constants that are provided by OpenTX.
The input table defines what values are available as input(s) to mix scripts. There are two forms of input table entries.
SOURCE syntax
SOURCE inputs provide the current value of a selected OpenTX variable. The source must set by the user when the mix script is configured. Source can be any value OpenTX knows about (inputs, channels, telemetry values, switches, custom functions,...). Note: typical range is -1024 thru +1024. Simply divide the input value by 10.24 to interpret as a percentage from -100% to +100%.
VALUE syntax
VALUE inputs provide a constant value that is set by the user when the mix 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 (warning : was 8 in 2.1)
The return statment is the last statement in an OpenTX Lua script. It defines the input/output table values and functions used to run the script.
Parameters init, input and output are optional. If a script doesn't use them, they can be omitted from return statement.
Example without init and output:
WARNING - Do not use Lua mix scripts for controlling any aspect of your model that could cause a crash if script stops executing.
Each model can have several mix scripts associated with it. These scripts are run periodically for entire time that model is selected. These scripts behave similar to standard OpenTX mixers but at the same time provide much more flexible and powerful tool.
Mix scripts take one or more values as inputs, do some calculation or logic processing based on them and output one or more values. Each run of a script should be as short as possible. Exceeding the script execution runtime limit will result in the script being forcefully stopped and disabled.
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.
mix 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...)
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).
script is loaded from SD card when model is selected
script init function is called
script run function is periodically called (inside GUI thread, period cca 30ms)
script is killed (stopped and disabled) if it misbehaves (too long runtime, error in code, low memory)
all mix scripts are stopped while one-time script is running (see Lua One-time scripts)
If as script output is used as a mixer source
and the script is killed for what ever reason, then the whole mixer line is disabled
! This can be used for example to provide a fall-back in case Lua mixer script gets 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:
Every script must include a return statement at the end, that defines its interface to the rest of OpenTX code. This statement defines:
init_func() function is called once when script is loaded.
run_func() function is called periodically
OpenTX Companion 2.2 is available for download at http://www.open-tx.org/downloads.html
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.
script input table (optional, see )
script output table (optional, see )
script init function (optional, see )
script run function (see )
inputs table defines input parameters (name and source) to run function ()
outputs table defines names for values returned by run function (see )
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
command
command
data
table of data bytes
boolean
data queued in output buffer or not.
nil
incorrect telemetry protocol.
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
module
module index (0 = internal, 1 = external)
rxUid
receiver index
sensorId
physical sensor ID
frameId
frame ID
dataId
data ID
value
value
boolean
data queued in output buffer or not.