Join the chat on Discord

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 and need the docs for that specific version.

Please feel free to make suggestions or corrections to the documentation on GitHub, but the preferred method of editing is to use GitBook, so all changes will need to be made by someone who is authorized as a writer there.

This guide covers the development of user-written scripts for R/C transmitters running the EdgeTX 2.7 operating system with Lua support. Readers should be familiar with EdgeTX, the EdgeTX Companion, and know how to transfer files the SD card in the transmitter.

If you are new to Lua programming, you may also find the Lua Reference Manual of assistance.

Part I is an overview of the different script types, along with basic examples of each.

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 covers advanced topics with examples

This section provides more specifics on the EdgeTX Lua implementation. Here you will find syntax rules for interface tables and functions.

This section includes Acknowledgments and Getting Started.

Downloading EdgeTX Companion

EdgeTX Companion 2.7 is available for download here (pick the appropriate download for your operating system from Assets heading at the bottom of the page - the filename will have cpn in the name).

Enabling support for Mixer Scripts

If you intend to use mixer scripts, when compiling the firmware for your transmitter you need to make sure the LUA_MIXER option is set. This is not required if you only intend to run any of the other types of Lua script (i.e. telemetry, one-time, function scripts, widgets) as support for those is included by default.

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. However, the project is more expensive to maintain than most open source projects. This in mainly because there is a never ending flood of hardware to integrate and maintain code for. Hardware that costs. In addition, in order to develop for this hardware, certain specalised test and measurement equipment is also required.

In order to support this, EdgeTX has chosen to use OpenCollective to allow for donations from the community, as well as funding from manufacturers who choose to partner with and sponsor the project. This also allows for transparent accounting of what the funds are spent on.

Please visit our OpenCollective page if you would like to financially help support the project!

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.

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)

Get available memory remaining in the Heap for Lua.

Parameters

none

Return value

• usage (number) a value returned in b

@status current Introduced in 2.6

Parameter

• switchIndex: integer identifying a switch as returned by getSwitchIndex(positionName) or fields in the table returned by model.getLogicalSwitch(switch) identifying switches.

Return value

• value: string naming the switch position as it is shown on radio menus where a switch can be chosen.

@status current Introduced in 2.6

Parameter

• switchIndex: integer identifying a switch as returned by getSwitchIndex(positionName) or fields in the table returned by model.getLogicalSwitch(switch) identifying switches.

Return value

• value: true/false. The value of the switch.

This functions allows for sending telemetry data toward the Ghost link.

When called without parameters, it will only return the status of the output buffer without sending anything.

@status current Introduced in 2.7.0

Parameters

• command command

• data table of data bytes

Return value

• boolean data queued in output buffer or not.

• nil incorrect telemetry protocol.

This section describes the Lua libraries, functions and constants that are provided by EdgeTX.

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

The io.open() function is used to open the file on SD card for subsequent reading or writing. After the script is done with the file manipulation io.close() function should be used.

Parameters

• filename

The io.close() function is used to close open file.

Parameters

• file object a file object that was returned by the io.open() function.

The io.read() function is used to read data from the file on SD card.

Notice: other read commands (like "all", etc..) are *not supported.

Parameters

The io.write() function is used to write data to the file on SD card.

Parameters

• file object a file object that was returned by the io.open() function. The file must be opened in write or append mode.

• CHAR_RIGHT

• CHAR_LEFT

• CHAR_UP

• LS_FUNC_NONE

• LS_FUNC_VEQUAL

• LS_FUNC_VALMOSTEQUAL

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

Return flight mode data.

@status current Introduced in 2.1.7

Parameters

@status current Introduced in 2.6

Parameters

• positionName: string naming a switch position as it is shown on radio menus where you can select a switch. Notice that many names have special characters in them like arrow up/down etc. (see

Reads the value of a logical switch.

@status current Introduced in 2.6

Parameter

The io.seek() function is used to move the current read/write position.

Notice: other read standard seek bases (like "cur", "end") are not supported.

Parameters

Parameters

• sourceIndex: integer identifying a value source as returned by getSourceIndex(sourceName) or the id

Play a time value (text to speech)

@status current Introduced in 2.1.0

Parameters

Remove all mixers

@status current Introduced in 2.0.0

Parameters

none

Return the time since the radio was started in multiple of 10ms

The timer internally uses a 32-bit counter which is enough for 497 days so overflows will not happen.

@status current Introduced in 2.0.0

Parameters

none

Return current system date and time that is kept by the RTC unit

Parameters

none

Get percent of already used Lua instructions in current script execution cycle.

@status current Introduced in 2.2.1

Parameters

none

Return rotary encoder current speed

@status current Introduced in 2.3.10

Parameters

none

Stops key state machine. See for the detailed description.

@status current Introduced in 2.0.0

Parameters

Change the working directory

@status current Introduced in 2.3.0

Parameters

Set baudrate for serial port(s) affected to LUA

@status current Introduced in 2.3.12

Parameters

baudrate Desired baudrate

This function reads/writes the Multi protocol buffer to interact with a protocol².

@status current Introduced in 2.3.2

Parameters

Sets the value of a shared memory variable that can be used for passing data between Lua widgets and other Lua scripts.

@status current Introduced in 2.6

Parameters

• id: integer between 1 and 16 identifying the shared memory variable.

Returns gray value which can be used in LCD functions

@status current Introduced in 2.0.13

Parameters

none

Clear all flightModes

@status current Introduced in 2.3.10

Parameters

none

• FUNC_OVERRIDE_CHANNEL

• FUNC_TRAINER

• FUNC_INSTANT_TRIM

• FUNC_RESET

• FUNC_SET_TIMER

• FUNC_ADJUST_GVAR

• FUNC_VOLUME

• FUNC_SET_FAILSAFE

• FUNC_RANGECHECK

• FUNC_BIND

• FUNC_PLAY_SOUND

• FUNC_PLAY_TRACK

• FUNC_PLAY_VALUE

• FUNC_PLAY_SCRIPT

• FUNC_RESERVE5

• FUNC_BACKGND_MUSIC

• FUNC_BACKGND_MUSIC_PAUSE

• FUNC_VARIO

• FUNC_HAPTIC

• FUNC_LOGS

• FUNC_BACKLIGHT

• FUNC_SCREENSHOT

• FUNC_RACING_MODE

• FUNC_DISABLE_TOUCH

Parameters

• sourceName: string naming a value source as it is shown on radio menus where you can select it. Notice that many names have special characters in them.

Return value

• sourceIndex: integer. The source index, which can be used as input for getSourceName(sourceIndex), getValue(sourceIndex), and getFieldInfo(sourceIndex).

Notice

The source names shown on the screen are not the same as the names used by getFieldInfo and getValue. But the indices are the same, so e.g. getValue(index) will work with the indices obtained here.

This function is rather time consuming, and should not be used repeatedly in a script, if it can be avoided.

Status

Current Introduced in 2.6

Raises a pop-up on screen that shows a warning

@status current Introduced in 2.2.0

Parameters

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

Get channel assigned to stick. See Default Channel Order in General Settings

@status current Introduced in 2.0.0

Parameters

• stick (number) stick number (from 0 to 3)

Return value

• number channel assigned to this stick (from 0 to 3)

• nil stick not found

Delete all Inputs

@status current Introduced in 2.0.0

Parameters

none

Return value

none

Pops a received Ghost Telemetry packet from the queue.

@status current Introduced in 2.7.0

Parameters

none

Return value

• nil queue does not contain any (or enough) bytes to form a whole packet

• multiple returns 2 values:

• type (number)

• packet (table) data bytes

Set all inputs to defaults

@status current Introduced in 2.0.0

Parameters

none

Return value

none

Delete line from specified input

@status current Introduced in 2.0.0

Parameters

• input (unsigned number) input number (use 0 for Input1)

• line (unsigned number) input line (use 0 for first line)

Return value

none

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

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

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

This is an iterator function over switch positions.

for switchIndex, switchName in switches() do ...

will iterate over all available switch positions.

Parameters

• first: the first switch index. If nil or omitted, the first available switch is used.

• last: the last switch index. If nil or omitted, the last available switch is used.

Status

Current Introduced in 2.6

@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

none

Return value

• str string. Empty if no new characters were available.

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.

The loadScript(<file>) 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:

-- /SCRIPTS/TestScript.lua
local c = ...

local function f(x)
  return x + c
end

return f

You can load and use the above file with the following code:

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

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 chunk, f1 and f2 have different closures with different values of c.

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

Play a tone

@status current Introduced in 2.1.0

Parameters

• 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

• 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 input data for given input and line number

@status current Introduced in 2.3.10

Parameters

• index (unsigned number) flight mode number (use 0 for FM0)

Return value

• nil requested input or line does not exist

• table input data:

Play a numerical value (text to speech)

@status current Introduced in 2.0.0

Parameters

• 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

Return value

none

Get current Model information

@status current Introduced in 2.0.6, changed in 2.2.0, filename added in 2.6.0.

Parameters

none

Return value

• table model information:

  • name (string) model name

  • bitmap

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:

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

• Key Events

• Touch Events

• Flags and Patterns

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

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

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

Return value

• nil queue does not contain any (or enough) bytes to form a whole packet

• multiple returns 4 values:

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.

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:

Return detailed information about field (source)

The list of valid sources is available:

The io library has been simplified and only a subset of functions and their functionality is available. What follows is a complete reference of io functions that are available to EdgeTX scripts

Available functions:

• io.open()

Play a file from the SD card

@status current Introduced in 2.0.0, changed in 2.1.0

Parameters

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

Gets the value of a shared memory variable that can be used for passing data between Lua widgets and other Lua scripts.

@status current Introduced in 2.6

Parameters

• id: integer between 1 and 16 identifying the shared memory variable.

Return value

This is an iterator function over value sources.

for sourceIndex, sourceName in sources() do ...

will iterate over all available value sources.

Parameters

@status current Introduced in 2.2.0

Parameters

• id Id of the sensor, valid range is from 0 to 0xFFFF

@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

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

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

Get Custom Function parameters

@status current Introduced in 2.0.0, TODO rename function

Parameters

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

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. Full screen mode can be entered by selecting the widget, pressing ENTER and selecting Full screen on the widget menu, or by double tapping the widget on radios with a touch screen. Full screen mode can be exited by long pressing the RETURN button, or by calling the Lua function lcd.exitFullScreen().

Each model can have up to five main views, with up to 8 widgets per screen, depending on their size and layout. Each instance of a widget has his own options table.

Please note: Widget scripts are only available on radios with color screens, e.g. FrSky Horus models, Radiomaster TX16 and Jumper T16.

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

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

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.

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

Load a Lua script file. This is similar to Lua's own loadfile() 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

Parameters

• 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

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

Get Curve parameters

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

• curve (unsigned number) curve number (use 0 for Curve1)

Return value

• nil requested curve does not exist

• table curve data:

  • name

Returns the value of a source.

The list of fixed sources:

An argument with drawing flags can be given to the various functions that draw on the LCD screen. The lower half of the flags (bits 1-16) are the flag attributes shown below, and the upper half of the flags (bits 17-32) are a color value.

Not all of the flags below should be directly manipulated from Lua, but those that are meant to be set directly by Lua, are accessible by the .

Since the flags are bits, you can add them up to combine, as long as you only add each flag one time. If you add the same flag twice, then it will add up to the next bit over, e.g. INVERS + INVERS = VCENTER. If you want to add a flag to a value where it may already be set, then use flags = bit32.bor(flags, INVERS).

Sets the value of a sticky logical switch.

@status current Introduced in 2.6

Parameters

Flags

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.

Regarding memory, the situation is a bit different for the radios with black/white or grey scale screens and telemetry scripts, and the radios with color screens and widget scripts. The telemetry script radios only have 128-192 KB RAM memory - that is very small! The widget script radios have 8 MB RAM memory. But the way that widgets are designed means that all widget scripts present on the SD card will be loaded into memory, whether or not they are actually used. Therefore, different strategies should be applied to save memory for the two different types of radios and scripts.

Telemetry Script Radios

Radios with black/white or grey scale screens and telemetry scripts such as e.g. FrSky Taranis, Xlite, Jumper T12 and Radiomaster TX12 have extremely small RAM memories, and therefore it may be necessary to divide up your script into smaller loadable modules.

The following simple example demonstrates how different screens can be loaded on demand, and how shared data can be stored in a table.

The table shared contains data that is shared between the main telemetry script and the loadable screens. Notice that the functions shared.changeScreen and shared.run are also shared this way.

Code is loaded by shared.changeScreen with the loadScript function, which returns the loadable script as a chunk of code. The code is executed with shared as the argument, and the loadable script adds a new run function to the shared table. shared.run is called by run in the main script.

Widget Script Radios

Radios with color screens and widget scripts such as e.g. FrSky Horus, Jumper T16 and Radiomaster TX16S have fairly large RAM memories, but since all widget scripts present on the SD card are always loaded into memory, they could run out of memory if many big widget scripts are present on the card - even if they are not being used by the selected model. Therefore, large widget scripts should be divided into a small main script and a large loadable part. One way to accomplish this is the following.

The create function loads the file loadable.lua in the folder /WIDGETS/<widget name>/, and calls it immediately as described in . It passes zone and options as arguments to loadable.lua. This scripts adds the functions refresh, update and (optionally) background to the widget table:

zone and options are stored in the of loadable.lua, therefore they do not need to be added to the widget table, as is commonly done.

Obviously, the bulk of the widget's code goes in loadable.lua, and is only loaded if the widgets is in fact being used. Therefore, if the widget is not used, only the small amount of code in main.lua is loaded into the radio's memory.

For an example of a widget that uses the above design pattern, please have a look at the EventDemo widget that is included on the SD card with EdgeTX for color screen radios.

In general terms, there are two different types of data that can be exchanged with EdgeTX:

• Values, which generally fall on a scale between -1024 and 1024, also sometimes reported as -100% to 100%, e.g. for mixer values and channel outputs.

• Switches, which are either true or false.

A specific data source type, e.g. Global Variables, can be indexed directly with an index that starts with 0 for the first one. This can be a little confusing, as e.g. GV1 for FM0 is read with , because GV1 is the first global variable, and FM0 is the first flight mode. But as long as you remember that all direct indices start with 0 for the first one, you should be fine!

Global Variables is a value data source that can return a value between -1024 and 1024. Examples of value sources are:

• Global Variables

• Sticks, sliders and knobs

• Trim values

There is a way to access a value of any such type with a meta-index. You use the function where name can be any of the valid source names listed . It returns a table with a description of the value source, including the field id, which is the meta-index.

You can use id with the function to read the current value. You can also use name directly, but this is less efficient, as EdgeTX does a linear search for the name every time it is called. Therefore, the procedure of first extracting the meta-index from getFieldInfo(name).id, and then using that, is recommended.

For switches, uses a direct index to read this specific type of switch sources, again using the index 0 for LS1 etc. But there are also several types of switch sources, such as:

• Logical switches

• Switch positions, testing if a physical switch is in a particular position, e.g. SA↑.

• Trim buttons

You can find the meta-index of a particular switch source with , where name is exactly the name that you see in the radio menus where you can select a switch source.

You can read the current value of a switch source with as a true/false value.

It can be very confusing that some source can be read both as a value and as a switch. As an example, elevator trim can be read as the current value of the trim:

Or it can be read as the current value of the trim button position:

These are really two different things, as the elevator trim is an internal value stored by the radio, which is changed with the trim button, and the button is a physical button.

But it can also be a more direct comparison, e.g. the 3-position switch B, which can be read as a value source with:

Or the current position of switch B can be read with:

Hopefully, these examples illustrated the differences between values and switches, and showed how these can be retrieved in a Lua script.

You can also send data the other way: from Lua to the EdgeTX model setup.

To send a value, use a global variable: model.setGlobalVariable(index, fm, value). If you use the default GV setting, where all other flight modes use the value of FM0, then you can use 0 for fm.

To send a switch, setup a STICKY type logical switch, and then use setStickySwitch(index, true/false).

The following table gives an overview of the Lua API functions that can be used to exchange data with the EdgeTX model setup.

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

Return the internal GPS position or nil if no valid hardware found

@status current Introduced in 2.2.2

Parameters

none

Return value

• table representing the current radio position

  • lat (number) internal GPS latitude, positive is North

Raises a pop-up on screen that allows uses input

@status current Introduced in 2.0.0

Parameters

Overview

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

Typical uses of Function scripts are: