This guide covers the development of user-written scripts for R/C transmitters running the EdgeTX 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.

Sections

EdgeTX LUA development support

Quickest way to get support from seasoned EdgeTX LUA developers is to join our Discord server and ask on dedicated #lua channel

Join the chat on Discord

LUA Reference guide collaboration

Please feel free to make suggestions or corrections to the documentation.

• Preferred method of editing is to use GitBook, as it uses WYSWIG editor allowing two-stage publication. If you want to change or add whole page or become collaborator <decribe what to do>.

Project support

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!

Standard LUA io library has been simplified and only a subset of functions and their functionality is available.

Available functions:

• io.open()

• io.close()

• io.read()

• io.write()

• io.seek()

Examples

Read the whole file

-- this is a One-time script

local function run(event)
  print("lua io.read test")         -- print() statements are visible in Debug output window
  local f = io.open("foo.bar", "r")
  while true do
    local data = io.read(f, 10)     -- read up to 10 characters (newline char also counts!)
    if #data == 0 then break end    -- we get zero length string back when we reach end of the file
    print("data: "..data)
    end
  io.close(f)
  return 1
end

return {  run=run }

Append data to file

-- this is a One-time script

local function run(event)
  print("lua io.write test")
  local f = io.open("foo.bar", "a")        -- open file in append mode
  io.write(f, "first line\r\nsecond line\r\n")
  io.write(f, 4, "\r\n", 35.6778, "\r\n")  -- one can write multiple items at the same time
  local foo = -4.45
  io.write(f, foo, "\r\n")
  io.close(f)
  return 1    -- this will end the script execution
end

return { run=run }

Introduction

Lua was chosen for 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 Fundamental Concepts in Programming Languages 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:

local function counter(start, step)
  local x = start

  return function()
    local y = x
    x = x + step
    return y
  end
end

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 widget scripts 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:

local function match(x, ...)
  for i, y in ipairs({...}) do
    if x == y then
      return true
    end
  end
  return false
end

It takes an argument x and a vararg 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.

Purpose

One-time scripts are used mainly to perform tasks that are not connected with flying. In example ELRS configuration LUA script. They do their task and are then terminated (by user or function) and unloaded.

Execution & Lifetime

Script is executed when user selects "Execute" on a script file from SD card browser screen, or opens a Lua Tool, or creates a new model with a Wizard script.

The script executes until:

• it returns value different from 0 (except returning string that contains new script name to be executed)

• is forcefully closed by user by long press of EXIT key

• is forcefully closed by system if it misbehaves (e.g. run-time error or low

  memory)

File Location

One-Time Scripts can be placed anywhere on SD card, however, the folder /SCRIPTS/ is recommended.

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:

Parameters

Return values

Parameters none

Return Values none

Examples

Simplest one-time LUA script

One-Time LUA script with initialization and exit feature if user short press and release EXIT (RTN) key

For detailed function explanation see in EdgeTX manual.

Purpose

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

Typical uses of Function scripts are:

• specialized handling in response to switch position changes

• customized announcements

Execution & Lifetime

Function script is loded when model is selected. Script executes until

• it misbehaves (e.g. run-time error or low memory)

• is running. When One-time script finishes execution, Wigdet Script resumes execution.

File Location

Function scripts are located on the SD card in the folder /SCRIPTS/FUNCTIONS/

Interface

Every Function script must include a return statement at the end, defining its interface to EdgeTX.

This statement returns a table with the following fields:

Parameters none

Return values none

Parameters none

Return Values none

Parameters none

Return Values none\

Example

Purpose

Widget scripts are avaiable on radios equiped with color LCD. They are designed to run constantly in the background performinfg various task. Widget scripts are mostly used to extend EdgeTX functionality via Widgets that are places by user on Main Views. They are equivalent of Telemetry Scripts on radios equiped with B&W LCD.

Most of the time, widget scripts show some info in a Widget's zone in one of the user defined Main Views. They cannot receive direct input from the user via key events with exeption of being displayed in so called Full Screen mode. Full screen mode can be entered by selecting the widget, pressing ENTER and selecting Full screen from the widget's contextual menu, or by double tapping the widget on radios with a touch screen. Full screen mode can be exited by long pressing the EXIT (RTN) button, or by calling the Lua function lcd.exitFullScreen().

Each model can have up to nine 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.

Execution & 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 Widget Script placed in proper location on the SD card will consume part of the radio's memory - even if it is not being used.

Script executes until:

• it misbehaves (e.g. too long runtime, run-time error, or low memory)

• One-Time script is running. When One-time script finishes execution, Wigdet Script resumes execution.

File Location

Widget scripts are located on the SD card, each one in their specific folder: /WIDGETS/<folder name>/

Widget script name is constant and has to be named main.lua

Interface

Every Widget Script must include a return statement at the end, defining its interface to EdgeTX. This statement returns a table with the following fields:

Parameters

Return values

Parameters

Return values none

Parameters

Return values none

Parameters

Return values none

Examples

LUA Version

EdgeTX 2.10 uses LUA interpreter and compiler version 5.2 For detailed reference read

Included standard libraries

Purpose

Mixes Scripts take one or more values as inputs, do some processing in Lua code, and output one or more values. Each model can have several Mixes Scripts associated with it, and these scripts are run periodically. They behave similarly to standard EdgeTX mixers, but at the same time they provide a much more flexible and powerful tool.

Typical use cases:

• 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

Execution & Lifetime

Mixes script is loded when model is selected. Script executes until

• it misbehaves (e.g. run-time error or low memory)

• is running. When One-time script finishes execution, Wigdet Script resumes execution.

File Location

Mixes scripts are located on SD card in folder /SCRIPTS/MIXES/

Interface

Every Mixes Script must include a return statement at the end, defining its interface to EdgeTX. This statement returns a table with the following fields:

This function is called periodicaly when script is running. Parameters Variables matching those used in input table Return values Variables matching those used in output table\

This function is called once when Mixes Script is loaded and executed for the first time

Parameters none Return values none\

The input table defines what values are available as input(s) to custom scripts.

There are two forms of input table entries

SOURCE

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

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

The output table defines only name(s), as the actual values are returned by the script's run function.

Examples

Example of <decribe what it does>.

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:

Radios with B&W LCD screen

Radios with Grayscale LCD screen

Radios with COLOR LCD screen

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

• Key Events

• Touch Events

• Flags and Patterns

• Colors

• Screen size

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

• YELLOW

• BLUE

• DARKBLUE

• GREY

• DARKGREY

• LIGHTGREY

• RED

• DARKRED

• GREEN

• DARKGREEN

• LIGHTBROWN

• DARKBROWN

• BRIGHTGREEN

• ORANGE

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

• 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

Purpose

Although they are named "Telemetry scripts" in fact they can be used to perform constant task while running in background. Telemetry scripts are mostly used for building customized screens that are avalilable to user directly from main screen using key shortcut. 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.

Execution & Lifetime

Telemetry script is loaded and executed when model is selected. Script executes until:

• it misbehaves (e.g. run-time error or low memory)

• One-time Script is running. When One-time script finishes execution, Wigdet Script resumes execution.

File Location

Telemetry scripts are located on the SD card in the folder /SCRIPTS/TELEMETRY/.

Interface

Every Telemetry script must include a return statement at the end, defining its interface to EdgeTX. This statement returns a table with the following fields:

Parameters

Return values none

Parameters none

Return Values none

Parameters none

Return Values none

Examples

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

local function my_background()
  -- background is called periodically
end

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

return { run = my_run, background = my_background, init = my_init }

Technical Data

LUA data

Inputs overview

EdgeTX internal Source List contains every source available on particular radio model.

Source List groups

Source List ID

Particular Source List ID is a integer number from 1 to whatever last source entry is used by EdgeTX developers during firmware implementation. Different Radios have different number of physical inputs that affects this list. Therefore for the same source type (ie LS04 - Logical switch number 4) sourceListID can have different value on particular radio model

Source List Name

Source List name can also change due to firmware changes during development or user configuration (ie. assigning custom name to input). In current version of EdgeTX firmware Source List Name also may contain special visual symbols to indicate type source (see Special Charactes Constants).

lcd.drawText Flags

lcd drawing functions flags on B&W LCD radios

lcd.drawLine function patterns

There are several option types that can be specified in the widget options table, which are exposed to the user via the Widget Settings menu.

Example

Description

Lcd functions allow scripts to interact with the transmitter display. This access is limited to the 'run' functions of One-Time and Telemetry scripts. Widget scripts on the Horus (X10 and X12S) can make use of the lcd functions as well.

Notes:

The run function is periodically called when the screen is visible. In OpenTX 2.0 each invocation starts with a blank screen (unless lcd.lock() is used). Under OpenTX 2.1 screen state is always persisted across calls to the run function. Many scripts originally written for OpenTX 2.0 require a call to lcd.clear() at the beginning of their run function in order to display properly under 2.1 and 2.2.

Many of the lcd functions accept parameters named flags and patterns. The names and their meanings are described below.

Flags Constants

Patterns Constants

Screen Constants

Screen Information

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:

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:

  • 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 / swipeRight may be present only withEVT_TOUCH_SLIDE.

• tapCount is zero for anything but EVT_TOUCH_TAP.

Clears the LCD screen optionaly filling it with selected color

Syntax

lcd.clear( [color] )

Parameters

Returns

none

Notes

This function works only in stand-alone and telemetry & widget scripts. See .

Available on

API status

Examples

Related topics

Draw a combo box

@status current Introduced in 2.0.0

Parameters

• x,y (positive numbers) top left corner position

• w (number) width of combo box in pixels

• list (table) combo box elements, each element is a string

• idx (integer) index of entry to highlight

• flags (unsigned number) drawing flags, the flags can not be combined:

• BLINK combo box is expanded

• INVERS combo box collapsed, text inversed

• 0 or not present combo box collapsed, text normal

Return value

none

Notice

Only available on Taranis

Draw a solid rectangle from top left corner (x,y) of specified width and height

@status current Introduced in 2.0.0

Parameters

• x,y (positive numbers) top left corner position

• w (number) width in pixels

• h (number) height in pixels

• flags (unsigned number) drawing flags

Return value

none

Draw a straight line on LCD

@status current Introduced in 2.0.0, flags introduced in 2.3.6

Parameters

• x1,y1 (positive numbers) starting coordinate

• x2,y2 (positive numbers) end coordinate

• pattern SOLID or DOTTED

• flags lcdflags

Return value

none

Notice

If the start or the end of the line is outside the LCD dimensions, then the whole line will not be drawn (starting from OpenTX 2.1.5)

Draw a bitmap at (x,y)

@status current Introduced in 2.0.0

Parameters

• x,y (positive numbers) starting coordinates

• name (string) full path to the bitmap on SD card (i.e. “/IMAGES/test.bmp”)

Return value

none

Notice

Maximum image size is [display width / 2] x [display height] pixels.

• CHAR_RIGHT

• CHAR_LEFT

• CHAR_UP

• CHAR_DOWN

• CHAR_DELTA

• CHAR_STICK

• CHAR_POT

• CHAR_SLIDER

• CHAR_SWITCH

• CHAR_TRIM

• CHAR_INPUT

• CHAR_FUNCTION

• CHAR_CYC

• CHAR_TRAINER

• CHAR_CHANNEL

• CHAR_TELEMETRY

• CHAR_LUA

• 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

Draw a single pixel at (x,y) position

@status current Introduced in 2.0.0

Parameters

• x (positive number) x position

• y (positive number) y position

• flags (optional) lcdflags

Return value

none

Notice

Taranis has an LCD display width of 212 pixels and height of 64 pixels. Position (0,0) is at top left. Y axis is negative, top line is 0, bottom line is 63. Drawing on an existing black pixel produces white pixel (TODO check this!)

Draw a simple gauge that is filled based upon fill value

@status current Introduced in 2.0.0, changed in 2.2.0

Parameters

• x,y (positive numbers) top left corner position

• w (number) width in pixels

• h (number) height in pixels

• fill (number) amount of fill to apply

• maxfill (number) total value of fill

• flags (unsigned number) drawing flags

Return value

none

Draw a rectangle from top left corner (x,y) of specified width and height

@status current Introduced in 2.0.0, changed in 2.2.0

Parameters

• x,y (positive numbers) top left corner position

• w (number) width in pixels

• h (number) height in pixels

• flags (unsigned number) drawing flags

• t (number) thickness in pixels, defaults to 1 (only on Horus)

Return value

none

Draw a text representation of switch at (x,y)

@status current Introduced in 2.0.0

Parameters

• x,y (positive numbers) starting coordinate

• switch (number) number of switch to display, negative number displays negated switch

• flags (unsigned number) drawing flags, only SMLSIZE, BLINK and INVERS.

Return value

none

Displays the name of the corresponding input as defined by the source at (x,y)

@status current Introduced in 2.0.0

Parameters

• x,y (positive numbers) starting coordinate

• source (number) source index

• flags (unsigned number) drawing flags