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

• 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

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 beginning at (x,y)

@status current Introduced in 2.0.0, SHADOWED introduced in 2.2.1

Parameters

• x,y (positive numbers) starting coordinate

• text (string) text to display

• flags (unsigned number) drawing flags. All values can be combined together using the + character. ie BLINK + DBLSIZE. See the for available characters in each font set.

• 0 or not specified normal font

• XXLSIZE jumbo sized font

• DBLSIZE double size font

• MIDSIZE mid sized font

• SMLSIZE small font

• INVERS inverted display

• BLINK blinking text

• SHADOWED Horus only, apply a shadow effect

Return value

none

LUA Version

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

Included standard libraries

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

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

Display a number at (x,y)

@status current Introduced in 2.0.0, SHADOWED introduced in 2.2.1

Parameters

• x,y (positive numbers) starting coordinate

Draw an arc

Parameters

• x,y (positive numbers) coordinates of the center

Draw a title bar

Parameters

• title (string) text for the title

Draw a rectangle in perspective

Parameters

• pitch,roll (positive numbers) pitch and roll to define the orientation of the rectangle

• FUNC_OVERRIDE_CHANNEL

• FUNC_TRAINER

• FUNC_INSTANT_TRIM

• FUNC_RESET

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

Draw a single pixel at (x,y) position

@status current Introduced in 2.0.0

Parameters

• x (positive number) x position

Returns the rightest x position from previous drawtext or drawNumber output

@status current Introduced in 2.2.0

Parameters

none

Draw a bitmap at (x,y)

@status current Introduced in 2.0.0

Parameters

• x,y (positive numbers) starting coordinates

Reset the backlight timeout

@status current Introduced in 2.3.6

Parameters

none

Returns gray value which can be used in LCD functions

@status current Introduced in 2.0.13

Parameters

none

Displays a bitmap pattern pie at (x,y)

@status current Introduced in 2.8.0

Parameters

• bitmap (pointer) point to a bitmap previously opened with Bitmap.open()

• x,y (positive numbers) starting coordinates

Refresh the LCD screen

@status current Introduced in 2.2.0

Parameters

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

Returns the rightmost x position from previous output

@status current Introduced in 2.0.0

Parameters

none

Return value

• number (integer) x position

Notice

Only available on Taranis

For added clarity, it is recommended to use lcd.getLastRightPos()

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

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

@status current Introduced in 2.8.0

Parameters

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

• w (number) width in pixels

• h (number) height in pixels

• flags (optional) please see Lcd functions overview

Return value

none

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

• title (string) title to display

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

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

Return value

none

Display a value formatted as time at (x,y)

@status current Introduced in 2.0.0, SHADOWED introduced in 2.2.1

Parameters

• x,y (positive numbers) starting coordinate

• value (number) time in seconds

• flags (unsigned number) drawing flags:

• 0 or not specified normal representation (minutes and seconds)

• TIMEHOUR display hours

• other general LCD flag also apply

• SHADOWED Horus only, apply a shadow effect

Return value

none

Returns the leftmost x position from previous drawtext or drawNumber output

@status current Introduced in 2.2.0

Parameters

none

Return value

• number (integer) x position

Notice

Only available on Taranis

Raises a pop-up on screen that allows uses input

@status current Introduced in 2.0.0

Parameters

• title (string) text to display

• event (number) the event variable that is passed in from the Run function (key pressed)

• input (number) value that can be adjusted by the +/­- keys

• min (number) min value that input can reach (by pressing the -­ key)

• max (number) max value that input can reach

Return value

• number result of the input adjustment

• "OK" user pushed ENT key

• "CANCEL" user pushed EXIT key

Notice

Use only from stand-alone and telemetry scripts.

Displays a bitmap pattern at (x,y)

@status current Introduced in 2.8.0

Parameters

• bitmap (pointer) point to a bitmap previously opened with Bitmap.open()

• x,y (positive numbers) starting coordinates

• flags (optional) please see Lcd functions overview

Return value

none

Notice

Only available on Horus

Exit full screen widget mode.

@status current Introduced in 2.5.0

Notice

Only available on radios with color display

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)

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

Append data to file

Technical Data

LUA data

Inputs overview

Draws channel value defined in source variable at (x,y)

Syntax

lcd.drawChannel(x, y, source [, flags])

Parameters

Returns

none

Notes

Available on

API status

Examples

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

Draw a filled triangle

Parameters

• x1,y1,x2,y2,x3,y3 (positive numbers) coordinates of the three vertices

• flags (optional) please see and constants

Return value

none

Available on

API status

Draw an arc

Parameters

• x,y (positive numbers) coordinates of the center

• r (positive number) radius

• start,end (positive numbers) start and end of the arc

• flags (optional) please see and constants

Return value

none

Available on

API status

Draw a circle at (x, y) of specified radius

Parameters

• x,y (positive numbers) center position

• r (number) radius in pixels

• flags (optional) please see and constants

Return value

none

Available on

API status

Draw a line only inside a rectangle

@status current Introduced in 2.4.0

Parameters

• x1,y1,x2,y1 (positive numbers) coordinates of the start and end of the unclipped line

• xmin,xmax,ymin,ymax (positive numbers) the limits of the rectangle inside which the line is drawn

• pattern (FORCE, ERASE, DOTTED) please see

• flags (optional) please see and constants

Return value

none

API Status

Change log

Displays prevoiusly loaded bitmap at (x,y) and optionally scales it.

Syntax

lcd.drawBitmap( bitmap, x, y [, scale] )

Returns colorFlag in RGB565 format that can be used with lcd draw functions.

Syntax

lcd.RGB( r, g, b | rgb )

Get the width and height of a text string drawn with flags

@status current Introduced in 2.5.0

Parameters

• text (string)

Clears the LCD screen optionaly filling it with selected color

Syntax

lcd.clear( [color] )

Syntax

lvgl.align([parent], {settings})

parent:align({settings})

Draw a filled circle at (x, y) of specified radius

Parameters

• x,y (positive numbers) center position

Set a color for specific area

@status current Introduced in 2.2.0

Parameters

• area (unsigned number) specific screen area in the list bellow

EdgeTX widgets and One-Time scipts can make use of LVGL controls and objects to create the script user interface. In addition to providing much better performance, this gives Lua scripts the same styles applied to firmware LVGL pages and controls.

The LVGL API can be used to add varios objects such as labels, rectangles, circles, buttons, toggle switches, sliders and more. Objects can be grouped, e.g. a rectangle can contain child labels or any other object. Objects can be moved, resized and updated as needed.

Many object properties can be set dynamically through functions in the Lua script - whenever the function returns a new value the objects property is automaticall changed. This removes the need for manually re-drawing the user interface.

Limitations:

Draw text inside rectangle (x,y,w,h) with line breaks

Parameters

• x,y (positive numbers) starting coordinate

Raises a pop-up on screen that shows a warning

@status current Introduced in 2.2.0

Parameters

• title (string) text to display

Get the color for specific area : see lcd.setColor for area list

@status current Introduced in 2.3.11

Parameters

none

Return value

none

Notice

Only available on Colorlcd radios

Radios with B&W LCD screen

Radios with Grayscale LCD screen

Radios with COLOR LCD screen

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)

• 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

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

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

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

Draw a triangle

Parameters

• x1,y1,x2,y2,x3,y3 (positive numbers) coordinates of the three vertices

• flags (optional) please see and constants

Return value

none

Available on

API status

Syntax

lvgl.circle([parent], {settings})

parent:circle({settings})

Parameters

See the API page for parameter description and common settings.

Note: 'w', 'h' and 'size' should not be used with lvgl.circle. Use 'radius' instead.

Circle specific settings:

Return values

LVGL object

API Status

Change log

One-Time script

local exitTool = false

local function close()
  lvgl.confirm({title="Exit", message="Really exit?",
    confirm=(function() exitTool = true end)
  })
end

local function init()
  if lvgl == nil then return end

  lvgl.clear();

  local pg = lvgl.page({title="Test Tool", subtitle="Page 1", back=close})

  pg:label({x=70, y=16, color=BLACK, font=DBLSIZE, text="Test Page"})
  pg:button({x=200, y=150, text="CLOSE", press=close})
end

local function run(event, touchState)
  if lvgl == nil then
    lcd.drawText(0, 0, "LVGL support required", COLOR_THEME_WARNING)
  end

  if (exitTool) then return 2 end
  return 0
end

return {init = init, run = run, useLvgl=true}

When run this produces the page shown below.

The user can exit the script by tapping the 'CLOSE' button or tapping the 'EdgeTX' button in the top-left corner. In both cases a popup dialog will be shown - if the user selects 'Yes' the script will close.

Widget script

LVGL version of the 'Counter' script.

Draw a pie slice

@status current Introduced in 2.4.0

Parameters

• x,y (positive numbers) coordinates of the center

• r (positive number) radius

• start,end (positive numbers) start and end of the pie slice

• flags (optional) please see and constants

Return value

none

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:

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

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.

Syntax

lvgl.arc([parent], {settings})

parent:arc({settings})

Parameters

Syntax

lvgl.file([parent], {settings})

parent:file({settings})

Parameters

Syntax

lvgl.build([parent], {{settings}})

parent:build({{settings}})

Parameters

Syntax

lvgl.button[parent], {settings})

parent:button({settings})

Parameters