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

Part I of the guide shows how to enable Lua support for Taranis and includes basic examples of each types of script.

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

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.

Lifetime

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 (e.g. run-time error or low

  memory)

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.

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:

• init function (optional)

• run function

Example

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

local function run(event)
  -- run is called periodically only when screen is visible
  -- A non-zero return value will halt the script
  return x
end

return { run=run, init=init }

Notes:

• The event parameter indicates which transmitter key has been pressed (see Key Events).

• A non-zero return value from run will halt the script.

TODO: Need to determine status of wizard in 2.2

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 is called periodically when the widget instance is not visible. Note: this is different from the way that telemetry scripts are handled.

• refresh is called periodically when the widget instance is visible. Note: if you want background to run when the widget is visible, then call it from refresh.

• A widget script is stopped and disabled if it misbehaves (e.g. too long runtime, run-time error, or low memory)

• All widgets are stopped while a One-Time script is running (see One-Time scripts).

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

• update function

• background function (optional)

• refresh function

Example

local name = "WidgetName"

-- Create a table with default options
-- Options can be changed by the user from the Widget Settings menu
-- Notice that each line is a table inside { }
local options = {
  { "Source", SOURCE, 1 },
  -- BOOL is actually not a boolean, but toggles between 0 and 1
  { "Boolean", BOOL, 1 },
  { "Value", VALUE, 1, 0, 10},
  { "Color", COLOR, ORANGE },
  { "Text", STRING, "Max8chrs" }
}

local function create(zone, options)
  -- Runs one time when the widget instance is registered
  -- Store zone and options in the widget table for later use
  local widget = {
    zone = zone,
    options = options
  }
  -- Add local variables to the widget table,
  -- unless you want to share with other instances!
  widget.someVariable = 3
  -- Return widget table to EdgeTX
  return widget
end

local function update(widget, options)
  -- Runs if options are changed from the Widget Settings menu
  widget.options = options
end

local function background(widget)
  -- Runs periodically only when widget instance is not visible
end

local function refresh(widget, event, touchState)
  -- Runs periodically only when widget instance is visible
  -- If full screen, then event is 0 or event value, otherwise nil
end

return {
  name = name,
  options = options,
  create = create,
  update = update,
  refresh = refresh,
  background = background
}

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.

• If options is changed by the user in the Widget Settings menu, then update will be called with a new options table, unaffected by any changes made by Lua code to the old options table.

• Maximum five options are allowed, with names of max. 10 characters, and no spaces.

• If local variables are declared outside functions in the widget script, then they are shared between all instances of the widget.

• Therefore, local variables that are private for each instance should be added to the widget table in the create function before returning the widget table to EdgeTX.

• When the widget is in full screen mode, then event is either 0, a key event value, or a touch event value.

• If event is a touch event value, then touchState is a table. Otherwise, it is nil.

• When the widget is not in full screen mode, then both event and touchState are nil.

• The size of the widget's screen area is as follows:

  • Full screen mode: LCD_W by LCD_H

  • Not full screen mode: zone.w by zone.h

This section includes Acknowledgments and Getting Started.

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.

Lifetime

• Telemetry scripts are loaded when the model is selected.

• init function is called one time when the script is loaded

• background function is periodically; both when the telemetry screen is visible and when it is not.

• run function is called periodically only when the telemetry screen is visible

• script is stopped and disabled if it misbehaves (e.g. run-time error or low memory)

• all telemetry scripts are stopped if a one-time script is running (see One-time scripts)

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

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:

• init function (optional)

• background function (optional)

• run function

Example

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

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

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

return { run = run, background = background, init = init }

Notes:

• The event parameter indicates which transmitter key has been pressed (see Key Events).

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