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.

WARNING! -

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

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.

Lifetime of One-Time scripts

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)

Telemetry Scripts

General description

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.

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

Lifetime of telemetry script

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)

Script interface definition

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

Example (interface only):

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

local function bg_func()
  -- bg_func is called periodically (always, the screen visibility does not matter)
end

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

return { run=run_func, background=bg_func, init=init_func  }

Notes:

• 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.

This section introduces the types of Lua scripts supported by OpenTX and how they may be used.

TODO: Need to determine status of wizard in 2.2

TODO: describe how theme scripts work on Horus type transmitters.

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

Description

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.

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.

• 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...)

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

Lifetime

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

Disabled script

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:

Script interface definition

Every script must include a return statement at the end, that defines its interface to the rest of OpenTX code. This statement defines:

Example (interface only):

Notes:

• init_func() function is called once when script is loaded.

• run_func() function is called periodically

General description

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.

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

Lifetime of widgets

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.

Script interface definition

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

Example (draws a moving counter that counts only when not visible):

Notes:

• 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

Overview

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

Typical uses

• specialized handling in response to switch position changes

• customized announcements

Limitations

• 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

Location

Place them on SD card in folder /SCRIPTS/FUNCTIONS/

Lifetime

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

Script interface definition

Every script must include a return statement at the end, that defines its interface to the rest of OpenTX code. This statement defines:

Example (interface only):

Notes:

• local variables retain their values for as long as the model is loaded regardless of switch condition value

Advanced example (save as /SCRIPTS/FUNCTIONS/cntdwn.lua)

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.