• Share page
  •  
  •  
  •  
  •  

Lua script for beginners

Here, we will introduce the basics of Lua script, a programming language that can be used on OpenTX / EdgeTX radio.
このページを日本語で見る
Table of contents

What is a Lua script?

Lua script is one of the programming languages and can be run on the radio with OpenTX (Version 2.0.0 or later) or EdgeTX.
This is an interpreted language that uses an intermediate language, The grammar is similar to Java and JavaScript, Experienced people in these languages can easily code. Create source code as a text file, store it in each folder under the "SCRIPTS" folder on SD card, and specify input / output parameters and execution timing (startup trigger) on OpenTX / EdgeTX radio screen. Details of the language specifications can be read on The Programming Language Lua Official site site. You can also read about how to create and use Lua scripts on OpenTX, API, etc. on EdgeTX Lua Reference Guide, OpenTX 2.3 Lua Reference Guide .
The Programming Language Lua Official site
EdgeTX Lua Reference Guide
OpenTX 2.3 Lua Reference Guide

Sample of Lua script

If you have an OpenTX/EdgeTX radio, you can quickly try out the Lua script sample source and how it works. When creating a new model of drone , the wizard screen for selecting "Plane", "Delta", and "Multi" opens first. This wizard is written in Lua script. And it's source code is stored in /SCRIPTS/WIZARD folder of SD card image. "wizard.lua" is the first script to start, and "multi.lua" is called when "Multi (multi-rotor)" is selected. If you have experience with Java or JavaScript, opening them in a text editor will give you some idea of what language Lua can do.
In addition, some sample code is published in Introduction To OpenTX Lua Scripts (RCdiy) . You can read the sample code and how to set it to the radio.
Introduction To OpenTX Lua Scripts (RCdiy)

Development tool for Lua script

ZeroBrane (USD24.00 shareware) is a well-known integrated development environment (IDE) for Lua scripts. This is a lightweight Lua IDE with text editor, code completion, syntax highlighting, live coding, code analyzer, and debug support. It runs on MacOS (10.9 or later), Windows (32bit), and Linux.
OpenTX Companion, EdgeTX Companion also has a transmitter simulator that allows you to run Lua scripts. You can open the Lua debug screen to see the output of the script and where the crash occurred.
ZeroBrane Official site
ZeroBrane download page
How to install OpenTX Companion
How to install EdgeTX Companion

Types of Lua script

There are following types of Lua scripts that users can create on OpenTX/EdgeTX radio.
Type Execute Maximum number per model Storage folder in SD card Overview
Mix auto 7 /SCRIPTS/MIXES Describes process that replaces MIXS screen of radio. Loaded when select a model and automatically executed repeatedly. Can not read user's switch operation or display information on radio screen. The processing time should be minimal and should be completed within approximately 30ms. Specify on the "CUSTOM SCRIPTS" screen of the model.
Telemetry auto 3 /SCRIPTS/TELEMETRY Describes process of operating telemetry data from aircraft and display it on main screen (custom telemetry screen) of radio. Loaded when select a model and automatically executed repeatedly. One script can be assigned to multiple models. Specify on DISPLAY screen of the model.
One-Time manual - Anywhere ( Recommended under /SCRIPTS/TOOLS ) Starts when user selects a script file from [SD-HC CARD/SD CARD] screen of RADIO(SYSTEM) menu, and stops when the script returns non-zero value or when user presses and holds [EXIT] button. Mix, Telemetry, and Function scripts are paused while this script is running.
Scripts stored under /SCRIPTS/TOOLS folder can also be started from [TOOLS] screen of RADIO(SYSTEM) menu.
Function manual - /SCRIPTS/FUNCTIONS Describe the process you want to start when radio switch is operated. Runs repeatedly as long as associated switch remains in specified state. Can not display information on radio screen. Specify on SPECIAL FUNCTIONS / GLOBAL FUNCTIONS screen of the model.
Wizard auto - /SCRIPTS/WIZARD Wizard screen starts when you create a new "MODEL" in radio. Pre-installed on OpenTX/EdgeTX (SD card image). A type of One-Time script
  • In addition, there are Widget and Theme scripts that can be used only with a radio equipped with a color display / touch panel.
  • Mix and Telemetry scripts are loaded when radio is started or when model is switched. And it will continue to be called from within main loop of radio. However, if an error occurs or execution time or amount of memory used exceeds allowable value, execution will be interrupted. For this reason, you should avoid using this script to control flight itself. File name of Mix and Telemetry scripts must be 6 alphanumeric characters + extension (".lua").

Widget, Theme Script related information

Widget Scripts (OpenTX)
Widget Scripts (EdgeTX)
OpenTX widgets (github)
EdgeTX themes (github)

Betaflight Lua Scripts

Receivers that use Betaflight firmware with the corresponding telemetry function can change PID value and VTX settings from radio. Install and use Betaflight TX Lua Scripts on your radio.
Betaflight TX Lua Scripts (github)
Setup Betaflight LUA Script on OpenTX Radios (oscarliang)

How to write Mix script

Describes process that replaces MIXS screen of radio. You can configure up to 7 Mix scripts per model. You can describe complicated mixing processes that cannot be specified on MIXS screen of radio. For input data, you can specify sticks, switches, dials (Pot: Potentiometer), logical switches, output of other Mix scripts, telemetry, channel input, constants, etc. that can be selected as Source on MIXS screen. Data is output as a variable and can be used as a Source on MIXS screen.

Construction


Mix script requires the definition of at least following five statements / functions.
Input Table
Define input datas. You can define up to 6 items.
Output Table
Define output datas. You can define up to 6 items. This statement can be omitted.
Init Function
Describes initial setting process executed only once when radio is started or model is switched. This function can be omitted.
Run Function
Describes main process. Repeatedly executed in control loop of radio.
Return Statement
Describes what part of the actual code four statements / functions shown above correspond to.

Input Table


Following is a description example of Input Table. 
local inp_tbl =
    {
        { "Throttle", SOURCE },
        { "SwitchG",  SOURCE },
        { "Speed",    VALUE,    0, 100,  0 },
        { "Interval", VALUE, -128, 128, 50 }
    }
"Inp_tbl" is name of this Input Table. It can be freely defined by the user.
This example defines two sources (Throttle, SwitchG) and two constants (Speed, Interval). These names can be freely defined by the user as long as up to 8 alphanumeric characters. Actual input devices and values assignment for these sources and constants are specified when you register this script on radio.
Constant "Speed" indicates that a minimum of 0 to a maximum of 100 is allowed and default value is 0. Constant "Interval" indicates that a minimum of -128 to a maximum of 128 is allowed and default value is 50. Permissible range for constants is a minimum of -128 to a maximum of 128.

Output Table


Following is a description example of Output Table. 
local out_tbl = { "Out1", "Out2" }
"out_tbl" is name of this Output Table. It can be freely defined by the user.
In this example, two output data (Out1, Out2) are defined. Names of these output data must be up to 4 characters. By registering this script on radio, the names of these output data can be selected as Source on MIXS screen.

Init Function


Following is a description example of Init Function. 
local function init_func()
  -- code here runs only once when the model is loaded
end
"init_func" is name of this Init Function. It can be freely defined by the user. There are no input parameters and return values. By the way, the line starting with "--" is a comment line.

Run Function


Following is a description example of Run Function. 
local function run_func( inSrc01, inSrc02, inConst01, inConst02 )
  -- code here runs every MIX loop
  return value1, value2
end
"run_func" is name of this Run Function. It can be freely defined by the user.
Input parameters of the function are assigned input values defined in Input Table in order. In above example, inSrc01 reads input defined in Throttle, inSrc02 reads input defined in SwitchG, inConst01 reads constant set to Speed, and inConst02 reads constant set to Interval.
If script has output data, list it after retrun statement. They are assigned in order to variables defined in Output Table. In above example, value1 can be selected as variable Out1, value2 can be selected as variable Out2 as Source on MIXS screen of radio.

Return Statement


Following is a description example of Return Statement. 
return { run=run_func, input=inp_tbl, output=out_tbl, init=init_func }
Return Statement is required on the last line of Mix script. Describes what part of the actual code four statements / functions Input Table, Output Table, Init Function, and Run Function correspond to. Order of four definitions is arbitrary. Also, output and init can be omitted.

How to set and execute on radio


Store script in SD card folder /SCRIPTS/MIXES. Then open "CUSTOM SCRIPTS" screen in the model menu of radio. You can define one script per line here.
Press and hold [ENTER] on any line to enter edit mode. In first field, select the name of script. Then, in "Inputs" field on the left side of screen, names of input data defined in Input Table statement of script are displayed in a list. In "Outputs" field on the right side of screen, names of output data defined in Output Table statement of script are listed. Since "---" is displayed for input data that requires source to be specified, you can select the source by pressing [ENTER] here. In addition, default value is displayed for input data of constant, so you can specify any value by pressing [ENTER] here.
Next, open MIXS screen of model menu of radio. Then select name of script in Source field (if you want to use it in Source). Then, name of output data of script is set in the Source field.
After that, load the model set in radio and the script will work.

How to write Telemetry script

Describes process of operating telemetry data from aircraft and display it on main screen (custom telemetry screen) of radio. Data inside OpenTX/EdgeTX (timer value, etc.) other than telemetry can also be used and displayed. You can configure up to 3 Telemetry scripts per model. Names of the telemetry sensors that aircraft supports and can be used in scripts can be found in "Sensors" column by opening TELEMETRY screen in the MODEL menu.

Construction


Telemetry script requires the definition of at least following four statements / functions.
Init Function
Describes initial setting process executed only once when radio is started or model is switched. This function can be omitted.
Background Function
Describes main process. Repeatedly executed in the control loop of radio. (In OpenTX 2.0, it will stop working if you are viewing a custom telemetry screen on radio)
Run Function
Describes main process. Only when custom telemetry screen is displayed on radio, repeatedly executed in the control loop of radio. Screen display process is described here.
Return Statement
Describes what part of the actual code three functions shown above correspond to.

Init Function


Following is a description example of Init Function. 
local function init_func()
  -- code here runs only once when the model is loaded
end
"init_func" is name of this Init Function. It can be freely defined by the user. There are no input parameters and return values. By the way, the line starting with "--" is a comment line.

Background Function


Following is a description example of Background Function. 
local function bg_func()
  -- code here runs every radio process loop
end
"bg_func" is name of this Background Function. It can be freely defined by the user.

Run Function


Following is a description example of Run Function. 
local function run_func( key_event )
  -- code here runs every radio process loop when custom telemetry screen is visible
  return 0
end
"run_func" is name of this Run Function. It can be freely defined by the user.
If last "return" statement returns a non-zero value, the script will stop.
OpenTX/EdgeTX system passes information of radio key that was pressed at that time as "key_event". Use it in Run Function as needed. You can read more about key_event in Key Event Constants (OpenTX 2.3 Lua Reference Guide) . Also, use Lcd Functions (OpenTX 2.3 Lua Reference Guide) for drawing on screen of radio. You can draw not only characters but also lines, dots, bitmaps, etc.

Return Statement


Following is a description example of Return Statement. 
return { run=run_func, background=bg_func, init=init_func }
Return Statement is required on the last line of Telemetry script. Describes what part of the actual code Init Function, Background Function, and Run Function correspond to. Order of three definitions is arbitrary. Also, init can be omitted.

How to set and execute on radio


Store script in SD card folder /SCRIPTS/TELEMETRY. Open DISPLAY screen from MODEL menu of the radio, select "Script" as the display type, and select the name of the script. Or open "Telemetry" tab on the model edit screen of OpenTX Companion, EdgeTX Companion , and select one of "Telemetry Screen 1/2/3/4" at the bottom of the screen. Under "Custom Screen Type", select "Script" and name of the script. Then transfer the model data to radio.
After that, you can see result of the script by loading the model in radio and open custom telemetry screen.

How to write Function script

Describe the process you want to start when radio switch is operated. This script can not display information on radio screen. Note that local variables defined in the script retain their values as long as the model is loaded, regardless of switch state.

Construction


Function script requires the definition of at least following three statements / functions.
Init Function
Describes initial setting process executed only once when radio is started or model is switched. This function can be omitted.
Run Function
Describes main process. Runs repeatedly as long as associated switch remains in specified state.
Return Statement
Describes what part of the actual code two functions shown above correspond to.

Init Function


Following is a description example of Init Function. 
local function init_func()
  -- code here runs only once when the model is loaded
end
"init_func" is name of this Init Function. It can be freely defined by the user. There are no input parameters and return values. By the way, the line starting with "--" is a comment line.

Run Function


Following is a description example of Run Function. 
local function run_func()
  -- code here runs every radio process loop when specified state lasts on associated switch 
end
"run_func" is name of this Run Function. It can be freely defined by the user.

Return Statement


Following is a description example of Return Statement. 
return { run=run_func, init=init_func }
Return Statement is required on the last line of Function script. Describes what part of the actual code Init Function and Run Function correspond to. Order of two definitions is arbitrary. Also, init can be omitted.

How to set and execute on radio


Store script in SD card folder /SCRIPTS/FUNCTIONS. Then open SPECIAL FUNCTIONS / GLOBAL FUNCTIONS screen in the model menu of radio. You can define one script per line here.
Press and hold [ENTER] on any line to enter edit mode. In first field, select switch to associate with and its state. In second field, select "Lua Script". In third field, select name of the script.
After that, when you operate associated switch, the script will start.
How to use Special Functions / Global Functions

How to write One-Time script

One-Time scripts do not have required structure as in the Mix, Telemetry, and Function scripts described above. As long as you follow Lua language grammar, OpenTX/EdgeTX API, and usage, you can write anything else.
Stops when the script returns a non-zero value or when user presses and holds [EXIT] button.
However, Mix, Telemetry, and Function scripts are paused while One-Time script is running. When One-Time script finishes executing, paused scripts resumes operation.

Display the script title on TOOLS screen


One-Time scripts stored under /SCRIPTS/TOOLS folder can be started from [TOOLS] screen of RADIO(SYSTEM) menu. If you put the following line at the top of the script, it will be displayed on [TOOLS] screen as the title of the script. 
-- TNS|title_string|TNE
"title_string" is the title of the script. If you do not include this line in your script, [TOOLS] screen will display the script's file name.

How to set and execute on radio


Store script in any folder on SD card (recommended under /SCRIPTS/TOOLS folder), and select the script file from [Radio]-[SD-HC CARD/SD CARD] screen to start it.

How to use OpenTX / EdgeTX Radio

How to use OpenTX / EdgeTX

Detailed explanation of OpenTX / EdgeTX

To know more about How to Fly Hobby Drone

To know more about iPhone